> 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-and-upsert.md).

# Add & upsert

Insert records into a Telys collection with add / add\_texts for new rows, or upsert / upsert\_texts to insert-or-replace, then persist with save().

Telys has two ingest verbs and two input shapes — four methods:

| Method                               | Input                                  | Behavior                                                                               |
| ------------------------------------ | -------------------------------------- | -------------------------------------------------------------------------------------- |
| `add(vectors, ids, metadata)`        | precomputed vectors `(n, dim)` float32 | insert **new rows only** — `KeyError` if an id already exists                          |
| `add_texts(texts, ids, metadata)`    | strings (embedded for you)             | insert **new rows only** — `KeyError` on a duplicate id; `RuntimeError` if no embedder |
| `upsert(vectors, ids, metadata)`     | precomputed vectors `(n, dim)` float32 | **insert new + replace existing**                                                      |
| `upsert_texts(texts, ids, metadata)` | strings (embedded for you)             | **insert new + replace existing** — needs an embedder                                  |

All four take parallel `ids` and `metadata` lists and **return the external ids** they wrote. Each `metadata` dict supplies the partition key column (and any `filter_columns`) for its row.

{% hint style="info" %}
The `*_texts` methods need an embedder on the collection (attached at [creation](https://docs.telys.ai/working-with-data/create-a-collection.md) or via `open_collection`); without one they raise `RuntimeError`. Raw `add` / `upsert` never embed and work on any collection.
{% endhint %}

## Add new records from text

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

telys = Telys("telys-store")
embedder = AlgentaMultigramEmbedder()
memories = telys.create_collection(
    "memories",
    dim=embedder.profile.dimension,
    partition_by="scope",
    embedder=embedder,
)

ids = memories.add_texts(
    texts=[
        "the mitochondria is the powerhouse of the cell",
        "photosynthesis converts light into chemical energy",
    ],
    ids=["bio-1", "bio-2"],
    metadata=[
        {"scope": "user:42", "topic": "biology"},
        {"scope": "user:42", "topic": "biology"},
    ],
)
memories.save()
```

Each metadata dict includes `scope`, the partition key. `add_texts` returns `["bio-1", "bio-2"]`.

## add is new-only — duplicates raise

`add` and `add_texts` never overwrite. Re-adding an existing id raises `KeyError` — once the first batch has sealed the collection, the message points you at `upsert`:

```python
>>> memories.add_texts(
...     ["a different note"],
...     ids=["bio-1"],                       # already present
...     metadata=[{"scope": "user:42"}],
... )
KeyError: "ids already exist (use upsert): ['bio-1']"
```

A duplicate caught inside the very first batch (before the collection seals) raises `KeyError: "ids already exist: [...]"` instead. Either form lists up to three of the offending ids.

## upsert to insert-or-replace

To overwrite, use `upsert_texts` (or `upsert` for vectors): new ids are inserted, existing ids replaced in place.

```python
ids = memories.upsert_texts(
    texts=["the mitochondria produces most of the cell's ATP"],
    ids=["bio-1"],                            # replaced, not rejected
    metadata=[{"scope": "user:42", "topic": "biology"}],
)
# -> ["bio-1"]
```

## Add precomputed vectors

Skip embedding by passing vectors directly. Use a NumPy array of shape `(n, dim)`, dtype `float32`, with the row count matching `ids` and `metadata`.

```python
import numpy as np

vectors = np.random.rand(2, embedder.profile.dimension).astype("float32")
memories.add(
    vectors,
    ids=["v-1", "v-2"],
    metadata=[{"scope": "user:7"}, {"scope": "user:7"}],
)
```

## Expected result

Each call returns the external ids it wrote, and `len(col)` grows by the number of new ids. `add`/`add_texts` reject duplicates; `upsert`/`upsert_texts` accept them as replacements.

```python
>>> memories.add_texts(["note"], ids=["bio-3"], metadata=[{"scope": "user:42"}])
['bio-3']
>>> len(memories)
5
>>> "bio-3" in memories
True
```

Writes stay in memory until you persist. `memories.save()` commits and returns the collection directory.

## Next steps

* [Add text vs vectors](https://docs.telys.ai/working-with-data/add-text-vs-vectors.md) — when to embed vs bring your own vectors.
* [Update records](https://docs.telys.ai/working-with-data/update-records.md) — replace existing rows only, without inserting new ones.
* [Records, IDs & payloads](https://docs.telys.ai/understand-telys/records-ids-payloads.md) — how ids and metadata are stored.
