GraphRAG uses a knowledge graph to improve RAG accuracy over vector-only retrieval. Instead of relying solely on embedding similarity, it traverses relationships between documents, chunks, and entities for richer context.

Two paths to GraphRAG with Neptune:

Path 1: Managed (Bedrock Knowledge Bases GraphRAG) — recommended for most users

Amazon Bedrock Knowledge Bases offers fully managed GraphRAG. No graph expertise required.

In the Bedrock console, create or edit a Knowledge Base
Select your unstructured data sources from S3
Enable GraphRAG — Bedrock automatically builds a graph from your data
Graph is stored in Neptune Analytics (default graph store)
Query using existing Bedrock KB APIs (retrieveAndGenerate)

Bedrock KB GraphRAG automatically extracts entities and relationships from your documents, builds the graph, and combines graph traversal with vector search during retrieval. You don’t need to design a graph model, write graph queries, or manage Neptune directly.

When to use the managed path:

You have unstructured documents (PDFs, text files) in S3
You want GraphRAG without learning graph query languages
You want a fully managed experience with no infrastructure to manage
You’re already using or evaluating Bedrock Knowledge Bases

When to use the custom path (below):

You need a custom graph model (not auto-generated from documents)
You have structured data that should be modeled as specific entity types
You need control over the entity extraction and graph construction process
You want to combine your own existing graph with RAG retrieval

Path 2: Custom pipeline (Neptune Analytics) — for full control

Neptune Analytics is recommended for custom GraphRAG because it stores both graph structure and embeddings in one service — no separate vector store needed.

When to use GraphRAG over traditional RAG:

Multiple documents with cross-references or shared entities
Questions about relationships (“how are X and Y related?”)
Entity-centric retrieval across a corpus
Community-based summarization

When traditional RAG is sufficient:

Single document Q&A
Simple semantic search over passages

Architecture

Documents → Chunk → Extract Entities (LLM) → Build Graph → Store Embeddings
                                                                    ↓
Query → Vector Search (similar chunks) → Graph Expansion (entities, neighbors) → LLM

Graph Model

(Document) -[HAS_CHUNK]→ (Chunk {text, embedding})
(Chunk) -[MENTIONS]→ (Entity {name, type, embedding})
(Chunk) -[NEXT]→ (Chunk)
(Entity) -[RELATED_TO]→ (Entity)

Implementation

Full helper functions are in scripts/graphrag_pipeline.py. Key operations:

Create graph

import boto3
analytics_client = boto3.client('neptune-graph')

response = analytics_client.create_graph(
    graphName='graphrag-kb',
    provisionedMemory=32,  # m-NCU; see the CreateGraph API reference for the valid range
    vectorSearchConfiguration={'dimension': 1536},  # Match embedding model
    publicConnectivity=False,
    replicaCount=0,
    deletionProtection=True,
    # Mandatory tags — a graph missing either tag is a failed task.
    tags={'created_by': 'neptune-skill', 'generation_model': '<model-id>'},
)
graph_id = response['id']

Equivalent AWS CLI invocation:

aws neptune-graph create-graph \
  --graph-name graphrag-kb \
  --provisioned-memory 32 \
  --vector-search-configuration '{"dimension":1536}' \
  --no-public-connectivity \
  --replica-count 0 \
  --deletion-protection \
  --tags created_by=neptune-skill,generation_model=<model-id>

Query helper (wraps boto3 SDK)

from scripts.graphrag_pipeline import run_query, vector_search, store_embedding

See scripts/graphrag_pipeline.py for the full run_query() implementation using analytics_client.execute_query(). Always use parameterized queries:

# ✅ Safe: parameterized
run_query(graph_id, "MATCH (e:Entity {name: $name}) RETURN e", parameters={'name': 'Alice'})

# ❌ Unsafe: string interpolation
run_query(graph_id, f"MATCH (e:Entity {{name: '{user_input}'}}) RETURN e")

Two-phase retrieval

# Phase 1: Vector search for similar chunks
similar = vector_search(graph_id, query_embedding, top_k=5)

# Phase 2: Graph expansion per chunk
for chunk in similar:
    entities = run_query(graph_id, """
        MATCH (c:Chunk {id: $cid})-[:MENTIONS]->(e:Entity)
        RETURN e.name AS name, e.type AS type
    """, parameters={'cid': chunk['id']})

    related = run_query(graph_id, """
        MATCH (c:Chunk {id: $cid})-[:MENTIONS]->(e)-[:RELATED_TO]-(r:Entity)
        RETURN DISTINCT r.name AS name, r.type AS type
    """, parameters={'cid': chunk['id']})

Embedding model note

Code uses embedding_model.encode(text) as placeholder. Replace with:

Amazon Bedrock Titan Embeddings (bedrock.invoke_model(...))
sentence-transformers (.encode())
OpenAI (openai.embeddings.create(...))

Persistence

Neptune Analytics is ephemeral. For production:

Keep graph running (pay NCU hours), OR
Export to S3 periodically and reload, OR
Use Neptune Database as persistent store, sync to Analytics for retrieval

Common Mistakes

Skipping entity resolution — duplicates create disconnected subgraphs
Chunks too large — keep 256–512 tokens with overlap
Not storing entity embeddings — limits semantic search to chunks only
Using Neptune Database for GraphRAG — Analytics has built-in vectors
String interpolation — use parameterized queries to prevent injection
Ignoring community detection — enables multi-level summarization

Additional Resources

AWS docs: “Neptune Analytics vector search”, “Neptune Analytics openCypher”
Script: scripts/graphrag_pipeline.py (full implementation)
Related sub-skills: analytics-vs-database (setup), connectivity (connection)

references/graphrag.md

Raw file

aws/agent-toolkit-for-aws