Belajar ChromaDB - Setup, Client & Collection Pertama

#Pendahuluan

Fondasi sudah diletakkan di dua episode pertama. Sekarang saatnya menulis kode sungguhan. Episode 3 ini adalah gerbang praktis: kita akan memilih jenis klien yang sesuai kebutuhan, memahami perbedaan setiap jenisnya, lalu membuat collection pertama dengan konfigurasi yang benar.

Satu konsep akan berulang terus: hampir semua operasi dimulai dari klien. Klien menentukan ke mana ChromaDB berbicara — ke memori, ke direktori lokal, atau ke server HTTP. Pilihan ini sepele di development, tapi krusial di production. Mari kita bedah satu per satu.

#Jenis-Jenis Klien ChromaDB

#chromadb.Client: Default yang Fleksibel

Fungsi paling sederhana, chromadb.Client(), otomatis memilih mode berdasarkan environment. Jika tidak ada konfigurasi server, dia berperilaku sebagai klien embedded in-memory:

Klien default

import chromadb
 
client = chromadb.Client()

Klien ini praktis untuk eksperimen cepat. chromadb.Client() memakai sistem settings bawaan — nanti di episode 12 kita akan lihat bagaimana ia bisa dialihkan ke mode client-server dengan variabel environment.

#PersistentClient: Data yang Bertahan

PersistentClient adalah kakak dari klien default: semua data disimpan ke disk, sehingga tetap ada setelah proses berakhir. Ini pilihan utama untuk development jangka panjang dan aplikasi embedded single-process.

Klien persisten

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

Satu-satunya perbedaan dengan chromadb.Client() adalah argumen path, yang menentukan folder penyimpanan. PersistentClient(path="./data-chroma") akan membuat folder ./data-chroma secara otomatis saat collection pertama dibuat.

#EphemeralClient: Untuk Test

EphemeralClient persis seperti chromadb.Client() in-memory, tapi dibuat eksplisit. Semua data hilang saat proses selesai. Ini sempurna untuk unit test yang harus bersih dari data lama:

Klien ephemeral untuk test

client = chromadb.EphemeralClient()

#HttpClient: Terhubung ke Server

HttpClient menghubungkan klien ke server ChromaDB yang berjalan terpisah. Ini mode yang akan kalian pakai di production:

Klien HTTP

client = chromadb.HttpClient(host="localhost", port=8000)

Pastikan server sudah jalan sebelum memanggil kode di atas. chromadb.HttpClient(host="localhost", port=8000) mengirim semua operasi lewat HTTP ke server — detail lengkap mode ini akan kita bahas di episode 12.

#Membuat Collection Pertama

#create_collection dengan Parameter Dasar

Semua jenis klien di atas berbagi API yang sama untuk collection. Membuat collection pertama:

Membuat collection pertama

client = chromadb.PersistentClient(path="./data-chroma")
 
collection = client.create_collection(
    name="artikel-tech",
    metadata={"hnsw:space": "cosine"},
)

Argumen metadata pada create_collection(name="artikel-tech", metadata={"hnsw:space": "cosine"}) bukan sekadar hiasan: di sini kita mengatur distance function yang dipakai index. Nilai hnsw:space: cosine akan kita bedah lengkap di episode 9.

#get_collection: Mengambil yang Sudah Ada

Memanggil create_collection dua kali dengan nama yang sama akan error. Untuk mengambil collection yang sudah ada, gunakan get_collection:

Mengambil collection yang ada

collection = client.get_collection(name="artikel-tech")

Pola yang direkomendasikan: coba get dulu, create jika belum ada. Karena embedded embedding function disimpan di dalam collection, nama dan pengaturan embedding function harus konsisten antara create dan get.

#Embedding Function Default

Setiap collection punya embedding function. Jika tidak ditentukan, ChromaDB memakai DefaultEmbeddingFunction berbasis model ONNX MiniLM yang berjalan lokal — tanpa API key, tanpa internet. Ini alasan ChromaDB begitu mudah dipakai di episode 0.

Melihat embedding function

collection = client.create_collection(
    name="artikel-tech",
    embedding_function=chromadb.utils.embedding_functions.DefaultEmbeddingFunction(),
)

Untuk sebagian besar series ini, default sudah cukup. Embedding function ini menghasilkan vektor 384 dimensi. Saat kalian butuh kualitas lebih tinggi atau dimensi berbeda — misalnya dari OpenAI atau sentence-transformers — episode 6 akan memandu penggantiannya.

#Menambah Data Pertama dan Menampilkan Isi

Setelah collection berdiri, mari kita isi dan periksa:

Menambah dan melihat data

collection.add(
    ids=["a1", "a2"],
    documents=[
        "Docker mempermudah deploy aplikasi",
        "Kubernetes mengatur banyak container",
    ],
    metadatas=[{"topik": "devops"}, {"topik": "devops"}],
)
 
jumlah = collection.count()
print(jumlah)

Panggilan collection.count() mengembalikan jumlah item di collection — seharusnya menampilkan 2. Perhatikan bahwa embeddings tidak perlu diberikan karena dibangkitkan dari documents.

Untuk melihat isi lengkap:

Melihat semua dokumen

semua = collection.get()
print(semua["documents"])

collection.get() mengembalikan semua ids, documents, dan metadatas dalam bentuk dict — struktur ini akan sangat sering kita pakai di episode 4.

#Penutup

Episode 3 menandai dimulainya bagian praktis series ini. Kalian sekarang tahu empat jenis klien (Client, PersistentClient, EphemeralClient, HttpClient), cara membuat dan mengambil collection, pengaturan distance function lewat metadata, serta peran embedding function default berbasis ONNX MiniLM.

Inti yang harus dibawa pulang:

• Klien menentukan target: memori, disk, atau server HTTP.
• PersistentClient untuk development; HttpClient untuk production.
• create_collection error jika nama sudah ada; get_collection untuk mengambilnya.
• Metadata collection seperti hnsw:space mengatur perilaku index.
• Embedding function default berjalan lokal tanpa API key.
• collection.count() dan collection.get() adalah alat inspeksi dasar.

Di episode 4 selanjutnya kita akan membahas CRUD dasar — seluruh operasi manipulasi data: add, get, update, upsert, delete, count, dan modify, beserta kombinasi ids, documents, metadatas, dan embeddings yang bisa disimpan sekaligus. Koleksi pertama kalian sudah siap untuk diisi.