Keyspace

Keyspace adalah namespace atau grup terisolasi tempat enrollment wajah disimpan di FREMIS-N. Analoginya seperti folder atau tenant yang terpisah: enrollment di keyspace A sama sekali tidak bercampur dengan keyspace B, bahkan jika keduanya berjalan di instansi FREMIS-N yang sama.

---

Apa itu Keyspace

Keyspace adalah unit isolasi logis di FREMIS-N. Setiap keyspace memiliki namespace unik yang membatasi ruang lingkup penyimpanan dan pencarian. Ketika Anda melakukan enrollment, vektor wajah disimpan di dalam keyspace yang Anda tentukan. Ketika Anda melakukan recognition atau search, pencarian hanya menjangkau enrollment yang ada di keyspace target — tidak ada "kebocoran" data antar keyspace.

Secara internal, setiap keyspace mendapatkan ID numerik unik yang digunakan untuk mengelompokkan enrollment di PostgreSQL dan dalam indeks FAISS. Dalam mode cluster, data keyspace dapat tersebar di beberapa worker node sesuai partisi — namun dari perspektif API, keyspace tetap terlihat sebagai satu namespace yang utuh.

---

Use Case

Multi-Tenant

Jika Anda mengelola FREMIS-N untuk beberapa klien atau organisasi dalam satu deployment, buat satu keyspace per klien. Data antar klien sepenuhnya terisolasi — klien A tidak bisa "melihat" atau berinterferensi dengan enrollment klien B.

Multi-Departemen

Dalam satu organisasi, departemen yang berbeda bisa memiliki database wajah yang berbeda. Contoh:

• keyspace: hr_employees — untuk absensi karyawan
• keyspace: security_watchlist — untuk monitoring keamanan
• keyspace: vip_guests — untuk identifikasi tamu VIP

Environment Terpisah (Dev / Staging / Prod)

Gunakan keyspace berbeda untuk tiap environment sehingga data pengujian tidak mencemari data produksi:

• keyspace: prod_employees
• keyspace: staging_employees
• keyspace: dev_test

Watchlist Berbeda per Gedung atau Zona

Untuk deployment multi-lokasi, buat keyspace per gedung atau per zona akses. Kamera di Gedung A hanya mencari di keyspace gedung A; kamera di Gedung B di keyspace gedung B.

---

Isolasi Data

Isolasi keyspace bersifat penuh:

• Enrollment yang didaftarkan ke keyspace: gedung_a tidak terlihat dari keyspace: gedung_b.
• Operasi delete pada satu keyspace tidak memengaruhi keyspace lain.
• Menghapus sebuah keyspace menghapus semua enrollment di dalamnya secara permanen — operasi ini tidak dapat diurungkan.

---

Implikasi Search dan Match

Parameter keyspace pada endpoint recognition dan enrollment menentukan ruang lingkup operasi:

• Enrollment — vektor wajah disimpan ke dalam keyspace yang ditentukan.
• Recognition (1:N) — pencarian hanya dilakukan terhadap enrollment yang ada di keyspace yang ditentukan. Anda tidak bisa melakukan pencarian lintas keyspace dalam satu permintaan.
• Match (1:1) — tidak bergantung pada keyspace karena membandingkan dua gambar atau embedding secara langsung tanpa mengakses database.

Jika keyspace yang ditentukan tidak ada, permintaan enrollment atau recognition akan ditolak. Selalu buat keyspace terlebih dahulu sebelum melakukan enrollment.

---

Lifecycle Keyspace

1. Create — Buat keyspace baru sebelum melakukan enrollment apa pun.
2. Enroll — Daftarkan identitas wajah ke dalam keyspace. Lihat Enrollment untuk panduan lengkap.
3. Query — Gunakan keyspace sebagai parameter saat melakukan recognition atau inspeksi data.
4. Delete — Hapus keyspace beserta seluruh datanya jika sudah tidak diperlukan.

---

Limit dan Kuota Lisensi

Jumlah keyspace dan total enrollment di seluruh keyspace dibatasi oleh lisensi FREMIS-N yang aktif. Ketika batas enrollment tercapai, permintaan enrollment baru akan ditolak sampai sebagian enrollment dihapus atau lisensi ditingkatkan.

Untuk melihat penggunaan kuota saat ini, gunakan endpoint /v1/get-limit-usage atau pantau melalui halaman Quota & License Management.

---

Hubungan dengan Cluster Sharding

Dalam mode standalone, semua data keyspace disimpan dalam satu node. Dalam mode cluster, data setiap keyspace dapat tersebar (sharding) ke beberapa worker node berdasarkan partisi. Coordinator mengetahui pemetaan partisi dan mengarahkan permintaan ke worker yang tepat.

Dari perspektif API dan pengembang, keyspace tetap berfungsi sebagai satu namespace yang utuh — Anda tidak perlu mengetahui di worker mana data disimpan. Namun perlu dipahami bahwa operasi yang mencakup seluruh keyspace (seperti menghitung total vektor atau mendapatkan daftar enrollment) akan dikumpulkan dari semua worker yang relevan.

Untuk memahami bagaimana cluster sharding bekerja secara lebih mendalam, lihat Cluster Sharding.

---

Operasi Pendukung

Selain operasi CRUD utama, FREMIS-N menyediakan beberapa endpoint utilitas untuk inspeksi keyspace:

---

Selanjutnya