Skip to main content

Search Collection Node

Perform semantic search across documents in a Needle collection.

The Search Collection node queries a Needle collection using vector similarity search and returns the most relevant document chunks. It is useful for retrieving context from your indexed documents — for example, finding relevant passages to feed into an AI node for question answering or summarization.

Parameters​

ParameterTypeRequiredDefaultDescription
collectionIdstring✅The Needle collection to search
querystring✅""The search query (supports expressions)
instructionsstring❌""Additional instructions for the search (template mode)
runModestring✅itemRun mode: item or input

collectionId​

Type: string | Required: ✅

The ID of the Needle collection to search. The collection must contain indexed documents. You can select the collection from a dropdown in the node configuration UI.

query​

Type: string | Required: ✅

The text query to search for. The query is converted into a vector embedding and compared against document chunks in the collection using cosine similarity.

Examples:

  • Static: What are the key benefits of the product?
  • Dynamic (expression): input.question
  • Dynamic (item mode): item.searchTerm

instructions​

Type: string | Required: ❌

Additional natural language instructions that guide the search behavior. Evaluated in template mode — use ${...} syntax for dynamic values.

runMode​

Type: string | Required: ✅ | Default: item

Controls how the node processes input data:

  • item — Runs once per array element. Use item in expressions.
  • input — Runs once for the entire input. Use input in expressions.

Configuring This Node​

When you click the Search Collection node in the workflow builder, a configuration panel appears with the following sections from top to bottom:

Run Mode & Continue on Error​

At the top of the panel is a Run Mode dropdown with two options:

  • Item — The node executes once for every element in the input array. Use item in expressions to reference the current element.
  • Input — The node executes once for the entire input. Use input in expressions to reference the full input.

Next to the dropdown is a Continue on Error toggle. When enabled, the workflow continues executing downstream nodes even if this node fails. The error is captured in the node's output so downstream nodes can inspect and handle it.

Variables​

A multi-select dropdown that lets you bind workflow-level variables to this node. Variables are defined at the workflow level and can hold string, number, boolean, or secret values. Once selected, the variables become available in expressions via the variables object (e.g., variables.defaultQuery). You can also click the Create variable button to define a new variable without leaving the node configuration panel.

Collection​

A dropdown that lists all Needle collections available to you. Select the collection to search. The selected collection's ID is used as the collectionId parameter. The collection must contain indexed documents for search to return results.

Instructions​

A template text area for optional AI instructions. Supports ${...} template literal syntax for inserting dynamic values. These instructions guide the AI agent in how to use the tool when the node is part of an AI-driven workflow.

Property Fields​

The remaining parameters (query) are displayed as property fields, organized into Required and Optional sections based on the node's schema. Each field has a mode toggle that lets you switch between three parameter modes:

  • Fixed — Enter a static value directly in the field.
  • Expression — Write a JavaScript expression that is evaluated at runtime. Expressions can reference input, item, variables, and other context objects.
  • AI Decide — Let the AI agent determine the value based on the surrounding context and instructions.

Examples​

1. Simple Search Query​

Search a collection for relevant documents:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "query": "What is the refund policy?"
}

2. Dynamic Query from Input​

Use the previous node's output as the search query:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "query": "input.question",
  "parameterMode": {
    "query": "expression"
  }
}

3. Search per Item in a List​

Search for each question in an array of questions:

Parameters:

{
  "runMode": "item",
  "collectionId": "<your-collection-id>",
  "query": "item.question",
  "parameterMode": {
    "query": "expression"
  }
}

Output Structure​

The node returns an array of matching document chunks with relevance scores:

[
  {
    "id": "chk_01ABC...",
    "content": "Our refund policy allows returns within 30 days...",
    "fileId": "fle_01XYZ...",
    "fileName": "policies.pdf",
    "score": 0.87
  },
  {
    "id": "chk_02DEF...",
    "content": "For digital products, refunds are processed within...",
    "fileId": "fle_01XYZ...",
    "fileName": "policies.pdf",
    "score": 0.82
  }
]

Important Notes​

  • Collection access: The user running the workflow must have at least viewer access to the collection.
  • Indexed documents: Only documents that have been fully indexed will appear in search results.
  • Semantic search: The search is vector-based (semantic), not keyword-based. Queries like "refund policy" will match passages about "returns and exchanges" even if they don't contain the exact words.
  • Continue on Error: Use the toggle at the top of the configuration panel to allow the workflow to continue even if this node fails. The error details are captured in the node's output for downstream handling.
  • Workflow Variables: You can bind workflow-level variables (string, number, boolean, or secret) to this node using the Variables multi-select. Selected variables are accessible in expressions via the variables object.
  • Parameter modes: Each property field can be switched between Fixed (static value), Expression (runtime JavaScript expression), and AI Decide (let the AI agent choose the value) modes using the toggle on the field.