Vectors commands
24 commands. Each entry gives the invocation and an example, in the interface you pick; open the details for parameters, return shape and error codes.
batch_delete
Delete multiple vectors by key.
db.vectors.delete_many(collection: 'str', keys: 'Sequence[str]') -> 'BatchResult'
Deletes multiple vector keys and returns one positional mutation result per input key.
To see the complete help for this command, run:
help(db.vectors.delete_many)
Example
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert_many("docs", [{"key": "a", "vector": [1.0, 0.0, 0.0]}, {"key": "b", "vector": [0.0, 1.0, 0.0]}])_ = db.vectors.delete_many("docs", ["a", "b"])db.vectors.count("docs")
batch_exists
Check existence for multiple vector keys.
No CLI or Python spelling in this release. Wire type vector_batch_exists.
Checks several vector keys in one collection and returns positional boolean status values. The response preserves the input order.
View details →batch_get
Read multiple vectors by key.
db.vectors.get_many(collection: 'str', keys: 'Sequence[str]') -> 'BatchResult'
Reads several vector keys and returns positional item results. Each item records found or missing state.
To see the complete help for this command, run:
help(db.vectors.get_many)
Example
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert_many("docs", [{"key": "a", "vector": [1.0, 0.0, 0.0]}, {"key": "b", "vector": [0.0, 1.0, 0.0]}])[i.result.value.key for i in db.vectors.get_many("docs", ["a", "b"]).items]
batch_upsert
Upsert multiple vectors in one itemwise batch.
db.vectors.upsert_many(collection: 'str', entries: 'Any') -> 'BatchResult'
Writes multiple vector entries and returns positional mutation results. Valid items share commit facts where the engine applies them together.
To see the complete help for this command, run:
help(db.vectors.upsert_many)
Example
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert_many("docs", [{"key": "a", "vector": [1.0, 0.0, 0.0]}, {"key": "b", "vector": [0.0, 1.0, 0.0]}])db.vectors.count("docs")
count
Count visible vectors in a collection.
strata vector count
db.vectors.count(name: 'str', *, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'int'
Counts vectors visible in the selected collection, branch, and space.
To see the complete help for this command, run:
strata vector count --helphelp(db.vectors.count)
Example
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 count docs2
_ = 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])db.vectors.count("docs")
delete
Delete one vector key.
strata vector delete
db.vectors.delete(collection: 'str', key: 'str') -> 'Any'
Deletes one visible vector entry from a collection. Missing keys are represented as no-op mutation acknowledgements.
To see the complete help for this command, run:
strata vector delete --helphelp(db.vectors.delete)
Example
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 delete docs adeleted a in docsstrata vector exists docs afalse
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0])_ = db.vectors.delete("docs", "a")db.vectors.exists("docs", "a")
delete_all
Delete all vectors in a collection.
strata vector delete-all
db.vectors.delete_all(collection: 'str') -> 'Any'
Deletes all vectors visible in the selected collection while preserving the collection itself.
To see the complete help for this command, run:
strata vector delete-all --helphelp(db.vectors.delete_all)
Example
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 delete-all docsdeleted 1 vector from docsstrata vector count docs0
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0])_ = db.vectors.delete_all("docs")db.vectors.count("docs")
delete_by_filter
Delete vectors matching a metadata filter.
strata vector delete-by-filter
db.vectors.delete_by_filter(collection: 'str', filter: 'Any') -> 'Any'
Scans the collection for visible vectors matching the metadata filter and deletes the matching rows as a bulk mutation.
To see the complete help for this command, run:
strata vector delete-by-filter --helphelp(db.vectors.delete_by_filter)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector upsert docs a '[1.0,0.0,0.0]' --metadata '{"tag":"keep"}'created a in docsstrata vector upsert docs b '[0.0,1.0,0.0]' --metadata '{"tag":"drop"}'created b in docsstrata vector delete-by-filter docs --filter '{"conditions":[{"field":"tag","op":"eq","value":{"type":"string","value":"drop"}}]}'deleted 1 vector from docsstrata vector count docs1
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0], metadata={"tag": "keep"})_ = db.vectors.upsert("docs", "b", [0.0, 1.0, 0.0], metadata={"tag": "drop"})_ = db.vectors.delete_by_filter("docs", stratadb.filters.eq("tag", "drop"))db.vectors.count("docs")
exists
Check whether one vector key exists.
strata vector exists
db.vectors.exists(collection: 'str', key: 'str') -> 'bool'
Returns a boolean status for one vector key without loading the embedding.
To see the complete help for this command, run:
strata vector exists --helphelp(db.vectors.exists)
Example
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 exists docs atruestrata vector exists docs absentfalse
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0])db.vectors.exists("docs", "a")db.vectors.exists("docs", "absent")
get
Read one vector by key.
strata vector get
db.vectors.get(collection: 'str', key: 'str', *, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'Any'
Reads one visible vector entry. The optional timestamp reads the vector visible at that point in time when retained history allows it.
To see the complete help for this command, run:
strata vector get --helphelp(db.vectors.get)
Example
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 get docs akey avector_revision 1version …embedding [1.0,0.0,0.0]metadata -strata vector get docs absent(nil)
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0])db.vectors.get("docs", "a").keydb.vectors.get("docs", "absent") is None
history
Read retained vector history for one key.
strata vector history
db.vectors.history(collection: 'str', key: 'str') -> 'Optional[list]'
Returns retained history rows for one vector key, including vector revision facts and tombstones when present.
To see the complete help for this command, run:
strata vector history --helphelp(db.vectors.history)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector history docs absent(nil)
_ = db.vectors.create_collection("docs", 3, metric="cosine")db.vectors.history("docs", "absent") is None
keys
List vector keys in a collection.
strata vector keys
db.vectors.keys(collection: 'str', *, limit: 'Optional[int]' = None, cursor: 'Optional[Any]' = None, as_of: 'Optional[int]' = None, as_of_time: 'Optional[TimeLike]' = None) -> 'Page'
Lists visible vector keys with optional prefix and cursor arguments.
To see the complete help for this command, run:
strata vector keys --helphelp(db.vectors.keys)
Example
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 keys docsab
_ = 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])db.vectors.keys("docs").items
query
Search a vector collection.
strata vector query
db.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'
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.
To see the complete help for this command, run:
strata vector query --helphelp(db.vectors.query)
Example
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)]
sample
Sample vectors with values and version facts.
strata vector sample
Returns a deterministic representative sample of vectors from a collection: the total live count and up to `count` entries (default 10), evenly strided over the ordered keys. Latest state only.
To see the complete help for this command, run:
strata vector sample --help
Example
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 sample docsKEY VERSION VECTOR_REVISION EMBEDDING METADATAa … 1 [1.0,0.0,0.0] -b … 1 [0.0,1.0,0.0] -
scan
Scan vectors with values and version facts.
strata vector scan
Scans visible vectors in a collection starting at an optional key. Each item includes the key, embedding, metadata, and commit metadata exposed by the executor output.
To see the complete help for this command, run:
strata vector scan --help
Example
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 scan docsKEY VERSION VECTOR_REVISION EMBEDDING METADATAa … 1 [1.0,0.0,0.0] -b … 1 [0.0,1.0,0.0] -
upsert
Insert or replace one vector.
strata vector upsert
db.vectors.upsert(collection: 'str', key: 'str', vector: 'Optional[Sequence[float]]' = None, *, text: 'Optional[str]' = None, metadata: 'Optional[dict]' = None) -> 'Any'
Upserts one vector key with a dense embedding and optional metadata. The vector dimension must match the collection configuration. With `text` instead of a 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.
To see the complete help for this command, run:
strata vector upsert --helphelp(db.vectors.upsert)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector upsert docs a '[1.0,0.0,0.0]' --metadata '{"tag":"x"}'created a in docsstrata vector exists docs atrue
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0], metadata={"tag": "x"})db.vectors.exists("docs", "a")
Collections
collection create
Create a vector collection with a dimension, metric, and optionally the model that produces its vectors.
strata vector collection create
db.vectors.create_collection(name: 'str', dimension: 'int', *, metric: 'str' = 'cosine', embedding_model: 'Optional[str]' = None) -> 'Any'
Creates a collection for dense vectors. The dimension and metric become part of the collection contract for future upserts and queries. Passing `embedding_model` records which model produces the collection's vectors: it lets `text` be embedded for upserts and queries, and lets a query embedded with a different model be refused rather than silently compared. A collection created without one can declare it later with `vector.collection.set_embedding_model`.
To see the complete help for this command, run:
strata vector collection create --helphelp(db.vectors.create_collection)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector collection stats docsNAME DIMENSION METRIC COUNT EMBEDDING_MODELdocs 3 cosine 0 -
_ = db.vectors.create_collection("docs", 3, metric="cosine")db.vectors.stats("docs").dimension
collection delete
Delete a vector collection.
strata vector collection delete
db.vectors.delete_collection(name: 'str') -> 'Any'
Deletes the selected vector collection from the current branch and space. The current wire response is a transitional boolean status.
To see the complete help for this command, run:
strata vector collection delete --helphelp(db.vectors.delete_collection)
Example
strata vector collection create temp 3 --metric cosinecreated collection temp (3 dimensions, cosine)strata vector collection delete tempdeleted collection tempstrata vector collection list(empty)
_ = db.vectors.create_collection("temp", 3, metric="cosine")_ = db.vectors.delete_collection("temp")[c.name for c in db.vectors.list_collections()]
collection list
List vector collections.
strata vector collection list
db.vectors.list_collections() -> 'Page'
Lists vector collections visible in the selected branch and space, including collection dimension, metric, and count facts.
To see the complete help for this command, run:
strata vector collection list --helphelp(db.vectors.list_collections)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector collection listNAME DIMENSION METRIC COUNT EMBEDDING_MODELdocs 3 cosine 0 -
_ = db.vectors.create_collection("docs", 3, metric="cosine")[c.name for c in db.vectors.list_collections()]
collection set_embedding_model
Declare the embedding model a vector collection's vectors come from.
strata vector collection set-embedding-model
db.vectors.set_embedding_model(collection: 'str', model: 'str') -> 'Any'
Records, once, which embedding model produces this collection's vectors. A declaration, not a verification: a stored vector carries no model, so this takes the caller's word for the vectors present; from then on `text` on upsert and query is embedded with this model and no other, and a collection with no recorded model cannot embed `text` at all. A vector supplied directly is not checked against the record - it cannot be - so supplying one remains the caller's statement that the recorded model produced it. Declaring the model a collection already records is a no-op and commits nothing. Declaring a different one is refused with `failed_precondition.engine.embedding_model_mismatch`: the stored vectors came from the recorded model, so create a separate collection for the other one. The current wire response uses the collection-list output with one item.
To see the complete help for this command, run:
strata vector collection set-embedding-model --helphelp(db.vectors.set_embedding_model)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector collection set-embedding-model docs openai:text-embedding-3-small # Declared once; repeating it with the same model is a no-op.updated collection docs: embedding model openai:text-embedding-3-small
_ = db.vectors.create_collection("docs", 3, metric="cosine")db.vectors.set_embedding_model("docs", "openai:text-embedding-3-small").items[0].embedding_model
collection stats
Read facts for one vector collection.
strata vector collection stats
db.vectors.stats(name: 'str') -> 'Any'
Reads collection-level facts for one vector collection. The current wire response uses the collection-list output with one item.
To see the complete help for this command, run:
strata vector collection stats --helphelp(db.vectors.stats)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector collection stats docsNAME DIMENSION METRIC COUNT EMBEDDING_MODELdocs 3 cosine 0 -
_ = db.vectors.create_collection("docs", 3, metric="cosine")db.vectors.stats("docs").dimension
Embedding
embedding update
Replace the embedding for one vector, keeping its metadata.
strata vector update-embedding
db.vectors.update_embedding(collection: 'str', key: 'str', vector: 'Optional[Sequence[float]]' = None, *, text: 'Optional[str]' = None) -> 'Any'
Replaces one visible vector's embedding and leaves its metadata as it stands - the mirror of `vector update-metadata`, which patches metadata and leaves the embedding. Use this to re-embed a document after a model change, a re-chunk or a backfill; `vector upsert` writes the whole record, so metadata not restated there is removed. Missing vectors return a no-op mutation acknowledgement and are never created. With `text` instead of a vector, the text is embedded through the collection's recorded model on the same inference path as `vector upsert`, so the `inference.*` failures listed below apply only to that form.
To see the complete help for this command, run:
strata vector update-embedding --helphelp(db.vectors.update_embedding)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector upsert docs a '[1.0,0.0,0.0]' --metadata '{"lang":"en","tier":1}'created a in docsstrata vector update-embedding docs a '[0.0,1.0,0.0]'updated a in docsstrata vector query docs '[0.0,1.0,0.0]' --k 1KEY SCORE METADATAa 1.0 {"lang":"en","tier":1}
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0], metadata={"tag": "x"})_ = db.vectors.update_embedding("docs", "a", [0.0, 1.0, 0.0])db.vectors.get("docs", "a").data.metadata
Indexes
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]'
Runs vector search and includes planner diagnostics such as index policy, source usage, artifact status, and fallback facts.
To see the complete help for this command, run:
help(db.vectors.index_query)
Example
_ = 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]]
Metadata
metadata update
Patch metadata for one vector.
strata vector update-metadata
db.vectors.update_metadata(collection: 'str', key: 'str', metadata: 'dict') -> 'Any'
Applies a top-level metadata patch to one visible vector. Missing vectors return a no-op mutation acknowledgement.
To see the complete help for this command, run:
strata vector update-metadata --helphelp(db.vectors.update_metadata)
Example
strata vector collection create docs 3 --metric cosinecreated collection docs (3 dimensions, cosine)strata vector upsert docs a '[1.0,0.0,0.0]' --metadata '{"tag":"x"}'created a in docsstrata vector update-metadata docs a '{"tag":"z"}'updated a in docsstrata vector get docs akey avector_revision 2version …embedding [1.0,0.0,0.0]metadata {"tag":"z"}
_ = db.vectors.create_collection("docs", 3, metric="cosine")_ = db.vectors.upsert("docs", "a", [1.0, 0.0, 0.0], metadata={"tag": "x"})_ = db.vectors.update_metadata("docs", "a", {"tag": "z"})db.vectors.get("docs", "a").data.metadata