Knowledge Search Node

The knowledge_search node looks up the passages of one of your workspace’s knowledge bases that best match a query, and writes them to its outputVar as a list. It calls no language model. Use it to decide something before a model runs: answer from the passages with an llm node, or hand over to a person when nothing matches.

Unlike an llm node’s knowledgeBaseId (which carries on without passages if the lookup fails), a lookup problem fails this node, so a “no match” branch is never confused with “the lookup broke”. Finding nothing is not a failure: the list is empty.

See Workflow Overview for the node/edge envelope this fits into.

Config fields

Field	Type	Required	Description
knowledgeBaseId	integer	Yes	Id of one of your workspace’s knowledge bases. A base that does not exist, was deleted or belongs to another workspace fails the node at run time.
queryTemplate	string	Yes	The search query, a Handlebars template over the run variables (for example {{userMessage}}), at most 2000 characters. Rendered as plain text. An empty rendering fails the node.
outputVar	string	Yes	Variable that receives the list. Letters, digits and underscores, starting with a letter, at most 64 characters; reserved names are refused.
topK	integer	No	How many passages to return, 1 to 10. Default 5.
minScore	number	No	0 to 1. Drops passages whose similarity is below this value. No filter when absent.
includeText	boolean	No	false returns ids and scores only. Default true.
maxCharsPerChunk	integer	No	Cuts each returned passage to this many characters, 200 to 4000. Default 2000.
timeoutMs	integer	No	Bound on the whole lookup, 1000 to 60000. Default 15000; a larger value is cut to 60000. A lookup that runs over fails the node with a timeout.

Every rule is checked when you save or publish and refused with a BAD_USER_INPUT error naming the node and the field. With member-built drafts on, only a released knowledge base can be used at publish. The node also takes the common maxVisits field.

{
  "id": "find_policy",
  "type": "knowledge_search",
  "config": {
    "knowledgeBaseId": 12,
    "queryTemplate": "{{userMessage}}",
    "topK": 4,
    "minScore": 0.5,
    "outputVar": "hits"
  }
}

Output

ctx[outputVar] is a list, best match first, and nothing else is stored:

[
  {
    "chunkId": 481,
    "documentId": 17,
    "score": 0.91,
    "text": "Refunds are accepted within 14 days."
  }
]

score is a similarity from 0 to 1 (higher is closer). text is present unless includeText is false. The ids also appear on the run’s trace row as retrievedChunkIds, so you can see which passages a run used. Test the size with a condition such as length(hits) > 0, and give an llm node the passages with {{#each hits}}{{text}}{{/each}}.

The list is stored with the run, up to 10 passages of 4000 characters: set includeText to false or lower maxCharsPerChunk when the text is not needed later.

Failure and edges

Add a failure edge (with a success edge) to handle a lookup error, like any failure-routable node. The message the user can see is a fixed neutral sentence; provider and database messages never reach it.

A test run in mock mode runs this node for real: it only reads your own knowledge base and sends nothing out. The query is embedded once, which counts like any knowledge-base lookup.