docker compose up -d gets you a working pg_ripple instance in under a minute. No Rust compiler, no PostgreSQL development headers — just Docker.

• How to register prefixes and load Turtle data into pg_ripple
• How to write SPARQL queries with filters, aggregates, and graph traversals
• How data is organized as triples (subject–predicate–object)

• How to define data quality rules using SHACL shapes
• How to validate your knowledge graph and catch constraint violations
• How SHACL shapes act like CHECK constraints for graph data

• How to write Datalog rules that derive new facts from existing data
• How transitive inference works (if A connects to B and B connects to C, then A connects to C)
• How inference compares to SQL materialized views

• How to export your knowledge graph in Turtle and JSON-LD formats
• How SPARQL CONSTRUCT queries shape output for API consumers
• How JSON-LD framing produces nested, API-ready JSON documents

After large bulk loads, run ANALYZE on the internal tables to update PostgreSQL planner statistics:

SELECT pg_ripple.vacuum();

</div>
</div>

---

Gotchas and Debugging

IRI formatting: All IRIs must be wrapped in angle brackets (<...>) in function calls. Forgetting the brackets is the most common error:

-- WRONG: will be treated as a plain literal
SELECT pg_ripple.insert_triple(
    'https://example.org/paper/42',
    'http://purl.org/dc/terms/title',
    '"Hello"'
);

-- CORRECT: angle brackets around IRIs
SELECT pg_ripple.insert_triple(
    '<https://example.org/paper/42>',
    '<http://purl.org/dc/terms/title>',
    '"Hello"'
);

Blank node scoping: Blank nodes from separate load_turtle() calls are independent. Two calls using _:x create two different entities.

Literal quoting: Literals must be wrapped in double quotes within the single-quoted SQL string. Typed literals use ^^<datatype> suffix:

-- Plain string
'"Hello"'

-- Typed integer
'"42"^^<http://www.w3.org/2001/XMLSchema#integer>'

-- Language-tagged string
'"Bonjour"@fr'

Checking what is stored: Use find_triples() with wildcards to inspect data:

-- All triples about Paper 42
SELECT * FROM pg_ripple.find_triples(
    '<https://example.org/paper/42>', NULL, NULL
);

-- All triples with the dct:creator predicate
SELECT * FROM pg_ripple.find_triples(
    NULL, '<http://purl.org/dc/terms/creator>', NULL
);

-- Total triple count
SELECT pg_ripple.triple_count();

Duplicate triples: Inserting the same (s, p, o, g) twice is idempotent — the second insert returns the existing SID. Use deduplicate_all() to clean up historical duplicates.

---

Next Steps

• §2.2 Loading Data — bulk loading in all RDF formats with performance tuning.
• §2.3 Querying with SPARQL — query the triples you stored.
• §2.4 Validating Data Quality — enforce schema constraints with SHACL.

Further reading

• Blog: RDF-star — Statements About Statements — edge properties and provenance on triples
• Blog: Vertical Partitioning Explained — why pg_ripple stores one table per predicate

§2.2 Loading Data

What and Why

Getting data into pg_ripple is the first step in building a knowledge graph. pg_ripple supports every major RDF serialization format and offers three loading strategies tuned for different scenarios: inline string loading, server-side file loading, and single-triple insertion.

Choosing the right format and loading mode matters. A 10-million-triple dataset loaded via insert_triple() in a loop takes hours; the same dataset loaded from a server-side N-Triples file via load_ntriples_file() finishes in minutes.

---

How It Works

Supported Formats

Three Loading Modes

Mode 1: String loading — pass RDF text as a SQL string parameter. Best for small-to-medium datasets (up to a few MB) and interactive use:

SELECT pg_ripple.load_turtle('
@prefix ex: <https://example.org/> .
ex:paper/1 ex:title "Hello World" .
');

Mode 2: Server-side file loading — read from a file on the PostgreSQL server's filesystem. Best for large datasets. Requires superuser privileges:

SELECT pg_ripple.load_turtle_file('/data/papers.ttl');

Mode 3: Single-triple insertion — insert one triple at a time. Best for real-time ingestion from application code:

SELECT pg_ripple.insert_triple(
    '<https://example.org/paper/1>',
    '<https://example.org/title>',
    '"Hello World"'
);

The Loading Pipeline

Regardless of format, every loader follows the same internal pipeline:

1. Parse — deserialize the RDF serialization into (subject, predicate, object, graph) quads.
2. Encode — dictionary-encode each IRI, blank node, and literal to a BIGINT ID using batch ON CONFLICT DO NOTHING ... RETURNING.
3. Route — look up the predicate in _pg_ripple.predicates to find the target VP table (or vp_rare).
4. Insert — batch-insert encoded (s, o, g) rows into the appropriate VP delta table.

---

Worked Examples

Loading Turtle

The most common format for hand-authored data:

SELECT pg_ripple.load_turtle('
@prefix ex:    <https://example.org/> .
@prefix dct:   <http://purl.org/dc/terms/> .
@prefix foaf:  <http://xmlns.com/foaf/0.1/> .
@prefix bibo:  <http://purl.org/ontology/bibo/> .
@prefix schema: <https://schema.org/> .
@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .

ex:paper/42 a bibo:AcademicArticle ;
    dct:title "Knowledge Graphs in Practice"@en ;
    dct:creator ex:person/alice, ex:person/bob ;
    dct:date "2024-03-15"^^xsd:date ;
    bibo:citedBy ex:paper/99 ;
    schema:keywords "knowledge graph", "RDF", "SPARQL" .

ex:paper/99 a bibo:AcademicArticle ;
    dct:title "Graph Neural Networks for Entity Resolution" ;
    dct:creator ex:person/carol .

ex:person/alice foaf:name "Alice Johnson" ;
    schema:affiliation ex:institution/mit .

ex:person/bob foaf:name "Bob Smith" ;
    schema:affiliation ex:institution/stanford .

ex:person/carol foaf:name "Carol Williams" ;
    schema:affiliation ex:institution/mit .

ex:institution/mit foaf:name "Massachusetts Institute of Technology" .
ex:institution/stanford foaf:name "Stanford University" .
');

The function returns the number of triples loaded:

-- Returns: 15

Loading N-Triples

N-Triples is one triple per line with no abbreviations — optimal for machine-generated data:

SELECT pg_ripple.load_ntriples('
<https://example.org/paper/42> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://purl.org/ontology/bibo/AcademicArticle> .
<https://example.org/paper/42> <http://purl.org/dc/terms/title> "Knowledge Graphs in Practice" .
<https://example.org/paper/42> <http://purl.org/dc/terms/creator> <https://example.org/person/alice> .
<https://example.org/paper/42> <http://purl.org/dc/terms/creator> <https://example.org/person/bob> .
');

Loading N-Quads (with Named Graphs)

N-Quads extend N-Triples with a fourth field for the graph IRI:

SELECT pg_ripple.load_nquads('
<https://example.org/paper/42> <http://purl.org/dc/terms/title> "Knowledge Graphs in Practice" <https://example.org/graph/pubmed> .
<https://example.org/paper/99> <http://purl.org/dc/terms/title> "Graph Neural Networks" <https://example.org/graph/arxiv> .
<https://example.org/paper/42> <http://purl.org/dc/terms/creator> <https://example.org/person/alice> <https://example.org/graph/pubmed> .
');

Loading TriG (Turtle with Named Graphs)

TriG wraps Turtle blocks in GRAPH { } sections:

SELECT pg_ripple.load_trig('
@prefix ex:  <https://example.org/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix bibo: <http://purl.org/ontology/bibo/> .

GRAPH ex:graph/pubmed {
    ex:paper/100 a bibo:AcademicArticle ;
        dct:title "Drug Interaction Networks" ;
        dct:creator ex:person/dave .
}

GRAPH ex:graph/arxiv {
    ex:paper/200 a bibo:AcademicArticle ;
        dct:title "Transformer Architectures for NLP" ;
        dct:creator ex:person/eve .
}
');

Loading RDF/XML

The original XML serialization of RDF — common in older datasets and OWL ontologies:

SELECT pg_ripple.load_rdfxml('
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:dct="http://purl.org/dc/terms/"
         xmlns:bibo="http://purl.org/ontology/bibo/">
  <bibo:AcademicArticle rdf:about="https://example.org/paper/42">
    <dct:title>Knowledge Graphs in Practice</dct:title>
    <dct:creator rdf:resource="https://example.org/person/alice"/>
  </bibo:AcademicArticle>
</rdf:RDF>
');

Loading from Server-Side Files

For large datasets, server-side file loading avoids transferring data through the SQL protocol:

-- Load a large N-Triples dump (superuser required)
SELECT pg_ripple.load_ntriples_file('/data/exports/papers.nt');

-- Load Turtle with strict parsing (abort on any error)
SELECT pg_ripple.load_turtle_file('/data/exports/ontology.ttl', true);

-- Load into a specific named graph
SELECT pg_ripple.load_turtle_file_into_graph(
    '/data/exports/pubmed.ttl',
    'https://example.org/graph/pubmed'
);

Loading Turtle-Star (RDF-Star)

pg_ripple's Turtle parser supports RDF-star quoted triples natively:

SELECT pg_ripple.load_turtle('
@prefix ex:  <https://example.org/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<< ex:paper/42 ex:cites ex:paper/99 >> ex:confidence "0.92"^^xsd:decimal .
<< ex:paper/42 ex:cites ex:paper/99 >> ex:source ex:system/citation-extractor .
');

Loading into Named Graphs

Load data into a specific graph without the TriG/N-Quads format:

-- Create the graph first (optional — auto-created on load)
SELECT pg_ripple.create_graph('https://example.org/graph/2024');

-- Load Turtle into the named graph
SELECT pg_ripple.load_turtle_into_graph('
@prefix ex:  <https://example.org/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix bibo: <http://purl.org/ontology/bibo/> .

ex:paper/300 a bibo:AcademicArticle ;
    dct:title "New Findings in Graph Theory" ;
    dct:creator ex:person/frank .
', 'https://example.org/graph/2024');

Using SPARQL Update for Loading

SPARQL INSERT DATA is another way to add triples:

SELECT pg_ripple.sparql_update('
PREFIX ex:   <https://example.org/>
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX bibo: <http://purl.org/ontology/bibo/>

INSERT DATA {
    ex:paper/500 a bibo:AcademicArticle ;
        dct:title "SPARQL Performance Tuning" ;
        dct:creator ex:person/alice .
}
');

---

Common Patterns

Pattern: ETL Pipeline

A typical ETL pipeline loads data in stages:

-- Step 1: Load the ontology
SELECT pg_ripple.load_turtle_file('/data/ontology.ttl');

-- Step 2: Load reference data
SELECT pg_ripple.load_ntriples_file('/data/institutions.nt');

-- Step 3: Load the main dataset
SELECT pg_ripple.load_ntriples_file('/data/papers.nt');

-- Step 4: Load supplementary data into a named graph
SELECT pg_ripple.load_nquads_file('/data/citations.nq');

-- Step 5: Update statistics
SELECT pg_ripple.vacuum();

-- Step 6: Verify the load
SELECT pg_ripple.triple_count();
SELECT pg_ripple.stats();

Pattern: Incremental Loading

For streaming data ingestion, use insert_triple() inside application code:

-- Application inserts triples as events arrive
SELECT pg_ripple.insert_triple(
    '<https://example.org/paper/new123>',
    '<http://purl.org/dc/terms/title>',
    '"Just Published: A New Study"'
);

-- Periodically compact HTAP tables
SELECT pg_ripple.compact();

Pattern: Strict vs Lenient Parsing

-- Lenient (default): skip bad triples, emit WARNINGs
SELECT pg_ripple.load_turtle('
@prefix ex: <https://example.org/> .
ex:good ex:rel ex:target .
ex:bad ex:rel "unclosed literal .
ex:also_good ex:rel ex:other .
', false);
-- Returns: 2 (skipped the bad triple)

-- Strict: abort on any parse error
SELECT pg_ripple.load_turtle('
@prefix ex: <https://example.org/> .
ex:good ex:rel ex:target .
ex:bad ex:rel "unclosed literal .
', true);
-- ERROR: Turtle parse error at line 4

Pattern: Loading OWL Ontologies

-- Auto-detects format from file extension (.ttl, .nt, .xml, .rdf, .owl)
SELECT pg_ripple.load_owl_ontology('/data/ontologies/foaf.rdf');

-- Or load explicitly as RDF/XML
SELECT pg_ripple.load_rdfxml_file('/data/ontologies/dublin_core.rdf');

---

Performance and Trade-offs

Throughput by Loading Mode

Format Selection Guide

ANALYZE After Loads

After loading significant amounts of data, update PostgreSQL planner statistics:

-- Run ANALYZE on all VP tables
SELECT pg_ripple.vacuum();

This ensures the query planner has accurate row-count estimates for join ordering.

Batch Size Considerations

For string-based loaders, the entire input is processed in one transaction. Very large strings (hundreds of MB) can cause memory pressure. For datasets over 50 MB, prefer file-based loading:

-- Instead of a huge string literal:
-- SELECT pg_ripple.load_ntriples('... 100 million lines ...');

-- Use file loading:
SELECT pg_ripple.load_ntriples_file('/data/huge_dataset.nt');

---

Gotchas and Debugging

Blank Node Scoping

Each load_turtle() call creates a fresh blank-node scope. Two separate calls using _:x produce two different internal IDs:

-- Call 1: _:x maps to internal ID 12345
SELECT pg_ripple.load_turtle('
@prefix ex: <https://example.org/> .
_:x ex:name "Alice" .
ex:paper/1 ex:author _:x .
');

-- Call 2: _:x maps to internal ID 67890 (different!)
SELECT pg_ripple.load_turtle('
@prefix ex: <https://example.org/> .
_:x ex:name "Bob" .
ex:paper/2 ex:author _:x .
');

If you need the same anonymous node across loads, use a stable IRI instead:

SELECT pg_ripple.insert_triple(
    '<https://example.org/anon/shared-node>',
    '<https://example.org/name>',
    '"Shared Entity"'
);

Character Encoding

All loaders expect UTF-8 input. Non-UTF-8 data causes parse errors:

-- If your file is Latin-1, convert first:
-- iconv -f ISO-8859-1 -t UTF-8 data.nt > data_utf8.nt
SELECT pg_ripple.load_ntriples_file('/data/data_utf8.nt');

Verifying Loaded Data

After loading, verify with find_triples() or triple_count():

-- Check total triples
SELECT pg_ripple.triple_count();

-- Inspect specific triples
SELECT * FROM pg_ripple.find_triples(
    '<https://example.org/paper/42>', NULL, NULL
);

-- Check per-predicate statistics
SELECT pg_ripple.stats();

File Path Errors

File loaders read from the server filesystem. Common errors:

-- ERROR: could not open file "/data/papers.nt": No such file or directory
-- Fix: ensure the file exists and is readable by the postgres OS user

-- ERROR: permission denied for function load_turtle_file
-- Fix: file loaders require superuser; use string loaders for non-superusers

Duplicate Handling

Loading the same data twice does not create duplicates — VP tables use ON CONFLICT DO NOTHING:

SELECT pg_ripple.load_turtle('
@prefix ex: <https://example.org/> .
ex:a ex:rel ex:b .
');
-- Returns: 1

SELECT pg_ripple.load_turtle('
@prefix ex: <https://example.org/> .
ex:a ex:rel ex:b .
');
-- Returns: 0 (already exists)

---

Next Steps

• §2.1 Storing Knowledge — understand the triple model and named graphs.
• §2.3 Querying with SPARQL — query the data you loaded.
• §2.6 Exporting and Sharing — export data in various formats.

§2.3 Querying with SPARQL

What and Why

SPARQL is the W3C standard query language for RDF data — the SQL of the knowledge graph world. pg_ripple translates SPARQL queries into optimized PostgreSQL SQL behind the scenes, so you get the expressiveness of SPARQL with the performance of a mature relational engine.

Why SPARQL instead of raw SQL against VP tables?

• Graph pattern matching: find paths, cycles, and subgraph shapes naturally.
• Property paths: traverse variable-length relationships with +, *, ?.
• Federation: query remote SPARQL endpoints alongside local data.
• Standards compliance: queries are portable across triple stores.
• Update support: INSERT DATA and DELETE DATA for programmatic modifications.

pg_ripple supports all four SPARQL query forms (SELECT, CONSTRUCT, DESCRIBE, ASK) and SPARQL Update (INSERT DATA, DELETE DATA, DELETE/INSERT WHERE).

---

How It Works

The SPARQL Pipeline

1. Parse — spargebra parses the SPARQL text into an algebra tree.
2. Optimize — sparopt applies algebraic optimizations (filter pushdown, join reordering).
3. Translate — pg_ripple's SQL generator converts the algebra to PostgreSQL SQL with integer-only VP table joins.
4. Cache — the plan cache stores translated SQL keyed by SPARQL text hash.
5. Execute — SPI executes the SQL; results are batch-decoded from integer IDs back to IRIs and literals.
6. Return — each result row is returned as a JSONB object.

Key Functions

---

Worked Examples

All examples assume the bibliographic dataset from §2.1 and §2.2 has been loaded.

Basic Triple Patterns

Find all papers and their titles:

SELECT * FROM pg_ripple.sparql('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX bibo: <http://purl.org/ontology/bibo/>

SELECT ?paper ?title
WHERE {
    ?paper a bibo:AcademicArticle .
    ?paper dct:title ?title .
}
');

Each row is a JSONB object like {"paper": "<https://example.org/paper/42>", "title": "\"Knowledge Graphs in Practice\""}.

Filtering Results

Find papers published after 2023:

SELECT * FROM pg_ripple.sparql('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX bibo: <http://purl.org/ontology/bibo/>
PREFIX xsd:  <http://www.w3.org/2001/XMLSchema#>

SELECT ?paper ?title ?date
WHERE {
    ?paper a bibo:AcademicArticle ;
           dct:title ?title ;
           dct:date ?date .
    FILTER (?date > "2023-01-01"^^xsd:date)
}
');

OPTIONAL Patterns

Include authors even if they have no affiliation:

SELECT * FROM pg_ripple.sparql('
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX foaf:   <http://xmlns.com/foaf/0.1/>
PREFIX schema: <https://schema.org/>

SELECT ?paper ?authorName ?instName
WHERE {
    ?paper dct:creator ?author .
    ?author foaf:name ?authorName .
    OPTIONAL {
        ?author schema:affiliation ?inst .
        ?inst foaf:name ?instName .
    }
}
');

UNION

Find entities that are either papers or people:

SELECT * FROM pg_ripple.sparql('
PREFIX bibo: <http://purl.org/ontology/bibo/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX dct:  <http://purl.org/dc/terms/>

SELECT ?entity ?label
WHERE {
    {
        ?entity a bibo:AcademicArticle .
        ?entity dct:title ?label .
    }
    UNION
    {
        ?entity a foaf:Person .
        ?entity foaf:name ?label .
    }
}
');

MINUS

Find papers that have no citations:

SELECT * FROM pg_ripple.sparql('
PREFIX bibo: <http://purl.org/ontology/bibo/>
PREFIX dct:  <http://purl.org/dc/terms/>

SELECT ?paper ?title
WHERE {
    ?paper a bibo:AcademicArticle ;
           dct:title ?title .
    MINUS {
        ?paper bibo:citedBy ?other .
    }
}
');

Aggregation

Count papers per institution:

SELECT * FROM pg_ripple.sparql('
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX schema: <https://schema.org/>
PREFIX foaf:   <http://xmlns.com/foaf/0.1/>

SELECT ?instName (COUNT(DISTINCT ?paper) AS ?paperCount)
WHERE {
    ?paper dct:creator ?author .
    ?author schema:affiliation ?inst .
    ?inst foaf:name ?instName .
}
GROUP BY ?instName
ORDER BY DESC(?paperCount)
');

Subqueries

Find the most prolific author and all their papers:

SELECT * FROM pg_ripple.sparql('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>

SELECT ?authorName ?paper ?title
WHERE {
    {
        SELECT ?author (COUNT(?p) AS ?count)
        WHERE {
            ?p dct:creator ?author .
        }
        GROUP BY ?author
        ORDER BY DESC(?count)
        LIMIT 1
    }
    ?author foaf:name ?authorName .
    ?paper dct:creator ?author ;
           dct:title ?title .
}
');

Property Paths

Property paths let you traverse variable-length relationships.

Transitive closure (+) — find all classes an entity belongs to through the subclass hierarchy:

SELECT * FROM pg_ripple.sparql('
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

SELECT ?entity ?superClass
WHERE {
    ?entity rdf:type/rdfs:subClassOf+ ?superClass .
}
');

Zero-or-more (*) — include the starting node:

SELECT * FROM pg_ripple.sparql('
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?class ?ancestor
WHERE {
    ?class rdfs:subClassOf* ?ancestor .
}
');

Optional step (?) — zero or one hops:

SELECT * FROM pg_ripple.sparql('
PREFIX schema: <https://schema.org/>
PREFIX foaf:   <http://xmlns.com/foaf/0.1/>

SELECT ?person ?nameOrInst
WHERE {
    ?person schema:affiliation? ?target .
    ?target foaf:name ?nameOrInst .
}
');

Sequence path (/) — chain properties:

SELECT * FROM pg_ripple.sparql('
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX schema: <https://schema.org/>
PREFIX foaf:   <http://xmlns.com/foaf/0.1/>

SELECT ?paper ?instName
WHERE {
    ?paper dct:creator/schema:affiliation/foaf:name ?instName .
}
');

Alternative path (|) — match either property:

SELECT * FROM pg_ripple.sparql('
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX schema: <https://schema.org/>

SELECT ?entity ?label
WHERE {
    ?entity (dct:title | schema:name) ?label .
}
');

Inverse path (^) — traverse in reverse:

SELECT * FROM pg_ripple.sparql('
PREFIX dct: <http://purl.org/dc/terms/>

SELECT ?author ?paper
WHERE {
    ?author ^dct:creator ?paper .
}
');

GRAPH Patterns

Query data in specific named graphs:

SELECT * FROM pg_ripple.sparql('
PREFIX dct: <http://purl.org/dc/terms/>

SELECT ?paper ?title ?graph
WHERE {
    GRAPH ?graph {
        ?paper dct:title ?title .
    }
}
');

Query a specific named graph:

SELECT * FROM pg_ripple.sparql('
PREFIX dct: <http://purl.org/dc/terms/>

SELECT ?paper ?title
WHERE {
    GRAPH <https://example.org/graph/pubmed> {
        ?paper dct:title ?title .
    }
}
');

ASK Queries

Check if something exists:

SELECT pg_ripple.sparql_ask('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX bibo: <http://purl.org/ontology/bibo/>

ASK {
    ?paper a bibo:AcademicArticle ;
           dct:title "Knowledge Graphs in Practice" .
}
');
-- Returns: true

CONSTRUCT Queries

Build new triples from query results:

SELECT * FROM pg_ripple.sparql_construct('
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX schema: <https://schema.org/>
PREFIX foaf:   <http://xmlns.com/foaf/0.1/>
PREFIX ex:     <https://example.org/>

CONSTRUCT {
    ?author ex:worksOn ?paper .
    ?paper ex:authoredAt ?inst .
}
WHERE {
    ?paper dct:creator ?author .
    ?author schema:affiliation ?inst .
}
');

Get CONSTRUCT results as Turtle:

SELECT pg_ripple.sparql_construct_turtle('
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX foaf:   <http://xmlns.com/foaf/0.1/>
PREFIX ex:     <https://example.org/>

CONSTRUCT {
    ?author ex:wrote ?paper .
}
WHERE {
    ?paper dct:creator ?author .
}
');

Get CONSTRUCT results as JSON-LD:

SELECT pg_ripple.sparql_construct_jsonld('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX ex:   <https://example.org/>

CONSTRUCT {
    ?author ex:wrote ?paper .
}
WHERE {
    ?paper dct:creator ?author .
}
');

DESCRIBE Queries

Get everything about an entity using Concise Bounded Description:

SELECT * FROM pg_ripple.sparql_describe('
DESCRIBE <https://example.org/paper/42>
');

Get the description as Turtle:

SELECT pg_ripple.sparql_describe_turtle('
DESCRIBE <https://example.org/person/alice>
');

Choose the describe strategy:

-- Symmetric CBD: include triples where the entity is the object too
SELECT * FROM pg_ripple.sparql_describe(
    'DESCRIBE <https://example.org/person/alice>',
    'scbd'
);

SPARQL Update

Insert new triples:

SELECT pg_ripple.sparql_update('
PREFIX ex:  <https://example.org/>
PREFIX dct: <http://purl.org/dc/terms/>

INSERT DATA {
    ex:paper/600 a <http://purl.org/ontology/bibo/AcademicArticle> ;
        dct:title "Emerging Trends in Knowledge Graphs" ;
        dct:creator ex:person/alice .
}
');
-- Returns: 3

Delete specific triples:

SELECT pg_ripple.sparql_update('
PREFIX ex:  <https://example.org/>
PREFIX dct: <http://purl.org/dc/terms/>

DELETE DATA {
    ex:paper/600 dct:title "Emerging Trends in Knowledge Graphs" .
}
');
-- Returns: 1

Query Debugging with EXPLAIN

View the generated SQL without executing:

SELECT pg_ripple.sparql_explain('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX bibo: <http://purl.org/ontology/bibo/>

SELECT ?paper ?title
WHERE {
    ?paper a bibo:AcademicArticle ;
           dct:title ?title .
}
', false);

Run EXPLAIN ANALYZE to see execution times:

SELECT pg_ripple.sparql_explain('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX bibo: <http://purl.org/ontology/bibo/>

SELECT ?paper ?title
WHERE {
    ?paper a bibo:AcademicArticle ;
           dct:title ?title .
}
', true);

Use the extended explain with format options:

-- Show just the generated SQL
SELECT pg_ripple.explain_sparql('
PREFIX dct: <http://purl.org/dc/terms/>
SELECT ?paper ?title
WHERE { ?paper dct:title ?title }
', 'sql');

-- Show EXPLAIN ANALYZE as JSON (for programmatic consumption)
SELECT pg_ripple.explain_sparql('
PREFIX dct: <http://purl.org/dc/terms/>
SELECT ?paper ?title
WHERE { ?paper dct:title ?title }
', 'json');

-- Show the spargebra algebra tree
SELECT pg_ripple.explain_sparql('
PREFIX dct: <http://purl.org/dc/terms/>
SELECT ?paper ?title
WHERE { ?paper dct:title ?title }
', 'sparql_algebra');

---

Common Patterns

Pattern: Star Queries (Multiple Predicates on the Same Subject)

The optimizer detects star patterns and collapses them into efficient multi-way joins:

SELECT * FROM pg_ripple.sparql('
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX schema: <https://schema.org/>
PREFIX bibo:   <http://purl.org/ontology/bibo/>

SELECT ?paper ?title ?date
WHERE {
    ?paper a bibo:AcademicArticle ;
           dct:title ?title ;
           dct:date ?date ;
           schema:keywords ?kw .
    FILTER (CONTAINS(?kw, "knowledge"))
}
');

Pattern: Existence Checks with FILTER EXISTS

SELECT * FROM pg_ripple.sparql('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX bibo: <http://purl.org/ontology/bibo/>

SELECT ?paper ?title
WHERE {
    ?paper a bibo:AcademicArticle ;
           dct:title ?title .
    FILTER EXISTS {
        ?paper bibo:citedBy ?other .
    }
}
');

Pattern: VALUES Clause for Parameterized Queries

SELECT * FROM pg_ripple.sparql('
PREFIX dct: <http://purl.org/dc/terms/>

SELECT ?paper ?title
WHERE {
    VALUES ?paper {
        <https://example.org/paper/42>
        <https://example.org/paper/99>
    }
    ?paper dct:title ?title .
}
');

Pattern: BIND and Computed Values

SELECT * FROM pg_ripple.sparql('
PREFIX dct: <http://purl.org/dc/terms/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

SELECT ?paper ?title ?yearLabel
WHERE {
    ?paper dct:title ?title ;
           dct:date ?date .
    BIND(YEAR(?date) AS ?year)
    BIND(CONCAT("Published in ", STR(?year)) AS ?yearLabel)
}
');

---

Performance and Trade-offs

Plan Cache

pg_ripple caches translated SQL by SPARQL query hash. Repeated queries skip the parse and translate steps:

-- Check cache statistics
SELECT pg_ripple.plan_cache_stats();
-- Returns: {"hits": 42, "misses": 5, "size": 5, "capacity": 128, "hit_rate": 0.89}

-- Reset the cache (e.g., after schema changes)
SELECT pg_ripple.plan_cache_reset();

Filter Pushdown

SPARQL FILTERs on bound constants are encoded to integers before SQL generation. This means the database compares integers, not strings:

-- This FILTER is pushed down as an integer comparison:
SELECT * FROM pg_ripple.sparql('
PREFIX dct: <http://purl.org/dc/terms/>
SELECT ?paper WHERE {
    ?paper dct:creator <https://example.org/person/alice> .
}
');

Property Path Depth Limit

Recursive property paths (+, *) compile to WITH RECURSIVE ... CYCLE. The GUC pg_ripple.max_path_depth (default: 50) prevents runaway recursion:

-- Increase depth for deep hierarchies
SET pg_ripple.max_path_depth = 100;

Full-Text Search Integration

Create a GIN index for fast text search on specific predicates:

-- Index the dct:title predicate for full-text search
SELECT pg_ripple.fts_index('<http://purl.org/dc/terms/title>');

-- Then CONTAINS() and REGEX() filters on dct:title objects use the GIN index
SELECT * FROM pg_ripple.sparql('
PREFIX dct: <http://purl.org/dc/terms/>
SELECT ?paper ?title
WHERE {
    ?paper dct:title ?title .
    FILTER (CONTAINS(?title, "Knowledge"))
}
');

Or use the direct full-text search function:

SELECT * FROM pg_ripple.fts_search(
    'knowledge & graph',
    '<http://purl.org/dc/terms/title>'
);

---

Gotchas and Debugging

SPARQL Syntax Errors

pg_ripple uses the spargebra parser, which gives precise error messages:

SELECT * FROM pg_ripple.sparql('
SELECT ?x WHERE { ?x ?p }
');
-- ERROR: SPARQL parse error: Expected '.' or '}' at line 2

Check the query compiles before running:

SELECT pg_ripple.explain_sparql('
PREFIX dct: <http://purl.org/dc/terms/>
SELECT ?paper WHERE { ?paper dct:title ?title }
', 'sql');

No Results When Expected

Common causes:

1. Missing angle brackets: dct:title in SPARQL requires a PREFIX declaration. Without it, the parser treats it as a relative IRI.
2. Wrong literal format: "42" is a string, not a number. Use "42"^^xsd:integer.
3. Case sensitivity: IRIs are case-sensitive. <https://Example.org/X> and <https://example.org/x> are different.

Debug by checking what is stored:

-- Check if the predicate exists
SELECT * FROM pg_ripple.find_triples(
    NULL, '<http://purl.org/dc/terms/title>', NULL
);

Slow Queries

1. Check the generated SQL with sparql_explain().
2. Look for sequential scans on large VP tables — run pg_ripple.vacuum() to update statistics.
3. For property paths, check max_path_depth — lower it if the query is exploring too many paths.
4. Check the plan cache hit rate — a low hit rate means many unique queries are being parsed repeatedly.

-- Step 1: See the execution plan
SELECT pg_ripple.sparql_explain('
PREFIX dct: <http://purl.org/dc/terms/>
SELECT ?paper ?title
WHERE { ?paper dct:title ?title }
', true);

-- Step 2: Update statistics
SELECT pg_ripple.vacuum();

-- Step 3: Check plan cache
SELECT pg_ripple.plan_cache_stats();

SPARQL Update Limitations

sparql_update() supports INSERT DATA and DELETE DATA (ground triples only). Pattern-based DELETE/INSERT WHERE with variables is also supported for flexible graph modifications. Use delete_triple() for programmatic single-triple deletion.

---

Next Steps

• §2.4 Validating Data Quality — enforce constraints on your data with SHACL.
• §2.5 Reasoning and Inference — derive new facts with Datalog rules.
• §2.8 APIs and Integration — access SPARQL from application code via the HTTP endpoint.

Further reading

• Blog: SPARQL-to-SQL Translation — how pg_ripple compiles SPARQL into optimized PostgreSQL SQL
• Blog: Property Paths and Recursive CTEs — the implementation of * and + path operators
• Blog: Explain SPARQL Query Plans — understanding the SPARQL query debugger

§2.4 Validating Data Quality

Status: Available since v0.3.0 (SHACL-01)
Requires: No external dependencies.
SQL: pg_ripple.load_shacl_shapes(), pg_ripple.validate_shapes(), pg_ripple.list_shacl_violations()

---

What and Why

Storing knowledge is only half the battle — you also need to ensure it is correct. SHACL (Shapes Constraint Language) is the W3C standard for declaring and validating constraints on RDF data. It answers questions like:

• Does every paper have at least one author?
• Are all email addresses syntactically valid?
• Does every person have exactly one name?
• Are date values well-formed?

pg_ripple integrates SHACL validation directly into the database engine. You can validate on demand, enforce constraints synchronously on every insert, or queue triples for asynchronous background validation with violations routed to a dead-letter queue.

---

How It Works

The SHACL Model

A SHACL shape declares constraints on a set of focus nodes (entities matching a target pattern). Each shape contains one or more property shapes that constrain the values of a specific predicate.

NodeShape (target: instances of bibo:AcademicArticle)
  └─ PropertyShape (path: dct:title)
       ├─ sh:minCount 1     ← every paper must have at least one title
       ├─ sh:maxCount 1     ← at most one title
       └─ sh:datatype xsd:string  ← title must be a string

Validation Modes

Supported Constraints

---

Worked Examples

Loading Simple Shapes

Define shapes for the bibliographic dataset:

SELECT pg_ripple.load_shacl('
@prefix sh:     <http://www.w3.org/ns/shacl#> .
@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .
@prefix ex:     <https://example.org/> .
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix bibo:   <http://purl.org/ontology/bibo/> .
@prefix foaf:   <http://xmlns.com/foaf/0.1/> .
@prefix schema: <https://schema.org/> .

ex:PaperShape a sh:NodeShape ;
    sh:targetClass bibo:AcademicArticle ;
    sh:property [
        sh:path dct:title ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
        sh:datatype xsd:string ;
    ] ;
    sh:property [
        sh:path dct:creator ;
        sh:minCount 1 ;
        sh:class foaf:Person ;
    ] .

ex:PersonShape a sh:NodeShape ;
    sh:targetClass foaf:Person ;
    sh:property [
        sh:path foaf:name ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
        sh:datatype xsd:string ;
    ] ;
    sh:property [
        sh:path schema:affiliation ;
        sh:maxCount 1 ;
        sh:nodeKind sh:IRI ;
    ] .
');
-- Returns: 2 (number of shapes loaded)

Running Validation

Validate the default graph against all active shapes:

SELECT pg_ripple.validate();

The result is a JSONB validation report:

{
  "conforms": false,
  "violations": [
    {
      "focusNode": "<https://example.org/paper/99>",
      "shapeIRI": "<https://example.org/PaperShape>",
      "path": "<http://purl.org/dc/terms/creator>",
      "constraint": "sh:class",
      "message": "value <https://example.org/person/carol> is not an instance of <http://xmlns.com/foaf/0.1/Person>",
      "severity": "sh:Violation"
    }
  ]
}

Validate a specific named graph:

SELECT pg_ripple.validate('https://example.org/graph/pubmed');

Validate all graphs at once:

SELECT pg_ripple.validate('*');

Synchronous Validation

Enable sync mode so invalid triples are rejected at insert time:

SET pg_ripple.shacl_mode = 'sync';

-- This succeeds (paper has a title)
SELECT pg_ripple.insert_triple(
    '<https://example.org/paper/700>',
    '<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>',
    '<http://purl.org/ontology/bibo/AcademicArticle>'
);

-- This would fail if the shape requires dct:title and the paper doesn't have one yet
-- (sync validation checks per-triple, not transactionally)

Asynchronous Validation with Dead-Letter Queue

Enable async mode for high-throughput pipelines:

SET pg_ripple.shacl_mode = 'async';

-- Triples are inserted immediately; validation happens in the background
SELECT pg_ripple.insert_triple(
    '<https://example.org/paper/800>',
    '<http://purl.org/dc/terms/title>',
    '"A New Paper"'
);

-- Check the validation queue length
SELECT pg_ripple.validation_queue_length();

-- Manually process the queue (normally handled by background worker)
SELECT pg_ripple.process_validation_queue(1000);

-- Check for violations
SELECT pg_ripple.dead_letter_count();

-- View the full dead-letter queue
SELECT pg_ripple.dead_letter_queue();

Complex Shapes

Disjunctive constraints (sh:or):

SELECT pg_ripple.load_shacl('
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix ex:   <https://example.org/> .
@prefix dct:  <http://purl.org/dc/terms/> .

ex:DateShape a sh:NodeShape ;
    sh:targetSubjectsOf dct:date ;
    sh:property [
        sh:path dct:date ;
        sh:or (
            [ sh:datatype xsd:date ]
            [ sh:datatype xsd:gYear ]
            [ sh:datatype xsd:dateTime ]
        ) ;
    ] .
');

Closed shapes (reject unknown predicates):

SELECT pg_ripple.load_shacl('
@prefix sh:     <http://www.w3.org/ns/shacl#> .
@prefix ex:     <https://example.org/> .
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix bibo:   <http://purl.org/ontology/bibo/> .
@prefix schema: <https://schema.org/> .

ex:StrictPaperShape a sh:NodeShape ;
    sh:targetClass bibo:AcademicArticle ;
    sh:closed true ;
    sh:ignoredProperties (
        <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
    ) ;
    sh:property [
        sh:path dct:title ;
        sh:minCount 1 ;
    ] ;
    sh:property [
        sh:path dct:creator ;
        sh:minCount 1 ;
    ] ;
    sh:property [
        sh:path dct:date ;
        sh:maxCount 1 ;
    ] ;
    sh:property [
        sh:path schema:keywords ;
    ] ;
    sh:property [
        sh:path bibo:cites ;
    ] ;
    sh:property [
        sh:path bibo:citedBy ;
    ] .
');

Qualified cardinality:

SELECT pg_ripple.load_shacl('
@prefix sh:     <http://www.w3.org/ns/shacl#> .
@prefix ex:     <https://example.org/> .
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix bibo:   <http://purl.org/ontology/bibo/> .
@prefix foaf:   <http://xmlns.com/foaf/0.1/> .

ex:CollabPaperShape a sh:NodeShape ;
    sh:targetClass bibo:AcademicArticle ;
    sh:property [
        sh:path dct:creator ;
        sh:qualifiedValueShape [
            sh:class foaf:Person ;
        ] ;
        sh:qualifiedMinCount 2 ;
    ] .
');

Managing Shapes

-- List all loaded shapes
SELECT * FROM pg_ripple.list_shapes();

-- Deactivate a shape without deleting it
SELECT pg_ripple.disable_rule_set('custom');

-- Remove a shape entirely
SELECT pg_ripple.drop_shape('https://example.org/StrictPaperShape');

SHACL DAG Monitors

For real-time violation detection, enable DAG monitors (requires pg_trickle):

-- Load shapes first
SELECT pg_ripple.load_shacl('...');

-- Enable per-shape violation stream tables
SELECT pg_ripple.enable_shacl_dag_monitors();

-- View the live violation summary
SELECT * FROM _pg_ripple.violation_summary_dag;

-- List active monitors
SELECT * FROM pg_ripple.list_shacl_dag_monitors();

-- Disable when no longer needed
SELECT pg_ripple.disable_shacl_dag_monitors();

---

Common Patterns

Pattern: Validate After Bulk Load

The most common workflow — load first, validate second:

-- Turn off validation during load
SET pg_ripple.shacl_mode = 'off';

-- Load data
SELECT pg_ripple.load_turtle_file('/data/papers.ttl');

-- Load shapes
SELECT pg_ripple.load_shacl('...');

-- Validate
SELECT pg_ripple.validate();

Pattern: Data Quality Dashboard

Use the dead-letter queue as a data quality monitor:

-- Enable async validation
SET pg_ripple.shacl_mode = 'async';

-- Periodically check violation counts
SELECT pg_ripple.dead_letter_count();

-- Get violation details
SELECT pg_ripple.dead_letter_queue();

-- With pg_trickle: enable violation summary stream table
SELECT pg_ripple.enable_shacl_monitors();
SELECT * FROM _pg_ripple.violation_summary;

Pattern: Embedding Completeness Check

Ensure all entities have vector embeddings (see §2.7):

SELECT pg_ripple.load_shacl('
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix ex:   <https://example.org/> .
@prefix pg:   <urn:pg_ripple:> .
@prefix bibo: <http://purl.org/ontology/bibo/> .

ex:EmbeddingCompletenessShape a sh:NodeShape ;
    sh:targetClass bibo:AcademicArticle ;
    sh:property [
        sh:path pg:hasEmbedding ;
        sh:minCount 1 ;
        sh:hasValue "true"^^xsd:boolean ;
    ] .
');

-- Add embedding triples for entities that have been embedded
SELECT pg_ripple.add_embedding_triples();

-- Check completeness
SELECT pg_ripple.validate();

Pattern: Multi-Language Support

Ensure labels exist in required languages:

SELECT pg_ripple.load_shacl('
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix ex:   <https://example.org/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

ex:LabelShape a sh:NodeShape ;
    sh:targetSubjectsOf rdfs:label ;
    sh:property [
        sh:path rdfs:label ;
        sh:languageIn ( "en" "de" "fr" ) ;
        sh:uniqueLang true ;
    ] .
');

---

Performance and Trade-offs

• Shape count: validation time scales linearly with the number of active shapes and focus nodes. Deactivate shapes you do not need.
• DAG monitors: per-shape stream tables are IMMEDIATE mode — violations are detected within the same transaction. But pg_trickle must be installed.
• Dead-letter queue: grows without bound. Periodically review and clean it:

  -- Remove violations older than 30 days
  DELETE FROM _pg_ripple.dead_letter_queue
  WHERE detected_at < NOW() - INTERVAL '30 days';
  

---

Gotchas and Debugging

Shape Loading Errors

If load_shacl() returns 0, the Turtle may have syntax errors. Check for:

• Missing @prefix declarations
• Unclosed brackets in blank node property lists
• Missing semicolons between property shapes

Sync Mode and Transaction Boundaries

Sync validation checks individual triples, not entire transactions. A paper might pass the dct:creator check (because the triple being inserted is the author link) but fail the dct:title check because the title has not been inserted yet in the same transaction.

Solution: insert all triples for an entity, then validate explicitly:

SET pg_ripple.shacl_mode = 'off';

-- Insert all triples for the entity
SELECT pg_ripple.insert_triple('<https://example.org/paper/900>', '<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>', '<http://purl.org/ontology/bibo/AcademicArticle>');
SELECT pg_ripple.insert_triple('<https://example.org/paper/900>', '<http://purl.org/dc/terms/title>', '"My Paper"');
SELECT pg_ripple.insert_triple('<https://example.org/paper/900>', '<http://purl.org/dc/terms/creator>', '<https://example.org/person/alice>');

-- Then validate
SELECT pg_ripple.validate();

Viewing Shape Definitions

-- List all shapes and their active status
SELECT * FROM pg_ripple.list_shapes();

Validation Report Interpretation

The validation report JSONB has two top-level keys:

• conforms: true if no violations were found
• violations: array of violation objects, each with focusNode, shapeIRI, path, constraint, message, and severity

-- Extract just the violation messages
SELECT v->>'message'
FROM jsonb_array_elements(
    (SELECT pg_ripple.validate()::jsonb -> 'violations')
) AS v;

---

Next Steps

• §2.5 Reasoning and Inference — derive new facts from rules; SHACL shapes interact with inference.
• §2.6 Exporting and Sharing — SHACL quality enforcement for GraphRAG exports.
• §2.7 AI Retrieval and GraphRAG — embedding completeness shapes.

Further reading

• Blog: SHACL Data Quality — a deep dive into how SHACL shapes protect your data

§2.5 Reasoning and Inference

Status: Available since v0.6.0 (RULE-01)
Requires: No external dependencies. Rule sets are compiled to SQL by the Datalog engine.
SQL: pg_ripple.add_rule(), pg_ripple.run_inference(), pg_ripple.enable_builtin_rules()

---

What and Why

Inference lets pg_ripple derive new facts from existing data using logical rules. If Alice works at MIT and MIT is located in Massachusetts, inference can conclude that Alice is located in Massachusetts — without anyone explicitly inserting that triple.

pg_ripple ships a full Datalog reasoning engine that supports:

• Built-in rule sets: RDFS and OWL RL entailment out of the box.
• Custom rules: domain-specific inference in a Turtle-flavoured Datalog syntax.
• Stratified negation: "flag people without an email address."
• Aggregation: COUNT, SUM, MIN, MAX, AVG over grouped triple patterns.
• Magic sets: goal-directed inference that only materialises relevant facts.
• Semi-naive evaluation: efficient fixpoint iteration that skips unchanged rows.
• Well-Founded Semantics: handle programs with cyclic negation (v0.32.0).

Derived triples are stored with source = 1 (inferred) alongside explicit triples (source = 0), so you can always distinguish asserted from derived facts.

---

How It Works

The Datalog Pipeline

1. Parse — rules are parsed from a Turtle-flavoured Datalog syntax into an internal Rule IR.
2. Stratify — the dependency graph is analyzed; rules are grouped into strata such that negated predicates are fully computed in lower strata.
3. Compile — each stratum is compiled to PostgreSQL SQL: non-recursive rules become INSERT ... SELECT, recursive rules become WITH RECURSIVE ... CYCLE.
4. Execute — strata run bottom-up; each stratum's SQL is executed via SPI, inserting derived triples into VP delta tables.
5. Fixpoint — recursive strata iterate until no new facts are derived (semi-naive evaluation).

Rule Syntax

Rules use a Prolog-like notation with RDF terms. The prefix registry from register_prefix() is available:

head_triple :- body_triple1 , body_triple2 .

Variables start with ?. Constants are IRIs (prefixed or full). Negation uses NOT.

Built-in Rule Sets

---

Worked Examples

Loading Built-in RDFS Rules

-- Load the RDFS entailment rules
SELECT pg_ripple.load_rules_builtin('rdfs');
-- Returns: 12 (number of rules)

-- Load some class hierarchy data
SELECT pg_ripple.load_turtle('
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix bibo: <http://purl.org/ontology/bibo/> .
@prefix ex:   <https://example.org/> .

bibo:AcademicArticle rdfs:subClassOf bibo:Article .
bibo:Article rdfs:subClassOf bibo:Document .
bibo:Document rdfs:subClassOf rdfs:Resource .

ex:paper/42 rdf:type bibo:AcademicArticle .
');

-- Run inference
SELECT pg_ripple.infer('rdfs');

-- Now ex:paper/42 is also a bibo:Article, bibo:Document, and rdfs:Resource
SELECT * FROM pg_ripple.sparql('
PREFIX rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX bibo: <http://purl.org/ontology/bibo/>

SELECT ?type
WHERE {
    <https://example.org/paper/42> rdf:type ?type .
}
');

Loading OWL RL Rules

-- Load the OWL RL entailment rules
SELECT pg_ripple.load_rules_builtin('owl-rl');

-- Load ontology with OWL constructs
SELECT pg_ripple.load_turtle('
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix ex:   <https://example.org/> .

ex:cites owl:inverseOf ex:citedBy .
ex:collaboratesWith a owl:SymmetricProperty .
ex:influencedBy a owl:TransitiveProperty .

ex:paper/42 ex:cites ex:paper/99 .
ex:person/alice ex:collaboratesWith ex:person/bob .
ex:person/carol ex:influencedBy ex:person/alice .
ex:person/alice ex:influencedBy ex:person/dave .
');

-- Run OWL RL inference
SELECT pg_ripple.infer('owl-rl');

-- Derived: ex:paper/99 ex:citedBy ex:paper/42  (inverse)
-- Derived: ex:person/bob ex:collaboratesWith ex:person/alice  (symmetric)
-- Derived: ex:person/carol ex:influencedBy ex:person/dave  (transitive)

Writing Custom Rules

Define domain-specific rules for the bibliographic dataset:

SELECT pg_ripple.load_rules('
# Derive co-authorship: two people who authored the same paper
?a ex:coAuthor ?b :- ?paper dct:creator ?a , ?paper dct:creator ?b .

# Derive institutional collaboration
?inst1 ex:collaboratesWith ?inst2 :-
    ?paper dct:creator ?a ,
    ?paper dct:creator ?b ,
    ?a schema:affiliation ?inst1 ,
    ?b schema:affiliation ?inst2 .

# Derive prolific author (authored 5+ papers)
# Uses arithmetic guard: at least 5 papers
?author ex:isProlific "true"^^xsd:boolean :-
    ?paper1 dct:creator ?author ,
    ?paper2 dct:creator ?author ,
    ?paper3 dct:creator ?author ,
    ?paper4 dct:creator ?author ,
    ?paper5 dct:creator ?author .
', 'biblio');

-- Run the custom rule set
SELECT pg_ripple.infer('biblio');

Negation-as-Failure

Flag entities that are missing expected properties:

SELECT pg_ripple.load_rules('
# Flag papers without a date
?paper ex:missingDate "true"^^xsd:boolean :-
    ?paper rdf:type bibo:AcademicArticle ,
    NOT ?paper dct:date ?_ .

# Flag people without an affiliation
?person ex:missingAffiliation "true"^^xsd:boolean :-
    ?person rdf:type foaf:Person ,
    NOT ?person schema:affiliation ?_ .
', 'quality');

SELECT pg_ripple.infer('quality');

-- Query the derived quality flags
SELECT * FROM pg_ripple.sparql('
PREFIX ex: <https://example.org/>
SELECT ?paper WHERE { ?paper ex:missingDate "true"^^<http://www.w3.org/2001/XMLSchema#boolean> }
');

Named Graph Scoping

Write derived triples into a separate graph:

SELECT pg_ripple.load_rules('
# All RDFS inference goes into the "inferred" graph
GRAPH ex:graph/inferred { ?x rdf:type ?c } :-
    ?x rdf:type ?b , ?b rdfs:subClassOf ?c .
', 'scoped-rdfs');

SELECT pg_ripple.infer('scoped-rdfs');

-- Query only inferred types
SELECT * FROM pg_ripple.sparql('
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
SELECT ?x ?type WHERE {
    GRAPH <https://example.org/graph/inferred> {
        ?x rdf:type ?type .
    }
}
');

Semi-Naive Evaluation with Statistics

Get detailed inference statistics:

SELECT pg_ripple.infer_with_stats('rdfs');

Returns JSONB:

{
  "derived": 156,
  "iterations": 4,
  "eliminated_rules": [
    "?x rdf:type rdfs:Resource :- ?x ?p ?o ."
  ]
}

The eliminated_rules field shows rules removed by subsumption checking — rules whose body is a superset of another rule's body.

Goal-Directed Inference with Magic Sets

When you only need a subset of derived facts, magic sets avoids materialising everything:

-- Only derive facts relevant to: "What types does paper/42 have?"
SELECT pg_ripple.infer_goal('rdfs', '?x rdf:type <http://xmlns.com/foaf/0.1/Person>');

Returns JSONB:

{
  "derived": 12,
  "iterations": 3,
  "matching": 5
}

Compare with full inference:

-- Full materialization: derives ALL facts
SELECT pg_ripple.infer('rdfs');
-- derived: 156

-- Goal-directed: derives only what's needed for the goal
SELECT pg_ripple.infer_goal('rdfs', '?x rdf:type foaf:Person');
-- derived: 12 (much fewer)

Demand-Filtered Inference

For multiple goals at once, use demand-filtered inference:

SELECT pg_ripple.infer_demand('rdfs', '[
    {"p": "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"},
    {"s": "<https://example.org/paper/42>"}
]'::jsonb);

Returns:

{
  "derived": 45,
  "iterations": 3,
  "demand_predicates": [
    "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
  ]
}

Aggregate Rules (Datalog^agg)

Derive facts using aggregate functions:

SELECT pg_ripple.load_rules('
# Count papers per author
?author ex:paperCount ?count :-
    COUNT(?paper WHERE ?paper dct:creator ?author) = ?count .

# Sum citation counts per paper
?paper ex:totalCitations ?total :-
    COUNT(?citing WHERE ?citing bibo:cites ?paper) = ?total .
', 'metrics');

-- Use the aggregate-aware inference function
SELECT pg_ripple.infer_agg('metrics');

Returns:

{
  "derived": 25,
  "aggregate_derived": 25,
  "iterations": 1
}

Well-Founded Semantics (v0.32.0)

For programs with cyclic negation (where standard stratification fails):

SELECT pg_ripple.load_rules('
# Cyclic negation: a node is "in" if it is not "out", and vice versa
?x ex:in "true"^^xsd:boolean :- ?x rdf:type ex:Node , NOT ?x ex:out "true"^^xsd:boolean .
?x ex:out "true"^^xsd:boolean :- ?x rdf:type ex:Node , NOT ?x ex:in "true"^^xsd:boolean .
', 'wfs-demo');

-- Standard infer() would fail with "unstratifiable" error
-- WFS handles it gracefully
SELECT pg_ripple.infer_wfs('wfs-demo');

Returns:

{
  "derived": 6,
  "certain": 0,
  "unknown": 6,
  "iterations": 3,
  "stratifiable": false
}

Facts with certainty = 'unknown' are reported but NOT materialised into VP tables.

---

Common Patterns

Pattern: Layered Inference

Run rule sets in order — base entailment first, then domain rules:

-- Layer 1: RDFS entailment
SELECT pg_ripple.load_rules_builtin('rdfs');
SELECT pg_ripple.infer('rdfs');

-- Layer 2: OWL RL (builds on RDFS-derived facts)
SELECT pg_ripple.load_rules_builtin('owl-rl');
SELECT pg_ripple.infer('owl-rl');

-- Layer 3: Custom domain rules
SELECT pg_ripple.load_rules('...', 'domain');
SELECT pg_ripple.infer('domain');

Pattern: Incremental Re-Inference

After adding new data, re-run inference. Semi-naive evaluation only derives new facts:

-- Load new data
SELECT pg_ripple.load_turtle('
@prefix ex:  <https://example.org/> .
@prefix bibo: <http://purl.org/ontology/bibo/> .
ex:paper/newOne a bibo:AcademicArticle .
');

-- Re-run inference — only new derivations are computed
SELECT pg_ripple.infer_with_stats('rdfs');

Pattern: Explicit vs Inferred Triples

All VP tables have a source column: 0 = explicit, 1 = inferred. You can query this distinction via SPARQL or check the full triple store:

-- Find all inferred type assertions
SELECT * FROM pg_ripple.find_triples(
    NULL,
    '<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>',
    NULL
);

Pattern: owl:sameAs Canonicalization

When pg_ripple.sameas_reasoning = 'on' (default), owl:sameAs links are canonicalized before inference. All mentions of equivalent entities are collapsed to a single canonical ID, reducing redundant derivations.

-- Two IRIs refer to the same entity
SELECT pg_ripple.insert_triple(
    '<https://example.org/person/alice>',
    '<http://www.w3.org/2002/07/owl#sameAs>',
    '<https://other.org/people/a-johnson>'
);

-- After inference, both IRIs are treated as identical
SELECT pg_ripple.infer('owl-rl');

---

Performance and Trade-offs

Full Materialization vs Goal-Directed

Semi-Naive Evaluation

Semi-naive evaluation tracks which facts are new in each iteration and only joins new facts with existing facts. This reduces the work per iteration from O(n^2) to O(n * delta), where delta is the number of new facts per round.

Subsumption Checking

When two rules have the same head and one rule's body is a subset of the other's, the subsumed rule is eliminated. This reduces the number of SQL statements per iteration.

Tabling / Memoisation (v0.32.0)

Goal-directed inference results and WFS results are cached in _pg_ripple.tabling_cache. Cache entries are automatically invalidated when data changes (inserts or deletes).

-- Check tabling cache statistics
SELECT * FROM pg_ripple.tabling_stats();

Rule Set Management

-- List all rules and their metadata
SELECT pg_ripple.list_rules();

-- Enable/disable a rule set without deleting it
SELECT pg_ripple.enable_rule_set('rdfs');
SELECT pg_ripple.disable_rule_set('quality');

-- Drop all rules in a set
SELECT pg_ripple.drop_rules('quality');

---

Gotchas and Debugging

Unstratifiable Programs

If your rules contain cyclic negation, standard infer() will fail:

ERROR: unstratifiable rule set — negation cycle detected
DETAIL: ex:in negates ex:out, which depends on ex:in
HINT: remove the negation cycle or use infer_wfs() for well-founded semantics

Fix: either restructure the rules to eliminate the cycle, or use infer_wfs().

Prefix Registration

Rules use the prefix registry from register_prefix(). If a prefix is not registered, the parser treats it as a parse error:

-- Register required prefixes BEFORE loading rules
SELECT pg_ripple.register_prefix('ex', 'https://example.org/');
SELECT pg_ripple.register_prefix('dct', 'http://purl.org/dc/terms/');

-- Now load rules that use these prefixes
SELECT pg_ripple.load_rules('?x ex:rel ?y :- ?x dct:creator ?y .', 'test');

Checking What Was Derived

After inference, check the statistics:

-- How many triples total?
SELECT pg_ripple.triple_count();

-- Detailed stats including inferred count
SELECT pg_ripple.stats();

-- Check constraint rules for violations
SELECT pg_ripple.check_constraints();

Performance Diagnosis

If inference is slow:

1. Check iteration count with infer_with_stats() — many iterations suggest deep recursive chains.
2. Use goal-directed inference (infer_goal()) if you only need a subset.
3. Check for redundant rules with subsumption (eliminated_rules in stats output).
4. Run pg_ripple.vacuum() after inference to update planner statistics.

-- Get inference diagnostics
SELECT pg_ripple.infer_with_stats('rdfs');

-- Check rule plan cache
SELECT * FROM pg_ripple.rule_plan_cache_stats();

---

Next Steps

• §2.4 Validating Data Quality — SHACL shapes interact with inference; validate derived facts.
• §2.6 Exporting and Sharing — export inferred facts; Datalog enrichment for GraphRAG.
• §2.3 Querying with SPARQL — query both explicit and inferred facts with SPARQL.

Further reading

• Blog: Datalog Inside PostgreSQL — how the Datalog engine works under the hood
• Blog: Built-in Reasoning Rules Explained — the RDFS and OWL RL rule sets
• Blog: Magic Sets for Goal-Directed Inference — how demand-driven evaluation speeds up queries
• Blog: Well-Founded Semantics — handling negation in cyclic rules

§2.6 Exporting and Sharing

What and Why

Data in pg_ripple needs to flow out — to other systems, to files for archival, to LLMs for RAG pipelines, or to Microsoft's GraphRAG framework via Parquet files. pg_ripple supports all standard RDF serialization formats plus JSON-LD framing for API-ready output and BYOG (Bring Your Own Graph) Parquet export for GraphRAG.

This chapter is the canonical reference for all export functionality, including the GraphRAG BYOG pipeline. Other chapters cross-reference here for GraphRAG details.

---

How It Works

Export Formats

Streaming Exports

For large graphs, streaming exports return one row per triple (or per subject for JSON-LD), avoiding buffering the entire document in memory:

-- Stream Turtle one line at a time
SELECT * FROM pg_ripple.export_turtle_stream();

-- Stream JSON-LD one subject at a time (NDJSON)
SELECT * FROM pg_ripple.export_jsonld_stream();

JSON-LD Framing

JSON-LD framing reshapes flat RDF into nested, application-friendly JSON. A frame is a JSON template that specifies the desired structure:

1. pg_ripple translates the frame to a SPARQL CONSTRUCT query.
2. The CONSTRUCT query executes against the triple store.
3. The W3C embedding algorithm nests matched nodes per the frame.
4. The result is compacted with the frame's @context.

---

Worked Examples

Exporting as N-Triples

The simplest format — one triple per line:

-- Export the default graph
SELECT pg_ripple.export_ntriples(NULL);

Output:

<https://example.org/paper/42> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://purl.org/ontology/bibo/AcademicArticle> .
<https://example.org/paper/42> <http://purl.org/dc/terms/title> "Knowledge Graphs in Practice" .
<https://example.org/paper/42> <http://purl.org/dc/terms/creator> <https://example.org/person/alice> .

Export a specific named graph:

SELECT pg_ripple.export_ntriples('https://example.org/graph/pubmed');

Exporting as N-Quads

N-Quads include the graph IRI for each triple:

-- Export all graphs (pass NULL)
SELECT pg_ripple.export_nquads(NULL);

Exporting as Turtle

Compact, human-readable output with prefix declarations:

SELECT pg_ripple.export_turtle();

Output:

@prefix ex: <https://example.org/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix bibo: <http://purl.org/ontology/bibo/> .

ex:paper/42 a bibo:AcademicArticle ;
    dct:title "Knowledge Graphs in Practice" ;
    dct:creator ex:person/alice, ex:person/bob .

Exporting as JSON-LD

SELECT pg_ripple.export_jsonld();

Returns a JSONB array of expanded node objects:

[
  {
    "@id": "https://example.org/paper/42",
    "@type": ["http://purl.org/ontology/bibo/AcademicArticle"],
    "http://purl.org/dc/terms/title": [{"@value": "Knowledge Graphs in Practice"}],
    "http://purl.org/dc/terms/creator": [
      {"@id": "https://example.org/person/alice"},
      {"@id": "https://example.org/person/bob"}
    ]
  }
]

JSON-LD Framing

Shape the output into the exact JSON structure your application expects:

SELECT pg_ripple.export_jsonld_framed('{
    "@context": {
        "dct": "http://purl.org/dc/terms/",
        "foaf": "http://xmlns.com/foaf/0.1/",
        "bibo": "http://purl.org/ontology/bibo/",
        "schema": "https://schema.org/",
        "title": "dct:title",
        "creator": "dct:creator",
        "name": "foaf:name",
        "affiliation": "schema:affiliation"
    },
    "@type": "bibo:AcademicArticle",
    "creator": {
        "name": {},
        "affiliation": {
            "name": {}
        }
    }
}'::jsonb);

Returns nested JSON-LD:

{
  "@context": {"dct": "http://purl.org/dc/terms/", "...": "..."},
  "@graph": [
    {
      "@type": "bibo:AcademicArticle",
      "title": "Knowledge Graphs in Practice",
      "creator": [
        {
          "name": "Alice Johnson",
          "affiliation": {
            "name": "Massachusetts Institute of Technology"
          }
        },
        {
          "name": "Bob Smith",
          "affiliation": {
            "name": "Stanford University"
          }
        }
      ]
    }
  ]
}

Debugging Frames

See the generated SPARQL CONSTRUCT without executing:

SELECT pg_ripple.jsonld_frame_to_sparql('{
    "@context": {
        "dct": "http://purl.org/dc/terms/",
        "bibo": "http://purl.org/ontology/bibo/",
        "title": "dct:title"
    },
    "@type": "bibo:AcademicArticle",
    "title": {}
}'::jsonb);

CONSTRUCT-Based Exports

Use SPARQL CONSTRUCT for selective, transformed exports:

-- Export a citation graph as Turtle
SELECT pg_ripple.sparql_construct_turtle('
PREFIX bibo: <http://purl.org/ontology/bibo/>
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX ex:   <https://example.org/>

CONSTRUCT {
    ?paper ex:cites ?cited .
    ?paper dct:title ?title .
    ?cited dct:title ?citedTitle .
}
WHERE {
    ?paper bibo:cites ?cited ;
           dct:title ?title .
    ?cited dct:title ?citedTitle .
}
');

-- Same as JSON-LD for REST APIs
SELECT pg_ripple.sparql_construct_jsonld('
PREFIX bibo: <http://purl.org/ontology/bibo/>
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX ex:   <https://example.org/>

CONSTRUCT {
    ?paper ex:cites ?cited .
    ?paper dct:title ?title .
}
WHERE {
    ?paper bibo:cites ?cited ;
           dct:title ?title .
}
');

DESCRIBE-Based Exports

Export everything about specific entities:

-- Full description as Turtle
SELECT pg_ripple.sparql_describe_turtle('
DESCRIBE <https://example.org/paper/42>
');

-- Symmetric CBD (includes incoming links)
SELECT pg_ripple.sparql_describe_turtle(
    'DESCRIBE <https://example.org/person/alice>',
    'scbd'
);

-- As JSON-LD
SELECT pg_ripple.sparql_describe_jsonld(
    'DESCRIBE <https://example.org/paper/42>'
);

---

GraphRAG BYOG Pipeline

pg_ripple is the canonical source for Microsoft GraphRAG's Bring Your Own Graph (BYOG) data. The pipeline uses three export functions to produce Parquet files compatible with GraphRAG's ingestion format.

Step 1: Model Entities and Relationships

GraphRAG requires entities, relationships, and text units modeled with the gr: prefix. Load the GraphRAG ontology:

SELECT pg_ripple.load_turtle('
@prefix gr:   <urn:graphrag:> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix ex:   <https://example.org/> .

# Entity: a paper
ex:paper/42 a gr:Entity ;
    gr:title "Knowledge Graphs in Practice" ;
    gr:type "AcademicArticle" ;
    gr:description "A comprehensive survey of knowledge graph technologies and applications." ;
    gr:frequency 5 ;
    gr:degree 3 .

# Entity: an author
ex:person/alice a gr:Entity ;
    gr:title "Alice Johnson" ;
    gr:type "Person" ;
    gr:description "Researcher at MIT specializing in knowledge representation." ;
    gr:frequency 8 ;
    gr:degree 5 .

# Relationship
ex:rel/1 a gr:Relationship ;
    gr:source ex:paper/42 ;
    gr:target ex:person/alice ;
    gr:description "authored by" ;
    gr:weight "1.0"^^xsd:float ;
    gr:combinedDegree 8 .

# Text unit
ex:text/1 a gr:TextUnit ;
    gr:text "This paper surveys knowledge graph technologies..." ;
    gr:nTokens 150 ;
    gr:documentId "doc-001" .
');

Step 2: Enrich with Datalog Rules

Use Datalog rules to derive additional GraphRAG metadata:

SELECT pg_ripple.load_rules('
# Derive entity frequency from triple count
?e gr:frequency ?count :-
    ?e rdf:type gr:Entity ,
    COUNT(?t WHERE ?t ?anyPred ?e) = ?count .

# Derive relationship combined degree
?r gr:combinedDegree ?deg :-
    ?r rdf:type gr:Relationship ,
    ?r gr:source ?s ,
    ?r gr:target ?t ,
    COUNT(?p1 WHERE ?s ?p1 ?_) = ?sDeg ,
    COUNT(?p2 WHERE ?t ?p2 ?_) = ?tDeg .
', 'graphrag-enrichment');

SELECT pg_ripple.infer_agg('graphrag-enrichment');

Step 3: Validate with SHACL

Ensure data quality before export:

SELECT pg_ripple.load_shacl('
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix gr:   <urn:graphrag:> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

<urn:graphrag:EntityShape> a sh:NodeShape ;
    sh:targetClass gr:Entity ;
    sh:property [
        sh:path gr:title ;
        sh:minCount 1 ;
        sh:datatype xsd:string ;
    ] ;
    sh:property [
        sh:path gr:type ;
        sh:minCount 1 ;
    ] .

<urn:graphrag:RelationshipShape> a sh:NodeShape ;
    sh:targetClass gr:Relationship ;
    sh:property [
        sh:path gr:source ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
    ] ;
    sh:property [
        sh:path gr:target ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
    ] .
');

-- Validate before export
SELECT pg_ripple.validate();

Step 4: Export to Parquet

-- Export entities (requires superuser)
SELECT pg_ripple.export_graphrag_entities('', '/data/graphrag/entities.parquet');

-- Export relationships
SELECT pg_ripple.export_graphrag_relationships('', '/data/graphrag/relationships.parquet');

-- Export text units
SELECT pg_ripple.export_graphrag_text_units('', '/data/graphrag/text_units.parquet');

Each function returns the number of rows written. The Parquet files are directly compatible with pyarrow.parquet.read_table() and GraphRAG's BYOG configuration:

# GraphRAG settings.yaml
entity_table_path: /data/graphrag/entities.parquet
relationship_table_path: /data/graphrag/relationships.parquet
text_unit_table_path: /data/graphrag/text_units.parquet

Step 5: Export from a Named Graph

For multi-tenant or versioned exports:

-- Export only entities from the "production" graph
SELECT pg_ripple.export_graphrag_entities(
    'https://example.org/graph/production',
    '/data/graphrag/prod_entities.parquet'
);

SELECT pg_ripple.export_graphrag_relationships(
    'https://example.org/graph/production',
    '/data/graphrag/prod_relationships.parquet'
);

SELECT pg_ripple.export_graphrag_text_units(
    'https://example.org/graph/production',
    '/data/graphrag/prod_text_units.parquet'
);

---

Common Patterns

Pattern: API Response Formatting

Use JSON-LD framing to produce API-ready responses:

-- Papers endpoint: nested JSON with authors
SELECT pg_ripple.export_jsonld_framed('{
    "@context": {
        "title": "http://purl.org/dc/terms/title",
        "creator": "http://purl.org/dc/terms/creator",
        "name": "http://xmlns.com/foaf/0.1/name",
        "type": "@type"
    },
    "@type": "http://purl.org/ontology/bibo/AcademicArticle",
    "creator": { "name": {} }
}'::jsonb);

Pattern: Scheduled Exports via CONSTRUCT Views

For continuously updated exports, create a CONSTRUCT view (requires pg_trickle):

SELECT pg_ripple.create_construct_view(
    'citation_graph',
    'PREFIX bibo: <http://purl.org/ontology/bibo/>
     PREFIX dct: <http://purl.org/dc/terms/>
     CONSTRUCT { ?p bibo:cites ?c . ?p dct:title ?t . }
     WHERE { ?p bibo:cites ?c ; dct:title ?t }',
    '30s',
    true
);

-- The view is automatically refreshed every 30 seconds
SELECT * FROM pg_ripple.construct_view_citation_graph_decoded;

Pattern: Streaming Export to File

For large graphs, use COPY with streaming exports:

COPY (SELECT * FROM pg_ripple.export_turtle_stream())
TO '/data/export/full_graph.ttl';

COPY (SELECT * FROM pg_ripple.export_jsonld_stream())
TO '/data/export/full_graph.ndjson';

Pattern: Selective Export with SPARQL

Export only a subset of the graph:

-- Export only papers from 2024
SELECT pg_ripple.sparql_construct_turtle('
PREFIX dct:  <http://purl.org/dc/terms/>
PREFIX bibo: <http://purl.org/ontology/bibo/>
PREFIX xsd:  <http://www.w3.org/2001/XMLSchema#>

CONSTRUCT { ?paper ?p ?o }
WHERE {
    ?paper a bibo:AcademicArticle ;
           dct:date ?date ;
           ?p ?o .
    FILTER (?date >= "2024-01-01"^^xsd:date)
}
');

---

Performance and Trade-offs

Buffered vs Streaming Exports

Parquet Export Performance

GraphRAG Parquet export scans the relevant VP tables once per entity type. Performance depends on the number of gr:Entity, gr:Relationship, and gr:TextUnit nodes:

• ~100K entities: <5 seconds
• ~1M entities: ~30 seconds
• Write path requires superuser (writes to server filesystem)

JSON-LD Framing Cost

Framing involves executing a SPARQL CONSTRUCT query, then applying the W3C embedding algorithm. The cost is dominated by the CONSTRUCT query; the embedding step is linear in the number of matched nodes.

---

Gotchas and Debugging

Empty Parquet Files

If export_graphrag_entities() returns 0, check that your data uses the correct gr: prefix and that entities have rdf:type gr:Entity:

SELECT * FROM pg_ripple.find_triples(
    NULL,
    '<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>',
    '<urn:graphrag:Entity>'
);

Framing Returns Empty Result

Ensure the frame's @type matches actual rdf:type values in the store. The type must be a full IRI, not a prefixed name:

-- Check what types exist
SELECT * FROM pg_ripple.sparql('
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
SELECT DISTINCT ?type WHERE { ?x rdf:type ?type }
');

Server-Side File Permissions

Parquet export writes to the server filesystem. Ensure the postgres OS user has write permission to the output directory:

sudo mkdir -p /data/graphrag
sudo chown postgres:postgres /data/graphrag

Large Export Memory

For graphs with millions of triples, buffered exports (export_turtle(), export_jsonld()) may use significant memory. Switch to streaming variants or COPY ... TO with streaming.

---

Next Steps

• §2.7 AI Retrieval and GraphRAG — vector embeddings and RAG retrieval pipelines.
• §2.8 APIs and Integration — serve exported data via the HTTP endpoint.
• §2.3 Querying with SPARQL — CONSTRUCT and DESCRIBE queries for selective export.

Further reading

• Blog: JSON-LD Framing for Nested JSON — shaping graph data into API-ready JSON documents

Live Views and Subscriptions

Status: Live views available since v0.12.0; CDC subscriptions available since v0.42.0
See also: Live SPARQL Subscriptions · CDC Subscriptions

---

Two features cover the push side of pg_ripple — getting data out as it changes, instead of polling for it.

If you want a snapshot of what is true now, use a view. If you want a stream of what changed since I last looked, use CDC.

---

Materialized SPARQL and Datalog views

A SPARQL view compiles a SPARQL SELECT (or a Datalog goal) into a pg_trickle stream table that is incrementally maintained as triples change. The view always reflects the latest data without you running the query yourself.

Requires the optional pg_trickle extension. pg_ripple loads and runs without it; view functions detect its absence at call time and return a clear error with an install hint.

-- Check availability before using.
SELECT pg_ripple.pg_trickle_available();   -- true / false

-- Create a view of all people and their names, refreshed every second.
-- The stream table stores BIGINT dictionary IDs for IVM correctness.
SELECT pg_ripple.create_sparql_view(
    name     := 'people_names',
    sparql   := 'SELECT ?p ?name WHERE { ?p <http://xmlns.com/foaf/0.1/name> ?name }',
    schedule := '1s',
    decode   := true   -- also creates pg_ripple.people_names_decoded with TEXT columns
);

-- Query the raw BIGINT view.
SELECT * FROM pg_ripple.people_names;

-- Or use the auto-created decoded companion view for human-readable TEXT output.
SELECT * FROM pg_ripple.people_names_decoded;

-- Drop when you are done (also drops the _decoded companion view if present).
SELECT pg_ripple.drop_sparql_view('people_names');

The decode flag controls whether a _{name}_decoded companion VIEW is created on top of the stream table. The stream table itself always stores raw BIGINT dictionary IDs — this keeps pg_trickle's incremental view maintenance (IVM) working correctly, since IVM diffs rows using the integer columns of the underlying VP tables. When decode = true, a thin SQL VIEW named {name}_decoded is created alongside the stream table; it performs the dictionary lookups at read time and exposes TEXT columns. This is the same pattern used by create_construct_view.

You can build the same kind of view from a Datalog goal:

SELECT pg_ripple.create_datalog_view(
    name     := 'indirect_managers',
    goal     := '?x <https://example.org/indirectManager> ?y',
    schedule := '5s'
);

These views integrate with the materialised inference pipeline — the view stays correct after infer(), retract_rule(), and clear_graph().

---

CDC subscriptions

A subscription publishes a JSON message on a named PostgreSQL NOTIFY channel every time a triple is inserted or deleted that matches a SPARQL filter. Listeners receive changes with no polling.

Available since v0.42.0.

Create

-- Subscribe to all changes.
SELECT pg_ripple.create_subscription('all_changes');

-- Subscribe with a SPARQL pattern filter.
SELECT pg_ripple.create_subscription(
    'person_changes',
    filter_sparql := 'SELECT ?s ?p ?o WHERE { ?s a <https://schema.org/Person> ; ?p ?o }'
);

-- Subscribe with a SHACL-shape filter — only triples that *violate* the shape are published.
SELECT pg_ripple.create_subscription(
    'shape_violations',
    filter_shape := '<https://shapes.example.org/PersonShape>'
);

Listen

LISTEN pg_ripple_cdc_person_changes;

In your application (Python, Node.js, Go, …) connect, issue the same LISTEN, and read the notification stream:

import psycopg
import json

with psycopg.connect("...") as conn:
    conn.set_isolation_level(0)  # AUTOCOMMIT
    with conn.cursor() as cur:
        cur.execute("LISTEN pg_ripple_cdc_person_changes;")
    for notify in conn.notifies():
        event = json.loads(notify.payload)
        print(event["op"], event["s"], event["p"], event["o"])

Payload

{
  "op": "add",
  "s": "<https://example.org/alice>",
  "p": "<https://schema.org/name>",
  "o": "\"Alice\"",
  "g": ""
}

Manage

SELECT name, has_filter, created_at FROM pg_ripple.list_subscriptions();
SELECT pg_ripple.drop_subscription('person_changes');

WebSocket access via pg_ripple_http

When the pg_ripple_http companion service is running, every subscription is automatically exposed as a WebSocket endpoint:

ws://<host>:8080/ws/subscriptions/{name}

The HTTP service handles backpressure, reconnection, and authentication — you point a browser-side EventSource or a server-side stream consumer at the URL.

Lifecycle telemetry

The _pg_ripple.cdc_lifecycle_events table records every subscription create / drop / error, with timestamps. Useful for alerting on dropped subscriptions in production.

---

Choosing between views and subscriptions

The two compose: build a view of what is currently true, and a subscription of what just changed, and let your application choose per use case.

---

See also

• APIs and Integration — pg_ripple_http and WebSocket access.
• Cookbook: CDC → Kafka via JSON-LD outbox

Further reading

• Blog: CONSTRUCT Views — Live Transformations — incremental materialization of SPARQL views
• Blog: IVM with pg-trickle Integration — how pg_ripple keeps views up to date

Geospatial Queries (GeoSPARQL)

Status: Available since v0.36.0 (GEO-01)
Requires: PostGIS extension (CREATE EXTENSION postgis). Without PostGIS, loading succeeds but geof: filter functions return NULL.
SQL: pg_ripple.sparql_select() with geof: and geo: FILTER functions
Degraded: GeoSPARQL filter functions silently return NULL when PostGIS is absent — enable PostGIS before ingesting WKT data.

---

pg_ripple implements the GeoSPARQL 1.1 query function vocabulary for geographic data, delegating geometry computation to PostGIS. You store WKT literals as triple objects, and SPARQL filter functions like geof:sfWithin and geof:sfIntersects resolve them against PostGIS at query time — without any extra schema work on your part.

---

What you get

All of these compile to PostGIS function calls in the generated SQL. You inherit PostGIS's spatial index support automatically when you register a geometry index on the relevant VP table.

---

Storing geometries

Geometries live as Well-Known Text (WKT) literals on a geometry predicate of your choice. The conventional predicate is locn:geometry:

SELECT pg_ripple.load_turtle($TTL$
@prefix ex:   <https://example.org/> .
@prefix locn: <https://www.w3.org/ns/locn#> .

ex:berlin   locn:geometry "POINT(13.404954 52.520008)" .
ex:munich   locn:geometry "POINT(11.5820  48.1351)" .
ex:bavaria  locn:geometry "POLYGON((9.0 47.0, 13.8 47.0, 13.8 50.6, 9.0 50.6, 9.0 47.0))" .
$TTL$);

For better performance, create a PostGIS geometry index on the VP table for locn:geometry (one-time, per predicate):

SELECT pg_ripple.create_spatial_index('<https://www.w3.org/ns/locn#geometry>');

---

Querying

Find every point inside a polygon

PREFIX geof: <http://www.opengis.net/def/function/geosparql/>
PREFIX locn: <https://www.w3.org/ns/locn#>

SELECT ?city WHERE {
    ?city locn:geometry ?g .
    FILTER(geof:sfWithin(?g,
        "POLYGON((9.0 47.0, 13.8 47.0, 13.8 50.6, 9.0 50.6, 9.0 47.0))"))
}

Distance-bounded nearest-neighbour

SELECT ?city ?d WHERE {
    ?city locn:geometry ?g .
    BIND(geof:distance(?g, "POINT(11.5820 48.1351)") AS ?d)
    FILTER(?d < 200000)        # within 200 km of Munich
}
ORDER BY ?d

Buffer + intersect (constructive)

SELECT ?city WHERE {
    ?city locn:geometry ?g .
    FILTER(geof:sfIntersects(?g,
        geof:buffer("POINT(11.5820 48.1351)", 50000)))   # 50 km around Munich
}

---

Coordinate reference systems

GeoSPARQL literals can carry a CRS as an IRI suffix:

ex:berlin locn:geometry
    "<http://www.opengis.net/def/crs/EPSG/0/4326> POINT(13.4049 52.5200)" .

When the CRS is omitted, pg_ripple uses WGS84 (EPSG:4326) as the default. This matches the GeoSPARQL 1.1 default.

---

What is not implemented

• Egenhofer (geof:eh*) and RCC8 (geof:rcc8*) topological functions are not yet wired up.
• The gml:Geometry literal datatype is not parsed (only geo:wktLiteral).
• DE-9IM matrix queries are not exposed.

If you need any of these, file an issue — most are a thin wrapper over the corresponding PostGIS function.

---

See also

• GeoSPARQL function catalog
• PostGIS documentation

Further reading

• Blog: GeoSPARQL + PostGIS Spatial Queries — combining geographic and semantic queries

Full-Text Search

Sometimes the right query against a knowledge graph is not "find the entity with this exact label" but "find any entity whose label, description, or notes mention these words". pg_ripple uses PostgreSQL's built-in full-text search machinery — tsvector, tsquery, GIN indexes — for this, exposed both as a SQL function and as a SPARQL filter.

---

Setup

Full-text indexing is opt-in per predicate. Tell pg_ripple which literal-valued predicates are searchable:

SELECT pg_ripple.create_fts_index(
    predicate := '<http://www.w3.org/2000/01/rdf-schema#label>',
    config    := 'english'
);

SELECT pg_ripple.create_fts_index('<http://purl.org/dc/elements/1.1/title>',  'english');
SELECT pg_ripple.create_fts_index('<https://schema.org/description>',          'english');

Behind the scenes pg_ripple maintains a generated tsvector column on the relevant VP table and a GIN index over it. Inserts and updates flow through automatically.

The config parameter is any PostgreSQL text-search configuration name (english, simple, spanish, …). Use simple for languages whose stemmer you do not have, or for proper-noun-heavy data.

---

Searching from SQL

-- All subjects whose label matches the query.
SELECT * FROM pg_ripple.fts_search(
    predicate := '<http://www.w3.org/2000/01/rdf-schema#label>',
    query     := 'machine & learning'
);

The query argument follows PostgreSQL tsquery syntax: & for AND, | for OR, ! for NOT, <-> for adjacency. See the PostgreSQL FTS documentation.

---

Searching from SPARQL

The pg:fts() SPARQL filter function returns true when an entity's literal value matches the tsquery. It composes naturally with other graph patterns:

PREFIX pg:    <http://pg-ripple.io/fn/>
PREFIX rdfs:  <http://www.w3.org/2000/01/rdf-schema#>
PREFIX schema:<https://schema.org/>

SELECT ?paper ?title WHERE {
    ?paper a            <https://example.org/ScholarlyArticle> ;
           schema:author <https://example.org/alice> ;
           rdfs:label    ?title .
    FILTER(pg:fts(?title, "graph & neural & networks"))
}

pg:fts() only fires when the matched literal lives on a predicate that has been indexed. Otherwise it returns false (and emits a debug-level log entry).

---

Ranking

For ranked results, pg_ripple.fts_search_ranked() returns the FTS rank score per row:

SELECT subject, rank
FROM pg_ripple.fts_search_ranked(
    predicate := '<https://schema.org/description>',
    query     := 'sustainable & supply & chain'
)
ORDER BY rank DESC
LIMIT 25;

The ranking is ts_rank_cd with default normalisation. To override the normalisation, use fts_search_ranked(predicate, query, normalisation := 32).

---

Combining FTS and vector search

FTS catches exact lexical matches; vector search catches paraphrase. Combining them improves recall:

SELECT entity_iri, fused_score
FROM pg_ripple.hybrid_search(
    sparql := 'SELECT ?p WHERE { ?p a <https://example.org/Paper> .
                                 FILTER(pg:fts(?p, "neural & networks")) }',
    text   := 'deep learning architectures',
    k      := 25,
    alpha  := 0.4
);

This pattern — FTS for must-include keywords, vector for semantic broadening — is one of the most useful tricks in RAG pipelines.

---

When not to use FTS

• The data is structured with controlled vocabularies (skos:Concept taxonomies, code lists) — use the exact SPARQL pattern instead.
• Your dataset is small (< 10 K labels). Plain LIKE '%keyword%' is fine.
• You only ever query a single language. PostgreSQL's simple config is faster for that case than the language-aware ones.

---

See also

• Vector & Hybrid Search — the semantic counterpart to FTS.
• PostgreSQL Full-Text Search documentation

Temporal Queries and Provenance

Two of the most-asked compliance questions in any data system are:

1. "What did the graph look like at 03:14 last Tuesday?" — a temporal question.
2. "Where did this fact come from, and who introduced it?" — a provenance question.

pg_ripple answers both with first-class features that need no schema changes and no extra storage on the hot path.

The four are designed to compose. A regulator-defensible audit trail typically uses all four.

---

Temporal queries

Every triple in pg_ripple carries a globally-unique statement ID (i BIGINT) drawn from a shared sequence. The sequence value monotonically increases with insertion time, so it acts as a logical timestamp. The _pg_ripple.statement_id_timeline table maps wall-clock timestamps to SID ranges.

point_in_time(ts) sets a session GUC that restricts every subsequent SPARQL and Datalog query to the SID range that existed at ts.

-- See the graph as it stood last Tuesday at 03:14.
SELECT pg_ripple.point_in_time('2026-04-21 03:14:00+00'::timestamptz);

-- All queries in this session are now scoped to that point in time.
SELECT * FROM pg_ripple.sparql('
    SELECT ?paper ?title WHERE {
        ?paper <http://purl.org/dc/elements/1.1/title> ?title
    }
');

-- Reset to "now".
SELECT pg_ripple.point_in_time(NULL);

What this is good for

• Audits: prove what your application would have shown a user at the time of an event.
• Reproducible analytics: re-run a report against the exact data the original report saw.
• Debugging: bisect a quality regression by walking back through time.
• Historical change-detection: combine with CDC subscriptions to see what changed between two points in time.

What this is not

• It is not a full bitemporal store. You cannot query "the version of fact X that was believed in March but valid for January". For that you need RDF-star plus your own valid-time predicate.
• It is not safe across VACUUM FULL of _pg_ripple.statement_id_timeline. Routine VACUUM is fine.

---

PROV-O provenance

PROV-O is the W3C standard for describing the origin of data. Set one GUC and every bulk-load operation is automatically annotated with prov:Activity and prov:Entity triples.

SET pg_ripple.prov_enabled = on;

-- Every load is recorded.
SELECT pg_ripple.load_turtle_file('/data/products.ttl');
SELECT pg_ripple.load_nquads_file('/data/customers.nq');

-- Inspect the recorded activities.
SELECT * FROM pg_ripple.prov_stats();

A typical recorded activity looks like:

_:act_42 a prov:Activity ;
    prov:startedAtTime "2026-04-27T10:00:00Z"^^xsd:dateTime ;
    prov:endedAtTime   "2026-04-27T10:00:14Z"^^xsd:dateTime ;
    prov:wasAssociatedWith <urn:postgres-role:loader_service> ;
    pg:loadFunction       "load_turtle_file" ;
    pg:sourceFile         "/data/products.ttl" ;
    pg:tripleCount        128432 .

You can query provenance with SPARQL like any other data. PROV-O integrates cleanly with point_in_time() — "as of the close of business yesterday, which loader had touched this graph?" is a single query.

---

Audit log

While PROV-O captures bulk loads, the audit log captures every SPARQL UPDATE — INSERT DATA, DELETE DATA, INSERT { … } WHERE, MOVE, COPY, LOAD, etc. Set the GUC and entries land in _pg_ripple.audit_log:

SET pg_ripple.audit_log_enabled = on;

-- Every UPDATE is captured.
SELECT pg_ripple.sparql_update('
    INSERT DATA { <https://example.org/x> <https://example.org/y> "z" }
');

-- Inspect.
SELECT ts, role, txid, operation, query
FROM _pg_ripple.audit_log
ORDER BY ts DESC
LIMIT 20;

-- Cleanup (e.g. nightly).
SELECT pg_ripple.purge_audit_log(before := now() - interval '90 days');

The audit log is a PostgreSQL table — you can ship it to your SIEM, partition it, or replicate it like any other table.

Per-fact provenance with RDF-star

For granular, per-triple provenance (rather than per-load or per-update), use RDF-star quoted triples. See Storing Knowledge → RDF-star for the syntax. The most common pattern:

<< <:alice> <:knows> <:bob> >>
    :assertedBy <:dataset/foaf2024> ;
    :confidence "0.95"^^xsd:decimal ;
    :timestamp  "2026-04-27"^^xsd:date .

These quoted triples are queryable with the same SPARQL patterns as ordinary triples.

---

Putting them together — a worked example

A regulator asks: "On 21 March, did your system tell the user that drug A interacts with drug B? If so, on what evidence?"

-- 1. Replay the state of the graph.
SELECT pg_ripple.point_in_time('2026-03-21 12:00:00+00');

-- 2. Re-ask the question.
SELECT * FROM pg_ripple.sparql('
    ASK { <https://example.org/drugA> <https://example.org/interactsWith> <https://example.org/drugB> }
');
-- → true

-- 3. Find the evidence (RDF-star + PROV-O).
SELECT * FROM pg_ripple.sparql('
    SELECT ?source ?confidence ?activity WHERE {
        << <https://example.org/drugA> <https://example.org/interactsWith> <https://example.org/drugB> >>
            <https://example.org/source>     ?source ;
            <https://example.org/confidence> ?confidence .
        ?activity <http://www.w3.org/ns/prov#generated> ?source .
    }
');

-- 4. Find the operator who loaded it.
SELECT * FROM pg_ripple.sparql('
    SELECT ?role WHERE {
        ?activity <http://www.w3.org/ns/prov#wasAssociatedWith> ?role
    }
');

That four-line chain is the kind of evidence a regulated industry needs and a black-box system cannot produce.

---

Performance and storage notes

• point_in_time() is read-only and zero-cost on the write path.
• The _pg_ripple.statement_id_timeline table is a small append-only log: ~24 bytes per timestamp boundary. A 24/7 store accumulates a few KB per day.
• prov_enabled adds ~5–10 triples per bulk load. Negligible for any non-trivial load.
• audit_log_enabled writes one row per UPDATE statement. For OLTP-heavy workloads consider partitioning the table monthly.
• All three features are off by default. Enable them per database according to your compliance posture.

---

See also

• CDC Subscriptions — push changes in real time, complementary to point-in-time replay.
• Multi-Tenant Graphs — pair the audit log with RLS to attribute every change to a tenant role.
• Cookbook: Audit trail with PROV-O and temporal queries

Further reading

• Blog: Temporal Time-Travel Queries — point-in-time replay of your knowledge graph
• Blog: Provenance Tracking with PROV-O — tracing where every fact came from

Multi-Tenant Graphs

Multi-tenant graph storage is one of the trickiest patterns in any database. You have one logical product but many customers, each of whose data must be invisible to the others, bounded in size, and measurable for billing and capacity planning. pg_ripple solves this with three composable building blocks:

Together these give you true tenant isolation backed by PostgreSQL's permission system — no application-level filtering, no risk of an SQL injection bypassing the wall.

---

When to use this

• A SaaS product where every customer has their own knowledge graph.
• A research platform where each project is sandboxed.
• A multi-team data platform where you want to share an instance without sharing data.

If you only need labelled partitioning without isolation (e.g. "this graph is from PubMed, this one from Crossref"), plain named graphs are enough. The features on this page are about enforced isolation.

---

The model

   ┌──────────────────────────────────────────────────────────────┐
   │                    pg_ripple instance                         │
   │                                                               │
   │   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
   │   │  graph A     │  │  graph B     │  │  graph C     │      │
   │   │  (acme.com)  │  │  (globex)    │  │  (shared)    │      │
   │   │  500 K trip. │  │  120 K trip. │  │  20 K trip.  │      │
   │   │  quota: 1M   │  │  quota: 250K │  │  quota: ∞    │      │
   │   └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
   │          │                 │                 │              │
   │          └────► role tenant_acme   ◄─────────┤              │
   │                  role tenant_globex ◄────────┤              │
   │                                              │              │
   └──────────────────────────────────────────────┴──────────────┘
                                                  │
                                          everyone reads "shared"

• A graph IRI is the unit of isolation: triples are tagged with their graph at insert time.
• A role is the unit of access control: PostgreSQL roles own grants on graphs.
• A tenant is the unit of quota: every named graph that has been registered as a tenant carries a triple-count cap.

---

Step 1 — Register tenants

create_tenant() registers a named graph as a tenant and assigns it a triple-count quota. After registration, every insert into that graph is checked against the quota; an over-quota insert raises PT530.

SELECT pg_ripple.create_tenant(
    graph_iri    := 'https://example.org/tenants/acme',
    triple_quota := 1_000_000
);

SELECT pg_ripple.create_tenant(
    graph_iri    := 'https://example.org/tenants/globex',
    triple_quota := 250_000
);

You can list current usage at any time:

SELECT graph_iri, triple_count, triple_quota,
       round(100.0 * triple_count / triple_quota, 1) AS pct_used
FROM pg_ripple.tenant_stats()
ORDER BY pct_used DESC;

The view is built on a trigger-maintained counter, so it is O(1) — safe to call from a billing job.

---

Step 2 — Grant graphs to roles

grant_graph(role, graph_iri) is the analog of GRANT … ON … TO … for graphs. It registers a per-role visibility rule that pg_ripple enforces in every SPARQL query.

CREATE ROLE tenant_acme   LOGIN PASSWORD 'pw_a';
CREATE ROLE tenant_globex LOGIN PASSWORD 'pw_b';

GRANT USAGE ON SCHEMA pg_ripple, _pg_ripple TO tenant_acme, tenant_globex;
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA pg_ripple TO tenant_acme, tenant_globex;

SELECT pg_ripple.grant_graph('tenant_acme',   'https://example.org/tenants/acme');
SELECT pg_ripple.grant_graph('tenant_globex', 'https://example.org/tenants/globex');

-- Both tenants share access to a public reference graph.
SELECT pg_ripple.grant_graph('tenant_acme',   'https://example.org/shared');
SELECT pg_ripple.grant_graph('tenant_globex', 'https://example.org/shared');

A SPARQL query run by tenant_acme now sees only triples in acme and shared. There is no application-level filter to forget; the rule is enforced at the storage layer.

---

Step 3 — (Optional) attribute every change

Pair tenants with the audit log for billing-grade attribution:

SET pg_ripple.audit_log_enabled = on;

-- Per-tenant write volume in the last 24h:
SELECT role, count(*) AS updates
FROM _pg_ripple.audit_log
WHERE ts > now() - interval '24 hours'
GROUP BY role
ORDER BY updates DESC;

For per-tenant read volume, capture pg_stat_statements data; pg_ripple integrates with it transparently.

---

Operational concerns

Quota enforcement

The trigger that enforces quotas runs in the same transaction as the insert. If a bulk-load would exceed the quota, the entire load is rolled back — there is no partial commit. Plan your loaders accordingly: chunk loads if you expect to flirt with the quota, or pre-check via tenant_stats().

Eviction

Quotas are caps, not LRU. pg_ripple does not automatically evict old triples when a tenant fills up. To shrink a tenant: delete triples (or call clear_graph()) and the counter updates immediately.

Renaming or splitting a tenant

rename_tenant(old_iri, new_iri) updates the registration and re-tags every triple in a single transaction. Use it sparingly — it touches every triple in the graph.

Backup and restore

Tenants are pure PostgreSQL objects. pg_dump --schema=pg_ripple --schema=_pg_ripple captures everything. To export a single tenant for legal-hold or migration:

COPY (SELECT * FROM pg_ripple.export_quads_for_graph('https://example.org/tenants/acme'))
TO '/tmp/acme.nq';

---

Failure modes and pitfalls

1. Forgetting to grant the shared graph. A tenant without read access to your reference vocabularies will see types as opaque IRIs. Always grant https://example.org/shared (or your equivalent) to every tenant.
2. Granting the default graph. The default graph (graph ID 0) is not tenant-scoped. Do not put tenant data into the default graph; it will be visible to everyone.
3. Using a single role for all tenants. Quota and RLS attach to the role. Sharing a role across tenants defeats both.
4. Pre-emptive quotas vs reactive quotas. PT530 is raised before commit, not afterwards. Long-running bulk loads should split into batches and check tenant_stats() after each batch.

---

See also

• Operations → Security — the deeper PostgreSQL RLS background.
• Temporal & Provenance — audit-log capture for tenant attribution.
• Cookbook: Audit trail with PROV-O and temporal queries

Further reading

• Blog: Multi-Tenant Knowledge Graphs — isolation, quotas, and RLS patterns for SaaS deployments

OWL 2 Profiles — RL, EL, QL

OWL 2 is too expressive to evaluate in full inside a database — full OWL is undecidable for some queries. The W3C therefore standardised three OWL 2 profiles that trade expressiveness for tractability. pg_ripple ships built-in rule sets and query rewriters for all three.

A single GUC selects the active profile for new connections:

ALTER SYSTEM SET pg_ripple.owl_profile = 'rl';   -- 'rl' | 'el' | 'ql' | 'off'
SELECT pg_reload_conf();

Setting owl_profile = 'off' disables ontology rewriting — useful when you want to inspect raw triples without inference smoothing.

---

OWL 2 RL — the workhorse

OWL 2 RL is the profile most users want. It covers:

• Class hierarchy: rdfs:subClassOf, owl:equivalentClass, owl:disjointWith
• Property hierarchy: rdfs:subPropertyOf, owl:equivalentProperty, owl:propertyChainAxiom
• Property characteristics: owl:TransitiveProperty, owl:SymmetricProperty, owl:InverseOf, owl:FunctionalProperty, owl:InverseFunctionalProperty
• Class constructors: owl:unionOf, owl:intersectionOf, owl:hasValue, owl:someValuesFrom (in restricted positions)
• owl:sameAs and owl:differentFrom

Run it with:

SELECT pg_ripple.load_rules_builtin('owl-rl');
SELECT pg_ripple.infer('owl-rl');

Performance: the OWL 2 RL rule set has ~80 rules. On a 10 M-triple graph with a typical 1:1 T-Box / A-Box ratio, a full materialisation takes seconds with parallel stratum evaluation enabled.

pg_ripple is 100 % conformant with the W3C OWL 2 RL test suite — see OWL 2 RL Conformance Results.

---

OWL 2 EL — for large terminologies

EL was designed for ontologies with very large class hierarchies and few individuals — medical terminologies (SNOMED, NCIt), gene ontologies, product taxonomies. It supports:

• Class subsumption with existential restrictions: owl:someValuesFrom
• Property chains: e.g. partOf ∘ partOf ⊑ partOf
• owl:hasSelf
• Reflexive properties

EL classification (computing the full subclass hierarchy) is polynomial in the size of the ontology. pg_ripple's EL implementation uses a saturation-based algorithm and stores the closure in _pg_ripple.el_classified.

SELECT pg_ripple.load_rules_builtin('owl-el');
SELECT pg_ripple.infer('owl-el');

-- All classes that subsume :BacterialPneumonia.
SELECT * FROM pg_ripple.sparql('
    SELECT ?super WHERE { <https://example.org/BacterialPneumonia>
                          <http://www.w3.org/2000/01/rdf-schema#subClassOf>+ ?super }
');

---

OWL 2 QL — for query rewriting

QL is the profile of choice when you want to answer SPARQL queries over an ontology without materialising inferences first. Instead of expanding the data, pg_ripple rewrites the query at translation time using the ontology axioms. This keeps the data store small and lets you change the ontology without re-materialising.

QL supports a deliberately small set of constructs — rdfs:subClassOf, rdfs:subPropertyOf, owl:inverseOf, owl:someValuesFrom (in object position only), owl:disjointWith. The trade-off is that everything is fast.

SELECT pg_ripple.load_rules_builtin('owl-ql');
SET pg_ripple.owl_profile = 'ql';

-- This SELECT is rewritten using subClassOf axioms before execution.
SELECT * FROM pg_ripple.sparql('
    SELECT ?animal WHERE { ?animal a <https://example.org/Mammal> }
');

If Dog rdfs:subClassOf Mammal, the rewriter expands Mammal into (Mammal | Dog | Cat | …) automatically — without inserting any new triples.

---

SPARQL-DL — direct OWL axiom queries

When you want to query the T-Box itself (the ontology, not the data), pg_ripple exposes two SPARQL-DL helpers:

-- Direct subclasses of :Mammal.
SELECT * FROM pg_ripple.sparql_dl_subclasses('<https://example.org/Mammal>');

-- All superclasses of :Dog.
SELECT * FROM pg_ripple.sparql_dl_superclasses('<https://example.org/Dog>');

These route OWL vocabulary BGPs (owl:subClassOf, owl:equivalentClass, owl:disjointWith) directly to T-Box VP tables — no separate index required.

---

Choosing a profile

You can also load multiple profiles' rule sets at once and run them under different rule-set names — they are independent.

---

See also

• Reasoning & Inference — the Datalog engine that powers all three profiles.
• OWL 2 RL Conformance Results
• SPARQL Compliance Matrix

SHACL-SPARQL Rules and Constraints

Stock SHACL Core covers ~95 % of the constraints anyone needs in practice — cardinalities, datatypes, value ranges, property paths. The other 5 % is where SHACL Core runs out of expressiveness: cross-shape conditions, complex logical compositions, "this attribute must equal the sum of those attributes", and so on. SHACL-SPARQL (Advanced Features) closes the gap by letting you embed a SPARQL query inside a shape.

pg_ripple supports sh:SPARQLConstraint (validation), sh:TripleRule (inference), and sh:SPARQLRule (SPARQL CONSTRUCT-based inference, added in v0.79.0).

---

sh:SPARQLConstraint — custom validation

A sh:SPARQLConstraint runs an ASK or SELECT query for every focus node. If the query returns true (for ASK) or any rows (for SELECT), pg_ripple records a violation.

The classic example is "a person's birth date must be earlier than their death date" — not expressible in pure SHACL Core because it requires comparing two properties of the same node:

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix ex:   <https://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:LifeSpanShape a sh:NodeShape ;
    sh:targetClass foaf:Person ;
    sh:sparql [
        sh:message  "Birth date must be earlier than death date" ;
        sh:select   """
            SELECT $this WHERE {
                $this <https://example.org/birthDate> ?b ;
                      <https://example.org/deathDate> ?d .
                FILTER(?d <= ?b)
            }
        """ ;
    ] .
$TTL$);

-- Validate the whole store.
SELECT focus_node, message FROM pg_ripple.shacl_validate();

Inside the query, the special variable $this is bound to the focus node. The query is evaluated by the same SPARQL engine you would use for any other query, so anything you can write in SPARQL — property paths, FILTER, BIND, sub-SELECT — is fair game inside a constraint.

---

sh:TripleRule — inference from shapes

A sh:TripleRule adds triples to the store for every focus node that matches the shape. It is the recommended SHACL-AF inference primitive in pg_ripple because it compiles directly to a Datalog rule.

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix ex:   <https://example.org/> .

ex:AdultRule a sh:NodeShape ;
    sh:targetClass <https://schema.org/Person> ;
    sh:rule [
        a sh:TripleRule ;
        sh:subject   sh:this ;
        sh:predicate ex:isAdult ;
        sh:object    "true"^^<http://www.w3.org/2001/XMLSchema#boolean> ;
    ] .
$TTL$);

-- Apply the rule.
SELECT pg_ripple.shacl_apply_rules();

Triples produced by sh:TripleRule are written with source = 1 (inferred) — they coexist with explicit triples but stay distinguishable.

---

sh:SPARQLRule — inference from validation shapes

A sh:SPARQLRule runs a CONSTRUCT query whose graph pattern is evaluated for every focus node, and the constructed triples are added to the store. This is essentially "Datalog spelled in SPARQL" — useful when your validation already lives in SHACL and you want to derive new facts on the same data without writing a separate Datalog rule set.

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix ex:   <https://example.org/> .

ex:AdultRule a sh:NodeShape ;
    sh:targetClass <https://schema.org/Person> ;
    sh:rule [
        a sh:SPARQLRule ;
        sh:construct """
            CONSTRUCT { $this a ex:Adult }
            WHERE     { $this <https://example.org/age> ?age .
                        FILTER(?age >= 18) }
        """ ;
    ] .
$TTL$);

-- Apply the rule.
SELECT pg_ripple.shacl_apply_rules();

Triples constructed by sh:SPARQLRule are written with source = 1 (inferred) — they coexist with explicit triples but stay distinguishable.

---

When to use SHACL-SPARQL vs Datalog

Both can express custom validation and inference. Pick by audience:

Rule of thumb: if the rule fits in one SHACL shape, write it in SHACL-SPARQL. If it is naturally recursive or needs negation, use Datalog.

---

Performance notes

• sh:SPARQLConstraint is evaluated per focus node. For shapes whose target matches millions of nodes, pre-filter the target with a tighter sh:targetClass or sh:targetSubjectsOf.
• sh:SPARQLRule is reapplied on every shacl_apply_rules() call. It is not incremental. For incremental inference, use the Datalog engine.
• Both run in a single transaction; either everything succeeds or nothing changes.

---

See also

• Validating Data Quality — SHACL Core constraints.
• Reasoning & Inference — the Datalog alternative.
• SHACL Advanced Features (W3C)

R2RML — Map Relational Tables to RDF

Most enterprises already have their data in relational tables. Re-modelling that data as triples by hand is tedious and error-prone. R2RML (W3C Recommendation) is the standard mapping language that says, declaratively: "this column becomes this predicate, this row becomes this subject IRI". pg_ripple ships an R2RML executor that runs the mapping inside the same database — no ETL pipeline required.

Available since v0.55.0 via pg_ripple.r2rml_load(mapping_ttl).

---

Why R2RML?

If you already have an RDF triple store and are migrating from PostgreSQL, R2RML lets you avoid touching the source schema. If you are growing an RDF graph alongside a relational schema, it lets the two stay in sync with one declarative artefact.

---

A worked example

Suppose you have a tiny relational schema:

CREATE TABLE customer (
    id          SERIAL PRIMARY KEY,
    full_name   TEXT NOT NULL,
    email       TEXT,
    country     CHAR(2)
);

CREATE TABLE purchase (
    id          SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customer(id),
    sku         TEXT,
    amount_cents INT
);

INSERT INTO customer (full_name, email, country) VALUES
    ('Alice Chen', 'alice@example.org', 'US'),
    ('Bob Smith',  'bob@example.org',   'GB');

INSERT INTO purchase (customer_id, sku, amount_cents) VALUES
    (1, 'WIDGET-1', 1999),
    (2, 'WIDGET-2', 2999);

The R2RML mapping below turns each row into a triple cluster.

SELECT pg_ripple.r2rml_load($TTL$
@prefix rr:    <http://www.w3.org/ns/r2rml#> .
@prefix rml:   <http://semweb.mmlab.be/ns/rml#> .
@prefix ex:    <https://example.org/> .
@prefix foaf:  <http://xmlns.com/foaf/0.1/> .
@prefix schema:<https://schema.org/> .

# Map customer rows to ex:customer/{id}
<#CustomerMap>
    rr:logicalTable      [ rr:tableName "customer" ] ;
    rr:subjectMap        [ rr:template "https://example.org/customer/{id}" ;
                           rr:class    foaf:Person ] ;
    rr:predicateObjectMap [ rr:predicate foaf:name  ; rr:objectMap [ rr:column "full_name" ] ] ;
    rr:predicateObjectMap [ rr:predicate foaf:mbox  ; rr:objectMap [ rr:template "mailto:{email}" ;
                                                                     rr:termType rr:IRI ] ] ;
    rr:predicateObjectMap [ rr:predicate schema:addressCountry ; rr:objectMap [ rr:column "country" ] ] .

# Map purchase rows to ex:purchase/{id}, with a foreign-key reference to the customer
<#PurchaseMap>
    rr:logicalTable      [ rr:tableName "purchase" ] ;
    rr:subjectMap        [ rr:template "https://example.org/purchase/{id}" ;
                           rr:class    schema:Order ] ;
    rr:predicateObjectMap [ rr:predicate schema:customer ;
                            rr:objectMap [ rr:template "https://example.org/customer/{customer_id}" ;
                                           rr:termType rr:IRI ] ] ;
    rr:predicateObjectMap [ rr:predicate schema:sku    ; rr:objectMap [ rr:column "sku" ] ] ;
    rr:predicateObjectMap [ rr:predicate schema:price  ; rr:objectMap [ rr:column "amount_cents" ;
                                                                        rr:datatype <http://www.w3.org/2001/XMLSchema#integer> ] ] .
$TTL$);
-- Returns the count of triples produced.

After the call, your knowledge graph contains:

<https://example.org/customer/1>
    a foaf:Person ;
    foaf:name "Alice Chen" ;
    foaf:mbox <mailto:alice@example.org> ;
    schema:addressCountry "US" .

<https://example.org/purchase/1>
    a schema:Order ;
    schema:customer <https://example.org/customer/1> ;
    schema:sku "WIDGET-1" ;
    schema:price 1999 .

…and SPARQL queries work immediately:

SELECT * FROM pg_ripple.sparql($$
    PREFIX schema: <https://schema.org/>
    PREFIX foaf:   <http://xmlns.com/foaf/0.1/>
    SELECT ?name ?sku WHERE {
        ?order schema:customer ?c ; schema:sku ?sku .
        ?c     foaf:name       ?name .
    }
$$);

---

What pg_ripple's R2RML supports

---

Patterns and recipes

Per-row provenance via a graph map

Route every triple from a table into its own named graph for downstream tenant isolation or audit:

<#CustomerMap>
    rr:graphMap [ rr:template "https://example.org/source/customer-table" ] ;
    ...

Soft-delete handling

Restrict what gets exported with rr:sqlQuery:

<#ActiveCustomersMap>
    rr:logicalTable [ rr:sqlQuery "SELECT * FROM customer WHERE deleted_at IS NULL" ] ;
    ...

Re-running incrementally

R2RML is idempotent: running it twice produces the same triples (dictionary IDs are deterministic from XXH3-128 hashes, so no duplicates accumulate). Schedule it as a cron job that runs after your relational ETL.

Validate the result with SHACL

Pair every R2RML mapping with a SHACL shape that encodes the intended shape of the output. The shape catches mapping bugs and source-data drift in a single check:

SELECT pg_ripple.shacl_validate();

Combining with FDW

rr:tableName accepts any table — including a foreign table provided by postgres_fdw. This lets you map a remote relational database into the local triple store without copying data.

---

When not to use R2RML

• The source data is already RDF (use load_turtle() instead).
• The mapping is one-shot and you will never re-run it (a hand-crafted INSERT is faster to write).
• You need bidirectional sync (R2RML is one-way: relational → RDF).

---

See also

• Loading Data — for direct RDF formats.
• Validating Data Quality — pair every R2RML run with SHACL.
• Cookbook: Knowledge graph from a relational catalogue

Further reading

• Blog: R2RML — Relational to Graph — mapping existing PostgreSQL tables to RDF

Lattice Datalog — When and Why

The Lattice Datalog reference documents every function and GUC. This page answers a different question: should you reach for a lattice at all? Most users never need one. This page helps you decide.

---

The short answer

Use a lattice when you need to propagate a value along a graph edge — not just whether a node is reachable, but how much something is worth at that node — and the propagation is recursive.

If your rules are not recursive, standard Datalog aggregates (COUNT, SUM, AVG over strata) are simpler.

---

A concrete intuition

Standard Datalog asks: can you get from A to B?

Lattice Datalog asks: what is the best way to get from A to B?

The same graph, two different questions:

A ──0.9──► B ──0.85──► C ──0.95──► D

The moment "best path" is recursive — you don't know in advance which direction is best — you need a lattice.

---

Choosing the right built-in lattice

min — weakest-link reasoning

The strength of a chain is the strength of its weakest link.

Use min when:

• Propagating trust / confidence through a network (the result is only as trustworthy as the least-trusted step).
• Computing shortest path where the path cost is the maximum edge weight.
• Finding bottleneck capacity in a flow network (the flow is limited by the narrowest pipe).

-- Load rules (trust propagates, bottlenecked by the weakest hop).
SELECT pg_ripple.load_rules($RULES$
?x ex:trusts ?y :- ?x ex:directlyTrusts ?y .
?x ex:trusts ?z :- ?x ex:directlyTrusts ?y, ?y ex:trusts ?z .
@lattice ex:trusts confidence min .
$RULES$, 'trust');

SELECT pg_ripple.infer_lattice('trust', 'min');

max — best-case reasoning

Use max when:

• Propagating reputation / endorsement scores where having one highly-rated connection is enough.
• Finding the longest path weight in a DAG.
• Any "optimistic" or "best evidence wins" scenario.

@lattice ex:endorses score max .

set — provenance and multi-valued reasoning

Use set when:

• You need to track which source triples justify a derived fact (provenance semiring).
• You need the union of all witnesses along all derivation paths, not just one.
• Each node collects contributions from multiple parents and you need all of them.

-- Collect the set of all papers that support a hypothesis.
@lattice ex:supports evidence set .

Note: set-lattice results can be large. Consider a maximum set size or a bloom-filter approximation for large graphs.

interval — when truth has a time range

Use interval when reasoning about temporal overlap: "A and B are both true during the period when both of their valid intervals overlap".

-- Derived fact is valid only during the intersection of the body's intervals.
@lattice ex:validDuring interval interval .

---

Picking between min and a custom multiplicative lattice

The difference matters when the graph has many hops:

• min: "how reliable is my weakest source?" — appropriate for trust chains where one bad link invalidates everything.
• Multiplicative: "what is the combined probability, assuming independence?" — appropriate for Bayesian-style confidence propagation.

For the multiplicative case, register a custom aggregate:

-- Step 1: create the multiplicative aggregate.
CREATE OR REPLACE FUNCTION prob_mul(state FLOAT8, val FLOAT8)
    RETURNS FLOAT8 LANGUAGE sql IMMUTABLE AS $$ SELECT COALESCE(state, 1.0) * val $$;

CREATE AGGREGATE prob_product(FLOAT8) (SFUNC = prob_mul, STYPE = FLOAT8, INITCOND = '1.0');

-- Step 2: register the lattice.
SELECT pg_ripple.create_lattice('probability', 'prob_product', '0.0');

-- Step 3: run inference.
SELECT pg_ripple.infer_lattice('my_rules', 'probability');

---

Do I really need a lattice?

Before reaching for a lattice, check whether a simpler approach works:

Lattices add one piece of complexity: the fixpoint loop. If you can express the same computation as a single SQL WITH RECURSIVE query or a non-recursive Datalog rule, that is almost always simpler and faster.

---

Convergence and termination

Every lattice computation is guaranteed to terminate if the lattice has the ascending chain condition — no infinite strictly ascending chains. All four built-in lattices satisfy this:

• min over bounded integers / floats: descending-only.
• max over bounded integers / floats: ascending but bounded.
• set of a finite universe: a finite powerset, every chain terminates.
• interval over bounded timestamps: bounded.

Custom lattices over unbounded domains can diverge. Set pg_ripple.lattice_max_iterations (default: 1000) as a safety cap. The engine emits a PT540 warning if the cap is hit and returns the current (partial) fixpoint.

---

See also

• Lattice Datalog Reference — all SQL functions, GUCs, and catalog tables.
• Cookbook: Probabilistic Rules — end-to-end worked example.
• Reasoning and Inference — the full Datalog story.

Advanced Inference: WCOJ, DRed, and Tabling

Three terms appear in the pg_ripple release notes — worst-case optimal joins, DRed (Decremental Re-evaluation), and tabling — that have no obvious meaning to a SQL or SPARQL practitioner. This page explains what each one does, when the engine uses it, and why it matters for your queries.

You do not need to configure any of them. They are automatic. But knowing they exist helps you understand why certain queries are fast, why retraction is safe, and why recursive queries do not loop infinitely.

---

Worst-Case Optimal Joins (WCOJ)

The problem

Classical binary join plans — the kind every SQL query planner uses — are suboptimal for certain triangle and clique patterns. Given three tables R, S, T:

-- Triangle query: find all A-B-C triples where all three pair-wise edges exist.
SELECT r.a, s.b, t.c
FROM   R r JOIN S s ON r.b = s.b
           JOIN T t ON s.c = t.c
           WHERE r.a = t.a;   -- closing the triangle

A binary join plan processes R⋈S first (potentially generating many intermediate rows), then joins with T. For dense triangle patterns, the intermediate result can be quadratically larger than the final output. The join is correct, but wasteful.

Worst-case optimal joins (specifically, the Leapfrog Triejoin algorithm) process all three relations simultaneously, interleaving the enumeration so the intermediate result is never larger than the final output. The result is output-sensitive performance: fast on sparse results, fast on dense results, never pathological.

When pg_ripple uses it

WCOJ is used automatically for multi-predicate star patterns and triangle patterns in SPARQL. You trigger it without knowing:

# Triangle pattern: Alice-knows-someone-who-created-something-that-Alice-rated.
SELECT ?mid ?thing WHERE {
    ex:alice foaf:knows ?mid .
    ?mid schema:creator ?thing .
    ex:alice ex:rated ?thing .
}

This is a triangle (Alice → knows → mid → creator → thing ← rated ← Alice). pg_ripple's SPARQL-to-SQL translator detects the pattern and emits a WCOJ plan rather than two binary joins.

When to care

You almost never need to think about this. The relevant scenario: if you see a SPARQL query involving three or more VP tables in a cycle pattern performing significantly worse than expected, run EXPLAIN SPARQL and check that the plan shows a leapfrog node. If it shows a nested-loop join instead, the query optimizer may have missed the opportunity — file an issue with the query.

---

DRed — Decremental Re-evaluation

The problem

Materialised Datalog inference creates derived triples. When you delete a source triple, some derived triples may no longer be valid. Naïve re-derivation would mean rerunning the entire inference from scratch — expensive for large graphs.

DRed (Decremental Re-evaluation with Deletion) is a more efficient algorithm:

1. Mark the derived triples that might be invalid (the "over-delete" set).
2. Re-derive everything in the over-delete set from scratch, using only surviving source triples.
3. Re-insert anything that can still be derived.

The cost is proportional to the affected sub-graph, not the entire graph.

In pg_ripple

DRed kicks in automatically whenever you call sparql_update with a DELETE or DELETE WHERE that removes a triple that is used as a body atom in an active rule set.

# Delete a source triple.
DELETE DATA {
    <https://example.org/alice> foaf:knows <https://example.org/bob>
}

If any Datalog rule derives triples from foaf:knows, pg_ripple marks those derived triples for DRed re-evaluation and launches the algorithm. The derived triples that are still provable (via other paths) are kept; the ones that have no other derivation are removed.

What this means for you

• Deletes are safe. You never have to manually reconcile derived triples with base triples after a deletion. The engine handles it.
• Deletes are proportionally expensive. The cost of a deletion is proportional to the number of derived triples that depended on the deleted fact, not on the total triple count. For well-factored rule sets, this is small.
• Avoid manual derived-triple cleanup. Do not write DELETE WHERE queries that target _pg_ripple.vp_* tables directly. The DRed bookkeeping uses the OID of the source triple; direct table manipulation bypasses it and can leave the derived set inconsistent.

---

Tabling

The problem

Recursive Datalog rules can loop. Given:

ancestor(X, Y) :- parent(X, Y) .
ancestor(X, Z) :- ancestor(X, Y), ancestor(Y, Z) .

A naïve evaluator would keep expanding ancestor forever if there is a cycle in the parent graph (a real risk with, for example, owl:sameAs or skos:broader*).

Tabling (also called memoisation or SLG resolution) avoids infinite loops by caching — tabling — intermediate results and suspending evaluation when a recursive call would revisit a goal already on the active stack.

In pg_ripple

pg_ripple's Datalog evaluator uses a bottom-up semi-naïve iteration (SN) as its primary strategy. Tabling is used as a fallback for rule sets that cannot be safely stratified.

Under SN evaluation:

1. Start from the base facts.
2. Derive every new triple that the rules allow (the "delta" derivation).
3. Repeat with the new facts as seed until no new triples are produced (fixpoint).

The fixpoint condition ensures termination. Tabling is used during the fixpoint iteration to detect and break circular derivation chains that would otherwise prevent convergence.

What this means for you

• You can write mutually recursive rules safely. pg_ripple does not require you to manually identify the fixed point.
• Cycles in the data do not cause infinite loops. owl:sameAs chains, skos:broader cycles, or rdfs:subClassOf diamond hierarchies are all handled.
• Well-founded semantics for negation. When a rule uses negation-as-failure (NOT in the body), pg_ripple uses well-founded semantics (WFS) to assign a third truth value ("unknown") to atoms that participate in cycles through negation. This is the most principled treatment of negation under recursion available in any Datalog system.

---

How they compose

All three mechanisms operate together on the same query/rule execution:

None of them requires configuration. They are part of the engine's normal operation and are activated automatically based on query shape, rule structure, and update type.

---

See also

• Reasoning and Inference — the full Datalog reference.
• Lattice Datalog — when your reasoning needs to propagate values, not just facts.
• OWL 2 Profiles — the specific built-in rule sets.
• SPARQL Query Debugger — inspect which join strategy the planner chose.

Further reading

• Blog: Leapfrog Triejoin — how worst-case optimal joins accelerate cyclic patterns
• Blog: Well-Founded Semantics — three-valued logic for cyclic rules
• Blog: Magic Sets for Goal-Directed Inference — demand-driven evaluation

PageRank & Graph Analytics (v0.88.0+)

pg_ripple v0.88.0 adds a Datalog-native PageRank engine that runs entirely inside PostgreSQL via SPI and the existing Datalog aggregation infrastructure. All scores are persisted in _pg_ripple.pagerank_scores and are queryable with standard SQL — no external process required. v0.90.0 adds WCOJ integration, convergence norm GUC, IVM full-recompute threshold, and Count-Min Sketch approximate top-N. v0.91.0 adds IVM Prometheus gauges and explain_pagerank_json().

Quick Start

-- Load some RDF triples
SELECT pg_ripple.load_ntriples($nt$
  <http://example.org/Alice> <http://xmlns.com/foaf/0.1/knows> <http://example.org/Bob> .
  <http://example.org/Bob>   <http://xmlns.com/foaf/0.1/knows> <http://example.org/Carol> .
  <http://example.org/Carol> <http://xmlns.com/foaf/0.1/knows> <http://example.org/Alice> .
$nt$, 'http://example.org/graph');

-- Run PageRank (default: damping=0.85, 100 iterations)
SELECT node_iri, score
FROM pg_ripple.pagerank_run()
ORDER BY score DESC;

SQL Functions

pg_ripple.pagerank_run(...)

Runs iterative PageRank and persists results. Returns one row per node.

All parameters are optional and can be passed as named arguments (API-03, v0.91.0):

-- Named-argument invocation (recommended for clarity)
SELECT node_iri, score
FROM pg_ripple.pagerank_run(
    damping          => 0.85,
    max_iterations   => 50,
    topic            => 'citation'
);

-- Restrict to a specific named graph, reverse direction
SELECT node_iri, score
FROM pg_ripple.pagerank_run(
    graph_uri  => 'http://example.org/graph1',
    direction  => 'reverse'
)
ORDER BY score DESC LIMIT 20;

pg_ripple.centrality_run(metric text, ...)

Computes an alternative centrality measure and stores results in _pg_ripple.centrality_scores.

Supported metric values: 'betweenness', 'closeness', 'degree', 'pagerank'.

SELECT COUNT(*) FROM pg_ripple.centrality_run('betweenness');
SELECT * FROM _pg_ripple.centrality_scores ORDER BY score DESC LIMIT 10;

pg_ripple.explain_pagerank(node_iri text, top_k int DEFAULT 5)

Returns the score explanation tree for a node — which other nodes contributed how much.

SELECT depth, contributor_iri, contribution, path
FROM pg_ripple.explain_pagerank('<http://example.org/Alice>', 5);

pg_ripple.explain_pagerank_json(node_iri text, top_k int DEFAULT 5) (API-05, v0.91.0)

Returns the same explanation tree as explain_pagerank(), but serialised as a JSONB object. Use this when you need to return the explanation from a PL/pgSQL function or REST handler:

SELECT pg_ripple.explain_pagerank_json('<http://example.org/Alice>');
-- Returns JSONB: {"node_iri": "...", "total_score": 0.023, "contributors": [...]}

-- Useful in REST queries via pg_ripple_http /pagerank/explain/:iri?format=json

pg_ripple.export_pagerank(format text, top_k bigint DEFAULT 10000, topic text DEFAULT '')

Serialises scores in 'csv', 'turtle', 'ntriples', or 'jsonld' format.

SELECT pg_ripple.export_pagerank('turtle', 1000);

pg_ripple.pagerank_queue_stats()

Returns IVM dirty-edge queue metrics useful for monitoring.

SELECT * FROM pg_ripple.pagerank_queue_stats();
-- queued_edges | max_delta | oldest_enqueue | estimated_drain_seconds

pg_ripple.vacuum_pagerank_dirty()

Drains processed entries from _pg_ripple.pagerank_dirty_edges.

pg_ripple.pagerank_find_duplicates(metric text, centrality_threshold float8, fuzzy_threshold float8)

Returns candidate duplicate node pairs detected via centrality + label similarity.

GUC Parameters

---

Convergence Norm (v0.90.0)

pg_ripple uses the L1 norm (sum of absolute differences) to test convergence between iterations, consistent with NetworkX's default behaviour. The convergence threshold pg_ripple.pagerank_convergence_delta (default 0.0001) is compared against the L1 norm of the score delta vector.

Alternative norms can be selected via the pg_ripple.pagerank_convergence_norm GUC:

-- Match igraph convergence behaviour
SET pg_ripple.pagerank_convergence_norm = 'l2';
SELECT node_iri, score FROM pg_ripple.pagerank_run();

---

Incremental Refresh Error Bounds (v0.90.0)

The bounded K-hop incremental refresh approximates the full PageRank recomputation. The theoretical error bound after K hops of incremental propagation is:

$$|\Delta \text{score}| \leq \alpha^K \times \max_\text{delta_per_iteration}$$

where $\alpha$ is the damping factor (default 0.85) and $K$ is pagerank_khop_limit (default 30). At K=30:

$$\alpha^{30} = 0.85^{30} \approx 0.0076$$

The maximum error per dirty node is < 1% of the per-iteration delta — acceptable for most use cases. For high-precision applications, use pagerank_run() directly.

Tuning Damping for Your Graph (v0.92.0)

The default damping factor pg_ripple.pagerank_damping = 0.85 was calibrated for citation graphs and the original web (Brin & Page 1998). For other graph types:

• Sparse social graphs (Twitter-style follows): 0.50–0.75 recommended. High damping over-amplifies hub nodes in sparse graphs.
• Citation graphs (papers citing papers): 0.85 (default) is well-suited.
• Knowledge graphs (diverse predicate types): 0.85 is a safe default; consider per-predicate-filtered runs with lower damping for dense predicate subsets.
• Temporal graphs with decay (decay_rate > 0): lower damping (0.70–0.80) reduces the influence of long-range links that may be heavily time-discounted.

-- Tune for sparse social graph
SET pg_ripple.pagerank_damping = 0.65;
SELECT node_iri, score FROM pg_ripple.pagerank_run();

Automatic Full Recompute

When the fraction of stale = true rows in pagerank_scores for a given topic exceeds pg_ripple.pagerank_full_recompute_threshold (default 0.01 = 1%), the next IVM worker cycle automatically triggers a full pagerank_run() for that topic.

-- Lower threshold: trigger full recompute when 0.5% of scores are stale
SET pg_ripple.pagerank_full_recompute_threshold = 0.005;

---

Count-Min Sketch Parameters (v0.90.0)

The top-K PageRank query path uses a Count-Min Sketch to track approximate frequency distributions without materialising the full score table. Two GUCs control sketch memory:

Memory usage: width × depth × 8 bytes per active topic. With defaults: 2000 × 5 × 8 = 80 KB per topic — negligible even for thousands of topics.

Error bound: with probability $1 - e^{-\text{depth}}$ the frequency estimate overestimates by at most $e / \text{width}$ of the total stream mass.

-- Increase accuracy for large graphs at the cost of more memory
SET pg_ripple.pagerank_sketch_width = 10000;
SET pg_ripple.pagerank_sketch_depth = 7;

REST API (pg_ripple_http)

Storage

Scores are persisted in _pg_ripple.pagerank_scores:

\d _pg_ripple.pagerank_scores
-- node BIGINT, topic TEXT, score FLOAT8,
-- score_lower FLOAT8, score_upper FLOAT8,
-- computed_at TIMESTAMPTZ, iterations INT, converged BOOL,
-- stale BOOL, stale_since TIMESTAMPTZ

The IVM dirty-edge queue (_pg_ripple.pagerank_dirty_edges) tracks which edges changed since the last full run, enabling k-hop incremental refresh (PR-TRICKLE-01).

owl:sameAs Deduplication (v0.92.0)

When owl:sameAs canonicalization is active (v0.23.0), pg_ripple merges entity clusters into a canonical representative before computing PageRank. This deduplication ensures that edges to equivalent entities are not double-counted, which would otherwise inflate the PageRank score of heavily sameAs-clustered nodes.

See Reasoning and Inference for canonicalization details.

Portability Note (STD-04, v0.92.0)

pg:pagerank(), pg:centrality(), and pg:topN_approx() are pg_ripple-specific extension functions. They are not defined by the W3C SPARQL 1.1 specification and are not portable to other SPARQL endpoints (Apache Jena, Virtuoso, Stardog, etc.).

In federated queries, use the full IRI form and ensure the pg_ripple-specific endpoint is the SERVICE target. Federated queries that include pg:pagerank() in a SERVICE block targeting a non-pg_ripple endpoint will fail with SPARQL function not found.

Feature Status

SELECT feature, status, version FROM pg_ripple.feature_status()
WHERE feature LIKE 'pagerank%' OR feature LIKE 'centrality%';

Further reading

• Blog: PageRank in pg_ripple — Datalog-native PageRank with IVM and Prometheus integration

Uncertain Knowledge: Probabilistic Datalog, Fuzzy SPARQL, and Soft SHACL

pg_ripple v0.87.0 introduces the Uncertain Knowledge Engine — a suite of features for reasoning with imprecise, probabilistic, or fuzzy data.

---

Overview

Real-world knowledge graphs contain data of varying reliability. A fact extracted from a scientific paper has a different confidence level than one scraped from social media. pg_ripple now lets you:

1. Annotate Datalog rules with probability weights (@weight) so that inferred facts carry a confidence score.
2. Query confidence with SPARQL using the pg:confidence() extension function.
3. Traverse graphs with a fuzzy similarity filter using pg:confPath().
4. Match strings fuzzily with pg:fuzzy_match() and pg:token_set_ratio().
5. Score SHACL validation results with per-shape severity weights.
6. Export Turtle with RDF* confidence annotations.

---

Probabilistic Datalog (@weight)

Add a @weight(0.8) annotation to any Datalog rule to declare that derived facts have at most 0.8 confidence. The engine propagates confidence using noisy-OR combination:

parent(X, Y) :- father(X, Y).           @weight(1.0)
parent(X, Y) :- mother(X, Y).           @weight(1.0)
ancestor(X, Z) :- parent(X, Z).         @weight(0.9)
ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z). @weight(0.85)

Enable with:

SET pg_ripple.probabilistic_datalog = on;

Confidence scores are stored in _pg_ripple.confidence:

SELECT statement_id, confidence, model
FROM   _pg_ripple.confidence
LIMIT  10;

GUCs for probabilistic evaluation

---

pg:confidence() — SPARQL confidence lookup

PREFIX pg: <http://pg-ripple.org/functions/>

SELECT ?s ?p ?o ?conf WHERE {
  ?s ?p ?o .
  BIND(pg:confidence(?s, ?p, ?o) AS ?conf)
  FILTER(?conf > 0.7)
}

Returns the maximum confidence across all models for the triple (?s, ?p, ?o). Returns 1.0 when no confidence row exists.

---

Fuzzy SPARQL functions

These require CREATE EXTENSION IF NOT EXISTS pg_trgm;.

pg:fuzzy_match(a, b)

Returns the trigram similarity (similarity()) between two string literals.

PREFIX pg: <http://pg-ripple.org/functions/>

SELECT ?label WHERE {
  ?entity rdfs:label ?label .
  FILTER(pg:fuzzy_match(?label, "Alice Smith") > 0.6)
}

pg:token_set_ratio(a, b)

Returns word-set similarity (word_similarity()) — better for substring matches.

FILTER(pg:token_set_ratio(?label, "Smith") > 0.5)

pg:confPath(predicate, threshold) — confidence property path

SELECT ?x WHERE {
  <http://example.org/alice> <pg:conf_path/http://example.org/knows/0.8> ?x
}

Traverses the knows predicate with a minimum confidence threshold of 0.8.

GUC

---

Soft SHACL scoring

Instead of a pass/fail validation, pg_ripple can compute a weighted data-quality score for a graph:

SELECT pg_ripple.shacl_score('http://example.org/data');
-- Returns a float8 in [0.0, 1.0], where 1.0 = fully compliant

Annotate shapes with sh:severityWeight to control their contribution:

ex:MyShape a sh:NodeShape ;
    sh:targetClass ex:Person ;
    sh:property [ sh:path ex:name ; sh:minCount 1 ] ;
    sh:severityWeight "2.0"^^xsd:decimal .

Extension note (STD-05, v0.92.0): sh:severityWeight is a pg_ripple-specific extension to the W3C SHACL Core specification. It is not defined by https://www.w3.org/TR/shacl/. A community submission to the W3C SHACL Community Group is being considered; see GitHub discussion for progress. The annotation is stable for the pg_ripple 1.x API line.

Score history is logged to _pg_ripple.shacl_score_log:

SELECT pg_ripple.log_shacl_score('http://example.org/data');
SELECT * FROM _pg_ripple.shacl_score_log ORDER BY measured_at DESC;

---

Loading triples with confidence

SELECT pg_ripple.load_triples_with_confidence(
    '<http://example.org/alice> <http://example.org/knows> <http://example.org/bob> .',
    confidence => 0.85,
    format => 'ntriples'
);

---

Exporting with confidence annotations (RDF*)

SET pg_ripple.export_confidence = on;
SELECT pg_ripple.export_turtle_with_confidence('http://example.org/data');

Returns Turtle with << s p o >> pg:confidence "0.85"^^xsd:float . annotations.

---

PROV-O confidence propagation

Set pg_ripple.prov_confidence = on to enable automatic confidence propagation from pg:sourceTrust predicates — triples derived from low-trust sources inherit lower confidence.

---

HTTP API (pg_ripple_http)

---

Garbage collection

Orphaned confidence rows (whose statement_id no longer exists in any VP table) are purged:

1. Automatically during each HTAP merge cycle.
2. On demand: SELECT pg_ripple.vacuum_confidence();

---

Convergence Guarantees for Cyclic Probabilistic Rules (v0.90.0)

When pg_ripple.prob_datalog_cyclic = on, pg_ripple iterates the noisy-OR composition to fixpoint. The noisy-OR operator is monotone on [0, 1] (adding more evidence can only increase confidence, never decrease it), which guarantees that the semi-naive iteration sequence is non-decreasing and bounded above by 1.0. Therefore, fixpoint convergence is guaranteed for any finite probabilistic Datalog program with noisy-OR semantics.

This result follows directly from Theorem 2 in De Raedt, Kimmig & Toivonen (2007), ProbLog: A Probabilistic Prolog and its Application in Link Discovery.

Extension note (STD-03, v0.91.0): pg_ripple's noisy-OR confidence composition is a pg_ripple-specific extension implementing probabilistic Datalog semantics. It is not defined by the W3C RDF or SPARQL specifications. The mathematical foundation is:

De Raedt, L., Kimmig, A., & Toivonen, H. (2007). ProbLog: A probabilistic Prolog and its application in link discovery. Proceedings of IJCAI 2007, pp. 2468–2473. https://ijcai.org/proceedings/2007/2

Convergence speed depends on cycle depth and confidence values; programs with near-1.0 confidence in cycles may converge slowly. The prob_datalog_max_iterations GUC (default 100) and prob_datalog_convergence_delta GUC (default 1e-6) control termination.

-- Tune convergence for deep cyclic programs
SET pg_ripple.prob_datalog_max_iterations = 500;
SET pg_ripple.prob_datalog_convergence_delta = 1e-8;

Formal Guarantee

Let $c_i^{(k)}$ denote the confidence of fact $i$ after $k$ iterations. Under noisy-OR semantics:

$$c_i^{(k+1)} = 1 - \prod_{j \in \text{parents}(i)} (1 - w_{ij} \cdot c_j^{(k)})$$

Since noisy-OR is monotone and the sequence ${c_i^{(k)}}$ is non-decreasing and bounded above by 1.0, by the Knaster–Tarski fixed-point theorem the iteration converges to the least fixed point of the probability propagation operator.

Further reading

• Blog: Probabilistic Datalog — noisy-OR, confidence propagation, and soft reasoning in pg_ripple
• Blog: Uncertain Knowledge — practical patterns for probabilistic reasoning

CDC Subscriptions

Status: Available since v0.42.0 (CDC-01)
Requires: pg_ripple_http for Server-Sent Events delivery. PostgreSQL LISTEN/NOTIFY works without it.
SQL: pg_ripple.subscribe_cdc(), pg_ripple.unsubscribe_cdc(), pg_ripple.list_cdc_subscriptions()
HTTP: GET /subscribe/{id} (Server-Sent Events, via pg_ripple_http)
See also: Live SPARQL Subscriptions · Live Views

---

Overview

Change Data Capture (CDC) subscriptions let your application subscribe to a real-time stream of RDF triple changes — filtered by SPARQL pattern or SHACL shape — without polling the database.

When a matching triple is inserted or deleted, pg_ripple sends a PostgreSQL NOTIFY message on a named channel. Listeners receive a JSON payload describing the change. The pg_ripple_http companion service exposes these subscriptions as Server-Sent Events (SSE) streams for web and streaming applications.

sequenceDiagram
    participant App
    participant pg_ripple_http
    participant PostgreSQL
    participant pg_ripple_ext as pg_ripple extension

    App->>pg_ripple_http: GET /subscribe/{id}
    pg_ripple_http->>PostgreSQL: LISTEN pg_ripple_sub_{id}
    Note over App,pg_ripple_http: SSE connection established

    loop Triple Changes
        App->>PostgreSQL: INSERT triple (via SPARQL or SQL)
        pg_ripple_ext->>PostgreSQL: NOTIFY pg_ripple_sub_{id}, payload
        PostgreSQL->>pg_ripple_http: async notification
        pg_ripple_http->>App: event: row\ndata: {...}
    end

Creating a Subscription

-- Subscribe to all triple changes.
SELECT pg_ripple.create_subscription('my_feed');

-- Subscribe with a SPARQL pattern filter.
SELECT pg_ripple.create_subscription(
    'person_changes',
    filter_sparql := 'SELECT ?s ?p ?o WHERE { ?s a <https://schema.org/Person> ; ?p ?o }'
);

-- Subscribe with a SHACL shape filter.
SELECT pg_ripple.create_subscription(
    'shape_violations',
    filter_shape := '<https://shapes.example.org/PersonShape>'
);

Parameters

Returns TRUE if created, FALSE if a subscription with that name already exists.

Listening for Changes

-- Start listening.
LISTEN pg_ripple_cdc_my_feed;

-- Insert a triple.
SELECT pg_ripple.insert_triple(
    '<https://ex.org/alice>',
    '<https://schema.org/name>',
    '"Alice"'
);

-- In your application, receive notifications via pg_notify/asyncpg/etc.

Notification Payload

Each notification carries a JSON payload:

{
  "op": "add",
  "s": "<https://ex.org/alice>",
  "p": "<https://schema.org/name>",
  "o": "\"Alice\"",
  "g": ""
}

Listing Subscriptions

SELECT name, filter_sparql IS NOT NULL AS has_filter, created_at
FROM pg_ripple.list_subscriptions()
ORDER BY created_at;

Dropping a Subscription

-- Returns TRUE if removed, FALSE if not found.
SELECT pg_ripple.drop_subscription('my_feed');

WebSocket Access via pg_ripple_http

When the pg_ripple_http companion service is running, subscriptions are accessible as WebSocket endpoints:

ws://<host>:8080/ws/subscriptions/{name}

The service supports content negotiation via the Accept header:

• application/json (default) — JSON payload
• text/turtle — Turtle-serialized change notification
• application/ld+json — JSON-LD change notification

Integration Patterns

GraphRAG Pipeline

import asyncpg

async def watch_entity_changes():
    conn = await asyncpg.connect(dsn)
    await conn.execute("LISTEN pg_ripple_cdc_entity_changes")

    async for notification in conn.listen("pg_ripple_cdc_entity_changes"):
        payload = json.loads(notification.payload)
        # Re-embed entity on change.
        await update_embedding(payload["s"])

Live Dashboard

const ws = new WebSocket("ws://localhost:8080/ws/subscriptions/dashboard_feed");
ws.onmessage = (event) => {
  const change = JSON.parse(event.data);
  updateDashboard(change.op, change.s, change.p, change.o);
};

Underlying Tables

Related Functions

Further reading

• Blog: CDC and Knowledge Graphs — real-time event streaming from your knowledge graph

Live SPARQL Subscriptions

Status: Experimental — v0.73.0 (SUB-01)
API: pg_ripple.subscribe_sparql() / pg_ripple.unsubscribe_sparql()
HTTP: GET /subscribe/:subscription_id (Server-Sent Events)
See also: CDC Subscriptions · Live Views

---

Overview

Live SPARQL subscriptions allow applications to receive real-time notifications when the result of a SPARQL SELECT query changes. Whenever a graph write or delete touches a graph that a registered subscription monitors, pg_ripple calls pg_notify('pg_ripple_subscription_<id>', ...) with the updated query result as a JSONB payload.

The pg_ripple_http companion service exposes a GET /subscribe/:id endpoint that translates PostgreSQL LISTEN notifications into Server-Sent Events (SSE) that any HTTP client can consume.

---

Quick start

1. Register a subscription

-- Register a subscription that fires whenever a triple is written to
-- the default graph and the query over it produces a different result.
SELECT pg_ripple.subscribe_sparql(
    'my-sub-01',
    'SELECT ?s ?label WHERE { ?s <https://schema.org/name> ?label }',
    NULL   -- NULL = monitor all graphs
);

2. Listen for changes in any PostgreSQL client

LISTEN pg_ripple_subscription_my-sub-01;
-- Each NOTIFY payload is a JSONB string of the updated result set.

3. Listen via HTTP SSE

curl -N http://localhost:7878/subscribe/my-sub-01 \
     -H "Authorization: Bearer $TOKEN"

Each Server-Sent Event has event: sparql_result and data: <jsonb> fields.

4. Unregister

SELECT pg_ripple.unsubscribe_sparql('my-sub-01');

---

SQL API reference

subscribe_sparql(subscription_id, query, graph_iri)

pg_ripple.subscribe_sparql(
    subscription_id TEXT,
    query           TEXT,
    graph_iri       TEXT DEFAULT NULL
) RETURNS VOID

Registers a subscription. Raises an error if a subscription with the same ID already exists.

• subscription_id — unique identifier; used in the channel name pg_ripple_subscription_<id>.
• query — SPARQL SELECT query to re-evaluate on change.
• graph_iri — if set, the subscription fires only when this named graph is written or deleted. NULL fires for any graph write.

unsubscribe_sparql(subscription_id)

pg_ripple.unsubscribe_sparql(subscription_id TEXT) RETURNS VOID

Removes the subscription. Silently succeeds if the ID does not exist.

---

HTTP SSE endpoint

GET /subscribe/:subscription_id

Event format:

event: sparql_result
id: <notification_id>
data: {"bindings": [...]}

event: keepalive
data: {}

A keepalive event is sent every 15 seconds to keep the TCP connection alive through proxies and load balancers.

---

Limitations

• Payload size: pg_notify has an 8 KB payload limit. When the updated result set exceeds this limit, pg_ripple sends a {"changed": true} signal instead of the full result. The client must then re-query to obtain the new result.
• At-least-once delivery: SSE is a fire-and-forget protocol. If the client disconnects and reconnects, it will receive the next notification but may miss intermediate ones.
• Prototype: This is an experimental implementation. The subscription mechanism is synchronous in the mutation path; very high write rates on a subscribed graph may add latency.

---

Implementation notes

Subscriptions are stored in _pg_ripple.sparql_subscriptions:

SELECT * FROM _pg_ripple.sparql_subscriptions;
-- subscription_id | query | graph_iri | created_at

The mutation journal (src/storage/mutation_journal.rs) calls crate::subscriptions::notify_affected_subscriptions() after flushing CWB hooks. This function queries the subscriptions catalog, re-executes the SPARQL query for any matching subscription, and calls pg_notify.

---

See also

• CDC Subscriptions — pg-trickle-based change data capture for CDC relay patterns.
• Live Views — SPARQL CONSTRUCT live views that automatically refresh derived graphs.

JSON Mapping

pg_ripple's JSON mapping feature provides a bidirectional bridge between JSON payloads and the RDF knowledge graph. Register a named JSON-LD context once with register_json_mapping(), then use it for both ingest and export.

Registration

SELECT pg_ripple.register_json_mapping(
    'contacts',
    '{"contact_id": "http://schema.org/identifier",
      "full_name":  "http://schema.org/name",
      "email_addr": "http://schema.org/email"}'::jsonb
);

Parameters:

Ingest (JSON → RDF)

SELECT pg_ripple.ingest_json(
    '{"contact_id": "c001", "full_name": "Alice Smith"}'::jsonb,
    'https://example.com/contacts/c001',
    'contacts'
);

Modes: 'append' (default), 'upsert', 'diff'.

Export (RDF → JSON)

SELECT pg_ripple.export_json_node(subject_id, 'contacts');

Relational Writeback (v0.128.0)

v0.128.0 adds the ability to write RDF graph changes back to the originating relational table — completing the full round-trip.

Configuration

Add writeback configuration to the mapping:

UPDATE _pg_ripple.json_mappings
SET writeback_table        = 'contacts',
    writeback_schema       = 'public',
    writeback_key_columns  = ARRAY['contact_id'],
    writeback_conflict_policy = 'replace'
WHERE name = 'contacts';

Conflict Policies

Direct Writeback

-- Write a single subject back to the relational table.
SELECT pg_ripple.writeback_json_row('contacts', 'https://example.com/contacts/c001');

-- Delete a subject from the relational table.
SELECT pg_ripple.writeback_json_row_delete('contacts', 'https://example.com/contacts/c001');

Trigger-Based Automation

Enable VP delta triggers for automatic async writeback:

SELECT pg_ripple.enable_json_writeback('contacts');

The background merge worker drains the queue in batches (controlled by pg_ripple.json_writeback_batch_size, default 100).

Monitor queue status:

SELECT * FROM pg_ripple.json_writeback_status();
--  mapping_name | pending | errors | last_error | last_processed_at

HTTP Writeback

The HTTP companion exposes the same writeback path for applications that do not call SQL directly:

curl -X POST http://localhost:7878/json-mapping/contacts/writeback \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"subject_iri":"https://example.com/contacts/c001"}'

Successful synchronous writeback returns:

{"rows_affected": 1}

Queue status for one mapping is available over HTTP as well:

curl http://localhost:7878/json-mapping/contacts/writeback/status \
    -H "Authorization: Bearer $TOKEN"

The status response mirrors json_writeback_status() for the selected mapping:

{
    "mapping_name": "contacts",
    "pending": 0,
    "errors": 0,
    "last_error": null,
    "last_processed_at": null
}

Disable triggers:

SELECT pg_ripple.disable_json_writeback('contacts');

Both enable_json_writeback() and disable_json_writeback() are idempotent.

Error Codes

See Also

• JSON-LD Reverse Mapping blog post
• GUC reference: json_writeback_batch_size
• HTTP API Reference
• R2RML for complex ETL

Cypher / LPG → RDF Mapping

If you are coming from Neo4j, Memgraph, or any other property-graph database, you already have a mental model of your data. This page shows how property graph concepts map to RDF, how to load a property graph schema into pg_ripple, and how to query it in SPARQL.

Nothing about your graph needs to change. The mapping is mechanical and reversible.

---

Two models, one idea

Both Labeled Property Graphs (LPG) and RDF represent knowledge as a graph. The terminology differs:

The only material difference is relationship properties (properties on an edge in LPG). In RDF these become RDF-star quoted triples.

---

Naming scheme for IRIs

LPG nodes have internal integer IDs. You need to convert them to IRIs. A simple and robust scheme:

https://example.org/node/{label}/{id}

For example, a Neo4j node (:Person {id: 42, name: "Alice"}) becomes:

<https://example.org/node/Person/42>  rdf:type  <https://example.org/vocab/Person> .
<https://example.org/node/Person/42>  <https://example.org/vocab/name>  "Alice" .

If your nodes have a domain-meaningful unique key (email, UUID, slug), use that instead of the internal ID — it makes the IRIs stable across re-imports.

---

Translating a Cypher schema to RDF

Nodes and node properties

Cypher:

CREATE (:Person {name: "Alice", age: 30, active: true})

RDF (Turtle):

@prefix ex:  <https://example.org/node/Person/> .
@prefix voc: <https://example.org/vocab/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ex:alice  a              voc:Person ;
          voc:name       "Alice" ;
          voc:age        30 ;
          voc:active     true .

Relationships without properties

Cypher:

MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"})
CREATE (a)-[:KNOWS]->(b)

RDF:

ex:alice  voc:KNOWS  ex:bob .

Relationships with properties (RDF-star)

Cypher:

CREATE (a)-[:KNOWS {since: 2020, strength: 0.9}]->(b)

RDF-star (Turtle-star):

ex:alice  voc:KNOWS  ex:bob .

<< ex:alice  voc:KNOWS  ex:bob >>
    voc:since     2020 ;
    voc:strength  "0.9"^^xsd:decimal .

Store this in pg_ripple:

SELECT pg_ripple.load_turtle($TTL$
@prefix ex:  <https://example.org/node/Person/> .
@prefix voc: <https://example.org/vocab/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ex:alice  voc:KNOWS  ex:bob .
<< ex:alice  voc:KNOWS  ex:bob >>
    voc:since    "2020"^^xsd:integer ;
    voc:strength "0.9"^^xsd:decimal .
$TTL$);

---

Translating common Cypher queries to SPARQL

Node by property

MATCH (p:Person {name: "Alice"}) RETURN p.age

PREFIX voc: <https://example.org/vocab/>
SELECT ?age WHERE {
    ?p  a       voc:Person ;
        voc:name "Alice" ;
        voc:age  ?age .
}

Traverse a relationship

MATCH (a:Person {name: "Alice"})-[:KNOWS]->(b) RETURN b.name

PREFIX ex:  <https://example.org/node/Person/>
PREFIX voc: <https://example.org/vocab/>
SELECT ?name WHERE {
    ex:alice  voc:KNOWS  ?b .
    ?b        voc:name   ?name .
}

Multi-hop traversal (variable depth)

MATCH (a:Person {name: "Alice"})-[:KNOWS*1..]->(b) RETURN b.name

PREFIX ex:  <https://example.org/node/Person/>
PREFIX voc: <https://example.org/vocab/>
SELECT ?name WHERE {
    ex:alice  voc:KNOWS+  ?b .   # + = one or more hops
    ?b        voc:name    ?name .
}

Or voc:KNOWS* for zero-or-more.

Relationship property filter

MATCH (a)-[r:KNOWS]->(b) WHERE r.strength > 0.8 RETURN a.name, b.name

PREFIX voc: <https://example.org/vocab/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
SELECT ?aName ?bName WHERE {
    ?a voc:KNOWS ?b .
    << ?a voc:KNOWS ?b >> voc:strength ?str .
    FILTER(?str > "0.8"^^xsd:decimal)
    ?a voc:name ?aName .
    ?b voc:name ?bName .
}

Aggregation

MATCH (p:Person)-[:KNOWS]->(friend) RETURN p.name, count(friend) AS friends

PREFIX voc: <https://example.org/vocab/>
SELECT ?name (COUNT(?friend) AS ?friends) WHERE {
    ?p  a           voc:Person ;
        voc:name    ?name ;
        voc:KNOWS   ?friend .
}
GROUP BY ?name
ORDER BY DESC(?friends)

---

Bulk migration from Neo4j

The recommended path for migrating a Neo4j database:

1. Export with neo4j-admin dump or the APOC export.graphml procedure to GraphML or CSV.
2. Convert to Turtle with a small Python script (or use R2RML if the source is a JDBC view).
3. Load into pg_ripple with pg_ripple.load_turtle_file().

A minimal Python translator for the CSV export:

import csv, sys

BASE   = "https://example.org/node/"
VOCAB  = "https://example.org/vocab/"

# nodes.csv: nodeId, label, propKey1, propKey2, ...
with open("nodes.csv") as f:
    for row in csv.DictReader(f):
        iri = f"<{BASE}{row['label']}/{row['nodeId']}>"
        print(f"{iri} <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <{VOCAB}{row['label']}> .")
        for k, v in row.items():
            if k not in ("nodeId", "label") and v:
                print(f"{iri} <{VOCAB}{k}> {_literal(v)} .")

For large dumps (> 100 M triples), use COPY via load_ntriples_file() rather than load_turtle() — N-Triples is streamed in bulk without parsing overhead.

---

What you gain over LPG

Once your graph is in pg_ripple, you have access to capabilities that most LPG databases lack:

• SHACL validation — define and enforce a schema on the graph with formal guarantees.
• OWL reasoning — automatically derive rdf:type assertions from owl:equivalentClass axioms across multiple schemas.
• Federated queries — join your local graph with Wikidata, DBpedia, or any other SPARQL endpoint in a single query.
• Vector + graph hybrid — embed entities and run HNSW similarity search combined with SPARQL graph traversal.
• Transactional writes — graph writes, vector index updates, and relational table updates in a single PostgreSQL transaction.

---

See also

• Storing Knowledge — RDF-star — relationship properties in detail.
• Querying with SPARQL — full SPARQL 1.1 reference.
• Record Linkage — useful if migrating two systems with overlapping entities.

AI, RAG and LLM Integration — An Overview

pg_ripple is one of the few PostgreSQL extensions that brings knowledge graphs, vector search, and large language models together in a single transaction. This page is the front door to that capability. It explains what each AI feature does, when to use which one, and which deep-dive page to read next.

If you only have five minutes, read this page. If you have an hour, follow the links to the chapters below.

---

Why pg_ripple for AI workloads?

Modern retrieval pipelines fall into one of three traps:

1. Pure vector search is great at fuzzy similarity ("things that look like X") but cannot answer questions that follow precise relationships ("which drugs interact with the medication my patient takes?").
2. Pure graph queries capture relationships exactly but cannot match a free-text question to the right entity.
3. Pipelines that stitch the two together (vector DB + graph DB + glue code) leak data between systems, suffer from sync lag, and cannot be rolled back atomically.

pg_ripple removes the third trap. Vectors live in pgvector, triples live in vertical-partitioning tables, and a single SQL transaction can update both at once. Every AI feature on this page is built on top of that foundation.

---

The five AI features at a glance

The features compose. A typical production pipeline uses three or four of them together — see the Use Case Cookbook for end-to-end recipes.

---

Decision tree

Use this tree to pick the right feature for a new project.

Do you need to answer free-text questions over your data?
├─ No  → You probably do not need any AI feature. Use plain SPARQL.
└─ Yes → Does the question name a specific entity, or describe one?
         ├─ Names it    → Plain SPARQL is fastest. (e.g. "show me Alice's papers")
         └─ Describes it → You need retrieval. Continue.
                          │
                          Is the answer a single fact, or a passage of context?
                          ├─ Fact      → Use NL → SPARQL.
                          └─ Context   → Use the RAG pipeline (rag_context()).
                                         │
                                         Do your queries need precise relationships
                                         on top of similarity?
                                         ├─ No  → Hybrid search may suffice.
                                         └─ Yes → Combine SPARQL + similar() in one query.

Do you have entities arriving from multiple sources that may overlap?
└─ Yes → You need record linkage. Start with KGE for candidate generation,
         then SHACL for hard rules, then suggest_sameas + apply.

Do your existing embeddings only capture text, ignoring relationships?
└─ Yes → Train knowledge-graph embeddings (TransE / RotatE) and use them
         for entity alignment, recommendations, or link prediction.

---

How the pieces fit together

                ┌─────────────────────────────────────┐
                │            Application              │
                └──────────────┬──────────────────────┘
                               │ SQL
                ┌──────────────┴──────────────────────┐
                │            pg_ripple                │
                │                                     │
   text query → │  rag_context()                      │ ← LLM prompt
                │     ├─ embed question (HTTP)        │
                │     ├─ HNSW vector recall  ─────────┼─→ pgvector
                │     ├─ SPARQL graph expansion ──────┼─→ VP tables
                │     └─ assemble JSON-LD             │
                │                                     │
   text query → │  sparql_from_nl()                   │ ← SPARQL string
                │     ├─ build VoID + SHACL context   │
                │     ├─ LLM /v1/chat/completions     │
                │     └─ parse + validate (spargebra) │
                │                                     │
   batch run  → │  embed_entities()  ─────────────────┼─→ pgvector
   batch run  → │  kge_train()       ─────────────────┼─→ kge_embeddings
   batch run  → │  suggest_sameas()  ─────────────────┼─→ owl:sameAs triples
                └─────────────────────────────────────┘
                               │
                ┌──────────────┴──────────────────────┐
                │   PostgreSQL transaction boundary   │
                └─────────────────────────────────────┘

Everything inside the dashed box runs inside a single PostgreSQL transaction. If anything fails, the whole pipeline rolls back — there is no half-updated vector store to clean up.

---

Prerequisites

All AI features degrade gracefully when their dependencies are missing — they emit a WARNING and return zero rows rather than raising an ERROR. You can ship code that uses these features into a CI environment that does not have an LLM endpoint configured.

---

Security notes

• API keys are never stored in PostgreSQL. Configure the name of an environment variable (e.g. pg_ripple.llm_api_key_env = 'OPENAI_API_KEY') and the extension reads the secret at call time.
• Outbound HTTP calls require an allowlisted endpoint. Both LLM endpoints (registered via llm_endpoint / embedding_api_url) and federated SPARQL services (registered via register_endpoint()) are checked against an allowlist on every call. This prevents Server-Side Request Forgery (SSRF).
• PII in prompts. rag_context() and sparql_from_nl() send graph excerpts to the configured LLM. Use named-graph row-level security (see Multi-Tenant Graphs) to keep tenant data out of prompts you do not control.

---

Where to go next

• Want to try it in five minutes? Cookbook: Chatbot grounded in a knowledge graph
• Already have a knowledge graph and want to add RAG? RAG Pipeline
• Merging customer data from multiple systems? Record Linkage
• Building a recommendation engine over a graph? Knowledge-Graph Embeddings
• Need a structured prompt for OpenAI structured outputs? Exporting and Sharing — JSON-LD framing

Vector Embeddings and Hybrid Search

Status: Available since v0.48.0 (VEC-01)
Requires: pgvector extension (required). An OpenAI-compatible embedding API is required for automatic embedding generation; manual float4[] insertion works without it.
SQL: pg_ripple.store_embedding(), pg_ripple.vector_search(), pg_ripple.hybrid_search()
HTTP: POST /sparql (supports pg:similar() inside SPARQL SELECT)
Degraded: Without pgvector, all embedding storage and pg:similar() queries fail at query time.

---

Vector search and graph queries answer different questions. Vector search is good at "things that look like X"; graph queries are good at "things in this exact relationship to X". Real-world questions usually need both — "prescriptions semantically similar to ibuprofen, taken by patients in the cardiology cohort". pg_ripple does both in one query.

This chapter is the practical reference. It covers:

• Storing vector embeddings alongside RDF entities.
• Building HNSW indexes with pgvector.
• Running pure similarity, pure SPARQL, and hybrid (RRF) search.
• The pg:similar() SPARQL function — vector search inside a SPARQL pattern.
• Federating to external vector stores (Weaviate, Qdrant, Pinecone, remote pgvector).

For higher-level decision-making, start with AI Overview. For an end-to-end RAG pipeline, see RAG Pipeline.

---

Setup

-- 1. pgvector is required.
CREATE EXTENSION IF NOT EXISTS vector;

-- 2. Point pg_ripple at an OpenAI-compatible embedding API.
ALTER SYSTEM SET pg_ripple.embedding_api_url      = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.embedding_api_key_env  = 'OPENAI_API_KEY';
ALTER SYSTEM SET pg_ripple.embedding_model        = 'text-embedding-3-small';
ALTER SYSTEM SET pg_ripple.embedding_dimensions   = 1536;
SELECT pg_reload_conf();

API keys are read from the named environment variable at call time and never stored in the database.

---

Embedding entities

Every entity that has an rdfs:label (or skos:prefLabel, or any of the configured label predicates) can be embedded:

-- Bulk-embed every labelled entity.
SELECT pg_ripple.embed_entities();

-- Or embed only one named graph.
SELECT pg_ripple.embed_entities('https://example.org/products');

-- Manually store a precomputed vector.
SELECT pg_ripple.store_embedding(
    iri    := '<https://example.org/aspirin>',
    vec    := '[...1536 floats...]'::vector,
    model  := 'text-embedding-3-small'
);

Set pg_ripple.use_graph_context = on to enrich each entity's embedding input with its 1-hop graph neighbourhood — this dramatically improves recall on entities whose labels alone are ambiguous ("Apple" the company vs the fruit).

Set pg_ripple.auto_embed = on to enqueue any newly-inserted labelled entity for background embedding. The merge-worker drains the queue.

---

The three search modes

1. Pure similarity

SELECT entity_iri, similarity
FROM pg_ripple.similar_entities('headache medication', k := 10);

Equivalent to the cosine-distance HNSW lookup you would write by hand against _pg_ripple.embeddings, but with text-to-vector handled for you.

2. Pure SPARQL

SELECT * FROM pg_ripple.sparql($$
    SELECT ?drug WHERE {
        ?drug a <https://example.org/Drug> ;
              <https://example.org/treats> <https://example.org/headache> .
    }
$$);

3. Hybrid (Reciprocal Rank Fusion)

Hybrid search returns the fused ranking of (a) the SPARQL query's top-k matches and (b) the vector query's top-k matches, using Reciprocal Rank Fusion. This catches both the exact relational matches and the fuzzy semantic neighbours.

SELECT entity_iri, score
FROM pg_ripple.hybrid_search(
    sparql := 'SELECT ?d WHERE { ?d a <https://example.org/Drug> }',
    text   := 'headache medication',
    k      := 10,
    alpha  := 0.5  -- 0.0 = pure SPARQL, 1.0 = pure vector
);

alpha is the relative weight given to the vector ranking. Tune by inspection; 0.5 is a sensible default.

---

pg:similar() — vector search inside SPARQL

The pg:similar() SPARQL function returns the cosine similarity between an entity and a free-text query. It is callable in BIND, FILTER, and ORDER BY.

PREFIX pg: <http://pg-ripple.io/fn/>

SELECT ?drug ?score WHERE {
    ?drug a <https://example.org/Drug> .
    BIND(pg:similar(?drug, "anti-inflammatory") AS ?score)
    FILTER(?score > 0.7)
}
ORDER BY DESC(?score)
LIMIT 20

This is the most expressive form — graph constraints and similarity score live in the same query plan, with no client-side post-processing.

---

Vector federation — Weaviate, Qdrant, Pinecone, remote pgvector

If you already operate a vector store and do not want to migrate, register it as a vector federation endpoint. hybrid_search() will blend results from local pg_ripple and the remote service.

SELECT pg_ripple.register_vector_endpoint(
    url      := 'https://qdrant.internal:6333',
    api_type := 'qdrant'
);

SELECT pg_ripple.register_vector_endpoint('https://weaviate.internal:8080', 'weaviate');
SELECT pg_ripple.register_vector_endpoint('https://my-index.pinecone.io', 'pinecone');

Supported api_type values: pgvector, weaviate, qdrant, pinecone. Endpoints are stored in _pg_ripple.vector_endpoints and register_vector_endpoint() is idempotent.

A federated hybrid_search() call automatically fans out, gathers per-endpoint top-k results, and re-fuses them.

---

GUCs at a glance

---

Tuning HNSW

The HNSW index built by pg_ripple is a standard pgvector index on _pg_ripple.embeddings(vector vector_cosine_ops). Tune it as you would any pgvector index:

See Vector Index Trade-offs for measured benchmarks across these knobs.

---

Graceful degradation

Every vector function in pg_ripple checks for pgvector at call time. If pgvector is missing, or pgvector_enabled = off, the function emits one WARNING and returns zero rows. Your application code can call vector functions in environments (CI, dev) that do not have pgvector without crashing.

---

See also

• AI Overview
• RAG Pipeline
• Knowledge-Graph Embeddings — graph-structural embeddings, complementary to text embeddings.
• Vector Index Trade-offs
• Embedding function reference

Further reading

• Blog: Vector + SPARQL Hybrid Search — combining graph traversal with similarity search

RAG Pipeline — rag_context()

pg_ripple v0.50.0 introduces pg_ripple.rag_context() — a single SQL function that assembles a retrieval-augmented generation (RAG) context string from your knowledge graph, ready for use as an LLM system prompt or user message.

---

Function Signature

pg_ripple.rag_context(
    question    TEXT,
    k           INT DEFAULT 10
) RETURNS TEXT

Parameters

---

How It Works

The function executes a five-step pipeline entirely inside PostgreSQL:

question TEXT
    │
    ▼  Step 1: Embed question
   HNSW cosine search on _pg_ripple.embeddings
    │
    ▼  Step 2: Vector recall
   Top-k most similar entities
    │
    ▼  Step 3: SPARQL graph expansion
   1-hop neighbourhood for each entity (labels, types, properties, neighbors)
    │
    ▼  Step 4: Assemble context
   JSON-LD fragments joined into a plain-text context string
    │
    ▼  Step 5 (optional): NL→SPARQL execution
   If pg_ripple.llm_endpoint is set, execute sparql_from_nl(question)
   and append the SPARQL result set
    │
    ▼
context TEXT

---

Prerequisites

rag_context() requires:

1. pgvector extension installed (CREATE EXTENSION vector)
2. pg_ripple.pgvector_enabled = on (default: on)
3. Entities loaded with embeddings via pg_ripple.embed_entities() or manually into _pg_ripple.embeddings

When pgvector is absent or the embeddings table is empty, the function degrades gracefully and returns an empty string with a WARNING rather than raising an ERROR.

---

Examples

Basic context retrieval

-- Retrieve context for a question (returns plain text)
SELECT pg_ripple.rag_context(
    'What drugs are used to treat headaches?',
    k := 5
);

Use the context as an LLM system prompt

-- Assemble context and pass to sparql_from_nl
SELECT pg_ripple.sparql_from_nl(
    'What drugs treat headaches? Use the context: ' ||
    pg_ripple.rag_context('What treats headaches?', k := 5)
);

End-to-end RAG with automatic SPARQL execution

When pg_ripple.llm_endpoint is configured, rag_context() automatically calls sparql_from_nl() and appends the SPARQL query result:

-- Set the LLM endpoint (once per session or in postgresql.conf)
SET pg_ripple.llm_endpoint = 'https://api.openai.com/v1';
SET pg_ripple.llm_api_key_env = 'OPENAI_API_KEY';

-- rag_context now includes vector context + SPARQL result
SELECT pg_ripple.rag_context('Who are the key authors in the knowledge graph?', k := 10);

---

Tuning

Adjusting k

Larger k returns more context but increases token usage. Start with k = 5–10 for most use cases.

-- Narrow context: k=3
SELECT pg_ripple.rag_context('What is aspirin?', k := 3);

-- Wide context: k=20
SELECT pg_ripple.rag_context('Give me a broad overview of drug interactions', k := 20);

Embedding freshness

Context quality depends on the embeddings being up to date. Run embed_entities() periodically or after bulk loads:

-- Re-embed all entities in the default graph
SELECT pg_ripple.embed_entities(graph_iri := NULL, model := NULL, batch_size := 100);

GUC settings

---

Output Format

The context string has the following structure for each entity:

Entity: https://example.org/aspirin
Label: aspirin
Context:
{
  "label": "aspirin",
  "types": ["https://pharma.example/Drug"],
  "properties": [
    {"predicate": "...", "object": "..."}
  ],
  "neighbors": ["https://pharma.example/Ibuprofen"]
}

---

Entity: https://example.org/ibuprofen
...

When Step 5 executes a SPARQL query, the result is appended:

---

SPARQL Result for: What treats headaches?
[{"?drug": "<https://pharma.example/aspirin>"}]

---

Graceful Degradation

Natural Language to SPARQL

pg_ripple v0.49.0 adds pg_ripple.sparql_from_nl(), a SQL function that converts a plain-English question into a SPARQL SELECT query using any configured OpenAI-compatible LLM endpoint.

Quick Start

-- Configure an OpenAI-compatible endpoint
SET pg_ripple.llm_endpoint = 'https://api.openai.com/v1';
SET pg_ripple.llm_model    = 'gpt-4o';
-- API key is read from the named environment variable, not stored inline:
SET pg_ripple.llm_api_key_env = 'OPENAI_API_KEY';  -- default

-- Generate a SPARQL query from plain English
SELECT pg_ripple.sparql_from_nl('List all people and their email addresses');

SELECT ?person ?email WHERE {
  ?person a <http://xmlns.com/foaf/0.1/Person> .
  ?person <http://xmlns.com/foaf/0.1/mbox> ?email .
}

The returned string is a valid, parseable SPARQL 1.1 query that you can pass directly to pg_ripple.sparql().

Configuring the LLM Endpoint

pg_ripple supports any OpenAI-compatible /v1/chat/completions API, including:

GUC Parameters

Setting the API Key Securely

pg_ripple never stores the API key in the database. Instead, it reads the value from a named environment variable at call time:

# In your shell or service environment:
export PG_RIPPLE_LLM_API_KEY="sk-..."

-- Tell pg_ripple which environment variable to read (default is PG_RIPPLE_LLM_API_KEY):
ALTER SYSTEM SET pg_ripple.llm_api_key_env = 'PG_RIPPLE_LLM_API_KEY';
SELECT pg_reload_conf();

How It Works

For each call to sparql_from_nl(question):

1. VoID context: pg_ripple builds a compact description of the graph — the predicate count and the most-frequent predicates — as context for the LLM.
2. SHACL context (when llm_include_shapes = on): active SHACL shapes are appended to the prompt.
3. Few-shot examples: any rows in _pg_ripple.llm_examples are included as question/SPARQL pairs.
4. LLM call: the prompt is sent to /v1/chat/completions with temperature = 0.0.
5. Extraction: the SPARQL string is extracted from the response and stripped of any markdown fencing.
6. Validation: spargebra parses the query. If parsing fails, PT702 is raised so callers can handle the error.

Adding Few-Shot Examples

Few-shot examples improve accuracy significantly for domain-specific vocabularies:

SELECT pg_ripple.add_llm_example(
    'Find all proteins that interact with insulin',
    'SELECT ?protein WHERE {
       ?protein <https://bio.ontology.org/interactsWith>
                <https://bio.ontology.org/Insulin> .
     }'
);

SELECT pg_ripple.add_llm_example(
    'Which drugs target EGFR?',
    'SELECT ?drug WHERE {
       ?drug <https://bio.ontology.org/targets>
             <https://bio.ontology.org/EGFR> .
     }'
);

Examples are stored in _pg_ripple.llm_examples and automatically included in every subsequent sparql_from_nl() call. Re-calling add_llm_example() with the same question updates the stored example (upsert behaviour).

Testing Without a Real LLM

Set pg_ripple.llm_endpoint = 'mock' to use the built-in test mock. The mock bypasses the HTTP call and returns a simple SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10 query, allowing you to test downstream code (result processing, SPARQL execution) without an external LLM dependency.

SET pg_ripple.llm_endpoint = 'mock';
SELECT pg_ripple.sparql_from_nl('anything') LIKE 'SELECT%';  -- t

Error Handling

Pipeline Pattern

A common pattern is to generate a query, log it, and execute it in one step:

DO $$
DECLARE
    sparql_q TEXT;
    result   TEXT;
BEGIN
    sparql_q := pg_ripple.sparql_from_nl(
        'Find all companies founded after 2010 with more than 500 employees'
    );
    RAISE NOTICE 'Generated SPARQL: %', sparql_q;
    -- Execute the generated query
    SELECT json_agg(row_to_json(t))::text
    INTO result
    FROM pg_ripple.sparql(sparql_q) t;
    RAISE NOTICE 'Results: %', result;
END;
$$;

Further reading

• Blog: Natural Language to SPARQL — how pg_ripple translates plain-English questions into SPARQL queries

Knowledge-Graph Embeddings (KGE)

A knowledge-graph embedding is a vector representation of an entity learned from the structure of the graph — its relationships — rather than from any text describing the entity. KGEs power three jobs that text embeddings do badly:

1. Entity alignment across graphs — match Apple in graph A to Apple Inc. in graph B based on shared neighbours, not on the strings.
2. Link prediction — score plausible edges that are not in the graph today (recommendations, cold-start, schema completion).
3. Cluster discovery — find groups of structurally-similar entities even when they have no labels in common.

pg_ripple ships two well-known KGE models, TransE and RotatE, with a unified SQL interface and an HNSW index for fast nearest-neighbour search.

Available since v0.55.0 (pg_ripple.kge_enabled GUC). Requires pgvector.

---

How TransE and RotatE differ

When in doubt, start with TransE. If your graph has lots of inverse or symmetric relations (spouse, siblingOf, coAuthor), switch to RotatE.

---

Quick start

-- 1. Enable the feature.
SET pg_ripple.kge_enabled = on;

-- 2. Train a model on the entire store.
SELECT pg_ripple.kge_train(
    model        := 'TransE',
    dimensions   := 128,
    epochs       := 100,
    learning_rate:= 0.01,
    margin       := 1.0
);

-- 3. Inspect the trained vectors.
SELECT entity_iri, vector
FROM _pg_ripple.kge_embeddings
LIMIT 5;

-- 4. Use the vectors for entity alignment.
SELECT * FROM pg_ripple.find_alignments(
    source_graph := 'https://example.org/g1',
    target_graph := 'https://example.org/g2',
    threshold    := 0.9
);

---

Choosing hyperparameters

Training writes its loss curve to the PostgreSQL log so you can monitor convergence in real time.

---

Three things people get wrong

1. Embedding too early. KGEs need a connected graph. If you train before loading owl:sameAs and inverse properties, the model learns isolated islands. Always materialise built-in RDFS / OWL inference (pg_ripple.infer('rdfs'), pg_ripple.infer('owl-rl')) before training.
2. Comparing across models. A vector trained with TransE 128-dim is meaningless to a model trained with RotatE 256-dim. The _pg_ripple.kge_embeddings table tracks (model, dimensions) per row; queries automatically scope to one model.
3. Forgetting to re-train. KGE quality drifts as the graph grows. Schedule a retrain whenever the entity count grows by ~25 %, or weekly for high-velocity ingestion.

---

Use case: link prediction

-- Score the plausibility of a candidate triple.
SELECT pg_ripple.kge_score(
    head     := '<https://example.org/Alice>',
    relation := '<https://example.org/worksAt>',
    tail     := '<https://example.org/MIT>'
);
-- Returns a real-valued score; higher = more plausible.

-- Find the top-10 most plausible employers for Alice.
SELECT tail, score
FROM pg_ripple.kge_predict_tails(
    head     := '<https://example.org/Alice>',
    relation := '<https://example.org/worksAt>',
    k        := 10
);

This is the foundation for cold-start recommendations and schema-completion workflows.

---

Use case: cross-graph alignment

find_alignments() is a thin wrapper that performs an HNSW cosine search of every entity in source_graph against every entity in target_graph, returning pairs above a threshold. The output is shaped exactly like suggest_sameas(), so it plugs into the Record Linkage pipeline unchanged.

SELECT s1, s2, similarity
FROM pg_ripple.find_alignments(
    source_graph := 'https://wikidata.example/',
    target_graph := 'https://internal-kb.example/',
    threshold    := 0.92
)
ORDER BY similarity DESC;

---

Storage and indexing

A 1 M-entity graph with 128-dim TransE embeddings occupies ~512 MB in _pg_ripple.kge_embeddings. Plan disk accordingly.

---

When not to use KGE

• Your graph is small (< 10 K entities). TransE will overfit; text embeddings are simpler.
• Your entities have no informative relationships. KGE has nothing to learn from.
• You need explainable scores. KGE is a black box; SHACL constraints and owl:sameAs are the right answer for regulator-facing decisions.

---

See also

• Record Linkage — uses find_alignments() for cross-graph entity resolution.
• Vector & Hybrid Search — text-embedding cousin of KGE.
• Reasoning & Inference — materialise inference before training to densify the graph.

Record Linkage and Entity Resolution

Status: Available since v0.67.0 (ER-01)
Requires: pgvector extension for embedding-based candidate generation (optional — rule-based linking works without it). pg_ripple_http optional for REST access.
SQL: pg_ripple.find_entity_candidates(), pg_ripple.merge_entities(), pg_ripple.entity_resolution_pipeline()
Degraded: Without pgvector, vector-similarity candidate generation is unavailable; SHACL hard-veto rules and owl:sameAs canonicalization still work.

---

Other names for this problem: entity resolution, deduplication, master data management (MDM), identity resolution, fuzzy matching. They all mean: find records that refer to the same real-world thing, and merge them safely.

Record linkage is one of the most consequential and difficult problems in data management. A hospital merging two patient databases, a bank consolidating customer records, a retailer unifying online and in-store profiles — all of them must answer the same question: do these two rows describe the same person?

pg_ripple ships a complete record-linkage stack inside PostgreSQL. It combines four techniques that traditionally each lived in a separate tool:

1. Knowledge-graph embeddings for fast, fuzzy candidate generation.
2. Vector similarity over text embeddings for semantic matching.
3. SHACL hard rules to veto unsafe merges (e.g. "never merge two patients with different blood types").
4. owl:sameAs canonicalization so the rest of your queries see one entity, not two.

Each step is a single SQL function call. Every decision is auditable.

---

The pipeline

   Source A triples           Source B triples
        │                          │
        └────────┬─────────────────┘
                 │
                 ▼
   ┌─────────────────────────────┐
   │ 1. Generate candidate pairs │
   │    suggest_sameas()         │ ← KGE or text embeddings + HNSW
   │    or find_alignments()     │
   └──────────────┬──────────────┘
                  │ (s1, s2, similarity) rows
                  ▼
   ┌─────────────────────────────┐
   │ 2. Apply hard rules         │
   │    SHACL shapes block pairs │ ← e.g. sh:disjoint on bloodType
   │    that violate constraints │
   └──────────────┬──────────────┘
                  │ filtered candidate rows
                  ▼
   ┌─────────────────────────────┐
   │ 3. Human review (optional)  │
   │    surface candidates       │ ← UI / approval queue
   │    with similarity, source, │
   │    and rule trail           │
   └──────────────┬──────────────┘
                  │ accepted pairs
                  ▼
   ┌─────────────────────────────┐
   │ 4. Apply owl:sameAs         │
   │    apply_sameas_candidates  │ ← inserts both directions
   └──────────────┬──────────────┘
                  │
                  ▼
   ┌─────────────────────────────┐
   │ 5. Canonicalize on read     │
   │    sameas_reasoning = on    │ ← SPARQL & Datalog see one entity
   │    audit_log captures all   │
   │    UPDATEs                  │
   └─────────────────────────────┘

---

A worked example: linking customer records across two systems

Suppose you operate two retail brands, each with its own customer database. You want a unified view without losing brand-specific history.

Step 1: Load both sources into named graphs

Using named graphs preserves provenance — you can always tell which record came from where.

-- Source A
SELECT pg_ripple.load_turtle_into_graph(
    'https://example.org/source-a',
    $TTL$
@prefix ex:   <https://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:a/c1  foaf:name  "Robert Smith"  ; foaf:mbox <mailto:rob.smith@example.com> .
ex:a/c2  foaf:name  "Jane Doe"      ; foaf:mbox <mailto:jdoe@example.com> .
$TTL$);

-- Source B
SELECT pg_ripple.load_turtle_into_graph(
    'https://example.org/source-b',
    $TTL$
@prefix ex:   <https://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:b/c1  foaf:name  "Bob Smith"     ; foaf:mbox <mailto:rob.smith@example.com> .
ex:b/c2  foaf:name  "Jane Q. Doe"   ; foaf:mbox <mailto:jane.doe@example.com> .
$TTL$);

Step 2: Generate candidate pairs

You have two options for candidate generation. Pick whichever fits your data.

Option A — text embeddings. Best when you have rich textual descriptions (names, addresses, product titles).

-- Embed every customer using their label.
SELECT pg_ripple.embed_entities();

-- Suggest sameAs pairs at a permissive threshold first.
SELECT s1, s2, similarity
FROM pg_ripple.suggest_sameas(threshold := 0.85)
ORDER BY similarity DESC
LIMIT 50;

Option B — knowledge-graph embeddings (KGE). Best when entities have rich relational structure (a customer's purchases, addresses, devices).

SET pg_ripple.kge_enabled = on;
SELECT pg_ripple.kge_train(model := 'TransE', epochs := 100);

SELECT * FROM pg_ripple.find_alignments(
    source_graph := 'https://example.org/source-a',
    target_graph := 'https://example.org/source-b',
    threshold    := 0.85
);

You can run both and union the results — text and KGE embeddings catch different mistakes.

Step 3: Block unsafe merges with SHACL

Define hard rules that say "these two records cannot be the same entity". The classic example is contradictory immutable attributes — different birth dates, different blood types, different national IDs.

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix ex:   <https://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:CustomerSafetyShape a sh:NodeShape ;
    sh:targetClass foaf:Person ;
    # If two people share owl:sameAs, their birth dates must agree.
    sh:property [
        sh:path ex:birthDate ;
        sh:disjoint ex:contradictoryBirthDate ;
    ] .
$TTL$);

When pg_ripple.shacl_mode = 'sync', an apply_sameas_candidates() call that would violate this shape is rejected before commit.

Step 4: Apply the surviving candidates

-- Apply at a strict threshold for auto-merge.
SELECT pg_ripple.apply_sameas_candidates(min_similarity := 0.95);

-- The remaining 0.85–0.95 band goes to a review queue.
CREATE TABLE review_queue AS
SELECT s1, s2, similarity
FROM pg_ripple.suggest_sameas(0.85)
WHERE similarity < 0.95;

A human reviewer can then approve or reject pairs from review_queue; approved pairs are applied with pg_ripple.insert_triple(s1, '<http://www.w3.org/2002/07/owl#sameAs>', s2) plus its inverse.

Step 5: Query the unified graph

With pg_ripple.sameas_reasoning = on (default), every SPARQL and Datalog query sees the merged entity transparently. There is no separate "golden record" table to maintain.

-- Returns Robert/Bob Smith's purchases from BOTH source databases as one customer.
SELECT * FROM pg_ripple.sparql($$
    SELECT ?purchase WHERE {
        <https://example.org/a/c1>
            <https://example.org/purchased> ?purchase .
    }
$$);

---

Tuning thresholds: precision vs. recall

The right band depends on the cost of each error type. In healthcare a wrong merge can endanger a patient — push the auto-merge threshold to 0.99 and route the rest to clinicians. In ad-tech a missed merge means a less-personalised ad — a 0.92 auto-merge is fine.

---

Auditability

Every record-linkage action leaves a trail. Three GUCs enable the audit chain:

Together these three give you the regulator-defensible trail that pure-ML pipelines cannot.

---

Why this is hard to get right elsewhere

Most record-linkage systems force a choice between neural (high-recall, opaque) and symbolic (auditable, low-recall). pg_ripple lets you compose both. The extended rationale is in plans/neuro-symbolic-record-linkage.md — that document is the strategic background for everything on this page.

---

Functions reference

Further reading

• Blog: Neuro-Symbolic Entity Resolution — combining embeddings with symbolic rules for deduplication
• Blog: owl:sameAs Entity Resolution — how equivalence canonicalization works

GraphRAG End-to-End

Microsoft GraphRAG is a popular open-source pipeline that turns unstructured documents into a structured knowledge graph of entities, relationships, text units, and community summaries. pg_ripple is a first-class storage and query backend for GraphRAG: you can ingest GraphRAG output directly, enrich it with Datalog rules, validate it with SHACL, and export it back as Parquet for downstream tools — all without leaving PostgreSQL.

This page is the canonical end-to-end guide. It assumes you already have a working GraphRAG output (the standard entities.parquet, relationships.parquet, text_units.parquet files).

---

What pg_ripple adds to GraphRAG

---

The data model

GraphRAG is mapped to four RDF classes:

Key properties:

The full ontology, including all SHACL shapes, lives at examples/graphrag_byog.sql.

---

End-to-end pipeline

   GraphRAG Python pipeline
            │
            ▼
   entities.parquet                    │
   relationships.parquet               │  Step 1: import
   text_units.parquet                  │
            │                          │
            ▼                          │
   pg_ripple.import_graphrag_parquet() ▼
   ──────────────────────────────────────────
            │
            ▼
   Step 2: enrich with Datalog
   pg_ripple.load_rules_builtin('graphrag-enrichment')
   pg_ripple.infer('graphrag-enrichment')
   → derives gr:coworker, gr:collaborates,
     gr:indirectReport, gr:relatedOrg
            │
            ▼
   Step 3: validate with SHACL
   pg_ripple.load_shacl(...)
   pg_ripple.shacl_validate()
   → catches missing labels, dangling references
            │
            ▼
   Step 4: query
   - SPARQL for relationship walks
   - rag_context() for grounded LLM prompts
   - hybrid_search() for similarity + structure
            │
            ▼
   Step 5 (optional): export back to Parquet
   pg_ripple.export_graphrag_entities()
   pg_ripple.export_graphrag_relationships()
   → for downstream Microsoft GraphRAG tooling

---

Step 1 — Import GraphRAG output

-- Register the gr: prefix once.
SELECT pg_ripple.register_prefix('gr', 'https://graphrag.org/ns/');

-- Import the three core files. Each file becomes triples in the named graph.
SELECT pg_ripple.import_graphrag_parquet(
    entities_path     := '/data/graphrag/entities.parquet',
    relationships_path:= '/data/graphrag/relationships.parquet',
    text_units_path   := '/data/graphrag/text_units.parquet',
    target_graph      := 'https://example.org/kb-2026-04'
);
-- Returns the count of triples inserted.

For ad-hoc loading, use load_turtle() directly:

SELECT pg_ripple.load_turtle($TTL$
@prefix gr:  <https://graphrag.org/ns/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<https://example.org/entity/alice>
    rdf:type  gr:Entity ;
    gr:title  "Alice" ;
    gr:type   "PERSON" .
$TTL$);

---

Step 2 — Enrich with Datalog

The bundled graphrag-enrichment rule set derives four useful relationships from the raw GraphRAG output:

SELECT pg_ripple.load_rules_builtin('graphrag-enrichment');
SELECT pg_ripple.infer('graphrag-enrichment');
-- Returns the count of derived triples (source = 1).

You can write your own rules — see Reasoning & Inference — but the bundled set is a good starting point.

---

Step 3 — Validate with SHACL

GraphRAG output is LLM-generated and can have quality issues: entities without titles, relationships pointing at deleted entities, weights outside [0, 1]. Catch them with SHACL:

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix gr:   <https://graphrag.org/ns/> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

gr:EntityShape a sh:NodeShape ;
    sh:targetClass gr:Entity ;
    sh:property [ sh:path gr:title ; sh:minCount 1 ; sh:datatype xsd:string ] ;
    sh:property [ sh:path gr:type  ; sh:in ( "PERSON" "ORG" "GEO" "EVENT" ) ] .

gr:RelationshipShape a sh:NodeShape ;
    sh:targetClass gr:Relationship ;
    sh:property [ sh:path gr:source ; sh:minCount 1 ; sh:class gr:Entity ] ;
    sh:property [ sh:path gr:target ; sh:minCount 1 ; sh:class gr:Entity ] ;
    sh:property [ sh:path gr:weight ; sh:datatype xsd:float ] .
$TTL$);

-- Validate everything currently in the store.
SELECT focus_node, message FROM pg_ripple.shacl_validate();

Set pg_ripple.shacl_mode = 'sync' to reject offending inserts at write time, or 'async' to route them to a dead-letter queue. See Validating Data Quality.

---

Step 4 — Query the enriched graph

GraphRAG-specific queries pair naturally with rag_context():

-- Find the LLM-ready context for a question.
SELECT pg_ripple.rag_context(
    'Who collaborates with Alice on machine learning?',
    k := 10
);

For purely structural queries, use SPARQL directly:

-- All co-workers of Alice's co-workers (a 2-hop search).
SELECT * FROM pg_ripple.sparql($$
    PREFIX gr: <https://graphrag.org/ns/>
    SELECT DISTINCT ?friend WHERE {
        <https://example.org/entity/alice> gr:coworker/gr:coworker ?friend .
        FILTER(?friend != <https://example.org/entity/alice>)
    }
$$);

---

Step 5 — Round-trip export

If you need to feed an enriched graph back into Microsoft GraphRAG's Python tools:

SELECT pg_ripple.export_graphrag_entities('', '/tmp/entities.parquet');
SELECT pg_ripple.export_graphrag_relationships('', '/tmp/relationships.parquet');

Pass '' for the default graph or a named-graph IRI to scope the export.

---

Operational tips

• Use a named graph per ingestion run (https://example.org/kb-2026-04). When a re-ingest runs, clear_graph() drops the old version atomically.
• Run inference after loading, not interleaved. Inference is bulk-friendly and parallelisable; per-row inference is not.
• Materialise embeddings after enrichment. Datalog-derived properties improve KGE quality and rag_context() recall.

---

See also

• AI Overview
• Reasoning & Inference
• Validating Data Quality
• Cookbook: Chatbot grounded in a knowledge graph
• GraphRAG function reference
• GraphRAG ontology reference

Further reading

• Blog: GraphRAG Knowledge Export — building a Microsoft GraphRAG pipeline with pg_ripple

Vector Federation

pg_ripple v0.28.0 introduces vector federation: registered external vector services (Weaviate, Qdrant, Pinecone, or another pgvector instance) can be queried alongside the local triple store.

---

Why Vector Federation?

Organizations often have multiple vector databases: a Qdrant cluster holding product embeddings, a Weaviate instance for customer data, and pg_ripple for the knowledge graph. Vector federation lets you blend all three sources in a single pg_ripple.hybrid_search() call without moving data.

---

Supported Service Types

---

Registering an Endpoint

-- Register a Qdrant instance.
SELECT pg_ripple.register_vector_endpoint(
    'https://qdrant.internal:6333',
    'qdrant'
);

-- Register a Weaviate instance.
SELECT pg_ripple.register_vector_endpoint(
    'https://weaviate.internal:8080',
    'weaviate'
);

-- Register a Pinecone index.
SELECT pg_ripple.register_vector_endpoint(
    'https://my-index-abc123.pinecone.io',
    'pinecone'
);

Registrations are idempotent — calling register_vector_endpoint() twice with the same URL is safe.

Endpoints are stored in _pg_ripple.vector_endpoints:

SELECT url, api_type, enabled, registered_at
FROM _pg_ripple.vector_endpoints;

---

Timeout Configuration

The federation timeout applies to all outbound HTTP calls to external vector services:

-- Set 10-second timeout.
SET pg_ripple.vector_federation_timeout_ms = 10000;

---

Security Considerations

• Endpoints are stored in an internal table accessible only to pg_ripple schema users.
• HTTPS is recommended for all external endpoints.
• API keys for external services are not stored by pg_ripple; configure them via environment variables or secrets management in your application layer.
• The pg_ripple.vector_federation_timeout_ms GUC prevents runaway federated queries from blocking the database.

---

Catalog Table Reference

_pg_ripple.vector_endpoints

---

GUC Reference

AI Agent Integration (LangChain, LlamaIndex, and Friends)

pg_ripple's AI capabilities — vector search, rag_context(), sparql_from_nl(), graph expansion — are exposed as plain SQL functions. Any framework that can call PostgreSQL can use them. No SDK required.

This page shows how to wire pg_ripple into the two most common Python agent frameworks, plus a framework-agnostic tool-calling pattern.

---

The mental model

An AI agent loop looks like this:

user question
     │
     ▼
   LLM decides: do I need to look something up?
     │
     ├── yes → call a tool (pg_ripple function via SQL) → get context
     │          └── loop back to LLM with context
     │
     └── no  → generate final answer

pg_ripple is the tool. The LLM calls it via rag_context(), sparql_from_nl(), or a custom SQL wrapper — whichever your framework exposes.

---

Prerequisites

-- Configure the embedding endpoint (once per database).
ALTER SYSTEM SET pg_ripple.embedding_api_url     = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.embedding_api_key_env = 'OPENAI_API_KEY';
ALTER SYSTEM SET pg_ripple.embedding_model       = 'text-embedding-3-small';

ALTER SYSTEM SET pg_ripple.llm_endpoint          = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.llm_api_key_env       = 'OPENAI_API_KEY';
ALTER SYSTEM SET pg_ripple.llm_model             = 'gpt-4o';

SELECT pg_reload_conf();

-- Embed your knowledge graph (once, then incrementally as new triples arrive).
SELECT pg_ripple.embed_entities();

---

LangChain

The cleanest integration is a Tool that calls rag_context() and a second Tool that calls sparql_from_nl() for fact-style answers.

from langchain.tools import Tool
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
import psycopg

DB_URL = "postgresql://..."

def graph_context(question: str) -> str:
    """Retrieve graph context for a question from the knowledge graph."""
    with psycopg.connect(DB_URL) as conn:
        cur = conn.cursor()
        cur.execute("SELECT pg_ripple.rag_context(%s, 8)", (question,))
        return cur.fetchone()[0]


def graph_query(sparql: str) -> str:
    """Execute a SPARQL query against the knowledge graph and return results as JSON."""
    with psycopg.connect(DB_URL) as conn:
        cur = conn.cursor()
        cur.execute("SELECT jsonb_agg(row_to_json(r)) FROM pg_ripple.sparql(%s) r", (sparql,))
        result = cur.fetchone()[0]
        return str(result) if result else "No results."


def nl_to_sparql_and_run(question: str) -> str:
    """Convert a natural-language question to SPARQL and run it."""
    with psycopg.connect(DB_URL) as conn:
        cur = conn.cursor()
        cur.execute(
            "SELECT jsonb_agg(row_to_json(r)) FROM "
            "pg_ripple.sparql(pg_ripple.sparql_from_nl(%s)) r",
            (question,)
        )
        result = cur.fetchone()[0]
        return str(result) if result else "No results."


tools = [
    Tool(name="graph_context",       func=graph_context,
         description="Retrieve rich graph context for open-ended questions."),
    Tool(name="nl_to_sparql_query",  func=nl_to_sparql_and_run,
         description="Answer precise factual questions using SPARQL auto-generation."),
]

llm    = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant with access to a knowledge graph. "
               "Use 'graph_context' for broad questions and 'nl_to_sparql_query' for specific facts."),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])
agent    = create_openai_tools_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

result = executor.invoke({"input": "Which drugs interact with insulin and should be avoided?"})
print(result["output"])

---

LlamaIndex

LlamaIndex's FunctionTool maps directly onto pg_ripple SQL calls.

from llama_index.core.tools import FunctionTool
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
import psycopg

DB_URL = "postgresql://..."


def retrieve_graph_context(question: str) -> str:
    """
    Search the knowledge graph for entities and relationships relevant to the question.
    Returns a structured text block suitable for LLM prompting.
    """
    with psycopg.connect(DB_URL) as conn:
        cur = conn.cursor()
        cur.execute("SELECT pg_ripple.rag_context(%s, 8)", (question,))
        return cur.fetchone()[0]


def sparql_fact_lookup(question: str) -> str:
    """
    Answer a precise factual question by auto-generating and executing a SPARQL query.
    Use this for questions like 'how many', 'list all', 'who is', 'what is'.
    """
    with psycopg.connect(DB_URL) as conn:
        cur = conn.cursor()
        cur.execute(
            "SELECT jsonb_agg(row_to_json(r)) FROM "
            "pg_ripple.sparql(pg_ripple.sparql_from_nl(%s)) r",
            (question,)
        )
        result = cur.fetchone()[0]
        return str(result) if result else "Query returned no results."


tools = [
    FunctionTool.from_defaults(fn=retrieve_graph_context),
    FunctionTool.from_defaults(fn=sparql_fact_lookup),
]

agent = ReActAgent.from_tools(tools, llm=OpenAI(model="gpt-4o"), verbose=True)
response = agent.chat("What are the known side effects of combining metformin with insulin?")
print(response)

---

Framework-agnostic: OpenAI tool-calling

If you are not using LangChain or LlamaIndex, use OpenAI's tool-calling API directly. This works with any framework or plain Python.

import json, psycopg, openai

DB_URL = "postgresql://..."
client = openai.OpenAI()

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "rag_context",
            "description": "Retrieve relevant context from the knowledge graph for an open-ended question.",
            "parameters": {
                "type": "object",
                "properties": {
                    "question": {"type": "string"},
                    "k":        {"type": "integer", "default": 8,
                                 "description": "Number of entities to retrieve."}
                },
                "required": ["question"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "sparql_fact_lookup",
            "description": "Answer a precise factual question using auto-generated SPARQL.",
            "parameters": {
                "type": "object",
                "properties": {"question": {"type": "string"}},
                "required": ["question"],
            },
        },
    },
]


def dispatch(tool_name: str, args: dict) -> str:
    with psycopg.connect(DB_URL) as conn:
        cur = conn.cursor()
        if tool_name == "rag_context":
            cur.execute("SELECT pg_ripple.rag_context(%s, %s)", (args["question"], args.get("k", 8)))
            return cur.fetchone()[0]
        elif tool_name == "sparql_fact_lookup":
            cur.execute(
                "SELECT jsonb_agg(row_to_json(r)) FROM "
                "pg_ripple.sparql(pg_ripple.sparql_from_nl(%s)) r",
                (args["question"],)
            )
            result = cur.fetchone()[0]
            return str(result) if result else "No results."
    return "Unknown tool."


def agent_loop(question: str, max_turns: int = 5) -> str:
    messages = [{"role": "user", "content": question}]
    for _ in range(max_turns):
        response = client.chat.completions.create(
            model="gpt-4o", messages=messages, tools=TOOLS, tool_choice="auto"
        )
        msg = response.choices[0].message
        messages.append(msg)
        if msg.tool_calls:
            for call in msg.tool_calls:
                result = dispatch(call.function.name, json.loads(call.function.arguments))
                messages.append({
                    "role": "tool", "tool_call_id": call.id, "content": result
                })
        else:
            return msg.content
    return "Max turns reached."


print(agent_loop("Which drugs interact with insulin and should be avoided?"))

---

Tips for production agents

• Cache rag_context() results per question hash (most questions repeat). A Redis or PostgreSQL cache in front of the tool call cuts LLM costs and latency significantly.
• Set pg_ripple.sparql_query_timeout to bound runaway auto-generated SPARQL queries.
• Use few-shot examples (pg_ripple.add_llm_example()) for domain-specific vocabularies — reduces the NL→SPARQL error rate dramatically for specialised graphs.
• Log tool call results to _pg_ripple.audit_log (enabled by default when audit_log_enabled = on) — every RAG retrieval is then auditable, which matters for regulated industries.
• Multi-tenant: apply graph RLS on the PostgreSQL connection used by each tenant's agent session — rag_context() respects RLS automatically.

---

What is coming in v1.1.0

• Native LangChain BaseTool and LlamaIndex QueryEngineTool wrappers published to PyPI as pg-ripple-langchain and pg-ripple-llamaindex.
• Streaming tool results via pg_ripple cursor API (useful for large graph context blocks).
• Graph-aware conversation memory: store conversation history as RDF triples so the agent can reason over past interactions.

---

See also

• AI Overview — which AI feature to use when.
• RAG Pipeline — rag_context() deep dive.
• NL → SPARQL — sparql_from_nl() and few-shot tuning.
• Cookbook: Grounded Chatbot — simpler single-agent recipe.

Use Case Cookbook

The chapters under Feature Deep Dives explain what each pg_ripple feature does. The recipes in this cookbook explain what you can do with the features chained together. Each recipe is a self-contained story: a real-world goal, the step-by-step SQL, and the trade-offs to be aware of.

If you are evaluating pg_ripple, start here — these are the patterns that decide whether the technology fits your problem.

Cookbook: Knowledge Graph from a Relational Catalogue

Goal. You have a working PostgreSQL schema for, say, a product catalogue. You want a queryable RDF graph that stays in sync with that schema, validates the output, and lets analysts answer relationship questions in SPARQL.

Why pg_ripple. Both schemas live in the same database. There is no ETL job, no eventual consistency, and a single SHACL contract guards the output.

Time to first result. ~15 minutes.

---

What you build

   relational tables                 RDF triples                SPARQL clients
   ─────────────────                 ───────────                ──────────────
   product (id, name, …)   ──┐      <…/product/42> a Product
   category (id, parent_id) ──┼──►  <…/product/42> in <…/category/7>      ──►  pg_ripple.sparql(...)
   inventory (sku, qty)    ──┘      <…/product/42> sku "WIDGET-1"              "all out-of-stock products
                                    <…/category/7> parent <…/category/3>        in the toy hierarchy"
                                    …
                                              ▲
                                              │
                                       SHACL validation
                                       fires on every load

---

Step 1 — The relational source

CREATE TABLE category (
    id        SERIAL PRIMARY KEY,
    name      TEXT NOT NULL,
    parent_id INT REFERENCES category(id)
);

CREATE TABLE product (
    id          SERIAL PRIMARY KEY,
    sku         TEXT UNIQUE NOT NULL,
    name        TEXT NOT NULL,
    category_id INT REFERENCES category(id),
    price_cents INT
);

CREATE TABLE inventory (
    product_id INT REFERENCES product(id),
    qty        INT NOT NULL DEFAULT 0
);

Populate it with a few rows; the recipe doesn't care about the data.

Step 2 — Define the R2RML mapping

SELECT pg_ripple.r2rml_load($TTL$
@prefix rr:    <http://www.w3.org/ns/r2rml#> .
@prefix ex:    <https://example.org/cat/> .
@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
@prefix schema:<https://schema.org/> .
@prefix skos:  <http://www.w3.org/2004/02/skos/core#> .

<#CategoryMap>
    rr:logicalTable [ rr:tableName "category" ] ;
    rr:subjectMap   [ rr:template "https://example.org/cat/{id}" ;
                      rr:class    skos:Concept ] ;
    rr:predicateObjectMap [ rr:predicate skos:prefLabel ; rr:objectMap [ rr:column "name" ] ] ;
    rr:predicateObjectMap [ rr:predicate skos:broader   ;
                            rr:objectMap [ rr:template "https://example.org/cat/{parent_id}" ;
                                           rr:termType rr:IRI ] ] .

<#ProductMap>
    rr:logicalTable [ rr:tableName "product" ] ;
    rr:subjectMap   [ rr:template "https://example.org/product/{id}" ;
                      rr:class    schema:Product ] ;
    rr:predicateObjectMap [ rr:predicate schema:sku   ; rr:objectMap [ rr:column "sku" ] ] ;
    rr:predicateObjectMap [ rr:predicate schema:name  ; rr:objectMap [ rr:column "name" ] ] ;
    rr:predicateObjectMap [ rr:predicate schema:category ;
                            rr:objectMap [ rr:template "https://example.org/cat/{category_id}" ;
                                           rr:termType rr:IRI ] ] ;
    rr:predicateObjectMap [ rr:predicate schema:price ;
                            rr:objectMap [ rr:column "price_cents" ;
                                           rr:datatype xsd:integer ] ] .

<#InventoryMap>
    rr:logicalTable [ rr:sqlQuery "SELECT product_id, qty FROM inventory" ] ;
    rr:subjectMap   [ rr:template "https://example.org/product/{product_id}" ] ;
    rr:predicateObjectMap [ rr:predicate <https://example.org/onHand> ;
                            rr:objectMap [ rr:column "qty" ; rr:datatype xsd:integer ] ] .
$TTL$);

Step 3 — Define a SHACL contract

This is the single most underappreciated trick in this recipe. The shape encodes the intended shape of the output. If the source schema drifts (a column is renamed, a foreign key is dropped), the SHACL run flags it immediately.

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:    <http://www.w3.org/ns/shacl#> .
@prefix schema:<https://schema.org/> .
@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
@prefix ex:    <https://example.org/> .

<https://shapes.example.org/ProductShape> a sh:NodeShape ;
    sh:targetClass schema:Product ;
    sh:property [ sh:path schema:sku   ; sh:minCount 1 ; sh:maxCount 1 ] ;
    sh:property [ sh:path schema:name  ; sh:minCount 1 ; sh:datatype xsd:string ] ;
    sh:property [ sh:path schema:category ; sh:minCount 1 ; sh:nodeKind sh:IRI ] ;
    sh:property [ sh:path schema:price ; sh:datatype xsd:integer ; sh:minInclusive 0 ] ;
    sh:property [ sh:path ex:onHand    ; sh:maxCount 1 ; sh:datatype xsd:integer ] .
$TTL$);

ALTER SYSTEM SET pg_ripple.shacl_mode = 'sync';
SELECT pg_reload_conf();

Step 4 — Re-run incrementally

Schedule the R2RML load to run after every relational ETL pass. Because the dictionary IDs are deterministic, repeated loads are idempotent — only changed rows generate new triples.

-- Cron job, once per minute:
SELECT pg_ripple.r2rml_reload();   -- shorthand: re-runs the most recent r2rml_load()
SELECT * FROM pg_ripple.shacl_validate() LIMIT 10;

If shacl_validate() returns rows, the relational source has drifted and an alert fires.

Step 5 — Query in SPARQL

SELECT * FROM pg_ripple.sparql($$
    PREFIX schema: <https://schema.org/>
    PREFIX skos:   <http://www.w3.org/2004/02/skos/core#>
    PREFIX ex:     <https://example.org/>

    # Out-of-stock products in the "Toys" hierarchy.
    SELECT ?sku ?name WHERE {
        ?p a schema:Product ;
           schema:sku ?sku ;
           schema:name ?name ;
           schema:category/skos:broader* <https://example.org/cat/toys> ;
           ex:onHand 0 .
    }
$$);

The skos:broader* property path walks the category hierarchy with no recursion-depth cap. Try expressing that in pure SQL and you will rediscover why graph queries exist.

---

Variations

• Multi-source. Add a rr:graphMap to each map so triples land in per-source named graphs (https://example.org/source/postgres-prod). Then Multi-Tenant Graphs gives you per-source RLS.
• Soft delete. Replace rr:tableName with an rr:sqlQuery that filters out deleted_at IS NOT NULL. Re-runs will remove the corresponding triples.
• Foreign-data wrapper. rr:tableName accepts foreign tables, so you can ingest a remote PostgreSQL or MySQL schema without copying data.

---

See also

• R2RML
• Validating Data Quality

Cookbook: Chatbot Grounded in a Knowledge Graph

Goal. Build an LLM-powered question-answering assistant that uses your knowledge graph as the source of truth, not the LLM's training data. Hallucinations drop dramatically; every answer is traceable to real triples.

Why pg_ripple. A single SQL function call (rag_context()) returns an LLM-ready prompt that fuses vector recall, graph expansion, and (optionally) executed SPARQL. No vector store to keep in sync, no orchestration framework to deploy.

Time to first result. ~10 minutes.

---

The pipeline

   user question                                   LLM response
        │                                                ▲
        ▼                                                │
   ┌─────────────────────────────────────────────────────┴───────┐
   │  application code (Python / TS / Go)                        │
   │      ┌─────────────────────────────────────────────────┐    │
   │      │  context = pg_ripple.rag_context(question, k=8) │    │
   │      │  prompt  = SYSTEM_PROMPT + context + question   │    │
   │      │  answer  = openai.chat(prompt)                  │    │
   │      └─────────────────────────────────────────────────┘    │
   └─────────────────────────────────────────────────────────────┘
                                                            ▲
                                                            │
                                                       LLM API

rag_context() does the four things every RAG pipeline must do, all inside one PostgreSQL transaction:

1. Embed the user question (HTTP call to your embedding endpoint).
2. HNSW cosine search to retrieve the top-k matching entities.
3. SPARQL graph expansion to gather each entity's 1-hop neighbourhood.
4. Assemble the context as JSON-LD or plain text.

---

Step 1 — Configure the LLM and embedding endpoints

ALTER SYSTEM SET pg_ripple.embedding_api_url     = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.embedding_api_key_env = 'OPENAI_API_KEY';
ALTER SYSTEM SET pg_ripple.embedding_model       = 'text-embedding-3-small';

ALTER SYSTEM SET pg_ripple.llm_endpoint          = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.llm_api_key_env       = 'OPENAI_API_KEY';
ALTER SYSTEM SET pg_ripple.llm_model             = 'gpt-4o';

SELECT pg_reload_conf();

API keys are read from environment variables at call time and are never stored in the database.

Step 2 — Load and embed your knowledge graph

-- Load whatever you have. Could be a Turtle file, an R2RML mapping, GraphRAG output, …
SELECT pg_ripple.load_turtle_file('/data/medical_kb.ttl');

-- (Recommended) materialise OWL RL inference so 'subClassOf' chains are visible.
SELECT pg_ripple.load_rules_builtin('owl-rl');
SELECT pg_ripple.infer('owl-rl');

-- Embed every labelled entity. Run once after each big load.
SELECT pg_ripple.embed_entities();

For very large graphs, set pg_ripple.use_graph_context = on so each entity's embedding input includes its 1-hop neighbours — recall jumps significantly on entities whose labels alone are ambiguous.

Step 3 — Retrieve context for a question

SELECT pg_ripple.rag_context(
    question := 'What drugs treat moderate hypertension?',
    k        := 8
);

Returns a single TEXT block, ready to drop into a prompt:

You are answering using the following knowledge graph context:

ENTITY: <https://example.org/lisinopril>
  type: Drug, ACEInhibitor
  rdfs:label: "Lisinopril"
  ex:treats: Hypertension, HeartFailure
  ex:contraindication: Pregnancy

ENTITY: <https://example.org/amlodipine>
  type: Drug, CalciumChannelBlocker
  ...

Step 4 — Combine with NL→SPARQL for fact-style answers

For questions where the answer is a small, well-defined set ("how many", "list the", "who is"), have the LLM also generate a SPARQL query that extracts the precise answer:

SELECT pg_ripple.sparql_from_nl(
    'How many drugs in the knowledge graph treat hypertension?'
);
-- Returns a parsed, validated SPARQL string.

-- Then execute it.
SELECT * FROM pg_ripple.sparql(
    pg_ripple.sparql_from_nl(
        'How many drugs in the knowledge graph treat hypertension?'
    )
);

When pg_ripple.llm_endpoint is set, rag_context() does this automatically: the assembled context includes both the vector-retrieved neighbourhood and the result rows of the auto-generated SPARQL query.

Step 5 — Wire it into your application

import psycopg
import openai

SYSTEM_PROMPT = """
You are a medical information assistant. Answer ONLY using the
knowledge graph context provided. If the answer is not in the
context, say "I do not have that information." Cite IRIs of
entities you reference.
""".strip()

def answer(question: str) -> str:
    with psycopg.connect("...") as conn:
        cur = conn.cursor()
        cur.execute("SELECT pg_ripple.rag_context(%s, 8)", (question,))
        context = cur.fetchone()[0]
    prompt = f"{SYSTEM_PROMPT}\n\n=== CONTEXT ===\n{context}\n\n=== QUESTION ===\n{question}"
    resp = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.0,
    )
    return resp.choices[0].message.content

---

Tuning

---

Why this beats a separate vector DB

• One transaction. Loading new triples and updating embeddings happens atomically. There is no half-updated vector store after a crash.
• No drift. A separate vector DB has its own schema; over months, the two diverge. Here there is one schema, one source of truth.
• Multi-tenant by default. Apply graph RLS and the same rag_context() call returns tenant-scoped context with no application-level filter.
• Audit-ready. Enable audit_log_enabled and every RAG-time UPDATE is captured. A separate vector DB cannot do that.

---

See also

• AI Overview
• RAG Pipeline reference
• NL → SPARQL

Cookbook: Deduplicate Customer Records Across Systems

Goal. Two source systems each hold a list of customers. Some customers are in both, with subtle differences (Robert Smith vs Bob Smith, JaneDoe vs Jane Q. Doe). You want a unified view in which each real-world customer appears as one entity, while the original records remain auditable.

Why pg_ripple. Combines knowledge-graph embeddings (high recall), SHACL hard rules (safe), and owl:sameAs canonicalization (transparent at query time) — the three pieces a record-linkage pipeline needs, with no external services.

Time to first result. ~20 minutes.

This recipe is the practical flavour of Record Linkage and Entity Resolution. Read that page first for the strategic background.

---

Step 1 — Load both sources into named graphs

Named graphs preserve the original provenance of every record.

SELECT pg_ripple.load_turtle_into_graph('https://example.org/source/crm', $TTL$
@prefix ex:   <https://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:crm/c1 foaf:name "Robert Smith"  ; foaf:mbox <mailto:rob@x.com> ; ex:dob "1985-03-12"^^<http://www.w3.org/2001/XMLSchema#date> .
ex:crm/c2 foaf:name "Jane Doe"      ; foaf:mbox <mailto:jane@x.com>; ex:dob "1990-07-09"^^<http://www.w3.org/2001/XMLSchema#date> .
$TTL$);

SELECT pg_ripple.load_turtle_into_graph('https://example.org/source/erp', $TTL$
@prefix ex:   <https://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:erp/c1 foaf:name "Bob Smith"     ; foaf:mbox <mailto:rob@x.com> ; ex:dob "1985-03-12"^^<http://www.w3.org/2001/XMLSchema#date> .
ex:erp/c2 foaf:name "Jane Q. Doe"   ; foaf:mbox <mailto:j.doe@x.com>; ex:dob "1990-07-09"^^<http://www.w3.org/2001/XMLSchema#date> .
ex:erp/c3 foaf:name "Carl Larsen"   ; foaf:mbox <mailto:carl@y.com>; ex:dob "1972-11-02"^^<http://www.w3.org/2001/XMLSchema#date> .
$TTL$);

Step 2 — Add structural context

Customers gain matching power when they have related facts (purchases, addresses, interaction history). Load whatever you have. The example below uses purchases:

SELECT pg_ripple.load_turtle_into_graph('https://example.org/source/crm', $TTL$
@prefix ex: <https://example.org/> .
ex:crm/c1 ex:purchased ex:product/widget1, ex:product/widget2 .
ex:crm/c2 ex:purchased ex:product/widget3 .
$TTL$);

SELECT pg_ripple.load_turtle_into_graph('https://example.org/source/erp', $TTL$
@prefix ex: <https://example.org/> .
ex:erp/c1 ex:purchased ex:product/widget1, ex:product/widget4 .
ex:erp/c2 ex:purchased ex:product/widget3, ex:product/widget5 .
$TTL$);

Step 3 — Generate candidate pairs

Run both text and KGE candidate generators, then union the results. They catch different mistakes.

-- Text-embedding candidates.
SELECT pg_ripple.embed_entities();

CREATE TEMP TABLE candidates AS
SELECT s1, s2, similarity, 'text' AS source
FROM pg_ripple.suggest_sameas(threshold := 0.85);

-- KGE candidates.
SET pg_ripple.kge_enabled = on;
SELECT pg_ripple.kge_train(model := 'TransE', epochs := 100);

INSERT INTO candidates
SELECT s1, s2, similarity, 'kge'
FROM pg_ripple.find_alignments(
    source_graph := 'https://example.org/source/crm',
    target_graph := 'https://example.org/source/erp',
    threshold    := 0.85
);

SELECT * FROM candidates ORDER BY similarity DESC;

Step 4 — Block unsafe merges with SHACL

The dob (date of birth) is immutable and unique per person. Two records with different DOBs cannot be the same person, no matter how similar their other attributes look.

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix ex:   <https://example.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:CustomerSafetyShape a sh:NodeShape ;
    sh:targetClass foaf:Person ;
    # If owl:sameAs links two persons, their dob must agree.
    sh:property [ sh:path ex:dob ; sh:maxCount 1 ] .
$TTL$);

ALTER SYSTEM SET pg_ripple.shacl_mode = 'sync';
SELECT pg_reload_conf();

When apply_sameas_candidates() would create a violation (two dob values for the merged person), the insert is rejected — the unsafe merge cannot happen.

Step 5 — Apply the auto-merge tier

-- High-confidence pairs auto-merge.
SELECT pg_ripple.apply_sameas_candidates(min_similarity := 0.95);

-- Mid-confidence pairs go to a review table.
CREATE TABLE customer_review_queue AS
SELECT DISTINCT ON (least(s1, s2), greatest(s1, s2))
       s1, s2, max(similarity) AS similarity
FROM   candidates
WHERE  similarity BETWEEN 0.85 AND 0.95
GROUP  BY s1, s2;

SELECT * FROM customer_review_queue ORDER BY similarity DESC;

A reviewer marks pairs as accepted or rejected in customer_review_queue; an accepted row triggers:

SELECT pg_ripple.insert_triple(s1, '<http://www.w3.org/2002/07/owl#sameAs>', s2),
       pg_ripple.insert_triple(s2, '<http://www.w3.org/2002/07/owl#sameAs>', s1)
FROM   customer_review_queue WHERE status = 'accepted';

Step 6 — Query the unified graph

pg_ripple.sameas_reasoning = on (the default) means SPARQL queries see merged customers as one entity:

-- Total spend by Robert/Bob — combined across CRM and ERP.
SELECT * FROM pg_ripple.sparql($$
    PREFIX ex: <https://example.org/>
    SELECT (COUNT(?p) AS ?n) WHERE {
        <https://example.org/crm/c1> ex:purchased ?p .
    }
$$);

The query targets the CRM identifier, but sameas_reasoning rewrites it to include the ERP identifier transparently.

---

Auditing the merge

Every merge action is captured by the audit log. Combined with point_in_time, a regulator can replay exactly what the system thought at any past timestamp.

SELECT ts, role, query
FROM   _pg_ripple.audit_log
WHERE  query ILIKE '%owl:sameAs%'
ORDER  BY ts DESC
LIMIT 50;

---

See also

• Record Linkage — strategic background.
• Knowledge-Graph Embeddings
• Validating Data Quality

PPRL: Cross-Organization Entity Resolution Without Sharing Raw PII

What you'll learn: How to use bloom_encode() and pg:dice_similarity to find records that refer to the same real-world person across two organizations — without either side ever seeing the other's raw personal data.

Why This Matters

Hospitals, banks, and government agencies often need to know whether their records overlap — the same patient, account holder, or citizen appearing in both systems. Regulations (GDPR, HIPAA, CCPA) typically prohibit sharing raw identifiers like full names, dates of birth, or Social Security Numbers.

Privacy-Preserving Record Linkage (PPRL) solves this using Bloom-filter encoding: sensitive identifiers are converted into fixed-length bit vectors that support similarity comparison without revealing the underlying values.

Reference: Schnell, Bachteler & Reiher (2009) — "Privacy-preserving record linkage using Bloom filters." BMC Medical Informatics and Decision Making 9:41.

Architecture

Organization A                         Organization B
──────────────                         ──────────────
Raw PII → bloom_encode() → bloomA      Raw PII → bloom_encode() → bloomB
          |                                        |
          └──── RDF triple store ─────────────────┘
                     |
              SPARQL SERVICE federation
                     |
              FILTER(pg:dice_similarity(?bloomA, ?bloomB) > 0.85)
                     |
              Candidate matches (no raw PII exchanged)

Both organizations use the same shared secret key (established out-of-band via a secure channel — e.g., TLS-protected key agreement) so that Bloom encodings of the same value from both sides are identical.

Step 1: Encode Patient Identifiers

Each organization runs this on their own database. The shared key must match exactly between organizations.

-- Enable the extension
CREATE EXTENSION IF NOT EXISTS pg_ripple;

-- Encode a patient record. The 'shared_secret_key' must be agreed upon
-- out-of-band between the two organizations.
INSERT INTO patient_triples (subject, predicate, object)
VALUES (
    '<http://hospitalA.example.org/patient/1001>',
    '<http://pprl.example.org/nameBloom>',
    pg_ripple.bloom_encode(
        'Alice M Smith',          -- concatenate relevant fields
        'shared_secret_key',      -- must match Organization B's key
        30,                       -- hash_count (minimum recommended: 30)
        1024                      -- length in bits (minimum recommended: 1024)
    )
);

-- Store a full patient record as RDF triples
SELECT pg_ripple.insert_triple(
    '<http://hospitalA.example.org/patient/1001>',
    '<http://pprl.example.org/nameBloom>',
    pg_ripple.bloom_encode('Alice M Smith 1985-04-12', 'shared_secret_key')
);

Step 2: Run Cross-Organization Matching

Use SPARQL SERVICE federation to query both organizations simultaneously. The SPARQL pg:dice_similarity FILTER compares the Bloom filters without retrieving the underlying PII.

PREFIX pprl: <http://pprl.example.org/>
PREFIX pg:   <http://pg-ripple.org/functions/>

SELECT ?patientA ?patientB ?sim WHERE {
  -- Hospital A's Bloom-encoded identifiers (local graph)
  ?patientA pprl:nameBloom ?bloomA .

  -- Hospital B's Bloom-encoded identifiers (remote SPARQL endpoint)
  SERVICE <http://hospitalB.example.org/sparql> {
    ?patientB pprl:nameBloom ?bloomB .
  }

  -- Find candidates where Bloom filters are highly similar
  FILTER(pg:dice_similarity(?bloomA, ?bloomB) > 0.85)

  -- Compute exact similarity for ranking
  BIND(pg:dice_similarity(?bloomA, ?bloomB) AS ?sim)
}
ORDER BY DESC(?sim)

From SQL:

SELECT * FROM pg_ripple.sparql($$
    PREFIX pprl: <http://pprl.example.org/>
    PREFIX pg:   <http://pg-ripple.org/functions/>

    SELECT ?patientA ?patientB ?sim WHERE {
      ?patientA pprl:nameBloom ?bloomA .
      SERVICE <http://hospitalB.example.org/sparql> {
        ?patientB pprl:nameBloom ?bloomB .
      }
      FILTER(pg:dice_similarity(?bloomA, ?bloomB) > 0.85)
      BIND(pg:dice_similarity(?bloomA, ?bloomB) AS ?sim)
    }
    ORDER BY DESC(?sim)
$$);

Step 3: Aggregate Reporting with Differential Privacy

If you only need aggregate statistics (e.g., "approximately how many shared patients do the two organizations have?") without exposing individual identities, use dp_noisy_count():

-- Count shared patients with ε=0.1 differential privacy
SELECT pg_ripple.dp_noisy_count(
    'SELECT COUNT(DISTINCT subject) FROM _pg_ripple.vp_rare
     WHERE predicate = pg_ripple.encode_iri(''http://pprl.example.org/nameBloom'')',
    0.1  -- epsilon: smaller = more privacy, more noise
) AS approx_shared_patients;

For a histogram of match confidence buckets:

CREATE TEMP TABLE match_buckets (bucket TEXT, n BIGINT);
INSERT INTO match_buckets VALUES
    ('high (>0.9)',    42),
    ('medium (0.7-0.9)', 17),
    ('low (0.5-0.7)',  8);

SELECT * FROM pg_ripple.dp_noisy_histogram(
    'SELECT bucket, n FROM match_buckets',
    'bucket',
    'n',
    0.5  -- epsilon
);

Step 4: Datalog Rules for Entity Resolution

You can also express the matching as a Datalog rule and use incremental materialization:

SELECT pg_ripple.load_rules($$
    -- Generate candidate pairs whose Bloom filters are similar
    pprl:candidate(?x, ?y) :-
        ?x <http://pprl.example.org/nameBloom> ?bx .
        ?y <http://pprl.example.org/nameBloom> ?by .
        ?x != ?y .
        pg:dice_similarity(?bx, ?by) > 0.85 .
$$);

-- Run inference to materialize all candidate pairs
SELECT pg_ripple.infer();

Security Notes

Recommended Parameters

Using fewer than 30 hash functions or fewer than 1024 bits significantly increases the risk of re-identification through graph-based attacks (Schnell et al. 2009, §4). pg_ripple logs a WARNING when parameters fall below the recommended minimums.

Key Management

The shared secret key (key parameter) must be:

1. Agreed out-of-band — never transmitted with the Bloom-encoded data
2. Kept secret — compromised keys allow the encoded data to be reversed
3. Organization-pair-specific — use a different key for each pair of organizations to limit blast radius

What the Bloom Filter Protects Against

• Honest-but-curious adversary: Cannot infer the original value from the bit vector alone (without the key)
• Eavesdropper: Sees only bit vectors; without the key, values cannot be recovered

Known Limitations

• Bloom filters with low hash_count or small length are vulnerable to graph-based reconstruction attacks even without the key
• High-frequency values (e.g., very common names) are more susceptible to inference attacks
• CLK encodings are not quantum-resistant

Patent Status

The CLK (Cryptographic Longterm Key) construction described in Schnell et al. (2009) is published academic work with no known patent encumbrances.

Verifying Your Encoding

-- Self-test: encoding the same value twice should give Dice = 1.0
SELECT pg_ripple.dice_similarity(
    pg_ripple.bloom_encode('Alice M Smith', 'testkey', 30, 1024),
    pg_ripple.bloom_encode('Alice M Smith', 'testkey', 30, 1024)
) AS should_be_one;

-- Encoding different values should give Dice < 1.0
SELECT pg_ripple.dice_similarity(
    pg_ripple.bloom_encode('Alice M Smith', 'testkey', 30, 1024),
    pg_ripple.bloom_encode('Bob J Jones',   'testkey', 30, 1024)
) AS should_be_less_than_half;

Further Reading

• Schnell, R., Bachteler, T., & Reiher, J. (2009). Privacy-preserving record linkage using Bloom filters. BMC Medical Informatics and Decision Making, 9, 41. https://doi.org/10.1186/1472-6947-9-41
• Christen, P., Ranbaduge, T., & Schnell, R. (2020). Linking Sensitive Data: Methods and Techniques for Practical Privacy-Preserving Information Sharing. Springer.
• pg_ripple SPARQL federation guide: federation-wikidata.md
• pg_ripple differential privacy functions: pg_ripple.dp_noisy_count(), pg_ripple.dp_noisy_histogram()

Cookbook: Audit Trail with PROV-O and Temporal Queries

Goal. Build an evidence chain that lets you answer regulator questions like "on 21 March, did your system tell user X that fact Y was true? On what evidence?".

Why pg_ripple. Three composable features — point_in_time, prov_enabled, audit_log_enabled — combine into the kind of audit trail that pure-ML pipelines cannot produce. Plus RDF-star for per-fact provenance.

Time to first result. ~10 minutes.

---

Step 1 — Turn on every layer

ALTER SYSTEM SET pg_ripple.prov_enabled       = on;   -- per-load PROV-O
ALTER SYSTEM SET pg_ripple.audit_log_enabled  = on;   -- per-UPDATE log
SELECT pg_reload_conf();

The third layer — RDF-star quoted triples for per-fact confidence/source — is loaded with the data itself.

Step 2 — Load data with per-fact provenance

SELECT pg_ripple.load_turtle($TTL$
@prefix ex:   <https://example.org/> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

ex:drugA ex:interactsWith ex:drugB .

# Annotate the fact itself.
<< ex:drugA ex:interactsWith ex:drugB >>
    ex:source     <https://pubmed.example/article/12345> ;
    ex:confidence "0.92"^^xsd:decimal ;
    ex:assertedAt "2026-03-15T09:00:00Z"^^xsd:dateTime ;
    prov:wasAttributedTo ex:loader/medkb-v3 .
$TTL$);

Step 3 — Time passes and data changes

-- Several updates happen over the next month.
SELECT pg_ripple.sparql_update('
    INSERT DATA {
        <https://example.org/drugA> <https://example.org/manufacturer>
            <https://example.org/acme>
    }
');

-- A different role makes a correction.
SET ROLE editor_alice;
SELECT pg_ripple.sparql_update('
    DELETE DATA { <https://example.org/drugA> <https://example.org/manufacturer>
                  <https://example.org/acme> }
');
SELECT pg_ripple.sparql_update('
    INSERT DATA { <https://example.org/drugA> <https://example.org/manufacturer>
                  <https://example.org/acmecorp> }
');
RESET ROLE;

Step 4 — Answer the regulator

The question is: "On 21 March, did your system tell users that drug A interacts with drug B? On what evidence?"

-- 1. Replay the graph as of 21 March 12:00.
SELECT pg_ripple.point_in_time('2026-03-21 12:00:00+00');

-- 2. Re-ask the question.
SELECT * FROM pg_ripple.sparql($$
    ASK { <https://example.org/drugA>
          <https://example.org/interactsWith>
          <https://example.org/drugB> }
$$);
-- → true

-- 3. Pull the per-fact evidence (RDF-star).
SELECT * FROM pg_ripple.sparql($$
    SELECT ?source ?confidence ?assertedAt WHERE {
        << <https://example.org/drugA>
           <https://example.org/interactsWith>
           <https://example.org/drugB> >>
            <https://example.org/source>     ?source ;
            <https://example.org/confidence> ?confidence ;
            <https://example.org/assertedAt> ?assertedAt .
    }
$$);

-- 4. Pull the loader activity (PROV-O).
SELECT * FROM pg_ripple.prov_stats()
WHERE  source_file LIKE '%medkb%';

-- 5. Pull every UPDATE since the load (audit log).
SELECT ts, role, operation, query
FROM   _pg_ripple.audit_log
WHERE  ts >= '2026-03-15'
   AND query ILIKE '%drugA%'
ORDER  BY ts;

-- 6. Reset point-in-time to "now".
SELECT pg_ripple.point_in_time(NULL);

That sequence is the kind of evidence chain a regulator looks for: truth value at a point in time, evidence per fact, attribution per UPDATE.

---

Building a one-shot audit report

Wrap the queries above in a SQL function so the compliance team can run a single command:

CREATE FUNCTION audit_report(
    fact_subject  TEXT,
    fact_predicate TEXT,
    fact_object   TEXT,
    as_of         TIMESTAMPTZ
)
RETURNS TABLE (kind TEXT, payload JSONB) AS $$
BEGIN
    PERFORM pg_ripple.point_in_time(as_of);

    RETURN QUERY
        SELECT 'truth_value'::TEXT,
               jsonb_build_object('asof', as_of, 'value', (
                   SELECT bindings FROM pg_ripple.sparql(
                       format('ASK { %s %s %s }', fact_subject, fact_predicate, fact_object)
                   )
               ));

    RETURN QUERY
        SELECT 'rdf_star_evidence'::TEXT, to_jsonb(s)
        FROM   pg_ripple.sparql(format($q$
            SELECT ?p ?o WHERE {
                << %s %s %s >> ?p ?o
            }
        $q$, fact_subject, fact_predicate, fact_object)) s;

    RETURN QUERY
        SELECT 'audit_log'::TEXT, to_jsonb(a)
        FROM   _pg_ripple.audit_log a
        WHERE  ts <= as_of AND query ILIKE '%' || fact_subject || '%'
        ORDER  BY ts;

    PERFORM pg_ripple.point_in_time(NULL);
END;
$$ LANGUAGE plpgsql;

SELECT * FROM audit_report(
    '<https://example.org/drugA>',
    '<https://example.org/interactsWith>',
    '<https://example.org/drugB>',
    '2026-03-21 12:00:00+00'
);

---

See also

• Temporal & Provenance
• Audit Log
• Storing Knowledge — RDF-star

Cookbook: CDC → Kafka via JSON-LD Outbox

Goal. Push a stream of structured graph-change events into Kafka (or NATS, RabbitMQ, AWS SNS — anywhere your event bus lives), without polling the database, and using a JSON-LD payload that downstream consumers can validate against the same SHACL shapes the database uses.

Why pg_ripple. Combines CDC subscriptions (push, no polling), JSON-LD framing (schema-shaped payloads), and the transactional-outbox pattern (no lost events).

Time to first result. ~30 minutes (most of it is wiring the Kafka producer).

---

Architecture

   triple INSERT/DELETE
            │
            ▼
   ┌────────────────────────┐
   │ CDC subscription       │  pg_ripple.create_subscription('out_persons',
   │ filter: SHACL shape    │       filter_shape := '<…/PersonShape>')
   └─────────┬──────────────┘
             │ NOTIFY  ──── JSON  ─────┐
             ▼                          │
   ┌────────────────────────┐           │
   │ outbox table           │           │  alternatively, a small
   │ INSERT trigger writes  │           │  Rust/Python LISTENer
   │ JSON-LD framed payload │           │
   └─────────┬──────────────┘           │
             ▼                          ▼
   ┌────────────────────────┐  ┌────────────────────────┐
   │ Debezium / outbox      │  │ asyncpg LISTENer       │
   │ connector → Kafka      │  │ → Kafka producer       │
   └────────────────────────┘  └────────────────────────┘

Two valid implementations:

• Outbox + Debezium (recommended for at-least-once durability).
• Direct LISTEN (recommended for low-latency, fire-and-forget streams).

The recipe shows both.

---

Step 1 — Define the change shape

The simplest payload is the entire updated entity in JSON-LD framed shape, so downstream consumers see a self-contained document. Define the frame once:

SELECT pg_ripple.register_jsonld_frame('person_event', $JSON$
{
  "@context": {
    "name":  "http://xmlns.com/foaf/0.1/name",
    "email": "http://xmlns.com/foaf/0.1/mbox",
    "knows": { "@id": "http://xmlns.com/foaf/0.1/knows", "@type": "@id" }
  },
  "@type": "http://xmlns.com/foaf/0.1/Person"
}
$JSON$);

Step 2 — Create a CDC subscription

-- Optional: create a SHACL shape so the subscription only fires for valid Persons.
SELECT pg_ripple.load_shacl($TTL$
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

<https://shapes.example.org/PersonShape> a sh:NodeShape ;
    sh:targetClass foaf:Person ;
    sh:property [ sh:path foaf:name ; sh:minCount 1 ] .
$TTL$);

SELECT pg_ripple.create_subscription(
    'persons_out',
    filter_sparql := 'SELECT ?s ?p ?o WHERE { ?s a <http://xmlns.com/foaf/0.1/Person> ; ?p ?o }'
);

Step 3a — Direct-LISTEN producer

The lowest-latency path: a tiny LISTENer reads the NOTIFY stream and produces straight to Kafka.

import asyncio, json, asyncpg
from aiokafka import AIOKafkaProducer

async def main():
    conn  = await asyncpg.connect("postgresql://…")
    kafka = AIOKafkaProducer(bootstrap_servers="kafka:9092")
    await kafka.start()
    queue: asyncio.Queue = asyncio.Queue()

    def callback(_conn, _pid, _channel, payload):
        queue.put_nowait(payload)

    await conn.add_listener("pg_ripple_cdc_persons_out", callback)

    while True:
        raw = await queue.get()
        evt = json.loads(raw)
        # Optionally re-frame the changed entity as JSON-LD.
        await kafka.send_and_wait("graph.persons", raw.encode())

asyncio.run(main())

The CDC payload already includes op, s, p, o, g — see CDC subscriptions.

For full-entity payloads (rather than per-triple events), call sparql_construct_jsonld() inside the LISTENer to fetch the framed entity at the time of the change.

Step 3b — Outbox + Debezium

For at-least-once durability you want the events in a table, replicated by Debezium. Add an outbox trigger that materialises the JSON-LD payload at write time:

CREATE TABLE outbox (
    id          BIGSERIAL PRIMARY KEY,
    aggregate   TEXT NOT NULL,
    event_type  TEXT NOT NULL,
    payload     JSONB NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE OR REPLACE FUNCTION enqueue_person_event() RETURNS trigger AS $$
DECLARE
    framed JSONB;
BEGIN
    framed := pg_ripple.sparql_construct_jsonld(
        format(
            'CONSTRUCT { %s ?p ?o } WHERE { %s ?p ?o }',
            NEW.s, NEW.s
        ),
        frame_name := 'person_event'
    );
    INSERT INTO outbox (aggregate, event_type, payload)
    VALUES (NEW.s, 'PersonChanged', framed);
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- pg_ripple.cdc_events is the catch-up table written by every subscription.
CREATE TRIGGER outbox_persons
AFTER INSERT ON _pg_ripple.cdc_events
FOR EACH ROW
WHEN (NEW.subscription = 'persons_out')
EXECUTE FUNCTION enqueue_person_event();

Point Debezium at the outbox table; configure it to delete rows after publishing. The pattern is canonical and is exactly what Debezium's "outbox event router" SMT was designed for.

Step 4 — Validate consumers

The same SHACL shape that filters the CDC subscription can be shipped to downstream consumers as the contract. Consumers that read the JSON-LD payload validate it with any standard SHACL library (Python pyshacl, Java topbraid-shacl, etc.). If the contract changes, only one document changes — the <https://shapes.example.org/PersonShape> definition.

---

Failure modes and how to handle them

The outbox path is more code; in return you get the durability guarantees most production event buses expect.

---

See also

• Live Views and Subscriptions
• Exporting and Sharing — JSON-LD framing
• APIs and Integration — pg_ripple_http

Cookbook: Probabilistic Rules for Soft Constraints

Goal. You want rules that propagate confidence, not just facts. "If A is similar to B with confidence 0.9, and B is similar to C with confidence 0.85, then A is similar to C with confidence ≥ 0.85 × 0.9." Classical Datalog cannot do this; it deals in true/false. Lattice Datalog can.

Why pg_ripple. Ships built-in lattices (min, max, set, interval) and lets you register custom ones. Inference fixpoints over a lattice instead of a boolean.

Time to first result. ~10 minutes.

---

The intuition

Standard Datalog: facts are in the relation or not. There is one truth value: derived.

Lattice Datalog: facts have an associated value — a confidence, a cost, a probability, a time interval. The lattice tells the engine how to combine multiple derivations of the same fact. For confidence we use min: a derivation chain is only as confident as its weakest link.

---

Step 1 — Pick a lattice

For confidence propagation, the built-in min lattice is exactly what we want. (Top of the lattice = 1.0 = certain. Bottom = 0.0 = unknown. Multiple derivations of the same fact take the strongest — i.e. minimum of the weak-link confidences.)

If you prefer max-of-min semantics (the strongest single chain wins), build a max lattice over chains of min. The bundled min lattice is the most common starting point.

Step 2 — Encode confidence with RDF-star

Confidence is a property of a triple, so RDF-star is the natural encoding:

SELECT pg_ripple.load_turtle($TTL$
@prefix ex:  <https://example.org/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ex:alice ex:similarTo ex:bob   .
ex:bob   ex:similarTo ex:carol .
ex:carol ex:similarTo ex:dan   .

<< ex:alice ex:similarTo ex:bob   >> ex:confidence "0.90"^^xsd:decimal .
<< ex:bob   ex:similarTo ex:carol >> ex:confidence "0.85"^^xsd:decimal .
<< ex:carol ex:similarTo ex:dan   >> ex:confidence "0.95"^^xsd:decimal .
$TTL$);

Step 3 — Write a lattice rule

SELECT pg_ripple.load_rules($RULES$
# Transitive similarity: confidence is the min of the chain.
?x ex:transSimilarTo ?y :- ?x ex:similarTo ?y .

?x ex:transSimilarTo ?z :-
    ?x ex:similarTo      ?y ,
    ?y ex:transSimilarTo ?z .

# Lattice-typed binding: each derived ex:transSimilarTo carries a confidence.
@lattice ex:transSimilarTo confidence min .
$RULES$, 'similarity');

SELECT pg_ripple.infer_lattice('similarity', 'min');

The @lattice directive tells the engine: whenever a ex:transSimilarTo triple is derived, its confidence is the min of the confidences of the body atoms. The engine then iterates to a fixpoint with the lattice as the join operator.

Step 4 — Query

SELECT * FROM pg_ripple.sparql($$
    PREFIX ex: <https://example.org/>
    SELECT ?z ?conf WHERE {
        <https://example.org/alice> ex:transSimilarTo ?z .
        << <https://example.org/alice> ex:transSimilarTo ?z >> ex:confidence ?conf .
    }
    ORDER BY DESC(?conf)
$$);

?z              ?conf
ex:bob          0.90
ex:carol        0.85   (min of 0.90, 0.85)
ex:dan          0.85   (min of 0.90, 0.85, 0.95)

Note that ex:dan keeps the bottleneck of 0.85, not 0.95 × 0.85 × 0.90. That is exactly what min semantics gives you — the weakest link. If you want multiplicative propagation, register a custom lattice (next section).

Step 5 — Custom lattice for multiplicative confidence

-- The PostgreSQL aggregate that combines two confidences multiplicatively.
CREATE OR REPLACE FUNCTION conf_mul(state DOUBLE PRECISION, val DOUBLE PRECISION)
RETURNS DOUBLE PRECISION
LANGUAGE plpgsql IMMUTABLE AS $$ BEGIN RETURN COALESCE(state, 1.0) * val; END; $$;

CREATE AGGREGATE prob_join(DOUBLE PRECISION) (
    SFUNC = conf_mul, STYPE = DOUBLE PRECISION, INITCOND = '1.0'
);

SELECT pg_ripple.create_lattice(
    name    := 'probability',
    join_fn := 'prob_join',
    bottom  := '0.0'
);

SELECT pg_ripple.infer_lattice('similarity', 'probability');

Now ?dan's confidence is 0.90 × 0.85 × 0.95 = 0.726 — chain decay, not weakest-link.

---

When lattice Datalog is the right tool

• Confidence propagation (this recipe).
• Shortest path (min lattice over edge weights).
• Maximum bandwidth (max lattice over edge capacity, then min along the chain).
• Time-interval reasoning (interval lattice — "the period during which all of these are true").
• Provenance semirings (custom lattice over witness sets).

When the rule's body has only boolean conjunction and the head needs only true/false, classical Datalog is simpler. Lattice Datalog earns its complexity only when the value associated with a fact matters.

---

See also

• Lattice-Based Datalog reference
• Reasoning & Inference

Rule Libraries

Version: v0.104.0
Foundation: plans/expert-system.md §5

A rule library is a versioned, distributable package of Datalog inference rules and SHACL validation shapes. Libraries allow teams to share domain-specific reasoning logic — patient-matching rules, anti-money-laundering patterns, supply-chain constraints — without each team re-implementing the same logic from scratch.

Rule libraries are analogous to npm packages or pip packages, but for knowledge-graph reasoning.

---

Library Format

A rule library is a single Turtle (.ttl) file with the following structure:

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix pg: <http://pg-ripple.org/lib/> .
@prefix sh: <http://www.w3.org/ns/shacl#> .

# ── Required: library declaration ────────────────────────────────────────────

<urn:my-org:my-library> a pg:RuleLibrary ;
    dcterms:title       "my-library" ;
    dcterms:description "Human-readable description of what the library does." ;
    dcterms:license     <https://spdx.org/licenses/MIT.html> ;
    owl:versionInfo     "1.2.0" ;

    # ── Optional: dependencies ───────────────────────────────────────────────

    # Declare another library as a dependency (its URL or local path).
    pg:dependsOn <https://example.org/shared-library.ttl> ;

    # ── Optional: Datalog rules ──────────────────────────────────────────────

    pg:rules """
        ?x <https://schema.org/ancestor> ?z :-
            ?x <https://schema.org/parent> ?z .

        ?x <https://schema.org/ancestor> ?z :-
            ?x <https://schema.org/parent> ?y ,
            ?y <https://schema.org/ancestor> ?z .
    """ .

# ── Optional: SHACL shapes ────────────────────────────────────────────────────

<https://my-org.example/shapes/PersonShape>
    a sh:NodeShape ;
    sh:targetClass <https://schema.org/Person> ;
    sh:property [
        sh:path <https://schema.org/name> ;
        sh:minCount 1 ;
        sh:datatype <http://www.w3.org/2001/XMLSchema#string> ;
    ] .

Required metadata triples

All four of these triples must appear on the pg:RuleLibrary subject:

Optional triples

---

Installing a Library

-- Install from a local file (absolute path):
SELECT pg_ripple.install_rule_library('/opt/pg_ripple/libraries/my-library.ttl');

-- Install from an HTTPS URL:
SELECT pg_ripple.install_rule_library(
    'https://libraries.example.org/my-library-1.2.0.ttl'
);

install_rule_library returns the library name on success.

Idempotency: re-installing the same name + version is a no-op. The function returns the name without error or duplication.

Accepting non-permissive licenses

If a library carries a non-permissive license (anything other than MIT, Apache-2.0, or the PostgreSQL License), you must explicitly acknowledge this:

SELECT pg_ripple.install_rule_library(
    '/opt/libraries/gpl-library.ttl',
    accept_license => true
);

Without accept_license => true, install_rule_library raises PT0455 and exits without loading the library.

---

Listing Installed Libraries

SELECT * FROM pg_ripple.list_rule_libraries();

---

Upgrading a Library

SELECT pg_ripple.upgrade_rule_library('my-library');

upgrade_rule_library re-fetches the library from its original source_url, replaces all installed rules and shapes, and updates the version in the catalog.

PT0456: If another installed library depends on my-library, the upgrade is rejected — uninstall the dependent library first.

---

Uninstalling a Library

SELECT pg_ripple.uninstall_rule_library('my-library');

This removes:

• All Datalog rules for the library's rule set name.
• All SHACL shapes loaded from the library's Turtle file.
• The catalog row in _pg_ripple.rule_libraries.

PT0456: Rejected when another installed library declares my-library as a dependency. Uninstall the dependent library first.

---

REST API

The pg_ripple_http companion service exposes a read-only endpoint:

GET /rule-libraries
Authorization: Bearer <token>

Returns a JSON array of installed library objects:

[
  {
    "name": "my-library",
    "version": "1.2.0",
    "installed_at": "2026-05-10 12:00:00",
    "description": "Human-readable description.",
    "license_iri": "https://spdx.org/licenses/MIT.html"
  }
]

---

Dependency Resolution

Dependencies declared with pg:dependsOn are resolved recursively in topological order: dependency libraries are installed before the library that requires them.

Constraints:

• Dependency graphs must be acyclic. Cycles raise PT0453.
• Only single-version dependencies are supported — no semver ranges.
• If a declared dependency URL cannot be fetched, PT0454 is raised.

---

License Requirements

pg_ripple distinguishes permissive from non-permissive licenses:

Operator responsibilities

Before installing a library with accept_license => true:

1. Read the license text at the SPDX IRI.
2. Consult your legal team if the library will be used in a commercial product or distributed as part of a service.
3. Document the accepted license decision in your change-management log.
4. Review the library content — pg_ripple does not audit library rules for correctness, safety, or regulatory compliance.

pg_ripple does not provide legal advice. The accept_license flag is a technical confirmation mechanism, not a legal guarantee.

---

SSRF Protection

URL-based library sources are validated against the federation SSRF allowlist before any network request is made. The check follows the same policy as SERVICE endpoints in SPARQL queries:

• default-deny (default): blocks RFC-1918, loopback, link-local addresses.
• allowlist: only URLs listed in pg_ripple.federation_allowed_endpoints.
• open: no restrictions (development/testing only).

A blocked URL raises PT0452.

---

Authoring a Library

1. Write the Turtle file

Follow the Library Format above. Rules must be valid pg_ripple Datalog syntax — test them with pg_ripple.load_rules() first.

2. Validate locally

# Test rule syntax:
psql -c "SELECT pg_ripple.load_rules(\$\$<rules here>\$\$, 'test')"

# Test install from local path:
psql -c "SELECT pg_ripple.install_rule_library('/path/to/my-library.ttl')"

# Verify it appears in the catalog:
psql -c "SELECT * FROM pg_ripple.list_rule_libraries()"

# Uninstall after testing:
psql -c "SELECT pg_ripple.uninstall_rule_library('my-library')"

3. Publish

Rule libraries can be published:

• As files on an HTTPS server.
• As GitHub releases with raw URLs.
• As OCI artifacts or Helm config maps (for Kubernetes deployments).

There is no central registry — operators install from any URL or local path they trust.

4. Versioning

Use semantic versioning (MAJOR.MINOR.PATCH) in owl:versionInfo. When you release a new version, update the Turtle file and re-publish. Users upgrade with upgrade_rule_library().

---

Error Reference

---

Relationship to Built-in Bundles

pg_ripple ships with several built-in bundles (SKOS, OWL RL, RDFS, DCTERMS, Schema.org, FOAF) accessible via load_datalog_bundle() and load_shape_bundle(). These are compiled into the extension binary.

External rule libraries (this feature) are the user-extensible counterpart: they are Turtle files loaded at runtime and stored in the _pg_ripple.rule_libraries catalog.

The two systems coexist. A rule library may declare a built-in bundle as a dependency using pg:dependsOn "skos" — install_rule_library will activate the bundle via load_datalog_bundle() before loading the library's own rules.

Library names that collide with built-in bundle names are rejected with PT0459.

Cookbook: SPARQL Repair Workflow

Goal. Build an iterative loop where an LLM proposes a SPARQL query, pg_ripple tells it what went wrong (parse error, missing prefix, no rows, schema mismatch), and the LLM tries again. Most "no result" cases self-heal in one or two iterations.

Why pg_ripple. sparql_from_nl() and explain_sparql() were designed to compose. Combine them with the error catalog and you get an automated SPARQL pair-programmer.

Time to first result. ~10 minutes.

---

The loop

   user question (NL)
        │
        ▼
   sparql_from_nl(question)
        │
        ├── parse fails (PT702) ──► describe error → LLM retry
        │
        ▼
   sparql(query)
        │
        ├── exception (PT…)     ──► describe error → LLM retry
        │
        ▼
   row count == 0 ?
        │
        ├── yes ──► explain_sparql(query, analyze:=true) → LLM retry
        │
        ▼
   answer

Maximum iterations: 3. Anything worse than that is usually a data-quality problem and should escalate to a human.

---

Step 1 — Configure NL → SPARQL

ALTER SYSTEM SET pg_ripple.llm_endpoint    = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.llm_api_key_env = 'OPENAI_API_KEY';
ALTER SYSTEM SET pg_ripple.llm_model       = 'gpt-4o';
ALTER SYSTEM SET pg_ripple.llm_include_shapes = on;
SELECT pg_reload_conf();

llm_include_shapes = on ships your active SHACL shapes with every prompt — the LLM sees the schema and produces queries that respect it.

Step 2 — Add few-shot examples for your vocabulary

SELECT pg_ripple.add_llm_example(
    'List all proteins that interact with insulin',
    'PREFIX bio: <https://bio.example/>
     SELECT ?p WHERE {
       ?p a bio:Protein ; bio:interactsWith bio:Insulin .
     }'
);

Five to ten examples per domain is usually enough.

Step 3 — The repair function

CREATE OR REPLACE FUNCTION sparql_repair(question TEXT, max_attempts INT DEFAULT 3)
RETURNS TABLE (attempt INT, query TEXT, status TEXT, rows JSONB) AS $$
DECLARE
    q TEXT;
    feedback TEXT := '';
    n INT := 0;
    err TEXT;
    row_count INT;
    out_rows JSONB;
BEGIN
    LOOP
        n := n + 1;
        EXIT WHEN n > max_attempts;

        -- 1. Generate a query.
        BEGIN
            q := pg_ripple.sparql_from_nl(question || E'\n' || feedback);
        EXCEPTION WHEN OTHERS THEN
            feedback := format('Previous attempt failed to generate SPARQL: %s. Try again.', SQLERRM);
            CONTINUE;
        END;

        -- 2. Try to execute it.
        BEGIN
            SELECT count(*), jsonb_agg(s) INTO row_count, out_rows
            FROM   pg_ripple.sparql(q) s;
        EXCEPTION WHEN OTHERS THEN
            err := SQLERRM;
            attempt := n; query := q; status := 'parse_or_runtime_error: ' || err;
            rows := NULL;
            RETURN NEXT;
            feedback := format('Previous SPARQL caused error: %s. The query was: %s', err, q);
            CONTINUE;
        END;

        -- 3. If empty, ask the LLM to broaden.
        IF row_count = 0 THEN
            attempt := n; query := q; status := 'empty_result_set'; rows := NULL;
            RETURN NEXT;
            feedback := format(
                'Previous query returned zero rows: %s. Loosen FILTERs or remove restrictive prefixes.',
                q
            );
            CONTINUE;
        END IF;

        -- 4. 
        attempt := n; query := q; status := 'ok'; rows := out_rows;
        RETURN NEXT;
        RETURN;
    END LOOP;
END;
$$ LANGUAGE plpgsql;

Step 4 — Use it

SELECT * FROM sparql_repair('Which proteins interact with the gene encoding insulin?');

Output:

attempt | query                                           | status                 | rows
--------+-------------------------------------------------+------------------------+-----
1       | SELECT ?p WHERE { ?p bio:interactsWith ...      | parse_or_runtime_error | NULL
2       | PREFIX bio: <https://bio.example/> SELECT ...   | empty_result_set       | NULL
3       | PREFIX bio: <https://bio.example/> SELECT ...   | ok                     | [...]

Three attempts, automated. The user gets the right answer; the audit log captures every attempted query for later analysis.

---

Telemetry

Wire sparql_repair() into your application telemetry:

• Average attempts per question — > 2 means you need more few-shot examples.
• Most common error code — likely a vocabulary gap.
• Retry depth — > 3 means the LLM is going in circles; escalate to a human.

---

Hardening

• Set pg_ripple.sparql_max_algebra_depth to reject pathological generated queries before they execute.
• Set pg_ripple.sparql_query_timeout so a bad generation cannot wedge the database.
• Cache successful (question → query) pairs — the LLM does not need to be called for repeats.

---

See also

• NL → SPARQL
• SPARQL Query Debugger — explain_sparql
• Error catalog

Cookbook: Ontology Mapping and Alignment

Goal. You import data from an external dataset (Wikidata, schema.org, an industry vocabulary) and want it to align with your internal ontology — same concepts, different IRIs. Manual mapping is tedious; KGE-driven candidate generation plus SHACL gates plus owl:sameAs canonicalization makes the job tractable.

Why pg_ripple. Composes the same building blocks as record linkage, but applied to classes and properties instead of individuals.

Time to first result. ~25 minutes.

---

The challenge

Your internal ontology calls a person intkb:Employee. Wikidata calls them wd:Q5 (human). Schema.org calls them schema:Person. None of these is wrong — they describe overlapping but not identical concepts. You want SPARQL queries to transparently see them as the same class for retrieval, but you also want to retain the source-specific axioms.

---

Step 1 — Load all three vocabularies

-- Internal ontology.
SELECT pg_ripple.load_turtle_into_graph('https://example.org/ontologies/intkb', $TTL$
@prefix intkb: <https://intkb.example/> .
@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .

intkb:Employee  rdfs:label "Employee" ;
                rdfs:comment "An employee of the organisation" .
intkb:Department rdfs:label "Department" .
intkb:reports   rdfs:label "reports to" .
$TTL$);

-- Schema.org subset.
SELECT pg_ripple.load_turtle_file_into_graph(
    'https://example.org/ontologies/schemaorg', '/data/schemaorg-people.ttl');

-- Wikidata subset.
SELECT pg_ripple.load_turtle_file_into_graph(
    'https://example.org/ontologies/wikidata',  '/data/wikidata-people.ttl');

Step 2 — Train KGE across all three

SET pg_ripple.kge_enabled = on;
SELECT pg_ripple.kge_train(model := 'RotatE', dimensions := 200, epochs := 200);

RotatE is preferred for ontology alignment because it captures inverse and symmetric patterns common in owl:inverseOf axioms.

Step 3 — Generate candidate alignments

SELECT * FROM pg_ripple.find_alignments(
    source_graph := 'https://example.org/ontologies/intkb',
    target_graph := 'https://example.org/ontologies/schemaorg',
    threshold    := 0.85
)
ORDER BY similarity DESC;

-- Same against Wikidata.
SELECT * FROM pg_ripple.find_alignments(
    source_graph := 'https://example.org/ontologies/intkb',
    target_graph := 'https://example.org/ontologies/wikidata',
    threshold    := 0.85
)
ORDER BY similarity DESC;

Step 4 — Gate with structural SHACL

You only want to align classes with classes and properties with properties. A SHACL shape blocks cross-kind alignment errors:

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:  <http://www.w3.org/ns/shacl#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

# An owl:equivalentClass link must point Class → Class.
[] a sh:NodeShape ;
   sh:targetSubjectsOf owl:equivalentClass ;
   sh:property [ sh:path rdf:type ; sh:hasValue owl:Class ] .

# An owl:equivalentProperty link must point Property → Property.
[] a sh:NodeShape ;
   sh:targetSubjectsOf owl:equivalentProperty ;
   sh:property [ sh:path rdf:type ;
                 sh:in ( owl:ObjectProperty owl:DatatypeProperty owl:AnnotationProperty ) ] .
$TTL$);

ALTER SYSTEM SET pg_ripple.shacl_mode = 'sync';
SELECT pg_reload_conf();

Step 5 — Apply alignments

For exact equivalences, use owl:equivalentClass / owl:equivalentProperty. For broader relationships, use rdfs:subClassOf / rdfs:subPropertyOf. The OWL 2 RL rule set will then propagate inferences in both directions.

-- High-confidence exact equivalences.
SELECT pg_ripple.insert_triple(
    s1, '<http://www.w3.org/2002/07/owl#equivalentClass>', s2
)
FROM pg_ripple.find_alignments(
    'https://example.org/ontologies/intkb',
    'https://example.org/ontologies/schemaorg', 0.95);

-- Mid-confidence: subclass instead of equivalent.
SELECT pg_ripple.insert_triple(
    s1, '<http://www.w3.org/2000/01/rdf-schema#subClassOf>', s2
)
FROM pg_ripple.find_alignments(
    'https://example.org/ontologies/intkb',
    'https://example.org/ontologies/schemaorg', 0.85)
WHERE similarity < 0.95;

Step 6 — Materialise the inference

SELECT pg_ripple.load_rules_builtin('owl-rl');
SELECT pg_ripple.infer('owl-rl');

After this, a SPARQL query for ?p a schema:Person returns every entity that is intkb:Employee (and vice versa for the equivalent classes) with no application-level glue.

---

Choosing equivalence vs subclass

A bidirectional owl:equivalentClass is a strong claim — both classes have exactly the same instances. If the source vocabularies disagree on edge cases (e.g. minor employee vs human), the weaker rdfs:subClassOf is safer.

---

See also

• Knowledge-Graph Embeddings
• OWL 2 Profiles
• Record Linkage — the individual counterpart to ontology alignment.

Cookbook: LLM Workflow — Natural Language to Knowledge Graph Answer

Goal. Build a complete end-to-end workflow where a user asks a question in plain English, an LLM generates a SPARQL query, the query runs against your knowledge graph, and the results are returned to the user as a fluent natural-language answer.

Why pg_ripple. All four steps run inside one SQL call chain — from NL question to SPARQL to result to summarised answer. No separate orchestration layer required.

Time to first result. ~10 minutes.

---

The four-step workflow

   User question (NL)
          │
          ▼
   sparql_from_nl()   ← LLM generates SPARQL from your schema + few-shot examples
          │
          ▼
   sparql()           ← execute the SPARQL against the VP tables
          │
          ▼
   sparql_construct_turtle()  ← optionally fetch the context subgraph as Turtle
          │
          ▼
   LLM summarises results into a fluent answer

pg_ripple handles steps 1–3 natively. Step 4 is your LLM call.

---

Step 1 — Set up the LLM endpoint

ALTER SYSTEM SET pg_ripple.llm_endpoint    = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.llm_api_key_env = 'OPENAI_API_KEY';
ALTER SYSTEM SET pg_ripple.llm_model       = 'gpt-4o';

-- (Optional) embed entities for vector-assisted SPARQL generation.
ALTER SYSTEM SET pg_ripple.embedding_api_url     = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.embedding_api_key_env = 'OPENAI_API_KEY';
ALTER SYSTEM SET pg_ripple.embedding_model       = 'text-embedding-3-small';

SELECT pg_reload_conf();

Step 2 — Load a sample graph

SELECT pg_ripple.load_turtle($TTL$
@prefix ex:     <https://example.org/> .
@prefix schema: <https://schema.org/> .

ex:Alice  a schema:Person ;
    schema:name     "Alice Smith" ;
    schema:jobTitle "Senior Engineer" ;
    schema:knows    ex:Bob .

ex:Bob  a schema:Person ;
    schema:name     "Bob Jones" ;
    schema:jobTitle "Data Scientist" ;
    schema:knows    ex:Carol .

ex:Carol  a schema:Person ;
    schema:name     "Carol Kim" ;
    schema:jobTitle "VP Engineering" .
$TTL$);

Step 3 — Add few-shot examples (recommended)

Domain-specific examples dramatically improve sparql_from_nl accuracy:

SELECT pg_ripple.add_llm_example(
    'Who does Alice know?',
    'PREFIX ex: <https://example.org/>
     PREFIX schema: <https://schema.org/>
     SELECT ?name WHERE {
         ex:Alice schema:knows ?p .
         ?p schema:name ?name .
     }'
);

SELECT pg_ripple.add_llm_example(
    'What is Bob''s job title?',
    'PREFIX ex: <https://example.org/>
     PREFIX schema: <https://schema.org/>
     SELECT ?title WHERE {
         ex:Bob schema:jobTitle ?title .
     }'
);

Step 4 — Generate and run a SPARQL query

-- Generate SPARQL from a natural-language question.
SELECT pg_ripple.sparql_from_nl('Who does Bob know?') AS generated_sparql;

Returns:

PREFIX ex:     <https://example.org/>
PREFIX schema: <https://schema.org/>
SELECT ?name WHERE {
    ex:Bob schema:knows ?person .
    ?person schema:name ?name .
}

Execute it:

SELECT result->>'name' AS person_name
FROM pg_ripple.sparql(
    pg_ripple.sparql_from_nl('Who does Bob know?')
);

Step 5 — Fetch the relevant subgraph as context

For richer answers, pass the whole subgraph to the LLM rather than just the result rows:

SELECT pg_ripple.sparql_construct_turtle($Q$
    CONSTRUCT { ?s ?p ?o }
    WHERE {
        ?s ?p ?o .
        FILTER(?s IN (<https://example.org/Alice>, <https://example.org/Bob>))
    }
$Q$) AS context_turtle;

The Turtle block goes into the LLM prompt alongside the SPARQL result rows and the user question.

Step 6 — Combine with hybrid vector search

For questions where the relevant entity cannot be named precisely ("who works on machine learning"), combine the NL→SPARQL path with a vector similarity pre-filter:

-- Embed all entities first (once per load cycle).
SELECT pg_ripple.embed_entities();

-- Hybrid: find similar entities, then expand via SPARQL.
SELECT * FROM pg_ripple.sparql($$
    PREFIX schema: <https://schema.org/>
    SELECT ?name ?title WHERE {
        ?p schema:name ?name ;
           schema:jobTitle ?title .
        FILTER(?p IN (
            SELECT s FROM pg_ripple.similar_entities('machine learning engineer', k := 5)
        ))
    }
$$);

Step 7 — A complete Python application

import psycopg, openai

DB_URL = "postgresql://..."
client = openai.OpenAI()

SYSTEM_PROMPT = """
You are a helpful assistant. You have been given the result of a SPARQL query against
a knowledge graph, as well as the subgraph context as Turtle. Answer the user's
question concisely using only the provided data. If the data does not contain the
answer, say so.
""".strip()

def answer_question(question: str) -> str:
    with psycopg.connect(DB_URL) as conn:
        cur = conn.cursor()

        # Step A: generate SPARQL and run it.
        cur.execute(
            "SELECT jsonb_agg(row_to_json(r)) FROM pg_ripple.sparql(pg_ripple.sparql_from_nl(%s)) r",
            (question,)
        )
        sparql_rows = cur.fetchone()[0] or []

        # Step B: fetch the context subgraph (optional but improves answer quality).
        # For simplicity we pull the 1-hop neighbourhood of every ?s in the result.
        turtle_context = ""
        if sparql_rows:
            subjects = [row.get("s") or row.get("p") or "" for row in sparql_rows if row]
            if subjects:
                subj_filter = ", ".join(f"<{s}>" for s in subjects if s.startswith("http"))
                if subj_filter:
                    cur.execute(
                        "SELECT pg_ripple.sparql_construct_turtle("
                        "  'CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o . FILTER(?s IN (" + subj_filter + ")) }'"
                        ")"
                    )
                    turtle_context = cur.fetchone()[0] or ""

    prompt = (
        f"{SYSTEM_PROMPT}\n\n"
        f"=== SPARQL RESULT ===\n{sparql_rows}\n\n"
        f"=== GRAPH CONTEXT (Turtle) ===\n{turtle_context}\n\n"
        f"=== QUESTION ===\n{question}"
    )
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.0,
    )
    return resp.choices[0].message.content

if __name__ == "__main__":
    print(answer_question("Who does Bob know and what are their job titles?"))

---

When to use each approach

---

See also

• NL → SPARQL — sparql_from_nl deep dive and tuning guide.
• AI Overview — decision tree for all AI features.
• Cookbook: Grounded Chatbot — simpler single-pass variant.
• Cookbook: SPARQL Repair Workflow — what to do when NL→SPARQL fails.
• AI Agent Integration — LangChain / LlamaIndex wiring.

---

Schema-Aware NL→SPARQL with Vocabulary Bundles (v0.119.0)

When your dataset uses custom ontologies or domain-specific vocabularies, sparql_from_nl() can automatically include vocabulary metadata in the LLM system prompt, improving translation accuracy for ontology-rich knowledge graphs.

Enable bundle injection

-- Enable vocabulary bundle metadata in NL→SPARQL prompts (default: on)
SET pg_ripple.nl_sparql_include_bundles = on;

When enabled, sparql_from_nl() queries the triple store for:

• skos:prefLabel — preferred labels for vocabulary terms
• dcterms:title — dataset and resource titles
• schema:name — Schema.org type names
• foaf:name — FOAF person/org names

This metadata is prepended to the LLM prompt as grounding context, helping the model generate property URIs that match your actual data.

Disable for performance

For datasets that do not use these vocabulary predicates, disable to skip the extra SPI query:

SET pg_ripple.nl_sparql_include_bundles = off;

Cookbook: Federation with Wikidata and DBpedia

Goal. Combine data from your local knowledge graph with information from public SPARQL endpoints — Wikidata, DBpedia, or any other — in a single query. No ETL, no copying data, no scheduled synchronisation.

Why pg_ripple. SPARQL 1.1 SERVICE federation is built in. A cost-based planner pushes filters to the remote endpoint, a circuit-breaker handles timeouts, and an in-process cache avoids hitting remote endpoints on every query.

Time to first result. ~10 minutes.

---

Step 1 — Register remote endpoints

Registering an endpoint once lets the planner assign it a cost estimate and lets the health monitor track its availability.

SELECT pg_ripple.register_federation_endpoint(
    endpoint := 'https://dbpedia.org/sparql',
    label    := 'DBpedia'
);

SELECT pg_ripple.register_federation_endpoint(
    endpoint        := 'https://query.wikidata.org/sparql',
    label           := 'Wikidata',
    -- Optional: pin the TLS certificate to prevent MITM.
    pin_fingerprint := NULL   -- e.g. 'sha256:AA:BB:CC:...'
);

Without registration, SERVICE still works but gets a generic cost estimate and no health monitoring.

Step 2 — Load your local facts

SELECT pg_ripple.load_turtle($TTL$
@prefix ex:   <https://example.org/people/> .
@prefix dbr:  <http://dbpedia.org/resource/> .
@prefix owl:  <http://www.w3.org/2002/07/owl#> .

ex:alice  <http://schema.org/name>  "Alice Smith" .
ex:alice  owl:sameAs  dbr:Alice_Smith_(scientist) .

ex:bob    <http://schema.org/name>  "Bob Jones" .
ex:bob    owl:sameAs  dbr:Robert_Jones_(chemist) .
$TTL$);

The owl:sameAs links tell the planner that your local entities correspond to DBpedia resources. With pg_ripple.sameas_reasoning = on (the default), the SERVICE query can use either IRI.

Step 3 — A simple federated query

Retrieve birth dates from DBpedia for people you have locally:

SELECT * FROM pg_ripple.sparql($$
    PREFIX schema: <http://schema.org/>
    PREFIX dbo:    <http://dbpedia.org/ontology/>
    PREFIX owl:    <http://www.w3.org/2002/07/owl#>

    SELECT ?name ?birthDate WHERE {
        -- Local: who do we know about?
        ?local  schema:name    ?name ;
                owl:sameAs     ?remote .

        -- Remote: fetch their birth dates from DBpedia.
        SERVICE <https://dbpedia.org/sparql> {
            ?remote  dbo:birthDate  ?birthDate .
        }
    }
$$);

The planner sends ?remote dbo:birthDate ?birthDate to DBpedia with the values of ?remote bound from the local result — this is bound-join federation, the most efficient pattern.

Step 4 — Multi-source enrichment

Enrich a medical graph with both Wikidata (drug indications) and a local proprietary store (clinical trial data):

SELECT * FROM pg_ripple.sparql($$
    PREFIX ex:  <https://example.org/>
    PREFIX wd:  <http://www.wikidata.org/entity/>
    PREFIX wdt: <http://www.wikidata.org/prop/direct/>
    PREFIX owl: <http://www.w3.org/2002/07/owl#>

    SELECT ?drugName ?indication ?trialId WHERE {
        -- Local store: drugs and their Wikidata cross-links.
        ?drug  ex:name       ?drugName ;
               owl:sameAs    ?wikidataDrug .

        -- Wikidata: approved indications.
        SERVICE <https://query.wikidata.org/sparql> {
            ?wikidataDrug  wdt:P2175  ?indicationEntity .
            ?indicationEntity  wdt:P1813  ?indication .   -- short name
        }

        -- Local store: clinical trial IDs.
        OPTIONAL { ?drug  ex:clinicalTrial  ?trialId }
    }
    ORDER BY ?drugName
$$);

Step 5 — Check endpoint health and cache

-- Which endpoints are reachable right now?
SELECT endpoint, label, last_ping_ms, is_healthy
FROM pg_ripple.federation_endpoint_health()
ORDER BY last_ping_ms;

-- How many remote results are cached?
SELECT * FROM pg_ripple.federation_cache_stats();

-- Clear the cache to force a fresh fetch.
SELECT pg_ripple.reset_cache_stats();

Step 6 — Inspect the federation plan

Before running a heavy federated query, check how the planner intends to execute it:

SELECT pg_ripple.explain_sparql($$
    PREFIX schema: <http://schema.org/>
    PREFIX dbo:    <http://dbpedia.org/ontology/>
    SELECT ?name ?birthDate WHERE {
        ?local schema:name ?name .
        SERVICE <https://dbpedia.org/sparql> {
            ?local dbo:birthDate ?birthDate .
        }
    }
$$, analyze := false);

A healthy federation plan shows a BoundJoin node rather than an IndependentService node. BoundJoin batches local values into a VALUES clause and sends one remote request; IndependentService executes the SERVICE clause for every row — much slower for large local result sets.

If you see IndependentService on a query that should be bound-join, ensure the shared variable (?local in the example) is bound by the local pattern before the SERVICE clause in the query text.

---

Circuit breaker and timeouts

When a circuit is open, queries that use that SERVICE endpoint return an empty binding for that sub-pattern and continue with local results — they do not fail outright. The pg_ripple.federation_endpoint_health() view shows which circuits are open.

---

Security note

Only register endpoints you trust and control (or well-known public endpoints). The federation circuit sends query text to the remote endpoint — potentially including literal values from your local store. For sensitive data, use a local SPARQL-over-HTTP cache (or pg_ripple_http) as a proxy rather than federating directly to a public endpoint.

---

See also

• Federation (SPARQL SERVICE) — full SQL function reference.
• Vector Federation — federating vector search to Weaviate / Qdrant / Pinecone.
• SPARQL Query Debugger

Cookbook: SHACL + Datalog Data Quality Pipeline

Goal. Validate a bibliographic (or any domain) graph against SHACL rules, identify violations, repair or enrich the data with Datalog inference, and confirm quality in a single reproducible pipeline.

Why pg_ripple. SHACL validation and Datalog inference coexist in the same transaction. The repair-then-revalidate loop runs entirely in SQL — no round trips to an external validator.

Time to first result. ~10 minutes.

---

The pattern

   raw data load
        │
        ▼
   define SHACL shapes
        │
        ▼
   run shacl_validate()  → violations found?
        │                        │
        │         yes            ▼
        │          ──── Datalog inference enriches missing triples
        │                        │
        │                        ▼
        │               run shacl_validate() again
        │                        │
        ▼         no violation   ▼
   accepted                  rejected / escalate

---

Step 1 — Load an imperfect graph

The example uses a bibliographic graph where some books are missing mandatory metadata:

CREATE EXTENSION IF NOT EXISTS pg_ripple;

SELECT pg_ripple.load_turtle($TTL$
@prefix bib:    <https://example.org/bib/> .
@prefix schema: <https://schema.org/> .
@prefix dc:     <http://purl.org/dc/terms/> .
@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .

bib:book1  a schema:Book ;
    dc:title   "Foundations of Databases" ;
    dc:creator  bib:author1 ;
    dc:date     "1995"^^xsd:gYear .

-- Intentionally missing: dc:creator and dc:date.
bib:book2  a schema:Book ;
    dc:title   "SPARQL 1.1 Query Language" .

bib:author1  a schema:Person ;
    schema:name "Abiteboul, Hull, Vianu" .
$TTL$);

Step 2 — Define SHACL shapes

A book must have a title, at least one creator, and a publication date.

SELECT pg_ripple.load_shacl($TTL$
@prefix sh:     <http://www.w3.org/ns/shacl#> .
@prefix schema: <https://schema.org/> .
@prefix dc:     <http://purl.org/dc/terms/> .

<https://shapes.example.org/BookShape>  a sh:NodeShape ;
    sh:targetClass  schema:Book ;
    sh:property [
        sh:path      dc:title ;
        sh:minCount  1 ;
        sh:datatype  <http://www.w3.org/2001/XMLSchema#string>
    ] ;
    sh:property [
        sh:path     dc:creator ;
        sh:minCount 1 ;
        sh:message  "A book must have at least one creator."
    ] ;
    sh:property [
        sh:path     dc:date ;
        sh:minCount 1 ;
        sh:message  "A book must have a publication date."
    ] .
$TTL$);

Step 3 — Run the first validation pass

SELECT *
FROM   pg_ripple.shacl_validate()
WHERE  severity = 'Violation'
ORDER  BY focus_node, result_path;

Expected output:

focus_node         | result_path | message
───────────────────┼─────────────┼────────────────────────────────────
bib:book2          | dc:creator  | A book must have at least one creator.
bib:book2          | dc:date     | A book must have a publication date.

Two violations. Before escalating to a human reviewer, try to repair them with inference.

Step 4 — Apply Datalog inference

Suppose you have a rule: "if a book's W3C spec URI matches the known SPARQL spec, infer the working group as its creator". This is a domain-specific repair rule.

SELECT pg_ripple.load_rules($RULES$
# If a book has a known W3C spec URI, infer the W3C SPARQL WG as creator.
?book dc:creator ex:W3C_SPARQL_WG :-
    ?book a schema:Book ,
    ?book dc:title "SPARQL 1.1 Query Language" .

# Infer publication year from the spec publication record.
?book dc:date "2013"^^xsd:gYear :-
    ?book a schema:Book ,
    ?book dc:title "SPARQL 1.1 Query Language" .
$RULES$, 'bib_repair');

SELECT pg_ripple.infer('bib_repair');

For more general inference, materialise OWL RL axioms if your vocabulary uses owl:sameAs or rdfs:subClassOf:

SELECT pg_ripple.load_rules_builtin('owl-rl');
SELECT pg_ripple.infer('owl-rl');

Step 5 — Re-validate after inference

SELECT count(*) AS remaining_violations
FROM   pg_ripple.shacl_validate()
WHERE  severity = 'Violation';

If the count drops to zero, the data quality pipeline passes. If violations remain, escalate them to a data steward:

-- Export remaining violations as JSON for a ticket system.
SELECT jsonb_agg(to_jsonb(v))
FROM   pg_ripple.shacl_validate() v
WHERE  severity = 'Violation';

Step 6 — Make the pipeline idempotent

Wrap Steps 3–5 in a function so it can be called after every load:

CREATE OR REPLACE FUNCTION run_quality_gate(
    rule_set TEXT DEFAULT 'bib_repair'
) RETURNS TABLE (violations BIGINT, violations_json JSONB) AS $$
BEGIN
    -- Re-run inference to pick up any new triples from the last load.
    PERFORM pg_ripple.infer(rule_set);

    RETURN QUERY
        SELECT count(*)::BIGINT,
               jsonb_agg(to_jsonb(v))
        FROM   pg_ripple.shacl_validate() v
        WHERE  v.severity = 'Violation';
END;
$$ LANGUAGE plpgsql;

SELECT * FROM run_quality_gate();

---

Production patterns

Hard-fail on load

Set pg_ripple.shacl_mode = 'sync' — any SPARQL UPDATE that creates a violation is rolled back immediately. Use this for schemas where invalid data must never enter the store.

Async queue for review

Set pg_ripple.shacl_mode = 'async' — violations are written to _pg_ripple.shacl_violations without blocking the write. A periodic job checks the queue and routes flagged triples to a review workflow.

Confidence-weighted violations

Combine SHACL with Datalog lattice confidence: only escalate violations where the offending triple has confidence below 0.7 (the data probably arrived by automated inference, not by human entry).

SELECT v.focus_node, v.result_message, conf.confidence
FROM   pg_ripple.shacl_validate() v
JOIN   LATERAL (
    SELECT CAST(o AS FLOAT) AS confidence
    FROM   pg_ripple.sparql(format(
        'SELECT ?conf WHERE { << <%s> %s ?o >> ex:confidence ?conf }',
        v.focus_node, v.result_path
    ))
) conf ON true
WHERE  v.severity = 'Violation'
  AND  conf.confidence < 0.7;

---

See also

• Validating Data Quality (SHACL) — all shape types and modes.
• Reasoning and Inference (Datalog)
• Cookbook: Audit Trail — combine SHACL with PROV-O for a full evidence chain.

SKOS Thesaurus Management in PostgreSQL

This cookbook chapter shows how to load, query, and validate a SKOS taxonomy inside pg_ripple using the W3C-conformant SKOS entailment rules added in v0.98.0.

What is SKOS?

SKOS (Simple Knowledge Organization System) is the W3C standard vocabulary for thesauri, taxonomies, classification schemes, and subject heading systems. A SKOS taxonomy consists of skos:Concept nodes linked by skos:broader/skos:narrower hierarchies, skos:related associative links, and labelled with skos:prefLabel.

Loading the SKOS Rule Set

-- Load all 28 W3C SKOS entailment rules (S7–S45).
SELECT pg_ripple.load_builtin_rules('skos');

-- Or use the named bundle API for versioned activation:
SELECT pg_ripple.load_datalog_bundle('skos');

Once loaded, pg_ripple automatically infers:

• skos:broaderTransitive and skos:narrowerTransitive transitive closures
• Inverse skos:narrower/skos:broader pairs
• skos:related symmetry
• Sub-property hierarchies for mapping predicates (broadMatch, exactMatch, etc.)
• Label sub-properties (prefLabel → rdfs:label)

Loading a Thesaurus

-- Load Turtle-encoded thesaurus data.
SELECT pg_ripple.load_turtle($$
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix ex:   <http://example.org/thesaurus/> .

ex:Animals a skos:ConceptScheme ;
    skos:hasTopConcept ex:Mammals .

ex:Mammals a skos:Concept ;
    skos:prefLabel "Mammals"@en ;
    skos:inScheme ex:Animals .

ex:Cats a skos:Concept ;
    skos:prefLabel "Cats"@en ;
    skos:broader ex:Mammals .

ex:Dogs a skos:Concept ;
    skos:prefLabel "Dogs"@en ;
    skos:broader ex:Mammals .

ex:Cats skos:related ex:Dogs .
$$);

-- Run inference to materialise transitive closures.
SELECT pg_ripple.infer('skos');

Querying Hierarchies with SPARQL

-- Find all broader transitive ancestors of Cats.
SELECT *
FROM pg_ripple.sparql($$
    SELECT ?ancestor WHERE {
        <http://example.org/thesaurus/Cats>
            <http://www.w3.org/2004/02/skos/core#broaderTransitive> ?ancestor .
    }
$$);

-- Find all concepts in the Mammals subtree (narrowerTransitive closure).
SELECT *
FROM pg_ripple.sparql($$
    SELECT ?child WHERE {
        <http://example.org/thesaurus/Mammals>
            <http://www.w3.org/2004/02/skos/core#narrowerTransitive> ?child .
    }
$$);

-- Cross-scheme mapping: find exactMatch counterparts.
SELECT *
FROM pg_ripple.sparql($$
    SELECT ?concept ?match WHERE {
        ?concept <http://www.w3.org/2004/02/skos/core#exactMatch> ?match .
    }
$$);

SQL Helper Functions

The five SQL helper functions provide convenient access to common thesaurus operations without writing SPARQL:

-- Traverse the broaderTransitive closure.
SELECT * FROM pg_ripple.skos_ancestors(
    'http://example.org/thesaurus/Cats'
);
-- Returns: (ancestor_iri, depth)

-- Traverse the narrowerTransitive closure.
SELECT * FROM pg_ripple.skos_descendants(
    'http://example.org/thesaurus/Mammals'
);
-- Returns: (descendant_iri, depth)

-- Look up the preferred label in English.
SELECT pg_ripple.skos_label(
    'http://example.org/thesaurus/Cats',
    'en'
);
-- Returns: "Cats"

-- Find all related concepts.
SELECT * FROM pg_ripple.skos_related(
    'http://example.org/thesaurus/Cats'
);
-- Returns: (related_iri, relation) — e.g. Dogs, skos:related

-- Find sibling concepts (sharing a common skos:broader parent).
SELECT * FROM pg_ripple.skos_siblings(
    'http://example.org/thesaurus/Cats'
);
-- Returns: (sibling_iri, shared_broader_iri) — e.g. Dogs, Mammals

Enabling SKOS-XL Extended Labels

SKOS-XL allows attaching structured metadata to labels. pg_ripple's SKOS-XL rule set automatically projects skosxl:Label instances to plain skos:prefLabel triples:

SELECT pg_ripple.load_builtin_rules('skosxl');
SELECT pg_ripple.infer('skosxl');

After loading, a triple <concept> skosxl:prefLabel <label> with <label> skosxl:literalForm "text"@en will produce <concept> skos:prefLabel "text"@en automatically.

Running Integrity Checks

The "skos-integrity" shape bundle validates 10 structural integrity conditions from the W3C SKOS specification:

-- Activate the integrity shape bundle (automatically loads skos-transitive).
SELECT pg_ripple.load_shape_bundle('skos-integrity');

-- Run validation.
SELECT * FROM pg_ripple.validate_skos();
-- Returns: (violation_id, subject, message)
-- Example violation: SKOS-IC-05: multiple prefLabels with same language tag.

The 10 validators cover:

Named Bundle API

Use load_datalog_bundle instead of load_builtin_rules when you need versioned, machine-checkable bundle tracking:

SELECT pg_ripple.load_datalog_bundle('skos');
SELECT pg_ripple.load_datalog_bundle('skos-transitive');

-- Check what is active.
SELECT * FROM pg_ripple.active_datalog_bundles;
-- Returns: (bundle_name, bundle_version, loaded_at, named_graph)

Performance Notes

• skos:broaderTransitive closure materialisation via WITH RECURSIVE … CYCLE takes ~200 ms for 1,000 concepts and ~8 s for 100,000 concepts on first materialisation.
• Subsequent IVM updates (when enabled) take ~10 ms per new skos:broader triple.
• skos_ancestors() runs a live WITH RECURSIVE query in ~5 ms for depth ≤ 10, using the materialised broaderTransitive triples as the base.

See Also

• SKOS Reference — W3C Recommendation
• Datalog Reference — built-in RDFS and OWL RL rule support
• SQL Functions Reference — all pg_ripple SQL functions

Common Vocabulary Bundles: DCTERMS, Schema.org, and FOAF

This cookbook chapter shows how to load and use the three most widely-deployed linked-data vocabularies in pg_ripple — Dublin Core Terms (DCTERMS), Schema.org, and FOAF — using the named bundle API introduced in v0.98.0.

Together with SKOS (v0.98.0), these bundles complete the "Big 5" vocabularies that cover the vast majority of real-world knowledge-graph interoperability.

Why These Vocabularies?

All three are already used in billions of public RDF documents, Wikidata exports, and enterprise knowledge graphs. Loading their rule sets lets pg_ripple perform property-hierarchy inference, type-subsumption reasoning, and integrity validation over data you already have — without any schema changes.

Loading the Bundles

-- DCTERMS: 11 Datalog rules + 8 integrity validators
SELECT pg_ripple.load_datalog_bundle('dcterms');
SELECT pg_ripple.load_shape_bundle('dcterms-integrity');

-- Schema.org: 15 Datalog rules + 6 integrity validators
SELECT pg_ripple.load_datalog_bundle('schema');
SELECT pg_ripple.load_shape_bundle('schema-integrity');

-- FOAF: 8 Datalog rules + 5 integrity validators
SELECT pg_ripple.load_datalog_bundle('foaf');
SELECT pg_ripple.load_shape_bundle('foaf-integrity');

After loading, confirm activation:

SELECT bundle_name, bundle_version, activated_at
FROM pg_ripple.active_datalog_bundles
ORDER BY activated_at;

DCTERMS — Dublin Core Terms

Inferred Properties

The dcterms bundle adds 11 rules, including:

• DC11 compatibility aliases — dc11:title is treated equivalently to dcterms:title, and similarly for creator, subject, description, publisher, date, type, format, identifier, source, language.
• Structural inverses — dcterms:hasPart ↔ dcterms:isPartOf, dcterms:hasVersion ↔ dcterms:isVersionOf, dcterms:replaces ↔ dcterms:isReplacedBy.
• DC-SKOS bridge (DC-SKOS-01) — resources whose dcterms:subject is a member of a SKOS ConceptScheme automatically receive a skos:Concept type assertion.

Example

-- Load some metadata triples using the old dc11: namespace.
SELECT pg_ripple.load_turtle($$
@prefix dc11: <http://purl.org/dc/elements/1.1/> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix ex: <https://example.org/> .

ex:Article1 dc11:creator "Alice" ;
            dcterms:hasPart ex:Section1 .
$$);

-- Load the dcterms rule set.
SELECT pg_ripple.load_datalog_bundle('dcterms');

-- dc11:creator is now mapped to dcterms:creator.
SELECT pg_ripple.sparql_select($$
  SELECT ?article ?creator
  WHERE { ?article <http://purl.org/dc/terms/creator> ?creator }
$$);

-- dcterms:isPartOf is inferred from dcterms:hasPart.
SELECT pg_ripple.sparql_select($$
  SELECT ?part ?whole
  WHERE { ?part <http://purl.org/dc/terms/isPartOf> ?whole }
$$);

Schema.org — Structured Data Vocabulary

Inferred Properties

The schema bundle adds 15 rules:

• Inverse pairs — schema:subjectOf ↔ schema:about, schema:hasPart ↔ schema:isPartOf, schema:workExample ↔ schema:exampleOfWork, schema:member ↔ schema:memberOf.
• Type hierarchy — schema:LocalBusiness ⊆ schema:Organization ⊆ schema:Thing, schema:Person ⊆ schema:Thing, schema:Product ⊆ schema:Thing, and several more.
• Cross-vocab bridges — schema:author → foaf:maker (SCHEMA-FOAF-01), schema:name → dcterms:title (SCHEMA-DC-01), schema:dataset → dcat:Dataset (SCHEMA-DCAT-01).

SQL Helper: schema_type_ancestors

-- Return all Schema.org type ancestors for a given IRI.
SELECT ancestor_type
FROM pg_ripple.schema_type_ancestors('https://schema.org/LocalBusiness');
-- Returns: schema:LocalBusiness, schema:Organization, schema:Thing

Example

-- Load a local business.
SELECT pg_ripple.load_turtle($$
@prefix schema: <https://schema.org/> .
@prefix ex: <https://example.org/> .

ex:AcmeCafe a schema:CafeOrCoffeeShop ;
    schema:name "ACME Café" ;
    schema:address ex:CafeAddress .
$$);

SELECT pg_ripple.load_datalog_bundle('schema');

-- CafeOrCoffeeShop is a FoodEstablishment, LocalBusiness, Organization, Thing.
SELECT pg_ripple.sparql_select($$
  SELECT ?type
  WHERE { <https://example.org/AcmeCafe> a ?type }
  ORDER BY ?type
$$);

FOAF — Friend-of-a-Friend

Inferred Properties

The foaf bundle adds 8 rules:

• foaf:knows symmetry — if Alice knows Bob, Bob knows Alice.
• Type subsumption — foaf:Person ⊆ foaf:Agent, foaf:Organization ⊆ foaf:Agent, foaf:Group ⊆ foaf:Agent.
• Inverse properties — foaf:account ↔ foaf:accountFor, foaf:made ↔ foaf:maker.
• DC-FOAF bridge (DC-FOAF-01) — dcterms:creator triples generate a corresponding foaf:maker assertion on the referenced resource.

SQL Helper: foaf_persons

-- Return all foaf:Person IRIs and their foaf:name labels.
SELECT person_iri, name_label
FROM pg_ripple.foaf_persons();

Example

-- Load FOAF data.
SELECT pg_ripple.load_turtle($$
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix ex: <https://example.org/> .

ex:Alice a foaf:Person ;
    foaf:name "Alice" ;
    foaf:knows ex:Bob .
ex:Bob a foaf:Person ;
    foaf:name "Bob" .
$$);

SELECT pg_ripple.load_datalog_bundle('foaf');

-- foaf:knows is symmetric: Bob knows Alice.
SELECT pg_ripple.sparql_select($$
  SELECT ?who ?knows
  WHERE { ?who <http://xmlns.com/foaf/0.1/knows> ?knows }
$$);

-- foaf:Person ⊆ foaf:Agent: Alice is also a foaf:Agent.
SELECT pg_ripple.sparql_select($$
  SELECT ?agent
  WHERE { ?agent a <http://xmlns.com/foaf/0.1/Agent> }
$$);

Cross-Vocabulary Inference

When all three bundles (and SKOS) are loaded together, cross-vocabulary bridges activate:

This means a resource described with schema:author can be found via a foaf:maker query, and a resource with schema:name can be found via a dcterms:title filter — without any data transformation.

Integrity Validation

Each vocabulary ships with a corresponding integrity bundle:

-- Validate DCTERMS constraints (title cardinality, date format, etc.)
SELECT pg_ripple.load_shape_bundle('dcterms-integrity');

-- Validate Schema.org constraints (required name, URL format, price range, etc.)
SELECT pg_ripple.load_shape_bundle('schema-integrity');

-- Validate FOAF constraints (homepage IRI, mbox mailto:, name cardinality)
SELECT pg_ripple.load_shape_bundle('foaf-integrity');

Integrity violations are surfaced through the standard SHACL validation report.

Checking Active Bundles

SELECT bundle_name, bundle_version, activated_at
FROM pg_ripple.active_datalog_bundles
ORDER BY bundle_name;

-- bundle_name         | bundle_version | activated_at
-- --------------------+----------------+---------------------------
-- dcterms             | 0.99.0         | 2026-05-07 10:00:00+00
-- foaf                | 0.99.0         | 2026-05-07 10:00:01+00
-- schema              | 0.99.0         | 2026-05-07 10:00:02+00
-- skos                | 0.98.0         | 2026-05-07 09:59:59+00

See Also

• SKOS Thesaurus Management — the fourth member of the "Big 5" vocabulary bundle suite
• SHACL + Datalog Data Quality Pipeline — how to combine rules and shapes for a full data-quality pipeline

Migrate from Neo4j to pg_ripple

This recipe walks through migrating a Neo4j property graph to pg_ripple's RDF triple store. You will export Neo4j data, convert it to RDF, load it into pg_ripple, and validate the migration.

Prerequisites

• Neo4j 5.x (Community or Enterprise)
• pg_ripple v0.90.0 or later
• Python 3.11+ with neo4j and rdflib packages

pip install neo4j rdflib

---

Step 1: Export the Neo4j Graph

Use the Neo4j Cypher shell or APOC to export nodes and relationships.

Option A: APOC Export to CSV

-- Export nodes
CALL apoc.export.csv.query(
  "MATCH (n) RETURN id(n) as id, labels(n) as labels, properties(n) as props",
  "/tmp/nodes.csv", {quotes: "always"}
)

-- Export relationships
CALL apoc.export.csv.query(
  "MATCH (a)-[r]->(b) RETURN id(a) as from, type(r) as type, properties(r) as props, id(b) as to",
  "/tmp/rels.csv", {quotes: "always"}
)

Option B: Python Direct Export

from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))

def export_nodes(session):
    return session.run("MATCH (n) RETURN id(n) as id, labels(n) as labels, properties(n) as props").data()

def export_rels(session):
    return session.run(
        "MATCH (a)-[r]->(b) RETURN id(a) as from, type(r) as rel, properties(r) as props, id(b) as to"
    ).data()

with driver.session() as s:
    nodes = export_nodes(s)
    rels = export_rels(s)

---

Step 2: Convert to RDF (Turtle)

Map Neo4j property graph concepts to RDF:

from rdflib import Graph, URIRef, Literal, Namespace, RDF
import json

EX = Namespace("https://example.org/")
g = Graph()

# Bind prefixes
g.bind("ex", EX)
g.bind("rdf", RDF)

# Convert nodes
for node in nodes:
    node_uri = EX[f"node_{node['id']}"]
    # Type assertions
    for label in node["labels"]:
        g.add((node_uri, RDF.type, EX[label]))
    # Properties
    props = json.loads(node["props"]) if isinstance(node["props"], str) else node["props"]
    for key, val in props.items():
        g.add((node_uri, EX[key], Literal(val)))

# Convert relationships
for rel in rels:
    from_uri = EX[f"node_{rel['from']}"]
    to_uri = EX[f"node_{rel['to']}"]
    pred_uri = EX[rel["rel"].lower()]
    g.add((from_uri, pred_uri, to_uri))

# Export to Turtle
turtle_data = g.serialize(format="turtle")
with open("/tmp/neo4j_export.ttl", "w") as f:
    f.write(turtle_data)
print(f"Exported {len(g)} triples to neo4j_export.ttl")

---

Step 3: Load into pg_ripple

-- Create a named graph for the migrated data
SELECT pg_ripple.insert_triple(
  'https://example.org/neo4j_import',
  'rdf:type',
  'pg_ripple:Graph'
);

-- Load the Turtle file
SELECT pg_ripple.load_turtle(
  pg_read_file('/tmp/neo4j_export.ttl'),
  'https://example.org/neo4j_import'
);

-- Verify the load
SELECT COUNT(*) FROM pg_ripple.sparql(
  'SELECT (COUNT(*) AS ?count) WHERE { GRAPH <https://example.org/neo4j_import> { ?s ?p ?o } }'
);

For large exports (millions of triples), use the bulk loader instead:

-- Stream via COPY for maximum throughput
SELECT pg_ripple.bulk_load_turtle_file(
  '/tmp/neo4j_export.ttl',
  'https://example.org/neo4j_import'
);

---

Step 4: Define SPARQL Views for Cypher-Style Queries

Map common Neo4j query patterns to SPARQL:

Neo4j: Shortest Path

MATCH p = shortestPath((a:Person {name: "Alice"})-[:KNOWS*]-(b:Person {name: "Bob"}))
RETURN p

-- pg_ripple equivalent (property path)
SELECT ?path WHERE {
  <https://example.org/Alice> ex:knows+ <https://example.org/Bob> .
}

Neo4j: Pattern Matching

MATCH (p:Person)-[:WORKS_AT]->(c:Company)<-[:WORKS_AT]-(q:Person)
WHERE p.name = "Alice"
RETURN q.name

SELECT ?coworkerName WHERE {
  <https://example.org/Alice> ex:worksAt ?company .
  ?company rdf:type ex:Company .
  ?coworker ex:worksAt ?company .
  ?coworker ex:name ?coworkerName .
  FILTER(?coworker != <https://example.org/Alice>)
}

---

Step 5: Add SHACL Constraints

Recreate Neo4j uniqueness and existence constraints as SHACL shapes:

@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix ex: <https://example.org/> .

ex:PersonShape a sh:NodeShape ;
  sh:targetClass ex:Person ;
  sh:property [
    sh:path ex:email ;
    sh:maxCount 1 ;           -- Neo4j uniqueness constraint equivalent
    sh:datatype xsd:string
  ] ;
  sh:property [
    sh:path ex:name ;
    sh:minCount 1 ;           -- NOT NULL equivalent
    sh:datatype xsd:string
  ] .

SELECT pg_ripple.load_shacl($$
  @prefix sh: <http://www.w3.org/ns/shacl#> .
  @prefix ex: <https://example.org/> .
  -- paste shapes here
$$);

---

Step 6: Validate and Reconcile

-- Check constraint violations
SELECT pg_ripple.validate();

-- Find nodes without required properties (replaces Neo4j NULL checks)
SELECT binding->>'?node' AS node
FROM pg_ripple.sparql($$
  SELECT ?node WHERE {
    ?node rdf:type ex:Person .
    FILTER NOT EXISTS { ?node ex:name ?n }
  }
$$);

-- Verify counts match Neo4j
SELECT binding->>'?count' AS triple_count
FROM pg_ripple.sparql('SELECT (COUNT(*) AS ?count) WHERE { ?s ?p ?o }');

---

Mapping Reference

---

Performance Tips

1. Batch load with bulk_load_turtle_file() — 10–100× faster than individual inserts.
2. Set pg_ripple.vp_promotion_threshold = 100 during migration to create individual VP tables for more predicates, then restore the default after.
3. Run VACUUM ANALYZE on _pg_ripple.dictionary after a large load.
4. Use pg_ripple.run_merge() to flush deltas to the main partition before heavy analytic queries.

Build a RAG Pipeline from Scratch

This recipe walks through building a complete Retrieval-Augmented Generation (RAG) pipeline using pg_ripple's hybrid SPARQL + vector search. By the end you will have a system that answers natural-language questions using your knowledge graph as the context source.

Architecture

flowchart LR
    Q[User question] --> E[Embed question\npg_ripple.embed_text]
    E --> V[Vector similarity search\n_pg_ripple.embeddings]
    V --> F[SPARQL filter\nopt. constraint]
    F --> R[Retrieved entities\n+ graph context]
    R --> P[Build LLM prompt]
    P --> L[LLM API call\ngpt-4o / llama3]
    L --> A[Answer + citations]

Prerequisites

• pg_ripple v0.49.0 or later (NL→SPARQL), v0.28.0+ (vector embeddings)
• pgvector extension installed
• OpenAI API key (or any OpenAI-compatible endpoint)
• Python 3.11+ with psycopg, openai, requests

pip install psycopg openai requests

---

Step 1: Enable Embeddings

-- Set embedding endpoint (OpenAI-compatible)
ALTER SYSTEM SET pg_ripple.embedding_api_url = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.embedding_api_key = 'sk-...';
ALTER SYSTEM SET pg_ripple.embedding_model = 'text-embedding-3-small';
ALTER SYSTEM SET pg_ripple.embedding_dimensions = 1536;
ALTER SYSTEM SET pg_ripple.auto_embed = on;
SELECT pg_reload_conf();

For local Ollama embeddings:

ALTER SYSTEM SET pg_ripple.embedding_api_url = 'http://localhost:11434/v1';
ALTER SYSTEM SET pg_ripple.embedding_model = 'nomic-embed-text';
ALTER SYSTEM SET pg_ripple.embedding_dimensions = 768;
ALTER SYSTEM SET pg_reload_conf();

---

Step 2: Load Your Knowledge Graph

-- Load domain data
SELECT pg_ripple.load_turtle($$
  @prefix ex: <https://pharma.example/> .
  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
  @prefix schema: <https://schema.org/> .

  ex:aspirin a ex:Drug ;
    rdfs:label "Aspirin" ;
    ex:treats ex:headache, ex:fever, ex:inflammation ;
    ex:class ex:NSAID ;
    ex:approvedBy ex:FDA .

  ex:ibuprofen a ex:Drug ;
    rdfs:label "Ibuprofen" ;
    ex:treats ex:pain, ex:inflammation ;
    ex:class ex:NSAID .

  ex:headache rdfs:label "headache" .
  ex:fever rdfs:label "fever" .
  ex:pain rdfs:label "pain" .
$$, 'https://pharma.example/graph');

---

Step 3: Embed the Knowledge Graph

Trigger embedding generation for all loaded entities:

-- Manually embed all entities (if auto_embed was off during load)
SELECT pg_ripple.embed_all_entities();

-- Check embedding coverage
SELECT COUNT(*) FROM _pg_ripple.embeddings;

Or with auto_embed = on, embeddings are generated automatically by the background worker as triples are loaded.

---

Step 4: Query via the HTTP API

The /rag endpoint handles the full pipeline:

# Simple question
curl -X POST http://localhost:7878/rag \
  -H "Content-Type: application/json" \
  -d '{
    "question": "what drugs treat headaches?",
    "k": 5
  }'

Response:

{
  "results": [
    {
      "entity_iri": "https://pharma.example/aspirin",
      "label": "Aspirin",
      "context_json": {
        "label": "Aspirin",
        "types": ["Drug"],
        "properties": [
          {"predicate": "treats", "object": "headache"},
          {"predicate": "class", "object": "NSAID"}
        ],
        "contextText": "Aspirin. Type: Drug, NSAID. Treats: headache, fever, inflammation."
      },
      "distance": 0.08
    }
  ],
  "context": "Aspirin. Type: Drug, NSAID. Treats: headache, fever, inflammation.\n\nIbuprofen. Type: Drug. Treats: pain, inflammation."
}

---

Step 5: Build a Python RAG Client

import os
import requests
from openai import OpenAI

RAG_ENDPOINT = "http://localhost:7878/rag"
AUTH_TOKEN   = os.environ["PG_RIPPLE_HTTP_AUTH_TOKEN"]
OPENAI_KEY   = os.environ["OPENAI_API_KEY"]

openai = OpenAI(api_key=OPENAI_KEY)

def retrieve(question: str, sparql_filter: str | None = None, k: int = 5) -> dict:
    payload = {"question": question, "k": k}
    if sparql_filter:
        payload["sparql_filter"] = sparql_filter
    r = requests.post(
        RAG_ENDPOINT,
        json=payload,
        headers={"Authorization": f"Bearer {AUTH_TOKEN}"},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

def answer(question: str, sparql_filter: str | None = None) -> str:
    retrieval = retrieve(question, sparql_filter)
    context = retrieval["context"]

    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {
                "role": "system",
                "content": (
                    "You are a helpful assistant. Answer the user's question using "
                    "only the following knowledge graph context. Cite entity IRIs "
                    "when making claims.\n\n"
                    f"Context:\n{context}"
                ),
            },
            {"role": "user", "content": question},
        ],
        temperature=0.2,
    )
    return response.choices[0].message.content


# Example usage
print(answer("What NSAIDs are approved by the FDA?"))
print(answer(
    "Which drugs treat fever?",
    sparql_filter="?entity a <https://pharma.example/Drug>"
))

---

Step 6: Filter with SPARQL Constraints

Use sparql_filter to restrict retrieval to a class or subgraph:

# Only retrieve drugs approved by the FDA
answer(
    "What are the safest pain relievers?",
    sparql_filter=(
        "?entity a <https://pharma.example/Drug> . "
        "?entity <https://pharma.example/approvedBy> <https://pharma.example/FDA>"
    )
)

---

Step 7: Use SHACL for Data Quality

Add SHACL constraints to ensure your knowledge graph contains complete information for RAG:

SELECT pg_ripple.load_shacl($$
  @prefix sh: <http://www.w3.org/ns/shacl#> .
  @prefix ex: <https://pharma.example/> .
  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

  ex:DrugShape a sh:NodeShape ;
    sh:targetClass ex:Drug ;
    sh:property [
      sh:path rdfs:label ;
      sh:minCount 1 ;
      sh:message "Every drug must have a label for RAG context generation"
    ] ;
    sh:property [
      sh:path ex:treats ;
      sh:minCount 1 ;
      sh:message "Every drug must have at least one indication"
    ] .
$$);

-- Validate the graph
SELECT pg_ripple.validate();

---

Step 8: Use Graph Context for Richer Embeddings

For semantically richer embeddings, enable graph-context mode:

ALTER SYSTEM SET pg_ripple.use_graph_context = on;
SELECT pg_reload_conf();

-- Re-embed all entities with graph context
SELECT pg_ripple.embed_all_entities(force_recompute := true);

With use_graph_context = on, each entity is embedded with its full RDF neighborhood serialized as text, producing embeddings that capture graph structure — not just the entity label.

---

Step 9: NL → SPARQL Generation (Advanced)

For complex queries, use the NL → SPARQL endpoint to generate and execute SPARQL directly:

-- Configure LLM
ALTER SYSTEM SET pg_ripple.llm_endpoint = 'https://api.openai.com/v1';
ALTER SYSTEM SET pg_ripple.llm_model    = 'gpt-4o';
ALTER SYSTEM SET pg_ripple.llm_api_key_env = 'OPENAI_API_KEY';
SELECT pg_reload_conf();

-- Generate and run SPARQL from natural language
SELECT pg_ripple.sparql_from_nl(
  'Find all NSAIDs approved by the FDA that treat headaches'
);

---

Production Checklist

• Set pg_ripple.embedding_api_key from a secrets manager (not ALTER SYSTEM)
• Enable PG_RIPPLE_HTTP_AUTH_TOKEN on all HTTP endpoints
• Configure pg_ripple.sparql_max_rows to limit runaway queries
• Monitor pg_ripple_embedding_queue_depth Prometheus gauge — grow workers if > 10,000
• Use pg_ripple.export_max_rows to prevent large RAG context blowup
• Add SHACL shapes to ensure all entities have labels (required for RAG context)

Further Reading

• Vector and Hybrid Search
• NL to SPARQL
• GraphRAG
• SHACL Validation
• HTTP API Reference

Rule-Library Federation Recipe

Added in v0.120.0

Use this recipe when you already have a versioned rule library and want to share it across pg_ripple instances. For the full walkthrough, including a two-instance setup and monitoring examples, see the Rule Library Federation guide.

When to Use This

Rule-library federation fits teams that maintain shared Datalog or SHACL rule sets, such as RDFS entailment, customer deduplication, or compliance checks, and need the same rules installed consistently across environments.

Minimal Flow

1. Install or create the library on the source instance.
2. Publish the library with the URL where the HTTP companion serves its stream.
3. Record a subscription on the target instance.
4. Ask the target HTTP companion to fetch and install the remote stream.

-- Source instance: publish an installed library.
SELECT pg_ripple.publish_rule_library(
  'rdfs-entailment',
  'https://instance-a.example.com/rule-libraries/rdfs-entailment/stream'
);

-- Target instance: record subscription intent.
SELECT pg_ripple.subscribe_rule_library(
  'https://instance-a.example.com/rule-libraries/rdfs-entailment/stream',
  'rdfs-entailment'
);

# Target HTTP companion: fetch and install the stream.
curl -X POST https://instance-b.example.com/rule-libraries/rdfs-entailment/subscribe \
  -H "Authorization: Bearer $PG_RIPPLE_HTTP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_uri":"https://instance-a.example.com/rule-libraries/rdfs-entailment/stream"}'

Notes

• publish_rule_library() and subscribe_rule_library() are catalog operations; they do not start a background daemon.
• POST /rule-libraries/{name}/subscribe performs the remote fetch and installs rules into the target instance.
• The current HTTP fetcher does not forward a separate Authorization header to the source stream. For protected source streams, use a trusted internal route or fetch from an authenticated client.

See Also

• Rule Library Federation guide
• SQL API: publish_rule_library
• SQL API: subscribe_rule_library
• HTTP API reference

§2.8 APIs and Integration

What and Why

pg_ripple's SQL functions are powerful, but most applications do not talk to PostgreSQL directly. The pg_ripple_http companion service exposes a W3C-compliant SPARQL Protocol endpoint over HTTP, so any SPARQL client, programming language, or tool can query your knowledge graph.

This chapter covers:

• pg_ripple_http: the standalone SPARQL endpoint service.
• Application code examples: Python, JavaScript, and Java.
• SPARQL federation: query remote SPARQL endpoints from within pg_ripple.
• Caching strategies: plan cache, connection pooling, and result caching.

---

How It Works

pg_ripple_http Architecture

pg_ripple_http is a standalone Rust binary (not a PostgreSQL extension) that:

1. Connects to PostgreSQL via a deadpool connection pool.
2. Receives SPARQL queries via HTTP GET/POST (W3C SPARQL Protocol).
3. Calls pg_ripple.sparql(), pg_ripple.sparql_construct(), etc. via SQL.
4. Returns results in standard formats: SPARQL Results JSON/XML, Turtle, N-Triples, JSON-LD.
5. Exposes a /rag endpoint for AI retrieval.

Supported Endpoints

Response Formats (Content Negotiation)

---

Worked Examples

Starting pg_ripple_http

# Set environment variables
export PG_RIPPLE_DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
export PG_RIPPLE_LISTEN="0.0.0.0:8080"
export PG_RIPPLE_AUTH_TOKEN="my-secret-token"  # optional

# Start the server
pg_ripple_http

Configuration via environment variables:

Querying via curl

SPARQL SELECT via GET:

curl -G http://localhost:8080/sparql \
  --data-urlencode 'query=PREFIX dct: <http://purl.org/dc/terms/> SELECT ?paper ?title WHERE { ?paper dct:title ?title } LIMIT 10' \
  -H "Accept: application/sparql-results+json"

SPARQL SELECT via POST (body):

curl -X POST http://localhost:8080/sparql \
  -H "Content-Type: application/sparql-query" \
  -H "Accept: application/sparql-results+json" \
  -d 'PREFIX dct: <http://purl.org/dc/terms/>
      PREFIX bibo: <http://purl.org/ontology/bibo/>
      SELECT ?paper ?title
      WHERE {
          ?paper a bibo:AcademicArticle ;
                 dct:title ?title .
      }
      ORDER BY ?title
      LIMIT 20'

SPARQL CONSTRUCT as Turtle:

curl -X POST http://localhost:8080/sparql \
  -H "Content-Type: application/sparql-query" \
  -H "Accept: text/turtle" \
  -d 'PREFIX dct: <http://purl.org/dc/terms/>
      PREFIX ex: <https://example.org/>
      CONSTRUCT { ?paper ex:hasTitle ?title }
      WHERE { ?paper dct:title ?title }'

SPARQL CONSTRUCT as JSON-LD:

curl -X POST http://localhost:8080/sparql \
  -H "Content-Type: application/sparql-query" \
  -H "Accept: application/ld+json" \
  -d 'PREFIX dct: <http://purl.org/dc/terms/>
      PREFIX ex: <https://example.org/>
      CONSTRUCT { ?paper ex:hasTitle ?title }
      WHERE { ?paper dct:title ?title }'

SPARQL Update:

curl -X POST http://localhost:8080/sparql \
  -H "Content-Type: application/sparql-update" \
  -d 'PREFIX ex: <https://example.org/>
      PREFIX dct: <http://purl.org/dc/terms/>
      INSERT DATA {
          ex:paper/new1 dct:title "A New Discovery" .
      }'

RAG endpoint:

curl -X POST http://localhost:8080/rag \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What papers discuss knowledge graphs?",
    "sparql_filter": "?entity a <http://purl.org/ontology/bibo/AcademicArticle> .",
    "k": 5,
    "output_format": "jsonld"
  }'

The RAG response includes a context field with pre-formatted text for LLM prompts:

{
  "results": [
    {
      "entity_iri": "https://example.org/paper/42",
      "label": "Knowledge Graphs in Practice",
      "context_json": {"@type": ["AcademicArticle"], "...": "..."},
      "distance": 0.12
    }
  ],
  "context": "Knowledge Graphs in Practice (AcademicArticle): A comprehensive survey..."
}

Authentication (when PG_RIPPLE_AUTH_TOKEN is set):

curl -X POST http://localhost:8080/sparql \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/sparql-query" \
  -d 'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5'

Python with psycopg2

Query pg_ripple directly from Python via SQL:

import json
import psycopg2

conn = psycopg2.connect("dbname=mydb user=postgres")
cur = conn.cursor()

# Execute a SPARQL query
cur.execute("""
    SELECT * FROM pg_ripple.sparql(%s)
""", ("""
    PREFIX dct:  <http://purl.org/dc/terms/>
    PREFIX bibo: <http://purl.org/ontology/bibo/>
    
    SELECT ?paper ?title ?author
    WHERE {
        ?paper a bibo:AcademicArticle ;
               dct:title ?title ;
               dct:creator ?author .
    }
    ORDER BY ?title
    LIMIT 20
""",))

for row in cur.fetchall():
    result = json.loads(row[0])
    print(f"Paper: {result['paper']}")
    print(f"Title: {result['title']}")
    print(f"Author: {result['author']}")
    print()

# Load Turtle data
cur.execute("""
    SELECT pg_ripple.load_turtle(%s)
""", ("""
    @prefix ex: <https://example.org/> .
    @prefix dct: <http://purl.org/dc/terms/> .
    ex:paper/new dct:title "Loaded from Python" .
""",))
conn.commit()

# Export as JSON-LD
cur.execute("SELECT pg_ripple.export_jsonld()")
jsonld = json.loads(cur.fetchone()[0])
print(json.dumps(jsonld, indent=2))

cur.close()
conn.close()

Python with SPARQLWrapper

Query the pg_ripple_http endpoint using the standard SPARQLWrapper library:

from SPARQLWrapper import SPARQLWrapper, JSON, TURTLE

# Point to the pg_ripple_http endpoint
sparql = SPARQLWrapper("http://localhost:8080/sparql")

# SELECT query
sparql.setQuery("""
    PREFIX dct:  <http://purl.org/dc/terms/>
    PREFIX bibo: <http://purl.org/ontology/bibo/>
    
    SELECT ?paper ?title
    WHERE {
        ?paper a bibo:AcademicArticle ;
               dct:title ?title .
    }
    LIMIT 10
""")
sparql.setReturnFormat(JSON)
results = sparql.query().convert()

for binding in results["results"]["bindings"]:
    print(f"{binding['paper']['value']}: {binding['title']['value']}")

# CONSTRUCT query as Turtle
sparql.setQuery("""
    PREFIX dct: <http://purl.org/dc/terms/>
    PREFIX ex:  <https://example.org/>
    
    CONSTRUCT { ?paper ex:hasTitle ?title }
    WHERE { ?paper dct:title ?title }
""")
sparql.setReturnFormat(TURTLE)
turtle_output = sparql.query().convert()
print(turtle_output.decode("utf-8"))

JavaScript with pg

Query pg_ripple directly from Node.js:

const { Client } = require('pg');

async function main() {
    const client = new Client({ connectionString: 'postgresql://localhost/mydb' });
    await client.connect();

    // SPARQL SELECT
    const { rows } = await client.query(
        `SELECT * FROM pg_ripple.sparql($1)`,
        [`
            PREFIX dct:  <http://purl.org/dc/terms/>
            PREFIX bibo: <http://purl.org/ontology/bibo/>
            
            SELECT ?paper ?title
            WHERE {
                ?paper a bibo:AcademicArticle ;
                       dct:title ?title .
            }
            LIMIT 10
        `]
    );

    for (const row of rows) {
        const result = row.result;
        console.log(`Paper: ${result.paper}, Title: ${result.title}`);
    }

    // Load Turtle
    const loadResult = await client.query(
        `SELECT pg_ripple.load_turtle($1)`,
        [`
            @prefix ex: <https://example.org/> .
            @prefix dct: <http://purl.org/dc/terms/> .
            ex:paper/fromjs dct:title "Loaded from JavaScript" .
        `]
    );
    console.log(`Loaded: ${loadResult.rows[0].load_turtle} triples`);

    // Export JSON-LD
    const jsonldResult = await client.query(`SELECT pg_ripple.export_jsonld()`);
    console.log(JSON.stringify(jsonldResult.rows[0].export_jsonld, null, 2));

    await client.end();
}

main().catch(console.error);

JavaScript with fetch (HTTP endpoint)

async function sparqlQuery(query) {
    const response = await fetch('http://localhost:8080/sparql', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/sparql-query',
            'Accept': 'application/sparql-results+json',
        },
        body: query,
    });
    return response.json();
}

const results = await sparqlQuery(`
    PREFIX dct: <http://purl.org/dc/terms/>
    SELECT ?paper ?title
    WHERE { ?paper dct:title ?title }
    LIMIT 10
`);

for (const binding of results.results.bindings) {
    console.log(`${binding.paper.value}: ${binding.title.value}`);
}

Java with JDBC

import java.sql.*;
import org.json.JSONObject;

public class PgRippleExample {
    public static void main(String[] args) throws Exception {
        Connection conn = DriverManager.getConnection(
            "jdbc:postgresql://localhost:5432/mydb", "postgres", "password"
        );

        // SPARQL SELECT
        PreparedStatement stmt = conn.prepareStatement(
            "SELECT * FROM pg_ripple.sparql(?)"
        );
        stmt.setString(1,
            "PREFIX dct: <http://purl.org/dc/terms/> " +
            "PREFIX bibo: <http://purl.org/ontology/bibo/> " +
            "SELECT ?paper ?title " +
            "WHERE { " +
            "    ?paper a bibo:AcademicArticle ; " +
            "           dct:title ?title . " +
            "} LIMIT 10"
        );

        ResultSet rs = stmt.executeQuery();
        while (rs.next()) {
            String jsonStr = rs.getString("result");
            JSONObject result = new JSONObject(jsonStr);
            System.out.println("Paper: " + result.getString("paper"));
            System.out.println("Title: " + result.getString("title"));
        }
        rs.close();
        stmt.close();

        // Load Turtle
        PreparedStatement loadStmt = conn.prepareStatement(
            "SELECT pg_ripple.load_turtle(?)"
        );
        loadStmt.setString(1,
            "@prefix ex: <https://example.org/> .\n" +
            "@prefix dct: <http://purl.org/dc/terms/> .\n" +
            "ex:paper/fromjava dct:title \"Loaded from Java\" .\n"
        );
        ResultSet loadRs = loadStmt.executeQuery();
        if (loadRs.next()) {
            System.out.println("Loaded: " + loadRs.getLong(1) + " triples");
        }
        loadRs.close();
        loadStmt.close();

        conn.close();
    }
}

---

SPARQL Federation

pg_ripple can query remote SPARQL endpoints from within a SPARQL query using the SERVICE keyword. This lets you join local data with remote datasets like Wikidata or DBpedia.

Querying a Remote SPARQL Endpoint

SELECT * FROM pg_ripple.sparql('
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX rdfs:   <http://www.w3.org/2000/01/rdf-schema#>
PREFIX wd:     <http://www.wikidata.org/entity/>
PREFIX wdt:    <http://www.wikidata.org/prop/direct/>

SELECT ?paper ?title ?wikidataLabel
WHERE {
    ?paper dct:title ?title ;
           dct:subject ?topic .
    
    SERVICE <https://query.wikidata.org/sparql> {
        ?topic rdfs:label ?wikidataLabel .
        FILTER (LANG(?wikidataLabel) = "en")
    }
}
LIMIT 10
');

Vector Federation

Register external vector services for federated similarity search (see Vector Federation for full details):

-- Register a Qdrant endpoint
SELECT pg_ripple.register_vector_endpoint(
    'https://qdrant.internal:6333',
    'qdrant'
);

-- Register a Weaviate endpoint
SELECT pg_ripple.register_vector_endpoint(
    'https://weaviate.internal:8080',
    'weaviate'
);