move_graph — move a graph into an empty graph

Move every triple of one graph into an empty destination, then drop the source. Returns the number of triples moved.

What it does

pgrdf.move_graph(src_iri TEXT, dst_iri TEXT) → BIGINT
pgrdf.move_graph(src BIGINT,   dst BIGINT)   → BIGINT

move_graph copies all of the source's triples, asserted and inferred, into the destination and then drops the source graph, IRI included. Both steps run in your transaction, so a ROLLBACK undoes both.

• The destination must be empty. A destination that holds any triples refuses with 55000 before anything is copied. An existing, empty graph is fine: one you just created with add_graph, or one you just cleared.
• By IRI, both graphs must exist. An unknown source or destination IRI refuses with 42704.
• By id, a missing destination is created and named urn:pgrdf:graph:<id>. Moving from an id that has no graph returns 0.
• Inferred triples come along. The destination's materialization reads unknown in graph_inventory() until you run materialize on it.
• Locked graphs refuse (55P03), whether the lock is on the source or the destination.
• The move copies rows, so its time grows with the size of the graph.

Why you'd use it

• Project managers — promote a staged version into production in one transaction.
• Data scientists — the last step of a stage → validate → publish pipeline, committed together with the rest of it.
• Ontologists — promote a working copy to the canonical IRI once its inferences and validation check out.
• Backend engineers — one SQL call with a well-defined refusal for the unsafe case (a destination that already holds data).

Example

Promote a staged ontology version into the production graph:

SELECT pgrdf.add_graph('http://example.org/ontology');           -- production
SELECT pgrdf.parse_turtle('
@prefix ex: <http://example.org/> .
ex:Widget ex:version "1" .
', pgrdf.graph_id('http://example.org/ontology'));
-- → 1

SELECT pgrdf.add_graph('http://example.org/ontology/staging');
SELECT pgrdf.parse_turtle('
@prefix ex: <http://example.org/> .
ex:Widget ex:version "2" .
ex:Gadget ex:version "2" .
', pgrdf.graph_id('http://example.org/ontology/staging'));
-- → 2

-- Moving into a graph that still holds data refuses:
SELECT pgrdf.move_graph('http://example.org/ontology/staging', 'http://example.org/ontology');
-- ERROR:  55000: move_graph: dst graph_id 1 already has data (1 rows); clear or drop it first

-- Clear production (it keeps its id and IRI), then move, atomically:
BEGIN;
SELECT pgrdf.clear_graph('http://example.org/ontology');
-- → 1
SELECT pgrdf.move_graph('http://example.org/ontology/staging', 'http://example.org/ontology');
-- → 2
COMMIT;

SELECT pgrdf.count_quads(pgrdf.graph_id('http://example.org/ontology'));
-- → 2
SELECT pgrdf.graph_id('http://example.org/ontology/staging');
-- → NULL   (the source graph is gone)

Clear the destination rather than dropping it: a dropped graph no longer exists, so a move to its IRI would refuse with 42704.

Refusals

SQLSTATE	When	Example message
55000	The destination already holds triples	move_graph: dst graph_id 1 already has data (1 rows); clear or drop it first
42704	The source or destination IRI is not a known graph	move_graph: unknown iri "http://example.org/nowhere"
22023	Source and destination are the same graph, or an id is negative	move_graph: src and dst must differ (both = 2)
55P03	The source or destination is locked	pgrdf: graph 1 is locked (release review): move_graph (source) 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.
• copy_graph — copy without removing the source.
• clear_graph — empty the destination before a move.