Belajar ChromaDB - Persistence, Import & Export

#Pendahuluan

Sejak episode 3 kalian sudah memakai PersistentClient — tapi seberapa dalam kalian memahami apa yang terjadi di baliknya? Episode 11 membahas persistence, import, dan export: bagaimana data benar-benar disimpan di disk, bagaimana membackup dan merestore, dan bagaimana memindahkan collection antar environment.

Data di collection kalian adalah aset — terutama setelah episode 10 mengajarkan cara mengisinya dengan rapi. Episode ini memastikan aset itu aman, bisa dipindah, dan tidak bergantung pada satu mesin.

#Bagaimana Persistence Bekerja

#Struktur Direktori Storage

PersistentClient menyimpan semua data ke folder yang kalian tentukan lewat path. Strukturnya bukan satu file tunggal — ChromaDB menggunakan SQLite untuk metadata dan segment files untuk index vektor:

chroma-data/
├── chroma.sqlite3
└── <collection-uuid>/
    ├── header.bin
    └── data_level0.bin

chroma.sqlite3 menyimpan definisi collection, dokumen, dan metadata. Folder per collection berisi index HNSW dalam format biner. Keduanya harus di-backup bersama — membackup hanya SQLite akan membuat index tidak konsisten.

#Membuat PersistentClient dengan Benar

PersistentClient dengan path eksplisit

client = chromadb.PersistentClient(path="/data/chroma")

chromadb.PersistentClient(path="/data/chroma") menciptakan folder jika belum ada. Pastikan folder bisa ditulis dan punya ruang cukup — index HNSW memakai space lebih besar dari sekadar dokumen teks.

#Backup dan Restore

#Backup dengan Stop-the-World

Cara paling aman dan paling sederhana: hentikan proses yang memakai collection, salin seluruh folder, lalu jalankan kembali:

rsync -a --delete /data/chroma/ /backup/chroma-$(date +%F)/

rsync -a --delete /data/chroma/ /backup/chroma-$(date +%F)/ membuat snapshot folder lengkap dengan nama tanggal. Restore tinggal menyalin kembali:

rsync -a /backup/chroma-2026-08-05/ /data/chroma/

Menyalin saat ChromaDB sedang menulis bisa menghasilkan file korup. Untuk jadwal backup otomatis, pause penulisan atau gunakan mode client-server dan backup di luar jam puncak.

#Export dan Import Data

#Export Semua Data ke Bentuk Portable

Cara paling portabel untuk memindahkan data: baca seluruh isi collection dan simpan sebagai parquet atau JSON. Langkah pertama, pastikan pandas terinstall:

pip install pandas pyarrow

Lalu export:

Export collection ke parquet

import pandas as pd
 
data = collection.get(include=["documents", "metadatas", "embeddings"])
df = pd.DataFrame({
    "id": data["ids"],
    "document": data["documents"],
    "metadata": data["metadatas"],
    "embedding": data["embeddings"],
})
df.to_parquet("export-artikel.parquet")

df.to_parquet("export-artikel.parquet") menghasilkan satu file yang bisa dipindah ke mesin lain. Parquet dipilih karena terkompresi dan cepat dibaca — format ideal untuk data besar.

#Import Kembali ke Collection Baru

Untuk mengimport, baca parquet lalu upsert dengan embedding yang sudah tersimpan:

Import dari parquet

df = pd.read_parquet("export-artikel.parquet")
 
collection = client.get_or_create_collection("artikel-restored")
collection.upsert(
    ids=df["id"].tolist(),
    documents=df["document"].tolist(),
    metadatas=df["metadata"].tolist(),
    embeddings=[list(v) for v in df["embedding"]],
)

collection.upsert(ids=df["id"].tolist(), ..., embeddings=[...]) mengembalikan data persis — termasuk embedding asli, sehingga tidak perlu men-embed ulang. Ini pola yang paling aman untuk migrasi data.

#Migrasi Antar Environment

#Copy Folder vs Export-Import

Dua strategi migrasi dengan karakter berbeda:

Copy folder paling cepat untuk dev ke staging yang versinya sama. Export-import lebih aman saat ada perbedaan versi atau kalian ingin memfilter data — misalnya hanya memindahkan collection dengan tenant tertentu.

#Memastikan Konsistensi Versi

Satu jebakan umum: file storage ChromaDB tidak dijamin kompatibel antar versi mayor. Sebelum memigrasi dengan copy folder, pastikan versi chromadb di kedua environment sama:

pip show chromadb | grep -i version

pip show chromadb | grep -i version di kedua mesin harus menampilkan nomor yang sama. Jika berbeda, gunakan jalur export-import parquet sebagai pengganti copy folder.

#Penutup

Episode 11 memastikan data kalian tidak lagi rapuh: memahami struktur storage SQLite dan index HNSW, melakukan backup dengan rsync, merestore, mengekspor collection ke parquet, dan mengimpornya kembali — termasuk strategi migrasi antar environment yang aman dan konsisten antar versi.

Inti yang harus dibawa pulang:

• Persistence terdiri dari SQLite dan file index biner; backup harus lengkap.
• Backup teraman: stop penulisan, rsync seluruh folder, jalankan lagi.
• Export parquet membawa ids, documents, metadatas, dan embeddings sekaligus.
• Import memakai upsert dengan embeddings asli agar tidak re-embed.
• Copy folder cepat; export-import fleksibel untuk versi berbeda.
• Pastikan versi chromadb sama sebelum migrasi via copy.

Di episode 12 selanjutnya kita akan membahas client-server mode dan settings — menjalankan chroma run, menghubungkan dengan HttpClient, mengatur host dan port, memahami model tenant dan database, serta konfigurasi server untuk deployment lokal versus produksi. Saatnya data kalian keluar dari satu proses.