---
question: Does vector_store embed text or store vectors I built?
kind: task
via_web: available
via_cli: na
via_python: available
via_api: available
via_config: na
ref_web: System › Data › Vector store
ref_python: add_documents
ref_api: PUT /api/admin/system/resources/vector_store/entry
prereq: The collection exists. [Create a collection](/user-guide/build/vector-search/create-a-collection) first.
next:
  - /capabilities/build/vector-search/search
  - /capabilities/build/vector-search/delete-a-collection
---

# Add embeddings

The vector store keeps vectors that already exist: it does not call an embedding model. Embed the text first, then store the vector with its metadata and payload. Writing an id that is already there replaces it.

## Web UI

Super admins only. Use it to fix or test an entry by hand; indexing is a module's job.

### Open the collection

In Nexus, open **System** in the sidebar, then the **Data** tab, then **Vector store**. Open the collection.

![System app, Data tab, on Vector store](/abi/Screenshot_System_Vector.png)

*System › Data › Vector store. Collections appear once a module writes a vector; this project has none yet.*

### Add a vector

Choose **New vector**. Name it with the document id, and fill the JSON:

```json title="New vector"
{
  "vector": [0.12, -0.03, 0.88],
  "metadata": {"source": "manual"},
  "payload": {"text": "Hello"}
}
```

The vector must have the collection's dimension. Choose **Create**. If the id exists, Nexus asks you to type it back, and **Replace** overwrites it.

## CLI

Not applicable. There is no `abi` command for the vector store. Use the Python steps on this page. The command list is the [CLI reference](/user-guide/reference/cli).

## Python

### Embed the text

```python
import numpy as np

embedding = self.engine.services.model_registry.get_default_embedding_model().model
vector = np.array(embedding.embed_query("the text"))
```

Pass NumPy arrays: the Qdrant adapters call `.tolist()` on each vector.

### Store it

```python
import uuid

store = self.engine.services.vector_store
store.add_documents(
    "my_module_notes",
    ids=[str(uuid.uuid5(uuid.NAMESPACE_URL, "note-1"))],
    vectors=[vector],
    metadata=[{"source": "manual"}],
    payloads=[{"text": "the text"}],
)
```

`ids` and `vectors` are parallel lists, not empty. `metadata` and `payloads` are optional lists of the same length. A length mismatch raises `ValueError`. `qdrant` hands ids to Qdrant as they are, and Qdrant accepts only UUIDs and unsigned integers: derive a UUID from your own key, as above.

### Change one entry

```python
store.update_document("my_module_notes", doc_id, metadata={"source": "reviewed"})
```

`update_document(collection, document_id, vector=None, metadata=None, payload=None)` needs at least one of the three.

## REST API

The System routes of the Nexus API. Auth: a Nexus session of a super admin (`POST /api/auth/login` returns the access token). Every change is audited.

### Write the vector

```bash
curl -X PUT "http://localhost:9879/api/admin/system/resources/vector_store/entry?id=my_module_notes/0b6f7c1e-6a4e-4a43-9a3c-6f0d6c1d2e11" \
  -H "Authorization: Bearer $NEXUS_TOKEN" \
  --data-binary '{"vector": [0.12, -0.03, 0.88], "metadata": {"source": "manual"}, "payload": {"text": "Hello"}}'
```

The `id` is `<collection>/<document id>`. A vector of the wrong length answers 400.

### Replace an existing id

The same call answers 409 when the id exists. Add `&confirm=<the same id>` to replace it.

## Config

Not applicable. `config.yaml` picks the vector store and the default embedding model, not the vectors. See [Vector store](/user-guide/get-started/configuration#vector-store).