Inline Turtle / TriG / N-Quads ingest

Pass RDF as a SQL text value: Turtle, TriG or N-Quads. No file on the database server is needed.

What it does

pgrdf.parse_turtle(content TEXT, graph_id BIGINT, base_iri TEXT DEFAULT NULL) → BIGINT
pgrdf.parse_turtle_verbose(content TEXT, graph_id BIGINT, base_iri TEXT DEFAULT NULL) → JSONB

parse_turtle parses Turtle (N-Triples is a subset, so that works too) into one graph and returns the number of triples loaded. It suits notebooks, application code, migration scripts, generated graphs and test fixtures: anywhere the data is already a string. parse_turtle_verbose returns a JSONB report instead of a count; see Verbose ingest statistics.

• base_iri resolves relative IRIs such as <alice>. Without it, a document with relative IRIs refuses to parse.
• Loading appends. Loading the same triples again stores them again. To replace a graph's contents, clear it first.
• Parse errors refuse the whole call, with a message giving the line and column; nothing is loaded.
• RDF-star (quoted triples) is not supported and refuses with 0A000.
• An empty string loads nothing and returns 0.

Quad formats — TriG and N-Quads

pgrdf.parse_trig(content TEXT, default_graph_id BIGINT DEFAULT 0, strict BOOLEAN DEFAULT false) → JSONB
pgrdf.parse_nquads(content TEXT, default_graph_id BIGINT DEFAULT 0, strict BOOLEAN DEFAULT false) → JSONB

These formats name the graph for each triple themselves: TriG with GRAPH <iri> { … } blocks, N-Quads with an optional fourth term on each line.

• Triples with no graph go into default_graph_id (the default graph, 0, unless you say otherwise).
• With strict => false (the default), a graph IRI that doesn't exist yet is created.
• With strict => true, an unknown graph IRI refuses with 42704, so a document can only write into graphs you created beforehand.
• Both return a JSONB report whose "graphs" array lists the ids of every graph written.

Why you'd use it

• Project managers — ship seed data for new tenants inside migration scripts; no file deployment needed.
• Data scientists — build small graphs as strings in a notebook and send them straight to pgRDF.
• Ontologists — sketch and load mini-ontologies from the SQL prompt.

Examples

SELECT pgrdf.add_graph('http://example.org/knows');

SELECT pgrdf.parse_turtle('
@prefix ex: <http://example.org/> .
ex:alice ex:knows ex:bob .
ex:bob   ex:knows ex:carol .
', pgrdf.graph_id('http://example.org/knows'));
-- → 2

SELECT pgrdf.count_quads(pgrdf.graph_id('http://example.org/knows'));
-- → 2

Relative IRIs with a base:

SELECT pgrdf.parse_turtle('<alice> <knows> <bob> .',
                          pgrdf.graph_id('http://example.org/knows'),
                          'http://example.org/');
-- → 1   (stored as http://example.org/alice, …)

TriG, writing into two named graphs and the default graph:

SELECT pgrdf.parse_trig('
@prefix ex: <http://example.org/> .
ex:alice ex:name "Alice" .
GRAPH <http://example.org/g/a> { ex:alice ex:knows ex:bob . }
GRAPH <http://example.org/g/b> { ex:bob ex:knows ex:carol . ex:bob ex:name "Bob" . }
') -> 'graphs';
-- → [0, 2, 3]

SELECT graph_id, iri, asserted FROM pgrdf.graph_inventory();
--  graph_id |           iri            | asserted
-- ----------+--------------------------+----------
--         0 | urn:pgrdf:graph:0        |        1
--         1 | http://example.org/knows |        3
--         2 | http://example.org/g/a   |        1
--         3 | http://example.org/g/b   |        2

With strict => true, only existing graphs are accepted:

SELECT pgrdf.parse_trig('
@prefix ex: <http://example.org/> .
GRAPH <http://example.org/g/unknown> { ex:x ex:y ex:z . }
', 0, strict => true);
-- ERROR:  42704: parse_trig: unknown graph iri http://example.org/g/unknown

N-Quads, with one line naming a graph and one without:

SELECT pgrdf.parse_nquads(
'<http://example.org/a> <http://example.org/p> <http://example.org/b> <http://example.org/g/c> .
<http://example.org/a> <http://example.org/p> "no graph" .
', pgrdf.graph_id('http://example.org/knows')) -> 'graphs';
-- → [4, 1]   (g/c was created as graph 4; the unlabelled line went to graph 1)

How it works

parse_turtle and load_turtle share the same parser and loading pipeline; only the source differs (a string versus a file on the server). For large files, see Bulk ingest.

See also

• Load Turtle from disk — the file variant.
• Verbose ingest statistics — what the JSONB reports contain.
• Named graphs — IRIs and ids.