> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/embeddings/dimensions-and-space-id.md).

# Dimensions & spaces

How a collection's dimension and space\_id lock it to one embedder — why changing model or dimension needs a new collection, and how to migrate by re-embedding.

A Telys collection is bound to one vector space for its whole life. Two numbers fix that space: the **dimension** (how wide each vector is) and the **space ID** (a digest of the embedder's [`EmbeddingProfile`](https://docs.telys.ai/embeddings/embedding-profile.md)). After creation both are frozen — you cannot search with vectors of a different width, and you cannot re-attach an embedder from a different space.

## The dimension contract

The `dim` you declare at creation must agree with the embedder in three places:

* the `dim` you pass to `create_collection`,
* the embedder's `profile.dimension`,
* the width of the array the embedder returns (`shape[1]`).

```python
from telys import Telys
from telys.embedding import CallableEmbedder, EmbeddingProfile

profile = EmbeddingProfile("openai", "text-embedding-3-small", "1", dimension=1536)
embedder = CallableEmbedder(embed_fn, profile)

ame = Telys("./store")
col = ame.create_collection("docs", dim=1536, partition_by="scope", embedder=embedder)
#                                     ^^^^ must equal profile.dimension (1536)
```

If those numbers disagree, the collection and embedder describe different spaces and the operation is rejected. After creation, every query vector is checked too: `search(vector, ...)` validates `len(vector) == dim`, and `add(vectors, ...)` requires an `(n, dim)` array.

## What a space ID is

The space ID is `EmbeddingProfile.space_id()` — `"sha256:"` plus 16 hex characters, computed from the space-defining fields (provider, model, version, dimension, dtype, normalization, distance, pooling, and the tokenizer/projection tags). It answers one question: *are these two sets of vectors comparable?*

```python
profile.space_id()          # e.g. "sha256:9c1f4a2b7e0d5163"
```

`save()` writes the profile to disk. `open_collection(...)` re-attaches an embedder from the provider registry by matching `model_id` and `space_id()`. A provider from a different space will not attach.

## Changing the embedder means a new space

Anything that changes the profile's identity changes the space ID, and a new space ID is **incompatible** with an existing collection:

| Change                                                          | New `space_id()`? | Effect on an existing collection                      |
| --------------------------------------------------------------- | ----------------- | ----------------------------------------------------- |
| Different model (`text-embedding-3-small` → `bge-base-en-v1.5`) | Yes               | Incompatible — vectors are not comparable.            |
| Different dimension (1536 → 512)                                | Yes               | Incompatible — and the width no longer matches `dim`. |
| Different `normalization` or `distance`                         | Yes               | Incompatible — scores would be meaningless.           |
| New `model_version`                                             | Yes               | Incompatible — treat as a fresh space.                |
| Only `created` (provenance timestamp)                           | No                | Still compatible — reopen keeps working.              |

There is no in-place "re-embed" and no way to swap a collection onto a new space. A different embedding model is a different space, and a different space is a new collection.

## Migrating to a new model

Create a **new** collection under the new space and re-embed your source text into it. Vectors cannot be reused across spaces, so re-run `add_texts` from the original documents — keep your source text.

{% stepper %}
{% step %}

#### Create a new collection for the new space

```python
new_profile = EmbeddingProfile("bge", "BAAI/bge-base-en-v1.5", "1.5", dimension=768)
new_embedder = CallableEmbedder(bge_embed, new_profile)

ame = Telys("./store")
new_col = ame.create_collection("docs_v2", dim=768, partition_by="scope", embedder=new_embedder)
```

{% endstep %}

{% step %}

#### Re-embed the source text into it

```python
new_col.add_texts(texts=source_texts, ids=source_ids, metadata=source_metadata)
new_col.save()
```

{% endstep %}

{% step %}

#### Cut over reads to the new collection

Point searches at `docs_v2`. Keep the old collection until you have verified recall, then delete its directory.
{% endstep %}
{% endstepper %}

## Dimension-mismatch errors

<details>

<summary>Query vector length does not match the collection</summary>

`search(vector, ...)` validates `len(vector) == dim`. Passing a 768-d vector to a 1536-d collection (or vice versa) fails. Embed the query with the **same** embedder that built the collection, or use `search_text`, which embeds through the attached embedder.

</details>

<details>

<summary>Raw vectors are not shaped <code>(n, dim)</code></summary>

`add(vectors, ...)` and `upsert(vectors, ...)` require a 2-D `float32` array whose second axis equals `dim`. Reshape or cast before inserting: `np.asarray(vectors, dtype="float32").reshape(-1, dim)`.

</details>

<details>

<summary>Reopened embedder will not attach</summary>

The registered provider's `space_id()` differs from the one stored in the collection. Register a provider that describes the same space (same model, version, dimension, normalization, distance) before calling `open_collection`.

</details>

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Embedding dimension mismatches</strong></td><td>Diagnose and fix the exact errors above.</td><td><a href="https://docs.telys.ai/troubleshooting/dimension-mismatches.md">Dimension mismatches</a></td></tr><tr><td><strong>EmbeddingProfile &#x26; space compatibility</strong></td><td>Every profile field and how space_id() is computed.</td><td><a href="https://docs.telys.ai/embeddings/embedding-profile.md">Embedding profiles</a></td></tr><tr><td><strong>Embeddings &#x26; vector spaces</strong></td><td>The concept behind spaces and comparability.</td><td><a href="https://docs.telys.ai/understand-telys/embeddings-and-spaces.md">Embeddings &amp; spaces</a></td></tr></tbody></table>

Next: work through concrete failures in [Embedding dimension mismatches](https://docs.telys.ai/troubleshooting/dimension-mismatches.md).
