Search Files by Name Node

Search for files in a Needle collection by their file name.

The Search Files by Name node searches within a Needle collection to find files whose names match the given keywords. Unlike the Search Collection node (which performs semantic search across document content), this node matches against file names only. It is useful when you know the name or naming pattern of the file you need.

Parameters

Parameter	Type	Required	Default	Description
collectionId	string	✅		The Needle collection to search in
keywords	string	❌	""	Keywords to search for in file names (supports expressions)
instructions	string	❌	""	Additional instructions (template mode)
runMode	string	✅	item	Run mode: item or input

collectionId

Type: string | Required: ✅

The ID of the Needle collection to search in. Select from the dropdown in the node configuration UI.

keywords

Type: string | Required: ❌

Keywords or patterns to match against file names. Can be static or dynamic.

Examples:

• Static: quarterly-report
• Dynamic (expression): A JavaScript expression that computes the file name:

const timestamp = new Date(input.timestamp);
const year = timestamp.getUTCFullYear();
const month = String(timestamp.getUTCMonth() + 1).padStart(2, "0");
const day = String(timestamp.getUTCDate()).padStart(2, "0");
`${year}-${month}-${day}.txt`;

instructions

Type: string | Required: ❌

Additional natural language instructions. Evaluated in template mode. You can describe what kind of file you're looking for.

Examples:

• Find messages from yesterday. File name will be: Needle-#notifications-YYYY-MM-DD.txt

runMode

Type: string | Required: ✅ | Default: item

Controls how the node processes input data:

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

Configuring This Node

When you select a Search Files by Name node on the workflow canvas, the right-hand configuration panel displays the following sections from top to bottom:

Run Mode & Error Handling

At the top of the panel you will find:

• Run Mode dropdown — Choose between Item (the node executes once per array element) and Input (the node executes once for the entire input object). This corresponds to the runMode parameter.
• Continue on Error toggle — When enabled, the workflow continues to the next node even if this node encounters an error. When disabled (the default), a node error will stop the workflow run.

Variables

A multi-select dropdown that lets you bind workflow variables to this node. Bound variables become accessible in expressions via the variables object (e.g. variables.myVar). You can also click the Create variable button to define a new workflow variable inline without leaving the node panel.

Collection

A dropdown listing all Needle collections you have access to. Select the collection whose files you want to search. This sets the collectionId parameter.

Instructions

A template text area where you can provide natural language guidance. Use ${...} syntax to interpolate dynamic values from the workflow context. For example:

Find the file named ${variables.targetFileName} in the collection.

Property Fields

Below the Instructions area, property fields are organized into Required and Optional sections:

• keywords (Optional) — The file name keywords to search for.

Each property field has a parameter mode selector (accessible via a small icon on the field) with three options:

Mode	Description
Fixed	Enter a static value directly.
Expression	Write a JavaScript expression with access to input, item, and variables from the workflow.
AI Decide	Let the AI agent determine the value at runtime based on the node's instructions and context.

Examples

1. Search by Date-Based File Name

Find today's log file using a computed file name:

Parameters:

{
  "runMode": "item",
  "collectionId": "<your-collection-id>",
  "keywords": "const timestamp = new Date(input.timestamp);\nconst year = timestamp.getUTCFullYear();\nconst month = String(timestamp.getUTCMonth() + 1).padStart(2, '0');\nconst day = String(timestamp.getUTCDate()).padStart(2, '0');\n`${year}-${month}-${day}.txt`",
  "parameterMode": {
    "query": "expression"
  }
}

2. Search with Natural Language Instructions

Describe the file you're looking for:

Parameters:

{
  "runMode": "item",
  "collectionId": "<your-collection-id>",
  "keywords": "Find messages from yesterday. File name will be:\n\nNeedle-#notifications-YYYY-MM-DD.txt",
  "parameterMode": {
    "query": "fixed"
  }
}

3. Simple Keyword Search

Search for files matching a keyword:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "keywords": "invoice"
}

Output Structure

The node returns an array of matching files:

[
  {
    "id": "fle_01ABC...",
    "name": "2025-03-15.txt",
    "type": "text/plain",
    "size": 4500,
    "status": "indexed",
    "createdAt": "2025-03-15T00:00:00Z"
  }
]

Important Notes

• Name-based search: This node searches file names, not file content. For content-based search, use the Search Collection node.
• Collection access: The user running the workflow must have at least viewer access to the collection.
• Common pattern: Use Search Files by Name to find a file, then Get File Contents to read it.
• Continue on Error: Enable the Continue on Error toggle in the node panel to allow the workflow to proceed even if the search fails (e.g. no files found or collection unavailable).
• Workflow Variables: Bind workflow variables to this node to use them in expressions. For example, set keywords to an expression like variables.searchPattern to make the search term configurable across runs.
• Parameter modes: Each property field supports three modes — Fixed (static value), Expression (JavaScript with access to input, item, variables), and AI Decide (the AI agent determines the value at runtime). Choose the mode that fits your use case via the mode selector on each field.