drop_graph — remove a graph

Remove a named graph completely in one call: its triples, its storage partition and its IRI. Returns the number of triples removed.

What it does

pgrdf.drop_graph(iri TEXT,  cascade BOOLEAN DEFAULT TRUE) → BIGINT
pgrdf.drop_graph(id BIGINT, cascade BOOLEAN DEFAULT TRUE) → BIGINT

Each graph is stored in its own partition, so drop_graph removes that partition rather than deleting rows one at a time. The cost does not grow with the size of the graph.

• Asserted and inferred triples go together. The return value counts both.
• cascade => false is a safety catch. It refuses to drop a graph that holds inferred triples (written by materialize), so a script can't discard reasoning output without saying so. The default is cascade => true.
• The default graph can't be dropped. Graph 0 (urn:pgrdf:graph:0) always exists; empty it with clear_graph instead.
• It is transactional. Inside BEGIN … ROLLBACK the graph comes back intact.
• Unknown input. Dropping an unknown IRI refuses (42704), which catches typos. Dropping by an id that has no graph returns 0.

Why you'd use it

• Project managers — tenant offboarding, snapshot pruning and erasure requests become one SQL call that reports how much it removed.
• Data scientists — clean up scratch graphs from a notebook session without leaving storage behind.
• Ontologists — retire an obsolete vocabulary version once its consumers have moved on.
• Backend engineers — branch on the SQLSTATE (2BP01, 42704, 55P03) rather than on message text.
• Operators — removing a graph is a metadata operation on one partition, not a scan of the whole quad table.

Example

SELECT pgrdf.add_graph('http://example.org/scratch');
SELECT pgrdf.parse_turtle('
@prefix ex:   <http://example.org/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

ex:Cat rdfs:subClassOf ex:Animal .
ex:tom a ex:Cat .
', pgrdf.graph_id('http://example.org/scratch'));
-- → 2

SELECT pgrdf.materialize(pgrdf.graph_id('http://example.org/scratch'), 'rdfs')
       ->> 'inferred_triples_written';
-- → 1   (ex:tom a ex:Animal)

SELECT pgrdf.drop_graph('http://example.org/scratch', cascade => false);
-- ERROR:  2BP01: drop_graph: inferred rows present (graph_id = 1); pass cascade => true to proceed

SELECT pgrdf.drop_graph('http://example.org/scratch');
-- → 3   (2 asserted + 1 inferred)

SELECT pgrdf.graph_id('http://example.org/scratch');
-- → NULL

SPARQL UPDATE has the same operation: DROP GRAPH <http://example.org/scratch>. See SPARQL UPDATE.

Refusals

SQLSTATE	When	Example message
2BP01	cascade => false and the graph holds inferred triples	drop_graph: inferred rows present (graph_id = 1); pass cascade => true to proceed
42704	The IRI is not a known graph	drop_graph: unknown iri "http://example.org/nope"
22023	The default graph, or a negative id	drop_graph: cannot drop default partition (graph_id = 0)
55P03	The graph is locked	pgrdf: graph 1 is locked (release review): drop_graph refused. Unlock with pgrdf.unlock_graph(1, '<reason>').

The full table is on Errors and diagnostics.

After a drop

• pgrdf.graph_id('<iri>') and pgrdf.graph_iri(<id>) return NULL.
• The graph no longer appears in pgrdf.graph_inventory().
• pgrdf.add_graph('<iri>') creates a new, empty graph under the same IRI.

See also

• Graph lifecycle — the four operations side by side.
• clear_graph — empty a graph but keep it.
• move_graph — move a graph's triples somewhere else and drop the source.