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