---
title: Search and Query
description: Choose ranked evidence or a grounded answer with citations.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Search and Query

Search retrieves ranked evidence. Query uses collection content to write an answer. Both operations stay within one collection and apply its access rules.

## Evidence or answer

*Illustration: The same incident report can produce a Search hit or support a Query answer. Search exposes evidence. Query links answer markers to evidence through its sources map.*

Use Search when your application needs to choose or display results. A hit includes the file, rank, score, matching mode, and evidence. Use Query when it needs an answer with citations. Search never writes an answer.

## Search controls

`keyword` matches words. `semantic` matches meaning and is the default. `interpretation: "literal"` uses the supplied query as written. `natural_language` can interpret the query and add filters. Interpretation still returns Search results rather than an answer.

`result_unit: "file"` groups matching passages by file. `passage` returns passage-level results. Evidence can identify text spans, pages, transcript times, image regions, or JSON locations.

Scores support ranking within the response. They are not confidence percentages. A filter selects application data; it does not authorize a reader. See [Search files](/engine/guides/search).

## Query modes and history

`standard` is the default Query mode. `ultra` performs deeper retrieval when the cluster supports it. Check `query.modes` from `/info` before requesting a mode. Both modes stay within the chosen collection and permitted content.

Your application stores conversation state. To supply context, send prior `user` and `assistant` messages in `history`, oldest first. Send the new question in `query`. The API does not store a conversation or accept a conversation ID.

## Citations connect the answer to content

**Answer and sources**

```json
{
  "request_id": "req_example_query",
  "answer": "Checkout stalled because the service exhausted its connection pool [[SRC:0001]].",
  "mode": "standard",
  "sources": {
    "[SRC:0001]": {
      "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
      "path": "/incidents/checkout.txt",
      "score": 0.81,
      "is_cited": true,
      "evidence": {
        "kind": "text",
        "text": "Checkout stalled because the service exhausted its connection pool.",
        "location": {
          "char_start": 0,
          "char_end": 67
        }
      }
    }
  }
}
```

An answer uses markers such as `[[SRC:0001]]`. Look up `[SRC:0001]` in `sources` to render the corresponding citation. Each source provides a file ID, path, score, citation flag, and evidence.

Keep `return_sources: true` when your UI needs citations. Setting it to false omits the source map. See [Generate answers with citations](/engine/guides/query).
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.