> 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

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](/start-here/verify-install.md).
{% endhint %}

## Signature

```python
Telys.create_collection(
    name,
    dim,
    partition_by,
    embedder=None,
    dtype="f32",
    filter_columns=(),
    tuner=None,
) -> 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](/tuning/why-tune.md)).                                         |

## 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](/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](/working-with-data/add-and-upsert.md) — put text or vectors into the collection you just made.
* [Collections](/understand-telys/collections.md) — how dimension, partition, and dtype fit together.
* [Choosing an embedder](/embeddings/choosing-an-embedder.md) — lexical vs dense, and bring-your-own.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/working-with-data/create-a-collection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.