vector
query
Search a vector collection.
strata vector querydb.vectors.query(collection: 'str', vector: 'Sequence[float]', *, k: 'int' = 10, filter: 'Any' = None, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'list'wire vector_query
Runs vector search through the engine planner and returns the best matches with scores and optional metadata.
Search responses return a bounded list of matches ordered by the engine. They are not cursor pages unless a later command explicitly advertises pagination.
To see the complete help for this command, run:
strata vector query --helphelp(db.vectors.query)
Example
Find the nearest vectors to a query vector.
strata vector collection create docs 3 --metric cosinestrata vector upsert docs a [1.0,0.0,0.0]strata vector upsert docs b [0.0,1.0,0.0]strata vector query docs [1.0,0.0,0.0] --k 2
_ = 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.query("docs", [1.0, 0.0, 0.0], k=2)]
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>
- dataarray
- 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 |