FalkorDBCypherRetriever

Execute arbitrary OpenCypher queries against a FalkorDBDocumentStore to retrieve documents using graph traversal and multi-hop relationships.

Key Features

• Runs custom OpenCypher queries against FalkorDB for flexible graph-based retrieval.
• Supports multi-hop graph traversal for GraphRAG pipelines.
• Accepts query parameters to prevent injection — never pass unsanitized user input directly in query strings.
• Accepts a static query at init time or a dynamic query passed at runtime.
• Returns results as a list of Haystack Document objects.

Configuration

1. Drag the FalkorDBCypherRetriever component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab, configure the nested FalkorDBDocumentStore with your FalkorDB connection details:
   • Set host and port to match your FalkorDB server.
   • Set password as a secret called FALKORDB_PASSWORD. For instructions, see Add Secrets.
4. Optionally, set a static custom_cypher_query to run by default.

Connections

FalkorDBCypherRetriever accepts an optional Cypher query string and a parameters dictionary at runtime. It outputs a list of Document objects that you can connect to a PromptBuilder or other downstream components.

Source Code

To check this component's source code, open cypher_retriever.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  FalkorDBCypherRetriever:
    type: haystack_integrations.components.retrievers.falkordb.cypher_retriever.FalkorDBCypherRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.falkordb.document_store.FalkorDBDocumentStore
        init_parameters:
          host: localhost
          port: 6379
          graph_name: haystack
      custom_cypher_query: "MATCH (d:Document)-[:RELATES_TO]->(:Concept {name: $concept}) RETURN d"

Using the Component in a Pipeline

# haystack-pipeline
components:
  document_store:
    type: haystack_integrations.document_stores.falkordb.document_store.FalkorDBDocumentStore
    init_parameters:
      host: localhost
      port: 6379
      graph_name: my_graph
      password:
        type: env_var
        env_vars:
        - FALKORDB_PASSWORD
        strict: false

  retriever:
    type: haystack_integrations.components.retrievers.falkordb.cypher_retriever.FalkorDBCypherRetriever
    init_parameters:
      document_store: document_store
      custom_cypher_query: "MATCH (d:Document) WHERE d.category = $category RETURN d LIMIT 10"

connections: []

inputs:
  parameters:
  - retriever.parameters

outputs:
  documents: retriever.documents

Parameters

Inputs

Parameter	Type	Description
query	Optional[str]	An OpenCypher query string. Overrides custom_cypher_query set at init time.
parameters	Optional[Dict[str, Any]]	Query parameters referenced as $param_name in the Cypher string.

Outputs

Parameter	Type	Description
documents	List[Document]	Documents retrieved by the Cypher query.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	FalkorDBDocumentStore		The FalkorDB document store to query.
custom_cypher_query	Optional[str]	None	A static OpenCypher query to execute. Can be overridden at runtime by passing query to run().

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
query	Optional[str]	None	OpenCypher query string. Overrides the init-time query.
parameters	Optional[Dict[str, Any]]	None	Query parameters to bind in the Cypher string.

Related Information

• FalkorDBEmbeddingRetriever
• Pipeline Components