Knowledge Graphs

Table of Contents

1. Why Vector-Only RAG Fails at Enterprise Scale
2. Ontology Engineering & Canonical Schema Governance
3. Hybrid GraphRAG Retrieval Architecture
4. Temporal Provenance, Lineage & Citation Grounding
5. Multi-Tenant RBAC, Compliance & Graph Security
6. Production Scaling, CDC Ingestion & Observability
7. Tutorial 1: Python Entity-Relationship Extractor & Neo4j Loader
8. Tutorial 2: Python Hybrid GraphRAG Query Engine
9. Tutorial 3: Enterprise Ontology & Entity Resolution Prompt
10. Tutorial 4: Cypher Synthesis & Injection-Safe Query Prompt
11. Tutorial 5: Step-by-Step Enterprise GraphRAG Deployment
12. Tutorial 6: Step-by-Step Entity Drift & Stale-Subgraph Recovery Runbook
13. Live References & Documentation

Why Vector-Only RAG Fails at Enterprise Scale

Standard Retrieval-Augmented Generation pipelines rely on chunking documents into fixed token windows, computing dense vector embeddings, and retrieving the top-k nearest neighbors by cosine similarity. While this pattern works well for isolated FAQ lookups, it breaks down rapidly when deployed across complex enterprise repositories spanning legal contracts, engineering runbooks, CRM records, supply-chain manifests, and financial ledgers. Vector similarity measures topical proximity, not structural causality. When an executive or compliance officer asks how a supplier bankruptcy in Tier 2 affects active enterprise SLAs across three regional business units, no single 512-token chunk contains the complete answer.

The failure modes of vector-only RAG fall into four predictable engineering categories. First, chunk blindness severs cross-document relationships: a master services agreement resides in SharePoint, its amendment sits in DocuSign, and the resulting billing exception lives in Snowflake. Second, multi-hop reasoning collapses because embedding models cannot perform transitive joins across entities without explicit graph edges. Third, global aggregation queries - such as listing every customer impacted by a deprecated API version - fail because top-k retrieval is bounded to a tiny fraction of the corpus. Fourth, entity ambiguity causes silent retrieval errors when two distinct subsidiaries, products, or individuals share similar names across decades of archival documents.

Enterprise Knowledge Graphs combined with GraphRAG retrieval architectures solve these structural limitations by representing organizational knowledge as typed nodes, directed relationships, and schema-validated properties. Instead of forcing a language model to guess connections from fragmented text snippets, the retrieval layer traverses explicit paths in a property graph database such as Neo4j, collecting exact relational subgraphs alongside supporting source passages. This architecture transforms probabilistic guesswork into deterministic, auditable reasoning suitable for regulated enterprise workflows.

When to Choose GraphRAG Over Standard Vector Search

Not every internal search problem requires a full property graph. If your corpus consists of standalone, self-contained support articles with minimal cross-referencing, well-tuned hybrid BM25-plus-vector retrieval is faster and simpler to maintain. However, GraphRAG becomes mandatory the moment your teams must answer questions involving transitive dependencies (such as supply-chain blast radius or microservice failure propagation), cross-document reconciliation (such as contract amendments overriding master terms), or global portfolio aggregation across thousands of interconnected records. In these high-stakes domains, a knowledge graph serves as the structural backbone that keeps generative synthesis anchored to verifiable organizational reality.

Ontology Engineering & Canonical Schema Governance

The most common mistake in GraphRAG implementations is allowing an LLM to invent arbitrary node labels and relationship verbs during document ingestion. Without a strict ontology, a 10,000-document ingestion run produces hundreds of synonymous edge types such as WORKS_AT, EMPLOYED_BY, IS_STAFF_OF, and MANAGES_TEAM_IN. Downstream Cypher queries become brittle, recall drops sharply, and graph analytics lose mathematical consistency. Enterprise deployments require a formal, version-controlled domain ontology engineered before a single document is processed.

Schema Contracts, Pydantic Enforcement & SHACL Validation

Our engineering blueprint treats the graph schema as a strict API contract. Every node label, allowed relationship direction, required property, and data type is defined in Pydantic validation models and, for RDF/semantic-web environments, validated against W3C SHACL shapes. When an extraction agent processes unstructured text, it must emit structured JSON conforming to the exact enum of permitted entity classes and relationship predicates. Any triple that violates cardinality rules, missing required identifiers, or type constraints is routed to a quarantine queue rather than polluting the production graph.

Deterministic & Probabilistic Entity Resolution

Duplicate entities destroy graph topology. If "Acme Corp", "ACME Corporation", and "Acme Inc." exist as three separate nodes, multi-hop queries miss two-thirds of the evidence. We implement a two-stage entity resolution pipeline: first, deterministic matching against canonical enterprise master data (LEI codes, DUNS numbers, Salesforce Account IDs, or internal employee UUIDs); second, hybrid blocking using Jaro-Winkler lexical similarity paired with embedding cosine distance and an LLM adjudication step for borderline merges. Every merge records an explicit ALIAS_OF or merged_from audit property so analysts can inspect or reverse resolution decisions.

Hybrid GraphRAG Retrieval Architecture

A production GraphRAG system never discards vector search; instead, it unifies vector similarity, full-text BM25 lexical matching, and structural graph traversal inside a single orchestration layer. When a user submits a complex query, a lightweight query planner decomposes the intent into anchor entities, temporal constraints, and traversal depth. Vector and full-text indexes locate candidate entry-point nodes and raw document chunks in milliseconds, while Cypher queries expand outward across 1 to 3 hops to pull in connected dependencies, owners, policies, and historical exceptions.

For global sensemaking queries - such as summarizing recurring risk themes across 50,000 audit reports - we implement hierarchical community summarization inspired by Microsoft GraphRAG. Using the Leiden community detection algorithm, densely connected clusters of entities are grouped into multi-level communities, each pre-summarized with key findings and citations. At query time, a map-reduce retrieval pass scores relevant community summaries in parallel and synthesizes a cohesive executive answer without exceeding context limits.

To prevent context-window bloat, all retrieved candidates (graph paths, node properties, community summaries, and verbatim text chunks) pass through Reciprocal Rank Fusion (RRF) and a cross-encoder reranker before entering the synthesis prompt. Using LangGraph state machines, the retrieval pipeline enforces strict token budgets and falls back gracefully to lexical-plus-vector search if a Cypher pattern returns zero matches.

Query Routing, Latency Budgets & Fallback Guarantees

Enterprise users expect sub-two-second time-to-first-token even when traversing millions of edges. Rather than running every retrieval strategy on every request, our query router classifies incoming prompts into three deterministic execution lanes: point-entity lookups (direct indexed node match plus 1-hop neighborhood), multi-hop dependency queries (vector seed discovery followed by 2-to-3-hop constrained Cypher expansion), and corpus-wide thematic questions (parallel map-reduce over precomputed Leiden community summaries). Each lane carries a strict database timeout ceiling and a deterministic fallback path so transient graph spikes never stall user-facing copilots.

Temporal Provenance, Lineage & Citation Grounding

Enterprise truth is time-dependent. A vendor might be approved in Q1, suspended in Q3, and reinstated under a new compliance addendum in Q4. A static knowledge graph that overwrites edges in place destroys historical auditability and causes severe hallucinations when teams ask point-in-time questions. To guarantee audit-grade accuracy, our architecture implements bitemporal modeling on every critical relationship: valid_from and valid_to capture when a fact was true in the real world, while tx_ingested_at and superseded_at record when the enterprise system learned about the change.

Every node and edge also maintains an explicit provenance link back to its originating Document and Chunk nodes via EXTRACTED_FROM relationships carrying the document SHA-256 hash, page number, and character span. Following Anthropic grounded citation practices, the synthesis model is instructed to cite only relationships and verbatim evidence returned in the verified subgraph. If a relationship has an expired valid_to timestamp relative to the query date, it is excluded from active-state answers while remaining queryable for historical audits.

Conflict Resolution & Source Authority Hierarchy

Large enterprises routinely contain contradictory statements across Slack threads, slide decks, wikis, and signed legal agreements. When two documents assert conflicting values for the same relationship - such as differing SLA uptime commitments or system ownership - our ingestion layer resolves precedence using a deterministic Source Authority Hierarchy. Signed contracts and ERP master tables outrank Confluence pages, which in turn outrank informal chat transcripts. Both assertions remain stored in the graph with distinct authority_rank and confidence_score properties, allowing compliance teams to inspect contradictions rather than silently overwriting authoritative records.

Multi-Tenant RBAC, Compliance & Graph Security

When an organization consolidates HR, M&A, legal, and engineering data into a unified knowledge graph, access control becomes non-negotiable. A junior support engineer must never be able to traverse an edge that surfaces confidential executive compensation or unreleased acquisition targets. Unlike flat vector stores where metadata filtering can be bypassed by overly broad similarity queries, property graphs must enforce role-based access control (RBAC) at both the node-label and relationship-property levels on every single hop.

Our security architecture implements a zero-trust policy enforcement point between the GraphRAG orchestrator and the database driver. User identity claims from your corporate OIDC or SAML identity provider are translated into immutable tenant and clearance parameters injected into every Cypher query. Furthermore, in alignment with the OWASP Top 10 for LLM Applications and the NIST AI Risk Management Framework, we never allow an LLM to execute raw, unvalidated write queries or arbitrary string-concatenated Cypher. Generated queries are restricted to read-only database roles, parsed through an AST allow-list validator, and executed with strict memory and timeout ceilings to prevent graph-traversal denial-of-service attacks.

PII Masking & Cross-Departmental Information Barriers

In regulated financial, healthcare, and legal organizations, Chinese-wall information barriers must prevent data leakage even across internal teams. We attach classification labels (such as Public, Internal, Confidential, and Restricted) directly to nodes and edges, while masking sensitive person-level properties behind tokenized pseudonyms for unauthorized roles. Every GraphRAG response logs the exact user principal, parameterized Cypher hash, returned node IDs, and cited document hashes to an append-only SIEM sink, satisfying SOC 2 Type II and GDPR auditability requirements.

Production Scaling, CDC Ingestion & Observability

Batch-rebuilding an entire knowledge graph every night does not scale past tens of thousands of documents. Modern enterprise deployments use Change Data Capture (CDC) pipelines over Apache Kafka and cloud warehouses such as Snowflake to stream incremental updates in near real time. When a contract is amended, an incident ticket is closed, or a Jira epic changes ownership, only the affected document subgraph is re-extracted and merged using idempotent Cypher UNWIND batches.

At scale, graph observability is critical. Every retrieval trace is instrumented with OpenTelemetry spans capturing vector search latency, Cypher execution time, node expansion counts, reranker scores, and token consumption. Engineering teams monitor entity-resolution collision rates, orphan-node ratios, and community-summary staleness through automated dashboards, ensuring that graph quality never degrades silently as organizational data evolves.

Benchmarking GraphRAG Accuracy & Cost Efficiency

Before promoting any ontology update or extraction model change to production, our CI/CD pipeline runs an automated evaluation suite measuring four core KPIs: multi-hop path recall (whether the retrieved subgraph contains the ground-truth reasoning chain), citation precision (whether every claim in the final answer maps to a verbatim quote), hallucination rate (claims unsupported by the retrieved subgraph), and cost per 1,000 queries. By offloading structural joins from expensive LLM reasoning tokens into sub-50ms Neo4j Cypher traversals, enterprises routinely cut synthesis token consumption by 40% to 65% while simultaneously eliminating multi-hop reasoning errors.

Tutorial 1: Python Entity-Relationship Extractor & Neo4j Loader

This production Python module enforces a strict Pydantic ontology contract during extraction and loads validated entities and bitemporal relationships into Neo4j using parameterized UNWIND batch queries. Notice how every extracted triple is bound to an immutable document SHA-256 hash and tenant identifier. In production, wrap extract_validated_subgraph in a dead-letter queue retry loop so any JSON validation exception is captured for schema tuning without halting the broader ingestion batch.

import hashlib
import json
import os
from datetime import datetime, timezone
from typing import Literal
from anthropic import Anthropic
from neo4j import GraphDatabase
from pydantic import BaseModel, Field

ALLOWED_TYPES = Literal["Organization", "System", "Policy", "Contract", "Person"]
ALLOWED_RELS = Literal["OWNS", "DEPENDS_ON", "GOVERNS", "SIGNED_BY", "SUPPLIES"]

class Entity(BaseModel):
    canonical_id: str = Field(..., description="Lowercase slug identifier")
    name: str
    entity_type: ALLOWED_TYPES

class Relation(BaseModel):
    source_id: str
    target_id: str
    rel_type: ALLOWED_RELS
    valid_from: str
    evidence_quote: str

class ExtractionPayload(BaseModel):
    entities: list[Entity]
    relations: list[Relation]

anthropic_client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
driver = GraphDatabase.driver(
    os.environ["NEO4J_URI"],
    auth=(os.environ["NEO4J_USER"], os.environ["NEO4J_PASSWORD"]),
)

def extract_validated_subgraph(text: str) -> ExtractionPayload:
    schema_hint = json.dumps(ExtractionPayload.model_json_schema())
    response = anthropic_client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1800,
        system=(
            "Extract enterprise entities and relationships strictly matching this JSON Schema: "
            f"{schema_hint}. Return valid JSON only."
        ),
        messages=[{"role": "user", "content": text[:8000]}],
    )
    return ExtractionPayload.model_validate_json(response.content[0].text)

def upsert_subgraph(tenant_id: str, doc_id: str, text: str, payload: ExtractionPayload) -> None:
    doc_hash = hashlib.sha256(text.encode("utf-8")).hexdigest()
    now_iso = datetime.now(timezone.utc).isoformat()
    entities_data = [e.model_dump() for e in payload.entities]
    rels_data = [r.model_dump() for r in payload.relations]

    with driver.session() as session:
        session.run(
            """
            MERGE (d:Document {doc_id: $doc_id, tenant_id: $tenant_id})
            SET d.sha256 = $doc_hash, d.ingested_at = $now_iso
            WITH d
            UNWIND $entities AS ent
            MERGE (e:Entity {canonical_id: ent.canonical_id, tenant_id: $tenant_id})
            SET e.name = ent.name, e.entity_type = ent.entity_type
            MERGE (e)-[:EXTRACTED_FROM]->(d)
            """,
            doc_id=doc_id, tenant_id=tenant_id, doc_hash=doc_hash,
            now_iso=now_iso, entities=entities_data,
        )
        session.run(
            """
            UNWIND $rels AS rel
            MATCH (src:Entity {canonical_id: rel.source_id, tenant_id: $tenant_id})
            MATCH (tgt:Entity {canonical_id: rel.target_id, tenant_id: $tenant_id})
            MERGE (src)-[r:RELATED {rel_type: rel.rel_type, doc_id: $doc_id}]->(tgt)
            SET r.valid_from = rel.valid_from,
                r.evidence_quote = rel.evidence_quote,
                r.tx_ingested_at = $now_iso
            """,
            rels=rels_data, tenant_id=tenant_id, doc_id=doc_id, now_iso=now_iso,
        )

Tutorial 2: Python Hybrid GraphRAG Query Engine

This retrieval engine executes a two-phase hybrid pass: first locating seed entities via Neo4j vector similarity search, then expanding 2 hops across tenant-isolated relationships while collecting verbatim evidence quotes. The resulting structured subgraph is passed to the synthesis model for citation-grounded answering. Notice the ALL(n IN nodes(path) ...) predicate inside the Cypher query: this guarantees that even intermediate nodes along a multi-hop path strictly belong to the authenticated tenant, eliminating indirect cross-tenant graph leakage.

import json
import os
from anthropic import Anthropic
from neo4j import GraphDatabase

anthropic_client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
driver = GraphDatabase.driver(
    os.environ["NEO4J_URI"],
    auth=(os.environ["NEO4J_USER"], os.environ["NEO4J_PASSWORD"]),
)

def retrieve_hybrid_context(tenant_id: str, query_embedding: list[float], top_k: int = 5) -> list[dict]:
    cypher = """
    CALL db.index.vector.queryNodes('entity_embedding_idx', $top_k, $embedding)
    YIELD node AS seed, score
    WHERE seed.tenant_id = $tenant_id
    MATCH path = (seed)-[r:RELATED*1..2]-(neighbor:Entity)
    WHERE ALL(n IN nodes(path) WHERE n.tenant_id = $tenant_id)
      AND ALL(rel IN relationships(path) WHERE rel.superseded_at IS NULL)
    RETURN seed.name AS seed_name,
           score AS vector_score,
           [n IN nodes(path) | n.name] AS chain,
           [rel IN relationships(path) | {type: rel.rel_type, quote: rel.evidence_quote, doc: rel.doc_id}] AS evidence
    LIMIT 25
    """
    with driver.session() as session:
        result = session.run(cypher, tenant_id=tenant_id, embedding=query_embedding, top_k=top_k)
        return [record.data() for record in result]

def answer_with_graphrag(question: str, tenant_id: str, query_embedding: list[float]) -> str:
    subgraph = retrieve_hybrid_context(tenant_id=tenant_id, query_embedding=query_embedding)
    if not subgraph:
        return "Insufficient verified graph evidence for this tenant."

    response = anthropic_client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1200,
        system=(
            "You are an Enterprise GraphRAG Analyst. Answer strictly from the provided "
            "subgraph chains and evidence quotes. Cite the exact doc ID for every claim."
        ),
        messages=[{
            "role": "user",
            "content": f"Question: {question}\n\nVerified Subgraph:\n{json.dumps(subgraph, indent=2)}"
        }],
    )
    return response.content[0].text

Tutorial 3: Enterprise Ontology & Entity Resolution Prompt

Use this production system prompt when extracting knowledge triples from unstructured enterprise documents. It forces canonical slug generation, resolves aliases against a provided master entity list, and rejects ungrounded inferences.

ROLE:
You are an Enterprise Ontology & Entity Resolution Engineer.

ALLOWED NODE TYPES:
- Organization, System, Policy, Contract, Person

ALLOWED RELATIONSHIP TYPES:
- OWNS, DEPENDS_ON, GOVERNS, SIGNED_BY, SUPPLIES

CANONICAL RESOLUTION RULES:
1. Check the supplied MASTER_ENTITY_REGISTRY first. If an entity matches an alias or abbreviation, emit its exact canonical_id.
2. Never invent new node labels or relationship verbs outside the allowed lists.
3. Every relationship MUST include:
   - valid_from (ISO-8601 date from the document, or "unknown" if unstated)
   - evidence_quote (verbatim substring copied directly from the source text)
4. Output valid JSON only. Omit any relationship that lacks verbatim textual support.

Tutorial 4: Cypher Synthesis & Injection-Safe Query Prompt

When natural language questions must be translated into analytical Cypher queries, this prompt enforces parameterized inputs, read-only clauses, mandatory tenant isolation, and bounded traversal depths.

ROLE:
You are a Senior Neo4j Cypher Security Architect. Generate a read-only parameterized Cypher query for the provided graph schema.

SECURITY & GOVERNANCE CONSTRAINTS:
1. READ-ONLY ONLY: Never emit CREATE, MERGE, SET, DELETE, DETACH, REMOVE, or CALL apoc.cypher.run.
2. MANDATORY TENANT FILTER: Every MATCHed node MUST include `tenant_id: $tenant_id`.
3. ACTIVE TEMPORAL FILTER: Filter relationships with `rel.superseded_at IS NULL` unless the user explicitly asks for historical state.
4. BOUNDED TRAVERSAL: Variable-length paths MUST specify an upper bound (maximum `*1..3`). Never use unbounded `*`.
5. PARAMETERIZATION: Use `$param` placeholders for all user-supplied strings. Never inline raw user text.
6. RESULT CAP: Always conclude with `LIMIT 50`.

Tutorial 5: Step-by-Step Enterprise GraphRAG Deployment

Follow this seven-step operational checklist to take an enterprise knowledge graph from architectural blueprint to governed production rollout.

1. Freeze the Domain Ontology (Week 1): Convene domain architects and legal stakeholders to ratify the canonical node labels, relationship verbs, and bitemporal property schema. Commit the Pydantic and SHACL contracts to Git.
2. Provision Composite Constraints & Vector Indexes: In Neo4j Enterprise, create uniqueness constraints on (canonical_id, tenant_id) and initialize HNSW vector indexes on entity descriptions and document chunks.
3. Run Historical Backfill with Quarantine Monitoring: Process archival repositories in parallel worker pools. Route any schema validation failures to the quarantine queue and tune extraction prompts until rejection rates fall below 1%.
4. Connect Streaming CDC Pipelines: Wire Kafka topics or Snowflake streams to your incremental ingestion workers so document edits, revocations, and CRM updates supersede old edges within seconds.
5. Execute Multi-Hop Golden Evaluation: Benchmark retrieval against 150+ SME-curated multi-hop questions measuring path recall, citation precision, and answer faithfulness compared to your baseline vector-only RAG.
6. Perform Cross-Tenant RBAC Penetration Testing: Verify that low-privilege service accounts cannot surface restricted subgraphs via indirect hops, wildcard Cypher generation, or vector seed leakage.
7. Canary Rollout with OpenTelemetry Alerts: Release to 10% of internal users with p95 latency alerts and citation-grounding telemetry before promoting to organization-wide traffic.

Tutorial 6: Step-by-Step Entity Drift & Stale-Subgraph Recovery Runbook

When entity resolution thresholds drift or a faulty ontology migration introduces duplicate or conflicting edges, execute this incident recovery runbook immediately without taking the read-only query tier offline. Having bitemporal timestamps and immutable document hashes on every edge allows platform engineers to perform surgical rollbacks in minutes rather than rebuilding the entire enterprise graph from scratch.

1. Pause CDC Ingestion Workers: Halt downstream Kafka consumers for the affected tenant or document source to stop additional bad triples from entering the graph.
2. Isolate Affected Subgraph by Ingestion Timestamp: Run a diagnostic Cypher query filtering on tx_ingested_at >= $incident_start to quantify impacted nodes, edges, and document IDs.
3. Restore Active State via Bitemporal Rollback: Mark corrupted edges with superseded_at = $rollback_ts and clear superseded_at on the prior valid edge version so live queries immediately return accurate pre-incident relationships.
4. Deduplicate Split Entities: Execute an APOC node-merge routine that consolidates duplicate canonical_id nodes, preserves all EXTRACTED_FROM provenance links, and logs the merge map for audit compliance.
5. Re-Compute Affected Leiden Community Summaries: Trigger incremental community re-summarization only for the modified graph partitions rather than recomputing the entire enterprise corpus.
6. Verify Golden Eval & Resume Streaming: Re-run the automated regression suite against the repaired subgraph, confirm zero orphan nodes or broken citations, and unpause the CDC consumer group.

Live References & Documentation

• Neo4j Cypher Query Language Official Manual
• Neo4j GraphRAG for Python Official Documentation
• Microsoft GraphRAG Architecture & Community Summarization
• Anthropic Grounded Citations & Verification Documentation
• LangGraph Stateful Agent Orchestration Documentation
• Pydantic Structured Schema Validation Documentation
• W3C Shapes Constraint Language (SHACL) Specification
• Apache Kafka Distributed Streaming & CDC Documentation
• Snowflake Streams & Change Data Capture Guide
• OpenTelemetry Distributed Tracing Specification
• NIST AI Risk Management Framework
• OWASP Top 10 for LLM Applications