AI Search

Controlled node

Overview

AI Search performs a one-shot semantic search over a set of text documents. Provide a query and one or more documents, and the node returns the passages most relevant to that query.

Each document is split into chunks, the query and every chunk are converted into embeddings, and chunks are ranked by semantic similarity to the query. Optionally, the best candidates can be rescored with a dedicated reranking model for higher quality ordering.

This is a controlled node: it executes when the Run event is received and fires Done when finished.

How it works

1. Chunking — Each input document is split into chunks according to the chunk options.
2. Embedding — The query and all chunks are embedded together in a single batch.
3. Scoring — Cosine similarity is calculated between the query embedding and each chunk embedding.
4. Sorting — Chunks are sorted by semantic score. Ties are broken deterministically by document order, then chunk order.
5. Reranking (optional) — The top semantic candidates are rescored with a reranker model and re-sorted.
6. Results — The top resultCount chunks are returned.

Reranking

When Rerank is enabled, the top candidates from the semantic pass are rescored using a reranking model, which typically produces a more accurate ordering than embedding similarity alone. The reranker considers the top 50 candidates, or resultCount candidates if you have requested more than 50 results.

tip

Reranking improves result quality but adds latency and cost. Enable it when result ordering matters, such as when feeding the results into an AI Write prompt.

Output events

• Done: Fires when the node has finished running. This is useful for triggering other nodes or actions in your workflow once the search results are ready.

Inputs

Input	Type	Description	Default
Run	Event	Triggers the search.	-
Query	Text	The natural language search query. Must be a non-empty string.	-
Input	Text or Text[]	The document or list of documents to search. A single string is treated as a one-item array.	-
Chunk Options	Chunk Options	Controls how documents are split into chunks before embedding.	See defaults below
Search Type	Enum	The search strategy. Currently only semantic is available.	semantic
Rerank	Boolean	When true, the top semantic candidates are rescored with a reranking model.	false
Result Count	Number	The number of top chunks to return. Must be a positive integer.	10

Chunk options defaults

Option	Description	Default
Strategy	count creates fixed-size chunks; divide splits each document into a set number of parts.	count
Unit	The unit used to measure chunk size: token, word, sentence, paragraph, custom, or page.	token
Size	The target size of each chunk (used with the count strategy).	500
Separator	The separator used to split text when the unit is custom.	\n\n
Overlap	The number of units shared between consecutive chunks, preserving context across boundaries.	50
Token Model	The tokenizer used for token-based chunking. Always forced to embedding.	embedding
Token Limit	The maximum tokens per chunk. Always forced to 32768.	32768

Outputs

Output	Type	Description
Result	Data	An array of matching chunks, or an { error } object if the search failed.
Done	Event	Fires when the node has finished.

Each item in the Result array has the following shape:

{
  "text": "The matching passage of text...",
  "documentIndex": 0,
  "start": 1234,
  "end": 1734
}

• text — The chunk content.
• documentIndex — The index of the source document in the input array.
• start / end — The character offsets of the chunk within its source document.

Runtime behavior and defaults

• If Input is a single string, it is automatically wrapped into a one-item array.
• The tokenModel and tokenLimit chunk options are always overridden to embedding and 32768, regardless of the values provided.
• Chunks that contain only whitespace are skipped.
• If no searchable chunks remain after chunking, the node returns an empty array [].
• Sorting is deterministic: equal scores are ordered by document index, then chunk index.
• Errors are returned on the Result output as an object with an error property rather than stopping the workflow. Possible errors include invalid inputs (empty query, non-string input, non-boolean rerank, non-positive result count), chunking failures, embedding failures, and reranking failures.

Chunk limit

AI Search supports a maximum of 50,000 chunks across all input documents. If chunking produces more than this, the node returns an error. Reduce the input size or increase the chunk size to stay under the limit.

Example

Suppose you have a collection of support articles and want to find the passages that best answer a user's question.

1. Add an AI Search node to your workflow.
2. Connect an array of article texts (for example, from a file loader or a list of Text nodes) to the Input socket.
3. Connect the user's question to the Query socket.
4. In the node panel, set Result Count to 5 and enable Rerank for the best ordering.
5. Trigger the Run event, then pass the Result into an AI Write node to compose a final answer grounded in the retrieved passages.

Example output for a query like "How do I reset my password?":

[
  {
    "text": "To reset your password, go to Settings > Security and click 'Reset password'...",
    "documentIndex": 2,
    "start": 412,
    "end": 905
  },
  {
    "text": "If you have forgotten your password, use the 'Forgot password' link on the login page...",
    "documentIndex": 0,
    "start": 1024,
    "end": 1530
  }
]