> 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/add-text-vs-vectors.md).

# Text vs vectors

Every Telys collection stores vectors. The only choice is who computes them: Telys, from your text through an attached embedder, or you, precomputed from any model. Both paths write to the same collection and query it the same way.

| Use the text path                              | Use the vector path                               |
| ---------------------------------------------- | ------------------------------------------------- |
| `add_texts` / `upsert_texts` / `search_text`   | `add` / `upsert` / `search`                       |
| Collection has an embedder attached            | Collection needs no embedder                      |
| You pass `str` documents and queries           | You pass `float32` arrays of shape `(n, dim)`     |
| Telys embeds with the collection's embedder    | You embed with OpenAI, BGE, or any model you like |
| Simplest for on-device lexical/semantic memory | Best when you already run a model elsewhere       |

{% hint style="warning" %}
The `*_texts` and `search_text` methods need an embedder; on a collection created with `embedder=None` they raise `RuntimeError`. Raw `add` / `upsert` / `search` never embed and work on any collection.
{% endhint %}

## The text path

Attach an embedder at creation and pass strings. You never touch a vector.

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

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

notes = telys.create_collection(
    "notes",
    dim=embedder.profile.dimension,
    partition_by="scope",
    embedder=embedder,
)

notes.add_texts(
    ["kubernetes rollout stuck on readiness probe"],
    ids=["note-1"],
    metadata=[{"scope": "ops"}],
)
notes.save()
```

## The vector path (bring your own)

If you already produce embeddings, create the collection with `dim` set to your model's output width and add raw vectors. No embedder is required.

```python
import numpy as np
from telys import Telys

DIM = 1536                       # your model's output dimension

telys = Telys("telys-store")
docs = telys.create_collection("docs", dim=DIM, partition_by="scope")

texts = ["invoice overdue reminder", "welcome email copy"]
vectors = np.asarray(my_model.encode(texts), dtype="float32")   # your model
assert vectors.shape == (len(texts), DIM)                       # (n, dim) float32

docs.add(
    vectors,
    ids=["doc-1", "doc-2"],
    metadata=[{"scope": "billing"}, {"scope": "marketing"}],
)
docs.save()
```

Two rules keep the vector path safe:

* **Shape.** Vectors must be `(n, dim)` with `n == len(ids) == len(metadata)`.
* **Dtype.** Vectors must be `float32`; call `.astype("float32")` if your model returns `float64`.

{% hint style="info" %}
Vector width is fixed at creation. A `dim=1536` collection accepts only 1536-wide vectors, and `search` raises on a wrong-length query. To switch embedding models, create a new collection. See [Dimensions & space IDs](/embeddings/dimensions-and-space-id.md).
{% endhint %}

## Expected result

Both paths return the external ids they wrote and grow the collection identically:

```python
>>> notes.add_texts(["disk pressure eviction"], ids=["note-2"], metadata=[{"scope": "ops"}])
['note-2']
>>> docs.add(vectors, ids=["doc-3", "doc-4"], metadata=[{"scope": "billing"}, {"scope": "billing"}])
['doc-3', 'doc-4']
```

At query time the two collections are indistinguishable: `notes` answers `search_text`, `docs` answers `search`, both over the same kind of vectors.

## Next steps

* [Search by text](/working-with-data/search-by-text.md) — query the text path with a string.
* [Search by vector](/working-with-data/search-by-vector.md) — query the vector path with a precomputed query.
* [CallableEmbedder (bring your own)](/embeddings/callable-byo.md) — wrap any model as an embedder to use `search_text` with BYO vectors.


---

# 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/add-text-vs-vectors.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.