vector
query
Search a vector collection.
strata vector querydb.vectors.query(collection: 'str', vector: 'Optional[Sequence[float]]' = None, *, text: 'Optional[str]' = None, 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. With `text` instead of a query vector, the text is embedded through the collection's recorded model on the same inference path as `inference.embed`, so the `inference.*` failures listed below apply only to that form; a supplied vector never reaches the inference runtime.
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 cosinecreated collection docs (3 dimensions, cosine)strata vector upsert docs a '[1.0,0.0,0.0]'created a in docsstrata vector upsert docs b '[0.0,1.0,0.0]'created b in docsstrata vector query docs '[1.0,0.0,0.0]' --k 2KEY SCORE METADATAa 1.0 -b 0.0 -
_ = 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. |
| 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. |
| query | array | no | Query embedding. Accepted at wire (f64) precision and narrowed to the searched f32; a value that underflows or overflows f32 is rejected. Empty when `text` is supplied instead. A vector carries no model, so when the collection records an embedding model, Strata cannot check this query against it: supplying one is the caller's statement that the recorded model produced it, and a query from another model returns neighbours that are ranked and meaningless. Only `text` is embedded under the record. |
| space | string or null | no | Target product space. Defaults to `"default"`. |
| text | string or null | no | Text to embed with the collection's recorded model, instead of supplying a query vector (D10). This is the half that makes provenance worth recording: the query is embedded with the same model the collection was written with, so a caller cannot accidentally compare vectors from two models. With `as_of` or `as_of_time`, the model is the one the collection recorded at that snapshot. A snapshot older than the model's declaration is refused with `failed_precondition.engine.embedding_model_missing`: the declaration vouched for the vectors present when it was made, not for what the collection held before. Search such a snapshot with a `query` vector. |
Returns
SearchResult<VectorMatch>
- dataarray
- typestring
Errors
Recover by code. Retry policy and commit outcome come from the shipped error registry.