> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-docsdy-1782337909-2539eb6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Graph RAG integration
> Integrate with the Graph RAG retriever using LangChain Python.
This guide provides an introduction to Graph RAG. For detailed documentation of all
supported features and configurations, refer to the
[Graph RAG Project Page](https://datastax.github.io/graph-rag/).
## Overview
The `GraphRetriever` from the `langchain-graph-retriever` package provides a LangChain
[retriever](/oss/python/langchain/retrieval/) that combines **unstructured** similarity search
on vectors with **structured** traversal of metadata properties. This enables graph-based
retrieval over an **existing** vector store.
### Integration details
| Retriever | Source | PyPI Package | Latest | Project Page |
| :--------------- | :------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------: |
| `GraphRetriever` | [github.com/datastax/graph-rag](https://github.com/datastax/graph-rag/tree/main/packages/langchain-graph-retriever) | [`langchain-graph-retriever`](https://pypi.org/project/langchain-graph-retriever/) |  | [Graph RAG](https://datastax.github.io/graph-rag/) |
## Benefits
* [**Link based on existing metadata:**](https://datastax.github.io/graph-rag/guide/get-started/)
Use existing metadata fields without additional processing. Retrieve more from an
existing vector store!
* [**Change links on demand:**](https://datastax.github.io/graph-rag/guide/edges/)
Edges can be specified on-the-fly, allowing different relationships to be traversed
based on the question.
* [**Pluggable Traversal Strategies:**](https://datastax.github.io/graph-rag/guide/strategies/)
Use built-in traversal strategies like Eager or MMR, or define custom logic to select
which nodes to explore.
* [**Broad compatibility:**](https://datastax.github.io/graph-rag/guide/adapters/)
Adapters are available for a variety of vector stores with support for additional
stores easily added.
## Setup
### Installation
This retriever lives in the `langchain-graph-retriever` package.
```bash pip theme={null}
pip install -qU langchain-graph-retriever
```
```bash uv theme={null}
uv add langchain-graph-retriever
```
## Instantiation
The following examples will show how to perform graph traversal over some sample
Documents about animals.
### Prerequisites
Toggle for Details
1. Ensure you have Python 3.10+ installed
2. Install the following package that provides sample data.
```bash theme={null}
pip install -qU graph_rag_example_helpers
```
3. Download the test documents:
```python theme={null}
from graph_rag_example_helpers.datasets.animals import fetch_documents
animals = fetch_documents()
```
4.
### Populating the vector store
This section shows how to populate a variety of vector stores with the sample data.
For help on choosing one of the vector stores below, or to add support for your
vector store, consult the documentation about
[Adapters and Supported Stores](https://datastax.github.io/graph-rag/guide/adapters/).
Install the `langchain-graph-retriever` package with the `astra` extra:
```bash theme={null}
pip install "langchain-graph-retriever[astra]"
```
Then create a vector store and load the test documents:
```python theme={null}
from langchain_astradb import AstraDBVectorStore
vector_store = AstraDBVectorStore.from_documents(
documents=animals,
embedding=embeddings,
collection_name="animals",
api_endpoint=ASTRA_DB_API_ENDPOINT,
token=ASTRA_DB_APPLICATION_TOKEN,
)
```
For the `ASTRA_DB_API_ENDPOINT` and `ASTRA_DB_APPLICATION_TOKEN` credentials,
consult the [AstraDB Vector Store Guide](/oss/python/integrations/vectorstores/astradb).
:::note
For faster initial testing, consider using the **InMemory** Vector Store.
:::
Install the `langchain-graph-retriever` package with the `chroma` extra:
```bash theme={null}
pip install "langchain-graph-retriever[chroma]"
```
Then create a vector store and load the test documents:
```python theme={null}
from langchain_chroma.vectorstores import Chroma
from langchain_graph_retriever.transformers import ShreddingTransformer
vector_store = Chroma.from_documents(
documents=list(ShreddingTransformer().transform_documents(animals)),
embedding=embeddings,
collection_name="animals",
)
```
For help creating an Chroma connection, consult the [Chroma Vector Store Guide](/oss/python/integrations/vectorstores/chroma).
:::note
Chroma doesn't support searching in nested metadata. Because of this
it is necessary to use the [`ShreddingTransformer`](https://datastax.github.io/graph-rag/reference/langchain_graph_retriever/transformers/#langchain_graph_retriever.transformers.shredding.ShreddingTransformer)
when inserting documents.
:::
Install the `langchain-graph-retriever` package:
```bash theme={null}
pip install "langchain-graph-retriever"
```
Then create a vector store and load the test documents:
```python theme={null}
from langchain_core.vectorstores import InMemoryVectorStore
vector_store = InMemoryVectorStore.from_documents(
documents=animals,
embedding=embeddings,
)
```
:::tip
Using the `InMemoryVectorStore` is the fastest way to get started with Graph RAG
but it isn't recommended for production use. Instead it is recommended to use
**AstraDB** or **OpenSearch**.
:::
### Graph traversal
This graph retriever starts with a single animal that best matches the query, then
traverses to other animals sharing the same `habitat` and/or `origin`.
```python theme={null}
from graph_retriever.strategies import Eager
from langchain_graph_retriever import GraphRetriever
traversal_retriever = GraphRetriever(
store = vector_store,
edges = [("habitat", "habitat"), ("origin", "origin")],
strategy = Eager(k=5, start_k=1, max_depth=2),
)
```
The above creates a graph traversing retriever that starts with the nearest
animal (`start_k=1`), retrieves 5 documents (`k=5`) and limits the search to documents
that are at most 2 steps away from the first animal (`max_depth=2`).
The `edges` define how metadata values can be used for traversal. In this case, every
animal is connected to other animals with the same `habitat` and/or `origin`.
```python theme={null}
results = traversal_retriever.invoke("what animals could be found near a capybara?")
for doc in results:
print(f"{doc.id}: {doc.page_content}")
```
```text theme={null}
capybara: capybaras are the largest rodents in the world and are highly social animals.
heron: herons are wading birds known for their long legs and necks, often seen near water.
crocodile: crocodiles are large reptiles with powerful jaws and a long lifespan, often living over 70 years.
frog: frogs are amphibians known for their jumping ability and croaking sounds.
duck: ducks are waterfowl birds known for their webbed feet and quacking sounds.
```
Graph traversal improves retrieval quality by leveraging structured relationships in
the data. Unlike standard similarity search (see below), it provides a clear,
explainable rationale for why documents are selected.
In this case, the documents `capybara`, `heron`, `frog`, `crocodile`, and `newt` all
share the same `habitat=wetlands`, as defined by their metadata. This should increase
Document Relevance and the quality of the answer from the LLM.
### Comparison to standard retrieval
When `max_depth=0`, the graph traversing retriever behaves like a standard retriever:
```python theme={null}
standard_retriever = GraphRetriever(
store = vector_store,
edges = [("habitat", "habitat"), ("origin", "origin")],
strategy = Eager(k=5, start_k=5, max_depth=0),
)
```
This creates a retriever that starts with the nearest 5 animals (`start_k=5`),
and returns them without any traversal (`max_depth=0`). The edge definitions
are ignored in this case.
This is essentially the same as:
```python theme={null}
standard_retriever = vector_store.as_retriever(search_kwargs={"k":5})
```
For either case, invoking the retriever returns:
```python theme={null}
results = standard_retriever.invoke("what animals could be found near a capybara?")
for doc in results:
print(f"{doc.id}: {doc.page_content}")
```
```text theme={null}
capybara: capybaras are the largest rodents in the world and are highly social animals.
iguana: iguanas are large herbivorous lizards often found basking in trees and near water.
guinea pig: guinea pigs are small rodents often kept as pets due to their gentle and social nature.
hippopotamus: hippopotamuses are large semi-aquatic mammals known for their massive size and territorial behavior.
boar: boars are wild relatives of pigs, known for their tough hides and tusks.
```
These documents are joined based on similarity alone. Any structural data that existed
in the store is ignored. As compared to graph retrieval, this can decrease Document
Relevance because the returned results have a lower chance of being helpful to answer
the query.
## Usage
Following the examples above, `invoke` is used to initiate retrieval on a query.
***
## API reference
To explore all available parameters and advanced configurations, refer to the
[Graph RAG API reference](https://datastax.github.io/graph-rag/reference/).
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/retrievers/graph_rag.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).