# Update vector embedding

Source: https://stratadb.org/docs/reference/vector/embedding/update

Replace the embedding for one vector, keeping its metadata.

| | |
|---|---|
| Command | `vector.embedding.update` |
| CLI | `strata vector update-embedding` |
| Wire type | `vector_update_embedding` |
| Python | `db.vectors.update_embedding(collection: 'str', key: 'str', vector: 'Optional[Sequence[float]]' = None, *, text: 'Optional[str]' = None) -> 'Any'` |
| Access | write |
| Commit | commits on success |
| Wire status | stable |

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.

Successful mutations return an acknowledgement of the outcome: for a state-changing write, the affected target with the mutation effect and commit facts; for mutations that produce a domain result (such as a branch or a promotion outcome), that result object.

## Examples

Re-embed a vector without restating its metadata.

### CLI

```console
$ strata vector collection create docs 3 --metric cosine
created collection docs (3 dimensions, cosine)
$ strata vector upsert docs a '[1.0,0.0,0.0]' --metadata '{"lang":"en","tier":1}'
created a in docs
$ strata vector update-embedding docs a '[0.0,1.0,0.0]'
updated a in docs
$ strata vector query docs '[0.0,1.0,0.0]' --k 1
KEY  SCORE  METADATA
a      1.0  {"lang":"en","tier":1}
```

### Wire

```json
{"collection":"docs","dimension":3,"metric":"cosine","type":"vector_create_collection"}
{"collection":"docs","key":"a","metadata":{"lang":"en","tier":1},"type":"vector_upsert","vector":[1.0,0.0,0.0]}
{"collection":"docs","key":"a","type":"vector_update_embedding","vector":[0.0,1.0,0.0]}
{"collection":"docs","k":1,"query":[0.0,1.0,0.0],"type":"vector_query"}
```

### Python

```python
_ = 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
```

## Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `branch` | `string or null` | no | Target branch. Defaults to the executor handle branch. |
| `collection` | `string` | yes | Collection name. |
| `key` | `string` | yes | Vector key. |
| `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 vector. Exactly one of `vector` or `text`. |
| `vector` | `array` | no | Dense embedding. Accepted at wire (f64) precision and narrowed to the
stored f32; a value that underflows or overflows f32 is rejected.

Empty when `text` is supplied instead, on the same terms as
`VectorUpsert`: a vector carries no model, so supplying one is the
caller's statement that the collection's recorded model produced it. |

## Returns

`MutationAck`

- `data` (`object`)
- `type` (`string`)

## Errors

Recover by code, never by message.

| Code | Retry | Commit outcome |
|---|---|---|
| [`failed_precondition.engine.runtime_closed`](https://stratadb.org/e/failed_precondition.engine.runtime_closed) | never | not_started |
| [`not_found.engine.branch`](https://stratadb.org/e/not_found.engine.branch) | never | not_applicable |
| [`invalid_argument.engine.product_space`](https://stratadb.org/e/invalid_argument.engine.product_space) | never | not_started |
| [`invalid_argument.engine.vector_collection`](https://stratadb.org/e/invalid_argument.engine.vector_collection) | never | not_started |
| [`invalid_argument.engine.vector_key`](https://stratadb.org/e/invalid_argument.engine.vector_key) | never | not_started |
| [`not_found.engine.vector_collection`](https://stratadb.org/e/not_found.engine.vector_collection) | never | not_applicable |
| [`invalid_argument.engine.vector_dimension`](https://stratadb.org/e/invalid_argument.engine.vector_dimension) | never | not_started |
| [`invalid_argument.engine.vector_embedding`](https://stratadb.org/e/invalid_argument.engine.vector_embedding) | never | not_started |
| [`invalid_argument.executor.vector_dimension`](https://stratadb.org/e/invalid_argument.executor.vector_dimension) | never | not_started |
| [`invalid_argument.executor.vector_input`](https://stratadb.org/e/invalid_argument.executor.vector_input) | never | not_started |
| [`failed_precondition.engine.embedding_model_missing`](https://stratadb.org/e/failed_precondition.engine.embedding_model_missing) | never | not_started |
| [`inference.invalid_request`](https://stratadb.org/e/inference.invalid_request) | never | not_applicable |
| [`inference.unsupported_operation`](https://stratadb.org/e/inference.unsupported_operation) | never | not_applicable |
| [`inference.missing_model`](https://stratadb.org/e/inference.missing_model) | after_state_change | not_applicable |
| [`inference.unknown_model`](https://stratadb.org/e/inference.unknown_model) | never | not_applicable |
| [`inference.io_failure`](https://stratadb.org/e/inference.io_failure) | after_state_change | not_applicable |
| [`inference.model_load_failed`](https://stratadb.org/e/inference.model_load_failed) | after_state_change | not_applicable |
| [`inference.local_runtime_failed`](https://stratadb.org/e/inference.local_runtime_failed) | after_state_change | not_applicable |
| [`inference.registry_corrupt`](https://stratadb.org/e/inference.registry_corrupt) | never | not_applicable |
| [`inference.missing_api_key`](https://stratadb.org/e/inference.missing_api_key) | after_state_change | not_applicable |
| [`inference.provider_auth_failed`](https://stratadb.org/e/inference.provider_auth_failed) | after_state_change | not_applicable |
| [`inference.provider_unavailable`](https://stratadb.org/e/inference.provider_unavailable) | same_request | not_applicable |
| [`inference.provider_timeout`](https://stratadb.org/e/inference.provider_timeout) | same_request | not_applicable |
| [`inference.provider_rate_limited`](https://stratadb.org/e/inference.provider_rate_limited) | after_state_change | not_applicable |
| [`inference.provider_quota_exhausted`](https://stratadb.org/e/inference.provider_quota_exhausted) | after_state_change | not_applicable |
| [`inference.provider_model_not_found`](https://stratadb.org/e/inference.provider_model_not_found) | never | not_applicable |
| [`inference.provider_malformed_response`](https://stratadb.org/e/inference.provider_malformed_response) | same_request | not_applicable |
| [`inference.unsupported_provider`](https://stratadb.org/e/inference.unsupported_provider) | never | not_applicable |
| [`inference.unsupported_parameter`](https://stratadb.org/e/inference.unsupported_parameter) | never | not_applicable |

## Related

- [Batch delete vectors](https://stratadb.org/docs/reference/vector/batch_delete)
- [Batch check vector existence](https://stratadb.org/docs/reference/vector/batch_exists)
- [Batch get vectors](https://stratadb.org/docs/reference/vector/batch_get)
- [Batch upsert vectors](https://stratadb.org/docs/reference/vector/batch_upsert)
- [Create vector collection](https://stratadb.org/docs/reference/vector/collection/create)
- [Delete vector collection](https://stratadb.org/docs/reference/vector/collection/delete)
- [List vector collections](https://stratadb.org/docs/reference/vector/collection/list)
- [Declare vector collection embedding model](https://stratadb.org/docs/reference/vector/collection/set_embedding_model)
- [Read vector collection stats](https://stratadb.org/docs/reference/vector/collection/stats)
- [Count vectors](https://stratadb.org/docs/reference/vector/count)
- [Delete vector](https://stratadb.org/docs/reference/vector/delete)
- [Delete all vectors](https://stratadb.org/docs/reference/vector/delete_all)
- [Delete vectors by filter](https://stratadb.org/docs/reference/vector/delete_by_filter)
- [Check vector existence](https://stratadb.org/docs/reference/vector/exists)
- [Get vector](https://stratadb.org/docs/reference/vector/get)
- [Read vector history](https://stratadb.org/docs/reference/vector/history)
- [Query vector index](https://stratadb.org/docs/reference/vector/index/query)
- [List vector keys](https://stratadb.org/docs/reference/vector/keys)
- [Update vector metadata](https://stratadb.org/docs/reference/vector/metadata/update)
- [Query vectors](https://stratadb.org/docs/reference/vector/query)
- [Sample vectors](https://stratadb.org/docs/reference/vector/sample)
- [Scan vectors](https://stratadb.org/docs/reference/vector/scan)
- [Upsert vector](https://stratadb.org/docs/reference/vector/upsert)