layers_clearUnload

Take a graph out of the database without losing it: package it as a canonical file plus a manifest that anyone can verify offline, then remove it. Typical cases: dropping a large source once you've carved your slice, archiving a finished result, or handing a graph to someone else.

How you run it

sql

pgrdf.export_graph(graph_id BIGINT)                         → SETOF TEXT
pgrdf.graph_manifest(graph_id BIGINT)                       → JSONB
pgrdf.drop_graph(iri TEXT | id BIGINT, cascade BOOLEAN DEFAULT true) → BIGINT
pgrdf.clear_graph(iri TEXT | id BIGINT)                     → BIGINT

export_graph returns the graph's asserted triples as canonical N-Triples, one triple per row, byte-sorted.
graph_manifest describes the graph and its export in one JSON document, including the SHA-256 of the exported bytes.
drop_graph removes the graph and its triples. clear_graph removes the triples but keeps the graph, empty, under the same IRI.

Step 1 — package

Write the content and the manifest to files. These commands use the Docker container from the install page; with a local server, drop the docker exec pgrdf prefix.

Q="pgrdf.graph_id('http://example.org/products')"

docker exec pgrdf psql -U postgres -Atc "SELECT * FROM pgrdf.export_graph($Q)" > products.nt
docker exec pgrdf psql -U postgres -Atc "SELECT pgrdf.graph_manifest($Q)"      > products.manifest.json

For the four-triple products graph from Seal, products.nt holds:

<http://example.org/gadget> <http://example.org/label> "Gadget" .
<http://example.org/gadget> <http://example.org/price> "25"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://example.org/widget> <http://example.org/label> "Widget" .
<http://example.org/widget> <http://example.org/price> "10"^^<http://www.w3.org/2001/XMLSchema#integer> .

Step 2 — verify, without a database

Anyone holding the two files can check that the content is intact:

sha256sum products.nt
# b397118cdba33a34831c8f376308f78a38a0b6336e206f3e60e09494d9b5d2de  products.nt

jq -r .digests.bytes.value products.manifest.json
# b397118cdba33a34831c8f376308f78a38a0b6336e206f3e60e09494d9b5d2de

The two hashes must match. On macOS without GNU coreutils, use shasum -a 256.

Step 3 — remove

sql

SELECT pgrdf.drop_graph('http://example.org/products');
-- → 4   (triples removed)

A sealed graph refuses to be dropped:

ERROR:  55P03: pgrdf: graph 1 is locked (release review): drop_graph refused.
        Unlock with pgrdf.unlock_graph(1, '<reason>').

Unlock it first, giving the reason:

sql

SELECT pgrdf.unlock_graph(pgrdf.graph_id('http://example.org/products'), 'packaged');
SELECT pgrdf.drop_graph('http://example.org/products');

Check it's gone:

sql

SELECT iri FROM pgrdf.graph_inventory();
--         iri
-- -------------------
--  urn:pgrdf:graph:0

Details:

Drop by IRI refuses an unknown IRI (42704), so a typo can't silently drop nothing.
cascade => false refuses when the graph holds inferred triples (2BP01). The default, cascade => true, removes them with it.
The default graph (0) can't be dropped (22023). Load data into named graphs you create with add_graph, so there's always a graph you can drop.
To empty a graph but keep its name, use clear_graph instead. It returns the number of triples removed and leaves an empty graph in the inventory.

Restoring

N-Triples is valid Turtle, so any loader reads the export back. Load it into a new graph and compare its identity digest with the manifest:

sql

SELECT pgrdf.load_turtle('/tmp/products.nt',
         pgrdf.add_graph('http://example.org/products-restored'));      -- → 4
SELECT pgrdf.graph_digest(pgrdf.graph_id('http://example.org/products-restored'));
-- → b397118cdba33a34831c8f376308f78a38a0b6336e206f3e60e09494d9b5d2de
--   equals digests.identity.value in products.manifest.json

The file has to be on the database server (docker cp products.nt pgrdf:/tmp/products.nt). Inferred triples, locks and materialization state are not carried: the manifest's not_carried list says so. Re-run materialize on the restored graph if you need its inferred triples. The full recipe is in Identity and export.

Where it sits in a chain

Last. Unload a graph once nothing in the chain needs it in the database: the source after Carve, or a result after Seal.

layers_clearUnload ​

How you run it ​

Step 1 — package ​

Step 2 — verify, without a database ​

Step 3 — remove ​

Restoring ​

Where it sits in a chain ​

See also ​