Named graphs — IRI and id

Every graph has an IRI, the name you use in SPARQL, and a numeric id, which the SQL functions take. Three functions move between the two.

What it does

pgrdf.add_graph(iri TEXT) → BIGINT    -- create (or find) a graph; returns its id
pgrdf.graph_id(iri TEXT)  → BIGINT    -- id for an IRI, or NULL
pgrdf.graph_iri(id BIGINT) → TEXT     -- IRI for an id, or NULL

• add_graph(iri) is idempotent: calling it again with the same IRI returns the same id.
• Graph 0 always exists. It is the default graph, named urn:pgrdf:graph:0.
• To see every graph at once, with sizes, lock state and reasoning freshness, use pgrdf.graph_inventory().

Graphs can also come into being without add_graph:

• SPARQL UPDATE: CREATE GRAPH <iri>, or INSERT DATA { GRAPH <iri> { … } } into a graph that doesn't exist yet.
• parse_trig / parse_nquads create the named graphs a document mentions (unless strict => true).
• copy_graph / move_graph by id create a missing destination, named urn:pgrdf:graph:<id>.

Why you'd use it

• Project managers — pick a stable IRI for each graph (a tenant, a snapshot, an ontology version) once. The id is an implementation detail.
• Data scientists — refer to graphs by IRI in SPARQL GRAPH clauses; pgRDF routes the query to the right partition.
• Ontologists — keep the usual "ontology IRI names the ontology graph" convention, so loaded vocabularies stay self-describing.

Example

SELECT pgrdf.add_graph('http://example.org/people');   -- → 1
SELECT pgrdf.add_graph('http://example.org/people');   -- → 1   (same graph)

SELECT pgrdf.graph_id('http://example.org/people');    -- → 1
SELECT pgrdf.graph_iri(1);                             -- → http://example.org/people
SELECT pgrdf.graph_iri(0);                             -- → urn:pgrdf:graph:0

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

-- SPARQL names the graph by IRI:
SELECT * FROM pgrdf.sparql('
  SELECT ?s ?o
   WHERE { GRAPH <http://example.org/people> { ?s ?p ?o } }');
--  {"o": "http://example.org/bob", "s": "http://example.org/alice"}

A SPARQL query without a GRAPH clause searches all graphs. Scope it with GRAPH <iri> { … }, or GRAPH ?g { … } to see which graph each match came from. FROM and FROM NAMED clauses are ignored, so use GRAPH instead. See GRAPH in SPARQL.

Watch for NULL

graph_id() returns NULL for an IRI that isn't a graph. Most pgRDF functions are strict: given a NULL argument they return NULL without doing anything. The loaders refuse instead:

SELECT pgrdf.graph_id('http://example.org/typo');
-- → NULL
SELECT pgrdf.count_quads(pgrdf.graph_id('http://example.org/typo'));
-- → NULL   (not 0: the graph doesn't exist)
SELECT pgrdf.parse_turtle('<http://e/a> <http://e/b> <http://e/c> .',
                          pgrdf.graph_id('http://example.org/typo'));
-- ERROR:  argument 1 must not be null

When a graph might be missing, create it with add_graph(iri) (safe to repeat) or check graph_id(iri) IS NOT NULL first. The IRI forms of the lifecycle functions refuse an unknown IRI with SQLSTATE 42704.

See also

• Managing graphs — inventory, copy, carve, lock and health-check.
• Per-graph partitions — how each graph is stored.
• GRAPH in SPARQL.