vector
index.query
Search vectors and return index diagnostics.
db.vectors.index_query(collection: 'str', vector: 'Sequence[float]', *, k: 'int' = 10, filter: 'Any' = None, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'Tuple[list, Any]'wire vector_index_query
Runs vector search and includes planner diagnostics such as index policy, source usage, artifact status, and fallback facts.
Search responses return a bounded list of matches ordered by the engine. They are not cursor pages unless a later command explicitly advertises pagination.
Diagnostic responses include operational facts intended for debugging and tuning. They should not be required for application correctness.
To see the complete help for this command, run:
help(db.vectors.index_query)
Example
Nearest-neighbor search that also returns index diagnostics.
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0])_ = db.vectors.upsert("docs", "b", [0.0, 1.0, 0.0])[m.key for m in db.vectors.index_query("docs", [1.0, 0.0, 0.0], k=2)[0]]
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| collection | string | yes | Collection name. |
| k | integer | yes | Maximum number of matches. |
| query | array | yes | Query embedding. Accepted at wire (f64) precision and narrowed to the searched f32; a value that underflows or overflows f32 is rejected. |
| as_of | integer or null | no | Read as of a position on the logical commit timeline - the `timestamp` from `history` output, not the `version`, and never a calendar date. To read as of a real time, use `as_of_time` instead. |
| as_of_time | integer or null | no | Read as of a real time: a wall-clock instant in microseconds since the Unix epoch (UTC), as reported by `committed_at` on a write ack or on any `history` row. Resolves to the commit at or before that instant, and fails rather than guessing if the instant falls outside the branch's recorded history. Mutually exclusive with `as_of`. |
| branch | string or null | no | Target branch. Defaults to the executor handle branch. |
| filter | any | no | Optional metadata filter. |
| space | string or null | no | Target product space. Defaults to `"default"`. |
Returns
SearchResult<VectorMatch> + IndexDiagnostics
- dataVectorIndexQueryResult
- typestring
Errors
Recover by code. Retry policy and commit outcome come from the shipped error registry.
| Code | Retry | Commit outcome |
|---|---|---|
| failed_precondition.engine.runtime_closed | never | not_started |
| not_found.engine.branch | never | not_applicable |
| invalid_argument.engine.product_space | never | not_started |
| invalid_argument.engine.vector_collection | never | not_started |
| invalid_argument.engine.vector_key | never | not_started |
| not_found.engine.vector_collection | never | not_applicable |
| invalid_argument.engine.vector_filter | never | not_started |
| invalid_argument.executor.vector_limit | never | not_started |