Query intelligence

Query intelligence is the layer between an empty search box and a submitted query: what to show before the first keystroke, what to offer while the visitor types, named presets for ready-made search parameter sets, and natural-language search that turns "red shoes under $50" into real search parameters.

presearchQueries and suggestQueries are search-scoped and can be called from a browser with a search or browser key. Presets and NL search models are configuration and need a full key. Identify the visitor with the X-NOVA-SESSION-ID header and the x_user_id / x_anonymous_id query parameters — recency and the query graph are per session.

Suggestions while typing

GET /collections/{collectionName}/suggest?q=… returns typeahead candidates for a prefix. Candidates come from the collection's popular queries, its documents, linked catalogue entities (brands, categories), continuations of the session's last query from the query graph, search-rule suggestions and the session's recent searches — ranked by expected downstream usefulness, not just by string match.

curl "https://api.aacsearch.com/v1/collections/products/suggest?q=iph&last_query=case" \
  -H "X-NOVA-API-KEY: $BROWSER_KEY"

const suggestions = await client.queryIntelligence.suggestQueries({
  collectionName: "products",
  q: "iph",
  lastQuery: "case",
});

Pre-search prompts

GET /collections/{collectionName}/presearch answers "what do I show in the empty search box": the session's or user's recent searches, contextual continuations of the last query, and what is trending on the collection. Sections are omitted when empty. The response carries a presearch_id; when the visitor picks an item, report it as a suggestion_select event with query_id set to that presearch_id so the loop is measured (see events).

Presets

A preset is a named, saved set of search parameters — the value is either a search parameter object or a multi-search request set. Presets let you keep parameter sets out of client code: the storefront asks for a preset by id instead of hardcoding query_by, facet_by and sort_by, and you can change the set without a redeploy.

await client.presets.upsertPreset({
  presetId: "category-shoes",
  body: {
    value: {
      query_by: "title,description,brand",
      filter_by: "category:=shoes && in_stock:true",
      sort_by: "popularity:desc",
    },
  },
});

For per-collection storefront configurations with immutable published versions, use search profiles instead; presets are the lighter, global counterpart.

Natural-language search

The nl_query search parameter turns a visitor's sentence into a normal search: a model translates it into q, filter_by and sort_by, and the response carries the translation in parsed_nl_query (with nl_query_debug=true also the raw model output). This is query understanding, not chat — for answers over your documents use an assistant.

Which model parses the query is a conversation of one: NL search models are named configurations with a model_name, the provider credentials or tokens (api_key, api_url, Cloudflare account_id, GCP Vertex AI project_id/access_token and friends), a system_prompt and sampling settings (temperature, top_p, top_k, stop_sequences, max_output_tokens). The nl_search plan feature gates the parameter; the model calls themselves are metered in credits.

const result = await client.documents.searchCollection({
  collectionName: "products",
  q: "красные кроссовки до 5000",
  nlQuery: true,
});
// result.parsed_nl_query shows how the sentence became q / filter_by / sort_by