> 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/working-with-data/create-a-collection.md).

# Create a collection

Create a Telys collection with a fixed dimension, a partition key, and an optional embedder, then commit it to disk with save().

A collection is Telys's unit of storage and search: records that share one vector dimension, one partition key, and an optional embedder. `Telys.create_collection(...)` builds the collection in memory and caches it on the facade; nothing touches disk until you call `col.save()`.

{% hint style="info" %}
Collection operations load the signed native runtime lazily, and the lexical embedders read their dimension from the native kernel. Without them, construction raises `RuntimeNotInstalled` / `ImportError`. Verify first with `telys runtime verify` — see [Verify your install](https://docs.telys.ai/start-here/verify-install.md).
{% endhint %}

## Signature

```python
Telys.create_collection(
    name,
    dim,
    partition_by,
    embedder=None,
    dtype="f32",
    filter_columns=(),
    tuner=None,
    lexical=False,
) -> Collection
```

| Parameter        | Type                        | Default | Meaning                                                                                                                                                                             |
| ---------------- | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | `str`                       | —       | Collection name; also the on-disk subdirectory under the store path.                                                                                                                |
| `dim`            | `int`                       | —       | Vector dimension. Must equal your embedder's `profile.dimension` (or the width of the vectors you will add).                                                                        |
| `partition_by`   | `str`                       | —       | Metadata column used as the physical partition key. A list/tuple uses only element `[0]` — see the note below.                                                                      |
| `embedder`       | `EmbeddingProvider \| None` | `None`  | Attaches an embedder so `add_texts` / `search_text` work. Omit for a vectors-only collection.                                                                                       |
| `dtype`          | `str`                       | `"f32"` | On-disk vector storage dtype (single-precision float by default).                                                                                                                   |
| `filter_columns` | `tuple[str, ...]`           | `()`    | Extra metadata columns you may constrain with `Eq` / `where`.                                                                                                                       |
| `tuner`          | `Tuner \| None`             | `None`  | Optional tuner for index tuning (see [Why tune](https://docs.telys.ai/tuning/why-tune.md)).                                                                                         |
| `lexical`        | `bool`                      | `False` | Retain code tokens at ingest so you can [`build_lexical`](https://docs.telys.ai/working-with-data/build-lexical-index.md) and query `search_text(mode="lexical")` (on-device BM25). |

## Create a text-backed collection

Construct an embedder and pass its `profile.dimension` as `dim` so the collection width always matches the vectors the embedder produces.

{% stepper %}
{% step %}

#### Open a store

`Telys(path)` creates the directory if needed and prepares the lazy runtime. The path holds every collection in this store.

```python
from telys import Telys

telys = Telys("telys-store")
```

{% endstep %}

{% step %}

#### Pick an embedder and read its dimension

Import embedders from `telys.embedding`, not the top level. `AlgentaMultigramEmbedder` is lexical; its width comes from the native kernel, so read it from the profile rather than hard-coding a number.

```python
from telys.embedding import AlgentaMultigramEmbedder

embedder = AlgentaMultigramEmbedder()
dim = embedder.profile.dimension          # kernel-sourced (e.g. 384)
```

{% endstep %}

{% step %}

#### Create the collection

```python
memories = telys.create_collection(
    "memories",
    dim=dim,
    partition_by="scope",
    embedder=embedder,
)
```

`memories` is a `Collection` you can query and mutate immediately, but it stays in memory until you save.
{% endstep %}

{% step %}

#### Commit it to disk

`save()` writes the `id_map.npy` sidecar, then `collection.json` (the commit point), and returns the directory it wrote.

```python
memories.save()
```

{% endstep %}
{% endstepper %}

## Add dtype and filter columns

`filter_columns` declares which metadata columns you can later constrain with `Eq`. The partition key is always filterable; any other column must be listed here at creation time.

```python
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder

telys = Telys("telys-store")
embedder = AlgentaMultigramEmbedder()

docs = telys.create_collection(
    "docs",
    dim=embedder.profile.dimension,
    partition_by="tenant_id",
    embedder=embedder,
    dtype="f32",
    filter_columns=("lang", "source"),
)
docs.save()
```

Records can now be filtered on `tenant_id`, `lang`, or `source`. See [Filter results](https://docs.telys.ai/working-with-data/filter-results.md).

{% hint style="warning" %}
`partition_by` is a single physical key, not a composite. A list or tuple uses only element `[0]`. To partition by several attributes, join them into one string with `scope_key(...)` and partition by that:

```python
from telys import scope_key

key = scope_key("acme", "user:42")     # -> "acme\x1fuser:42"
```

{% endhint %}

## Expected result

`create_collection` returns a `Collection` with zero records. `telys.collections()` lists only saved collections, so it stays empty until `save()`:

```python
>>> len(memories)
0
>>> telys.collections()           # nothing on disk yet
[]
>>> memories.save()               # commit point
'telys-store/memories'
>>> telys.collections()
['memories']
```

To reopen a saved collection later, call `telys.open_collection("memories", embedder=...)`, or register the embedder once with `telys.register_provider(...)` so `open_collection` re-attaches it automatically.

## Next steps

* [Add & upsert records](https://docs.telys.ai/working-with-data/add-and-upsert.md) — put text or vectors into the collection you just made.
* [Collections](https://docs.telys.ai/understand-telys/collections.md) — how dimension, partition, and dtype fit together.
* [Choosing an embedder](https://docs.telys.ai/embeddings/choosing-an-embedder.md) — lexical vs dense, and bring-your-own.
