SUsurrealdb

POST /api/v1/{context_id}/documents/query

Changed on

Runs a top-k semantic query over the Layer 0 chunks

Request

Path parameters

context_idstring required

Spectron context id

Request body

decomposeQueryboolean nullable

W5b: opt into sub-question decomposition for this query. The caller fans out to one retrieval per sub-question and RRF-merges the result lists. Like use_hyde, requires the Context to have an LLM provider attached.

expandGraphboolean
graphAlphanumber float
graphDepthinteger
graphEdgesGraphEdgeKind[]
kinteger

Max hits to return (default 10, max 50).

mode'hybrid' | 'vector' | 'bm25' | 'hybrid_graph'

Chunk query mode: vector-only, BM25-only, hybrid RRF, or hybrid plus graph-density re-rank.

querystring required
rrfKnumber float
thresholdnumber float
useHydeboolean nullable

W5a: opt into HyDE (Hypothetical Document Embeddings) for this query. Requires the Context to have an LLM provider attached; callers without one should leave this false. Defaults to false so existing agents see the same vector-only behaviour.

useRerankerboolean nullable

W5c: opt into cross-encoder reranking of the top-K. Requires the server to have a Reranker provider attached. Off by default; takes effect after the store returns results so it composes naturally with HyDE / decomposition / hybrid graph.

vectorWeightnumber float

Response

queryMsinteger required

Changes

  • 9f1598713067Revision changes
    • info

      added the non-success response with the status

  • 52b41ab517b6Revision changes
    • breaking

      removed the enum value keyword_cooccurrence of the request property /

    • info

      removed the keyword_cooccurrence enum value from the //// response property for the response status