---
question: How do I create a collection with the right dimension?
kind: task
via_web: na
via_cli: na
via_python: available
via_api: available
via_config: na
ref_python: ensure_collection
ref_api: PUT /api/admin/system/resources/vector_store/entry
prereq: You need an in-engine module that lists `VectorStoreService` in its dependencies. [Create a module](/user-guide/build/modules/creating-a-module) first.
next:
  - /capabilities/build/vector-search/add-embeddings
  - /capabilities/build/vector-search/search
---

# Create a collection

A collection has one dimension, the length of every vector in it, and one distance metric. A module creates the collections it needs when it starts. A super admin can also create one over the Nexus API by writing its first vector.

## Web UI

Not applicable. System › Data › Vector store adds vectors only inside a collection that already exists. Create the collection from the module (Python) or with the REST call on this page, then add vectors in Nexus: see [Add embeddings](/user-guide/build/vector-search/add-embeddings?via=web).

## 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

### Declare the service

```python title="src/my_module/__init__.py"
from naas_abi_core.module.Module import BaseModule, ModuleDependencies
from naas_abi_core.services.vector_store.VectorStoreService import VectorStoreService


class ABIModule(BaseModule):
    dependencies: ModuleDependencies = ModuleDependencies(
        modules=[],
        services=[VectorStoreService],
    )
```

### Ensure the collection

Call it once the services are loaded, in `on_initialized`:

```python title="src/my_module/__init__.py"
    def on_initialized(self):
        super().on_initialized()
        embedding = self.engine.services.model_registry.get_default_embedding_model()
        dimension = embedding.dimensions or len(embedding.model.embed_query("dimension probe"))
        self.engine.services.vector_store.ensure_collection(
            "my_module_notes",
            dimension=dimension,
            distance_metric="cosine",
        )
```

`ensure_collection` creates the collection when it is missing. When it exists, it is left as is, even if its dimension differs. `recreate=True` drops it and creates it again, with all its vectors gone.

Take the dimension from the embedding model rather than a fixed number. The model's `dimensions` can be `None`; only then does the example embed a short text to measure it, which calls the provider. Collection names are global, so prefix them with the module.

### Check it

```python
store = self.engine.services.vector_store
store.list_collections()                      # ["my_module_notes", ...]
store.get_collection_info("my_module_notes")  # CollectionInfo(name, dimension, distance_metric, size)
```

:::warning Distance metrics
`sqlite_vec` accepts `cosine`, `euclidean`, `l2`, `dot` and `l1`. `qdrant` and `qdrant_in_memory` map `cosine`, `euclidean` and `dot`; any other name silently becomes `cosine`.
:::

## 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 first vector

Writing a vector to a collection that does not exist creates it. The collection takes the vector's length as its dimension, and `distance_metric` from the body (`cosine` when left out):

```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"}, "distance_metric": "cosine"}'
```

The `id` is `<collection>/<document id>`. A real vector has the length of your embedding model's output, not three numbers. With `abi dev up`, use the `api` port that `abi dev ports` prints.

### List the collections

```http
GET /api/admin/system/resources/vector_store/entries
```

Each collection shows its size, dimension and distance metric.

## Config

Not applicable. `services.vector_store` in `config.yaml` picks the backend that holds the collections, not the collections. See [Vector store](/user-guide/get-started/configuration#vector-store).