{"id":9878,"library":"langchain-graph-retriever","title":"LangChain Graph Retriever","description":"langchain-graph-retriever is a specialized LangChain retriever for traversing document graphs built on top of vector-based similarity search. It enables RAG applications to perform contextual retrieval by following relationships between documents, moving beyond simple similarity. Currently at version 0.8.0, it maintains a frequent release cadence, typically with minor updates every few weeks.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/datastax/graph-rag","tags":["langchain","rag","graph","retriever","vectorstore","astra","datastax"],"install":[{"cmd":"pip install langchain-graph-retriever \"astrapy[graphs]\" langchain-community openai","lang":"bash","label":"Full installation for common usage (including AstraDB and OpenAI components)"}],"dependencies":[{"reason":"Core LangChain functionalities required by the retriever.","package":"langchain-core","optional":false},{"reason":"Required for integration with AstraDB as the underlying graph and vector store.","package":"astrapy","optional":false},{"reason":"Commonly used for various vector stores (e.g., Chroma) and embeddings providers within the LangChain ecosystem. Used in quickstart.","package":"langchain-community","optional":true},{"reason":"Provides OpenAI embeddings, a common choice for vectorizing documents. Used in quickstart.","package":"openai","optional":true}],"imports":[{"note":"The package uses its own namespace `langchain_graph_retriever`, not `langchain.graph_retriever`.","wrong":"from langchain.graph_retriever import GraphRetriever","symbol":"GraphRetriever","correct":"from langchain_graph_retriever import GraphRetriever"}],"quickstart":{"code":"import os\nfrom langchain_community.vectorstores import Chroma\nfrom langchain_community.embeddings import OpenAIEmbeddings\nfrom langchain_core.documents import Document\nfrom langchain_graph_retriever import GraphRetriever\n\n# Set your OpenAI API key. This example uses a mock key if not set in environment.\n# For actual use, ensure OPENAI_API_KEY is properly configured.\nos.environ[\"OPENAI_API_KEY\"] = os.environ.get(\"OPENAI_API_KEY\", \"sk-YOUR_OPENAI_API_KEY\")\n\nif not os.environ[\"OPENAI_API_KEY\"].startswith(\"sk-\") or os.environ[\"OPENAI_API_KEY\"] == \"sk-YOUR_OPENAI_API_KEY\":\n    print(\"OPENAI_API_KEY not set or is placeholder. Skipping quickstart execution.\")\n    print(\"Please set the OPENAI_API_KEY environment variable for a functional example.\")\nelse:\n    try:\n        # 1. Initialize Embeddings (requires 'openai' package)\n        embeddings = OpenAIEmbeddings()\n\n        # 2. Create a dummy vector store (in-memory Chroma for demonstration, requires 'langchain-community' package)\n        # In a real application, this would be populated with documents and their graph relationships\n        documents = [\n            Document(page_content=\"The quick brown fox jumps over the lazy dog.\", metadata={\"doc_id\": \"doc1\"}),\n            Document(page_content=\"The dog is lazy and enjoys napping.\", metadata={\"doc_id\": \"doc2\"}),\n            Document(page_content=\"A fox is a small omnivorous mammal.\", metadata={\"doc_id\": \"doc3\"}),\n            Document(page_content=\"Dogs are domesticated canids.\", metadata={\"doc_id\": \"doc4\"})\n        ]\n        vectorstore = Chroma.from_documents(documents, embeddings)\n\n        # 3. Initialize the GraphRetriever\n        # The GraphRetriever works by taking initial search results from the vector store\n        # and then traversing the graph of related documents. The 'k' and 'depth' parameters\n        # control the initial vector search and subsequent graph traversal depth.\n        retriever = GraphRetriever(\n            vectorstore=vectorstore,\n            k=2,     # Number of initial documents to retrieve from the vectorstore\n            depth=1  # How many levels deep to traverse the graph from the initial documents\n                     # (requires graph relationships to be defined in your actual vector store/graph DB)\n        )\n\n        # 4. Perform a retrieval\n        query = \"Tell me about animals.\"\n        relevant_docs = retriever.get_relevant_documents(query)\n\n        print(f\"\\nRetrieved {len(relevant_docs)} documents:\")\n        for i, doc in enumerate(relevant_docs):\n            print(f\"--- Document {i+1} ---\")\n            print(f\"Content: {doc.page_content}\")\n            print(f\"Metadata: {doc.metadata}\")\n    except Exception as e:\n        print(f\"An error occurred during quickstart execution: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize and use the `GraphRetriever` with an in-memory `Chroma` vector store and `OpenAIEmbeddings`. In a production environment, you would typically use a persistent vector store (like AstraDB as intended by the library) and populate it with documents and their defined graph relationships. Ensure you have installed `langchain-community` and `openai` (e.g., `pip install langchain-community openai`) in addition to `langchain-graph-retriever`."},"warnings":[{"fix":"Refer to the v0.5.0 migration guide (if available, check project's GitHub) or updated documentation for current strategy configuration parameters. Old parameters like `strategy_type` may no longer be valid.","message":"Major changes to strategy design and parameter names in v0.5.0. The internal architecture for traversal and node selection was refactored, leading to updated API signatures for strategy configuration.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"When defining graph edges or relationships, use the string `'$id'` instead of instantiating an `Id()` object for document identifiers. For example, `edge_data={'$id': 'doc_id_string'}`.","message":"The `Id()` class for representing document IDs on edges was replaced by directly passing the `'$id'` string in v0.6.0.","severity":"gotcha","affected_versions":">=0.6.0"},{"fix":"If experiencing issues with the `k` parameter after upgrading to v0.5.0, upgrade to v0.5.1 or later where it was restored. For versions after 0.5.1, `k` should function as expected for controlling initial vector store retrieval.","message":"The `k` parameter (number of initial documents to retrieve) was affected by the v0.5.0 strategy changes and then restored in v0.5.1.","severity":"gotcha","affected_versions":"0.5.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install langchain-graph-retriever` to install the package.","cause":"The `langchain-graph-retriever` package is not installed in your Python environment.","error":"ModuleNotFoundError: No module named 'langchain_graph_retriever'"},{"fix":"Update your `GraphRetriever` initialization code to use the current strategy configuration parameters as per the latest documentation. The strategy design was updated in v0.5.0.","cause":"You are using an old parameter name for configuring retrieval strategies that was removed or renamed in version 0.5.0 or later.","error":"TypeError: GraphRetriever.__init__ got an unexpected keyword argument 'strategy_type'"},{"fix":"This error should primarily occur if using versions prior to v0.6.0. If on v0.6.0 or later, ensure you are passing the string `'$id'` directly in edge definitions, as the `Id()` class was deprecated in favor of '$id' strings.","cause":"You are passing a string as a document ID where the `Id()` class was expected for older versions (pre-v0.6.0).","error":"TypeError: Expected an Id instance for the document ID, but received a string."}]}