Learn ChromaDB - Basic CRUD

#Introduction

Your first collection was created in episode 3. Now it is time to master every data manipulation operation — basic CRUD. Although it sounds simple, understanding each operation and how they differ is key to avoiding annoying production bugs: duplicated data, documents that cannot be updated, or deletions that remove too much.

Episode 4 covers seven operations: add, get, update, upsert, delete, count, and modify. The last four are the same as any other database, but the first three — especially update versus upsert — often trip people up. Let's get started.

#The Create Operation: add

#Adding New Data

add stores new data into a collection. Every id must be unique; adding an id that already exists triggers a UniqueConstraintError:

Menambah data baru

collection.add(
    ids=["dok-1", "dok-2"],
    documents=["Teks pertama", "Teks kedua"],
    metadatas=[{"sumber": "web"}, {"sumber": "pdf"}],
)

Notice the list-based argument pattern: ids, documents, and metadatas are all lists of equal length. collection.add(...) is the only way to add new data; all ids you send must not exist yet.

#Adding with Pre-Computed Embeddings

If embeddings are already generated outside ChromaDB, you can provide them directly:

Menambah dengan embedding jadi

collection.add(
    ids=["dok-3"],
    embeddings=[[0.12, 0.45, 0.87, 0.22]],
    metadatas=[{"sumber": "api"}],
)

When supplying embeddings, make sure their dimensionality is consistent with the collection's embedding function. collection.add(ids=["dok-3"], embeddings=[[...]]) gives you full control — this pattern will be used again in episode 6.

#The Read Operation: get

#Retrieving Data with Various Filters

get is how you read data. With no arguments, it returns all contents of the collection:

Mengambil semua data

semua = collection.get()

To filter, pass ids or where (metadata filtering — episode 7 will dissect it):

Mengambil berdasarkan id

dua_item = collection.get(ids=["dok-1", "dok-2"])
print(dua_item["metadatas"])

collection.get(ids=["dok-1", "dok-2"]) returns a dict with the keys ids, documents, metadatas, and embeddings (if requested via include). This is an important contrast with query in episode 5: get is based on id or metadata, whereas query is based on vector similarity.

#The Update Operation

#update: Only Modifying What Already Exists

update modifies the document, metadata, or embedding of an id that already exists. Ids that do not exist are silently ignored — behavior you need to be aware of:

Memperbarui metadata

collection.update(
    ids=["dok-2"],
    metadatas=[{"sumber": "pdf", "status": "revisi"}],
)

The code above replaces dok-2's metadata with a new dict. collection.update(ids=["dok-2"], metadatas=[...]) does not add new data — that is upsert's job.

#update vs add for Embeddings

Important: update does not automatically generate an embedding from a new document if an embedding function is active. To replace an embedding, pass explicit embeddings:

Mengganti embedding via update

collection.update(ids=["dok-1"], embeddings=[[0.5, 0.2, 0.9, 0.1]])

This rule confuses many people. Just remember: add may rely on automatic embeddings; update expects explicit embeddings when needed.

#The Upsert Operation

#Upsert: Add or Update at Once

upsert combines both: ids that do not exist are added, ids that already exist are updated. This is the most convenient operation for data synchronization:

Upsert: add atau update sekaligus

collection.upsert(
    ids=["dok-2", "dok-4"],
    documents=["Teks kedua versi baru", "Teks keempat"],
    metadatas=[{"sumber": "pdf"}, {"sumber": "manual"}],
)

In the example above, dok-2 is updated (because it exists) and dok-4 is added (because it is new). collection.upsert(...) is the best choice for periodic sync jobs from APIs or web scraping.

#The Delete and Count Operations

#Deleting Data

delete removes by id or metadata filter. Deleting by ids is the most common pattern:

Menghapus data

collection.delete(ids=["dok-4"])

collection.delete(ids=["dok-4"]) removes the matching items and does not return an error if the id is not found. For bulk deletion, use the where filter (episode 7) — for example, deleting all news with the category "draft".

#Counting Data

count returns the number of items:

Menghitung isi collection

jumlah = collection.count()
print(jumlah)

#The modify Operation: Changing Collection Configuration

Last, modify is not for data, but for the collection's own configuration — renaming it or changing its metadata:

Mengganti nama collection

collection.modify(name="artikel-tech-v2")

collection.modify(name="artikel-tech-v2") renames the collection in place, without deleting data. Useful when naming conventions change mid-development.

Perbandingan operasi CRUD

ringkasan = {
    "add": "id baru, error jika sudah ada, embedding otomatis",
    "get": "baca berdasarkan id atau where",
    "update": "ubah yang sudah ada saja, id baru diabaikan",
    "upsert": "tambah atau ubah sekaligus",
    "delete": "hapus berdasarkan id atau where",
    "count": "jumlah item",
    "modify": "ubah konfigurasi collection",
}
 
for nama, keterangan in ringkasan.items():
    print(f"{nama}: {keterangan}")

Keep the table above in mind — ringkasan["upsert"] will become your faithful companion for daily data synchronization.

#Closing

Episode 4 equipped you with all of ChromaDB's CRUD operations: add for new data, get for reading, update and upsert for modifying (with a crucial difference around ids that do not exist yet), delete for removing, count for counting, and modify for changing collection configuration.

Key takeaways:

• add rejects duplicate ids; upsert accepts them and updates instead.
• update does not generate automatic embeddings; pass explicit embeddings.
• get reads by id or metadata; query reads by similarity.
• delete and get accept the where filter for bulk operations.
• modify changes the collection's configuration, not its contents.
• Combinations of ids, documents, metadatas, and embeddings are always parallel lists.

In the next episode, episode 5, we will discuss querying and semantic search — the query API with query_texts and query_embeddings, the n_results setting, the include parameter, and how to interpret distance versus similarity. This is where ChromaDB starts to feel magical.