clear_graph — empty a graph in place

Remove every triple from a named graph but keep the graph itself: the same id, the same IRI, ready for the next load.

What it does

pgrdf.clear_graph(iri TEXT)  → BIGINT
pgrdf.clear_graph(id BIGINT) → BIGINT

Removes all of the graph's triples, asserted and inferred, and returns how many it removed. The graph keeps its id and IRI, so references to it by IRI (SPARQL GRAPH clauses, application config) keep working, and later loads go into the same graph.

Clearing empties the graph's storage partition in one step, so it is fast regardless of the graph's size.

• Reload = clear, then load. Loading the same data into a graph again adds it a second time; pgRDF does not remove duplicates on load. Clear first when you are replacing a graph's contents.
• Materialization goes stale. If the graph had been materialized, graph_inventory() reports materialization = stale after a clear until you run materialize again.
• The default graph can be cleared. Unlike drop_graph, clear_graph accepts graph 0.
• It is transactional. Wrap a clear and a reload in one transaction and a failed reload leaves the previous contents in place.
• Unknown input. Clearing an unknown IRI refuses (42704). Clearing by an id that has no graph returns 0.

Why you'd use it

• Project managers — periodic refresh cycles where the graph's identity stays fixed and its contents are recomputed each run.
• Data scientists — reset a working graph between experiments without breaking anything that refers to it by IRI.
• Ontologists — wipe an instance graph before loading a fresh snapshot, keeping the shapes graph and IRIs in place.
• Operators — emptying a graph is one partition-level operation, not a row-by-row delete.

Example

SELECT pgrdf.add_graph('http://example.org/feed');
SELECT pgrdf.parse_turtle('
@prefix ex: <http://example.org/> .
ex:gbp ex:rate "1.17" .
ex:usd ex:rate "1.09" .
', pgrdf.graph_id('http://example.org/feed'));
-- → 2

-- Replace the contents with the next feed, in one transaction.
BEGIN;
SELECT pgrdf.clear_graph('http://example.org/feed');
-- → 2
SELECT pgrdf.parse_turtle('
@prefix ex: <http://example.org/> .
ex:gbp ex:rate "1.18" .
ex:usd ex:rate "1.08" .
ex:jpy ex:rate "171.3" .
', pgrdf.graph_id('http://example.org/feed'));
-- → 3
COMMIT;

SELECT graph_id, iri, asserted
  FROM pgrdf.graph_inventory()
 WHERE iri = 'http://example.org/feed';
--  graph_id |           iri           | asserted
-- ----------+-------------------------+----------
--         1 | http://example.org/feed |        3

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

Refusals

SQLSTATE	When	Example message
42704	The IRI is not a known graph	clear_graph: unknown iri "http://example.org/nope"
22023	A negative id	clear_graph: graph_id must be >= 0, got -1
55P03	The graph is locked	pgrdf: graph 1 is locked (release review): clear_graph refused. Unlock with pgrdf.unlock_graph(1, '<reason>').

The full table is on Errors and diagnostics.

See also

• Graph lifecycle — the four operations side by side.
• drop_graph — remove the graph and its IRI too.
• Per-graph partitions.