SearchOptions

Type

Per-query options for search: how many results, how to retrieve, how to filter, and what to return.

The per-query options for search, all free to change since none touch a stored vector: they take effect on the next call and cost nothing, and the defaults come from the corpus's own configuration, so most callers pass nothing. mode: 'lexical' skips the query embedding entirely, the right call for identifier-shaped queries like error codes and SKUs. Anything that would require rebuilding the corpus, like chunk size or the embedding model, is a property of the corpus set from the CLI, not passed here.

SearchOptions.ts

interface SearchOptions {
  topK?: number
  scoreThreshold?: number
  filter?: SearchFilter
  mode?: 'hybrid' | 'semantic' | 'lexical'
  maxPerDocument?: number
  rerank?: boolean
  hybrid?: boolean
  highlight?: boolean
  explain?: boolean
  expand?: number
}

Fields

topK?

number

Results to return. Default 5, capped at 50.

scoreThreshold?

number

Floor on the RETRIEVAL score, applied to the retrieval branch and never to the fused hybrid score or the reranker's score: a cosine floor on the embedding branch in semantic and hybrid modes, a keyword-overlap floor in lexical. The scale depends on the embedding model, so measure before using, and with reranking on prefer cutting on each hit's returned score instead.

filter?

SearchFilter

Narrow the search before ranking, by metadata, filename, ids, pages, or required words.

mode?

enum

Which retrieval branches run. Defaults to hybrid.

maxPerDocument?

number

Cap hits per document, backfilled from others, so one document does not monopolize the results.

rerank?

boolean

Cross-encoder reranking. On by default; turn off on a latency-sensitive path.

hybrid?

boolean

Combine semantic with keyword matching. On by default. hybrid: false equals mode: 'semantic'.

highlight?

boolean

Add matches to each hit: where the query's distinctive terms land in the text.

explain?

boolean

Add explain to each hit. Costs two extra round trips; does not change results.

expand?

number

Also return this many neighbor chunks either side of each hit, 0 to 2.

Lexical lookup for an identifier

await Policies.search('ERR-7741X', {
  mode: 'lexical', // no query embedding, fastest for codes and SKUs
  topK: 3,
});