Search and Query

AI Draft

Choose ranked evidence or a grounded answer with citations.

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

Collection content

Checkout stalled because the service exhausted its connection pool.

“checkout connection failures”

1 · /incidents/checkout.txt

Evidence: “exhausted its connection pool”

Ranked results · evidence · locations

Query

“Why did checkout stall?”

The service exhausted its connection pool [1].

[1] checkout.txt · supporting evidence

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.

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

{
  "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.

Was this page helpful?