Pola Qdrant

Qdrant adalah mesin pencari vektor khusus yang dirancang di sekitar satu tipe data, yaitu vektor yang disertai metadata. Topik ini memperkenalkan pola data Qdrant versi 1.x, mulai dari collection sebagai wadah utama, payload sebagai metadata, indeks payload yang mempercepat filter, hingga pencarian terfilter yang memadukan keduanya. Seluruh contoh menggunakan klien resmi Python dan tidak dijalankan karena server Qdrant tidak tersedia di sandbox.

Collection sebagai unit utama#

Collection adalah wadah utama pada Qdrant dan sejajar dengan tabel pada basis data relasional. Versi terkini Qdrant adalah 1.20 pada Oktober 2026, dan pola data yang dibahas di sini berlaku untuk lini 1.x. Satu collection menyimpan kumpulan point, yakni satu entri data berisi id, vektor, dan payload, dengan dimensi vektor dan metrik jarak yang sama untuk seluruh isinya. Nilai keduanya ditetapkan saat collection dibuat dan menjadi bagian dari skemanya, sehingga vektor dari dua model embedding yang berbeda tidak boleh digabungkan ke dalam satu collection.

Collection dibuat dengan metode create_collection. Pada contoh berikut, nama collection-nya adalah docs, dimensi vektornya 384, dan metrik jaraknya cosine.

# tidak-dijalankan
from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="docs",
    vectors_config=models.VectorParams(size=384, distance=models.Distance.COSINE),
)

Parameter size=384 mengikuti dimensi model embedding yang dipilih, misalnya all-MiniLM-L6-v2 yang menghasilkan 384 dimensi, sedangkan distance menetapkan cara vektor dibandingkan. Pilihan metriknya adalah Distance.COSINE untuk kesamaan arah, Distance.EUCLID untuk jarak L2, dan Distance.DOT untuk perkalian titik. Metrik harus disesuaikan dengan cara pelatihan model embedding, karena metrik yang tidak cocok membuat peringkat hasil tidak bermakna. Di balik collection tersebut, Qdrant membangun indeks HNSW untuk pencarian, sehingga pencariannya bersifat aproksimatif sebagaimana indeks ANN pada umumnya.

Collection bersifat mandiri satu sama lain. Membuat collection baru, menghapusnya, atau mengganti isinya tidak mengubah collection lain pada server yang sama, sehingga setiap jenis arsip dapat dipisahkan ke dalam collection tersendiri. Penamaan yang konsisten memudahkan operasi harian, misalnya docs untuk arsip dokumen umum dan collection terpisah untuk kelompok data yang siklus hidupnya berbeda. Penghapusan collection menghilangkan seluruh point beserta indeksnya sekaligus, sehingga operasi ini perlu disertai kepastian sebelum dijalankan.

Payload dan indeks payload#

Payload adalah metadata yang menemani setiap point, misalnya kategori dokumen, tanggal unggah, atau penulisnya. Vektor menjawab pertanyaan makna, sedangkan payload menyimpan fakta terstruktur yang tetap diperlukan setelah dokumen berubah menjadi embedding. Pencarian kemiripan kemudian dapat dibatasi berdasarkan nilai payload tersebut, misalnya hanya dokumen berkategori panduan yang disertakan.

Data ditulis dengan upsert, yaitu menambah point baru atau memperbarui point dengan id yang sudah ada. Payload berisi nilai kategori seperti pada contoh, lalu diindeks dengan create_payload_index menggunakan KeywordIndexType.KEYWORD, sehingga nilai kategori membentuk indeks tersendiri di samping indeks vektornya.

# tidak-dijalankan
client.upsert(
    collection_name="docs",
    points=[
        models.PointStruct(id=1, vector=[...], payload={"kategori": "panduan"}),
        models.PointStruct(id=2, vector=[...], payload={"kategori": "arsip"}),
    ],
)

client.create_payload_index(
    collection_name="docs",
    field_name="kategori",
    field_schema=models.KeywordIndexType.KEYWORD,
)

Indeks payload bekerja serupa dengan indeks kolom pada basis data relasional, yaitu mempercepat filter karena titik yang memenuhi sebuah nilai kategori ditemukan tanpa memeriksa payload titik demi titik. Payload yang belum diindeks tetap tersimpan dan tetap dapat difilter, tetapi kecepatannya menurun pada collection besar.

Nilai payload dapat berupa teks, angka, atau daftar nilai, dan tiap point boleh membawa field yang berbeda-beda karena payload disimpan sebagai struktur bebas di samping vektornya. Indeks payload baru berguna setelah field yang sering menjadi syarat filter diketahui, sehingga praktik yang lazim adalah mengamati pola filter terlebih dahulu, lalu mengindeks field yang benar-benar digunakan.

Pencarian terfilter#

Satu permintaan pencarian dapat menyertakan vektor query, filter payload, dan parameter pencarian sekaligus. Metode query_points menerima ketiganya dalam satu pemanggilan, sehingga pembatasan kategori dan pencarian kemiripan berjalan sebagai satu operasi, bukan dua langkah berurutan yang disusun di sisi aplikasi.

# tidak-dijalankan
hasil = client.query_points(
    collection_name="docs",
    query=[...],
    query_filter=models.Filter(
        must=[models.FieldCondition(key="kategori", match=models.MatchValue(value="panduan"))]
    ),
    search_params=models.SearchParams(hnsw_ef=128, exact=False),
    limit=3,
)

Filter must menyatakan syarat yang wajib dipenuhi, yaitu payload kategori bernilai panduan, dan limit=3 meminta tiga hasil teratas. Yang menentukan kualitas hasil adalah tempat filter itu diterapkan. Qdrant memindahkan filter ke dalam traversal HNSW, yaitu kandidat yang tidak memenuhi filter dilewati selama pencarian berlangsung, sehingga hasil yang dikembalikan semuanya memenuhi syarat. Pola ini disebut filtered search.

Diagram berikut merangkum alur satu permintaan pencarian terfilter, dari query beserta filternya menuju hasil yang lolos.

Parameter search_params mengatur perilaku pencariannya. Nilai hnsw_ef=128 memperluas kumpulan kandidat yang dikunjungi selama traversal HNSW, sehingga recall naik dengan biaya latensi yang lebih besar, sedangkan exact=False membiarkan pencarian tetap aproksimatif. Apabila hasil terfilter harus dijamin akurat, SearchParams(exact=True) memaksa pencarian eksak yang membandingkan query dengan seluruh kandidat yang memenuhi filter. Hasil query_points berupa daftar point dengan id, skor kemiripan, dan payload yang tersimpan, sehingga aplikasi dapat menampilkan metadata tanpa pencarian tambahan, dan skor yang lebih tinggi berarti lebih dekat dengan query pada metrik yang dipilih.

Ringkasan#

• Collection menyimpan point berisi id, vektor, dan payload, dengan dimensi dan metrik yang dikunci saat collection dibuat.
• Payload diindeks melalui create_payload_index sehingga filter pada collection besar tidak memeriksa payload titik demi titik.
• Pencarian terfilter pada Qdrant menerapkan filter di dalam traversal HNSW, dengan SearchParams(exact=True) sebagai jalan menuju hasil eksak.

Referensi#

• Dokumentasi Qdrant — Qdrant — Dokumentasi resmi Qdrant yang memuat konsep collection, payload, dan indeks payload.
• Konsep pencarian — Qdrant — Halaman konsep pencarian Qdrant yang menjelaskan query_points, filter, dan parameter pencariannya.