Context Retrieval

Query Knowledge Bases and retrieve relevant chunks using RAG search without calling an LLM.

Overview

The Context Retrieval node is a specialized Integration Designer workflow node that performs RAG (Retrieval-Augmented Generation) searches against a Knowledge Base. Unlike the Custom Agent node, Context Retrieval does not call an LLM — it retrieves and returns matching chunks directly, giving you full control over how the results are processed downstream.

Use Context Retrieval when you want to separate the retrieval step from the generation step. This lets you inspect, filter, or transform retrieved chunks before passing them to an AI node for response generation.

---

When to use Context Retrieval vs Custom Agent

Scenario	Recommended node
You need the AI to reason about retrieved information and generate a response	Custom Agent with Knowledge Base enabled
You want raw chunks to process, filter, or route in your workflow	Context Retrieval
You need to combine chunks from multiple Knowledge Bases	Context Retrieval (one per KB) + downstream merge
You want a simple question-answer flow with RAG	Custom Agent with Knowledge Base enabled

---

Configuration

Knowledge Base

Knowledge Base · select · required

Select one or more Knowledge Base resource references to query.

Source

Source · enum

The source to query.

Options:

• Knowledge Base — Search the selected Knowledge Base (default)
• Memory — Search conversation memory

The Memory option is only available in chat-driven workflows.

Default: Knowledge Base

Settings

The settings below are available inside the Settings expander on the node configuration panel.

Search type

Search Type · enum

The strategy used for retrieving context from the Knowledge Base.

Options:

• Hybrid — Combines semantic and keyword search for balanced results (default)
• Semantic — Uses vector similarity for meaning-based search
• Keywords — Uses traditional keyword matching

Default: HYBRID

When Keywords is selected, the Min Relevance Score slider is hidden because keyword search does not produce a relevance score.

Query parameters

Max Number of Chunks · number

Maximum number of relevant chunks to return. Configurable from 1 to 10.

Default: 4

Min Relevance Score · number

Minimum relevance score threshold, expressed as a percentage (0–100). Only chunks with a relevance score above this threshold are returned. Not available when search type is set to Keywords.

Default: 50

Metadata filters

Metadata Filters · button

Opens a query builder modal where you compose conditions as field / operator / value triples. Operators depend on the metadata key type (equals, not equals, contains, in, not in, before, after, exists, etc.). Conditions can be grouped and combined with AND or OR.

To filter by store, add a condition on the system metadata key source.

Typed operators and AND/OR grouping are supported. See Filtering by metadata for the full operator list.

Use advanced metadata filters · boolean

Toggle to turn on advanced metadata filter expressions for more complex filtering logic. When turned on, a JSON expression field becomes available for defining property-based filters.

Default: false

Re-ranking

Use Re-Rank · boolean

When turned on, applies a re-ranking model to the retrieved chunks, reordering them by relevance to the query. This can improve result quality at the cost of slightly higher latency.

Default: false

---

User Query

User Query · string · required

The query text sent to the Knowledge Base. Supports ${} placeholder syntax for dynamic values from workflow input and configuration parameters.

Example:

${userMessage}

Both runtime input variables and configuration parameters are available for placeholder resolution.

---

Response Key

Response Key · string · required

Key under which the retrieved chunks are stored in the workflow data, so downstream nodes can reference them.

Default: responseKey

---

Output format

The Context Retrieval node returns an array of chunk objects. Each chunk contains:

Field	Type	Description
chunkContent	string	The text content of the retrieved chunk
chunkMetadata	object	Metadata associated with the chunk (key-value pairs)
relevanceScore	number	Similarity score between the query and the chunk (0–1)
searchType	string	Search strategy that returned this chunk. One of HYBRID, SEMANTIC, or KEYWORD. Only emitted when the RAG service returns a non-null value.
contentSource	string	The name of the store the chunk belongs to (field name preserved for API compatibility)

Example output

[
  {
    "chunkContent": "The onboarding process requires identity verification...",
    "chunkMetadata": {
      "source": "onboarding-guide.pdf",
      "page": "3"
    },
    "relevanceScore": 0.92,
    "contentSource": "Product Documentation"
  },
  {
    "chunkContent": "KYC checks must be completed within 48 hours...",
    "chunkMetadata": {
      "source": "compliance-policy.pdf",
      "page": "12"
    },
    "relevanceScore": 0.85,
    "contentSource": "Compliance Policies"
  }
]

---

Error handling

If the Context Retrieval node fails, the workflow produces a WORKFLOW_NODE_CONTEXT_RETRIEVAL_ERROR error. Common causes include:

Knowledge Base not found

The referenced Knowledge Base does not exist or is not accessible.

Solution: Verify the Knowledge Base exists in your project or dependencies and that you have the required permissions.

Invalid query

The operation prompt resolved to an empty or invalid query.

Solution: Check that the ${} placeholders in your operation prompt reference valid input or config variables.

Timeout

The RAG search exceeded the configured timeout.

Solution: The default timeout is 600 seconds (flowx.ai-service.nodeRunnerTimeoutSeconds). Consider simplifying your query or reducing the topK value.

---

Best practices

Optimizing Context Retrieval:

• Start with Hybrid search type for the best balance of precision and recall
• Use Semantic when your queries are natural-language questions; use Keywords for exact-match lookups
• The default minimum relevance threshold (50%) is a good starting point — increase it to filter out lower-quality matches
• Turn on Use Re-Rank when result quality is more important than latency
• Use metadata filters to narrow results to specific stores (via the source key) or metadata values
• Keep Max Number of Chunks reasonable (3–10) to avoid overwhelming downstream nodes with too much context

Building RAG pipelines:

• Chain Context Retrieval → Script Node → Custom Agent to build custom RAG flows with intermediate processing
• Use the relevanceScore field to implement your own relevance filtering logic in a Script node
• Combine results from multiple Context Retrieval nodes (querying different KBs) using a Script node before passing to generation

---

Related resources

Knowledge Base overview

Create and manage Knowledge Bases

Using Knowledge Base in workflows

Query Knowledge Bases with Custom Agent nodes

Custom Agent node

AI agents with MCP tools and Knowledge Base access

Integration Designer

Build and manage integration workflows