Property Graph RAG

Purpose and Scope

Property Graph RAG is the part of a LlamaIndex application where retrieved context is not only similar text, but also structured relationships among entities. In ordinary Retrieval-Augmented Generation, the application loads data, indexes it, stores it, retrieves relevant context for a user query, and sends that context to an LLM. A property graph adds an explicit graph model to that flow: nodes represent things, edges represent relationships, and properties attach names, labels, text, identifiers, or other metadata to both. This page explains how that graph-oriented model fits into the broader LlamaIndex learning path and how it connects to agents and workflows. Sources: docs/src/content/docs/framework/understanding/_meta.yml, docs/src/content/docs/framework/understanding/agent/_meta.yml

The official RAG introduction frames RAG as the answer to a common limitation: LLMs do not know your private or current data unless your application retrieves it. Graph-based RAG keeps that same purpose, but changes what can be retrieved. Instead of returning only chunks with high embedding similarity, a graph retriever can follow paths such as company to founder to product, use generated Cypher, expand synonyms, or combine vector context with graph traversal. That makes graph RAG useful when the question depends on relationships, hierarchy, provenance, or multi-hop facts rather than a single local passage. Sources: docs/src/content/docs/framework/understanding/_meta.yml

The requested repository sources for this page are located under the framework Learn section and its Building agents subsection. That matters because property graph retrieval is rarely an isolated feature in a real application. It is usually called by a query engine, exposed as a tool to an agent, or embedded in a workflow that streams events and maintains state. The agent documentation defines an agent as LLM-powered software that receives a task, selects tools, executes steps, and loops until it can return a result. A graph query engine or retriever can be one of those tools. Sources: docs/src/content/docs/framework/understanding/agent/index.mdx

Relevant Source Files

• docs/src/content/docs/framework/understanding/_meta.yml — Places this topic under the framework Learn documentation, which is the reader path for conceptual RAG material.
• docs/src/content/docs/framework/understanding/agent/_meta.yml — Places agent-related learning material under Building agents, the section most relevant when graph retrieval is exposed to an agent.
• docs/src/content/docs/framework/understanding/agent/index.mdx — Defines agents, tools, LLM-driven step execution, and the FunctionAgent tutorial flow that can consume graph-backed query tools.
• docs/src/content/docs/framework/understanding/agent/multi_agent.md — Describes AgentWorkflow, specialist agents, handoffs, orchestration, and sub-agents-as-tools patterns that can route work to graph retrieval specialists.
• docs/src/content/docs/framework/understanding/agent/state.md — Explains Context, serializable workflow state, and tool access to state, which are important when graph-RAG conversations need continuity across runs.
• docs/src/content/docs/framework/understanding/agent/human_in_the_loop.md — Shows event-based human approval with InputRequiredEvent, HumanResponseEvent, wait_for_event, and send_event, useful when graph updates or high-impact actions require review.

Conceptual Model

A property graph index should be understood as an index family for relationship-heavy retrieval. The official API reference names PropertyGraphIndex as the main index entry point and groups it with retriever and path-extractor classes. At indexing time, documents are converted into graph facts and supporting text context. Path extractors such as SimpleLLMPathExtractor, SchemaLLMPathExtractor, and ImplicitPathExtractor indicate that graph structure can come from LLM-extracted triples, schema-constrained extraction, or implicit relationships. The result is a retrievable structure where both graph topology and text context can participate in answering questions. Sources: docs/src/content/docs/framework/understanding/_meta.yml

The graph store side supplies the persistence contract. The official graph store reference lists GraphStore, PropertyGraphStore, DEFAULT_PERSIST_DIR, and DEFAULT_PERSIST_FNAME. In practice, the index and retriever layer should be read as the query-facing API, while the graph store layer is the storage-facing API. This separation lets an application reason about two concerns independently: how graph facts are extracted and retrieved, and where the graph data is stored. It also mirrors the broader LlamaIndex pattern where indexes, stores, retrievers, query engines, and agents are separate but composable primitives. Sources: docs/src/content/docs/framework/understanding/_meta.yml

Graph RAG also changes how readers should think about recall. A vector index is strongest when the answer is located in semantically similar passages. A property graph can improve recall when a query mentions one entity but the answer is connected through another entity, relationship, or schema field. For example, a user may ask who influenced a product, what organizations share a supplier, or which documents mention people connected to a contract. In those cases, a retriever can combine graph neighborhoods, generated graph queries, and supporting snippets before the LLM synthesizes the final answer. Sources: docs/src/content/docs/framework/understanding/_meta.yml

API Components

The property graph API surface is centered on three groups: index construction, retrieval, and path extraction. PropertyGraphIndex is the high-level index. PGRetriever, BasePGRetriever, and CustomPGRetriever define retriever behavior and extension points. Query-oriented retrievers include TextToCypherRetriever, CypherTemplateRetriever, LLMSynonymRetriever, and VectorContextRetriever. Extraction components include ImplicitPathExtractor, SchemaLLMPathExtractor, and SimpleLLMPathExtractor. The names are important because they describe the intended customization seams: change extraction when graph construction is wrong, change retrieval when query planning or context expansion is wrong. Sources: docs/src/content/docs/framework/understanding/_meta.yml

Area	Public names from the official API evidence	Reader task
Index	PropertyGraphIndex	Build a graph-oriented index over documents and extracted relationships.
Base retrieval	BasePGRetriever, PGRetriever, CustomPGRetriever	Retrieve graph context or implement custom retrieval behavior.
Cypher retrieval	TextToCypherRetriever, CypherTemplateRetriever	Convert natural-language questions or templates into graph database queries.
Hybrid retrieval	LLMSynonymRetriever, VectorContextRetriever	Expand entity mentions or combine graph context with vector-like text context.
Path extraction	ImplicitPathExtractor, SchemaLLMPathExtractor, SimpleLLMPathExtractor	Extract relationships from source documents during indexing.
Storage contract	GraphStore, PropertyGraphStore, DEFAULT_PERSIST_DIR, DEFAULT_PERSIST_FNAME	Persist and load graph data through graph store abstractions.

Because the official agent tutorial describes tools as ordinary Python functions or LlamaIndex query engines that an agent can select, a property graph retriever usually becomes most useful when wrapped behind a focused tool. The tool description should tell the LLM what the graph contains and when to use it, such as relationship questions, multi-hop company ownership questions, or entity-neighborhood exploration. The agent uses the tool name, parameters, docstring, and type hints to decide whether to call it, so graph-RAG tools need clear semantic boundaries rather than generic names like search. Sources: docs/src/content/docs/framework/understanding/agent/index.mdx

Execution Flow

A typical property graph RAG workflow begins with loading source data, then extracting graph paths and text context into an index, then storing the graph and related metadata. At query time, the application selects a graph retriever strategy, obtains structured and unstructured context, and asks an LLM to synthesize the answer. If the graph retriever is behind an agent tool, the agent decides whether to invoke it as one step in a larger task. This is consistent with the agent documentation: each step can use a tool, judge progress, and either continue or return a final answer. Sources: docs/src/content/docs/framework/understanding/agent/index.mdx

Multi-agent designs are a natural extension when graph RAG is only one specialty. The multi-agent documentation presents AgentWorkflow as a preconfigured workflow that receives a user message, executes tools, allows handoffs, and repeats until a final answer is returned. In a graph-RAG system, one agent might specialize in graph exploration, another in writing a report, and another in review. The orchestrator pattern can expose graph retrieval as a sub-agent tool, giving one coordinating agent control over when to call the graph expert and when to use other search or synthesis capabilities. Sources: docs/src/content/docs/framework/understanding/agent/multi_agent.md

State is especially important for graph RAG because entity disambiguation and conversational follow-ups often depend on previous turns. The state documentation explains that AgentWorkflow is stateless between runs by default, and that a workflow Context can maintain state within and between runs. A graph-RAG assistant can use that context to remember which entity the user meant, which graph neighborhood has already been explored, or which report section is being drafted. The same documentation shows that contexts can be serialized with JsonSerializer or JsonPickleSerializer and restored later. Sources: docs/src/content/docs/framework/understanding/agent/state.md

Human Review and Operational Constraints

Graph extraction and graph updates can introduce operational risk. A graph may assert relationships that came from ambiguous text, a generated Cypher query may be too broad, or a tool may prepare to write derived facts into a persistent store. The human-in-the-loop documentation provides a useful pattern for these cases. A workflow tool can call ctx.wait_for_event, emit an InputRequiredEvent, and wait for a matching HumanResponseEvent. The caller receives the event through the stream and sends the response back with handler.ctx.send_event. This lets a graph-RAG workflow pause before committing sensitive actions. Sources: docs/src/content/docs/framework/understanding/agent/human_in_the_loop.md

This event pattern is not specific to graphs, but it is a good fit for graph applications because relationships often become reusable application knowledge. If a system is only reading from a graph, human approval may be unnecessary. If it is adding extracted relationships, merging entities, deleting nodes, or using graph results to trigger external actions, review checkpoints are safer. The same page notes that input can come from a terminal, GUI, audio input, another agent, or another process, and that long-running input may require serializing context so the workflow can resume later. Sources: docs/src/content/docs/framework/understanding/agent/human_in_the_loop.md, docs/src/content/docs/framework/understanding/agent/state.md

Implementation Guidance

Start with the retrieval question rather than the storage technology. If users ask fact lookup questions over short documents, a vector index may be enough. Choose property graph RAG when the application must answer relationship questions, traverse entity neighborhoods, respect a schema, generate graph queries, or combine graph facts with text evidence. Then decide whether the graph interface should be exposed as a query engine, an agent tool, or a specialist agent. This keeps the design aligned with LlamaIndex’s composable model instead of forcing every query through the same retriever. Sources: docs/src/content/docs/framework/understanding/_meta.yml, docs/src/content/docs/framework/understanding/agent/index.mdx

When building an agent-facing graph tool, write the public contract as carefully as the implementation. The agent tutorial emphasizes that tool names, parameters, docstrings, and type hints are part of tool selection. A useful graph tool might accept an entity name, relationship type, or natural-language question, then return concise facts with supporting text. If a workflow keeps state, store disambiguated entity identifiers or prior graph paths in Context rather than relying on the LLM to remember them. If the workflow crosses a safety boundary, use the human-in-the-loop event pattern before continuing. Sources: docs/src/content/docs/framework/understanding/agent/index.mdx, docs/src/content/docs/framework/understanding/agent/state.md, docs/src/content/docs/framework/understanding/agent/human_in_the_loop.md

Next Steps

Use this page as the conceptual bridge between core RAG and graph-aware applications. Next, read the index and retriever material to understand how PropertyGraphIndex relates to other index families, then read the storage material to understand graph store persistence contracts. If your graph retriever will be used by an LLM-powered assistant, continue with the agent, tools, workflows, sessions, and streaming pages. For production systems, pay special attention to state serialization, review events, and clear tool contracts so graph retrieval remains understandable, inspectable, and safe as the application grows. Sources: docs/src/content/docs/framework/understanding/agent/index.mdx, docs/src/content/docs/framework/understanding/agent/multi_agent.md, docs/src/content/docs/framework/understanding/agent/state.md