Mengelola indeks di Cloud Firestore

Cloud Firestore memastikan performa kueri dengan mewajibkan indeks untuk setiap kueri. Indeks yang diperlukan untuk kueri paling dasar dibuat otomatis untuk Anda. Saat Anda menggunakan dan menguji aplikasi, Cloud Firestore membuat pesan error yang membantu Anda membuat indeks tambahan yang dibutuhkan aplikasi. Halaman ini menjelaskan cara mengelola indeks kolom tunggal dan gabungan.

Membuat indeks yang hilang melalui pesan error

Jika Anda mencoba kueri gabungan dengan klausa rentang yang tidak memetakan ke indeks yang ada, Anda akan menerima error. Pesan error menyertakan link langsung untuk membuat indeks yang tidak ada di Firebase console.

Ikuti link yang dihasilkan untuk membuka Firebase console, tinjau info yang terisi secara otomatis, lalu klik Buat.

Peran dan izin

Sebelum dapat membuat indeks di Cloud Firestore, pastikan Anda ditunjuk untuk salah satu peran berikut:

  • roles/datastore.owner
  • roles/datastore.indexAdmin
  • roles/editor
  • roles/owner

Jika Anda telah menentukan peran khusus, tetapkan semua izin berikut untuk membuat indeks:

  • datastore.indexes.create
  • datastore.indexes.delete
  • datastore.indexes.get
  • datastore.indexes.list
  • datastore.indexes.update

Menggunakan Firebase console

Untuk membuat indeks baru secara manual dari Firebase console:

gambar antarmuka pengindeksan firestore di firebase console

  1. Buka bagian Cloud Firestore di Firebase console.
  2. Buka tab Indeks dan klik Tambahkan Indeks.
  3. Masukkan nama koleksi dan tetapkan kolom yang ingin Anda urutkan indeksnya.
  4. Klik Create.

Kolom indeks harus sesuai dengan batasan pada jalur kolom.

Pembuatan indeks bisa membutuhkan waktu beberapa menit, tergantung pada ukuran kueri. Setelah membuatnya, Anda dapat melihat indeks dan statusnya di bagian Indeks Gabungan. Jika indeks masih dibuat, Firebase console akan menyertakan status bar pembuatan.

Menghapus indeks

Untuk menghapus indeks:

  1. Buka bagian Cloud Firestore di Firebase console.
  2. Klik tab Indeks.
  3. Arahkan kursor ke indeks yang ingin Anda hapus dan pilih Hapus dari menu konteks.
  4. Konfirmasi bahwa Anda ingin menghapusnya dengan mengklik Hapus dari pemberitahuan.

Menggunakan Firebase CLI

Anda juga dapat men-deploy indeks dengan Firebase CLI. Untuk memulai, jalankan firebase init firestore di direktori project Anda. Selama penyiapan, Firebase CLI menghasilkan file JSON dengan indeks default dalam format yang tepat. Edit file untuk menambahkan lebih banyak indeks dan men-deploynya dengan perintah firebase deploy.

Untuk hanya men-deploy indeks dan aturan Cloud Firestore, tambahkan flag --only firestore.

Jika mengedit indeks menggunakan Firebase console, pastikan Anda juga memperbarui file indeks lokal. Lihat referensi definisi indeks JSON.

Waktu build indeks

Untuk mem-build indeks, Cloud Firestore harus menyiapkan indeks, lalu mengisi ulang indeks dengan data yang ada. Waktu build indeks adalah jumlah waktu penyiapan dan waktu pengisian ulang:

  • Menyiapkan indeks memerlukan waktu beberapa menit. Waktu build minimum untuk indeks adalah beberapa menit, meskipun untuk database yang kosong.

  • Waktu pengisian ulang bergantung pada jumlah data yang ada dalam indeks baru. Semakin banyak nilai kolom yang cocok dengan definisi indeks, semakin lama waktu yang diperlukan untuk mengisi ulang indeks.

Build indeks merupakan operasi yang berjalan lama.

Setelah Anda memulai build indeks, Cloud Firestore akan menetapkan nama unik untuk operasi tersebut. Nama operasi diawali dengan projects/[PROJECT_ID]/databases/(default)/operations/, misalnya:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Namun, Anda dapat tidak menyertakan awalan saat menentukan nama operasi untuk perintah describe.

Mencantumkan semua operasi yang berjalan lama

Untuk mencantumkan operasi yang berjalan lama, gunakan perintah gcloud firestore operations list. Perintah ini mencantumkan operasi yang sedang berlangsung dan yang baru saja selesai. Operasi tercantum selama beberapa hari setelah selesai:

gcloud firestore operations list

Memeriksa status operasi

Alih-alih mencantumkan semua operasi yang berjalan lama, Anda dapat mencantumkan detail satu operasi:

gcloud firestore operations describe operation-name

Memperkirakan waktu penyelesaian

Saat operasi berjalan, lihat nilai kolom state untuk mengetahui status operasi secara keseluruhan.

Permintaan untuk status operasi yang berjalan lama juga menampilkan metrik workEstimated dan workCompleted. Metrik ini ditampilkan untuk sejumlah dokumen. workEstimated menunjukkan perkiraan jumlah total dokumen yang akan diproses dalam operasi. workCompleted menunjukkan jumlah dokumen yang diproses sejauh ini. Setelah operasi selesai, workCompleted mencerminkan jumlah total dokumen yang sebenarnya diproses yang mungkin berbeda dari nilai workEstimated.

Bagilah workCompleted dengan workEstimated untuk mengetahui perkiraan kasar dari progresnya. Perkiraan ini mungkin tidak akurat karena tergantung pada pengumpulan statistik yang tertunda.

Misalnya, berikut adalah status progres dari suatu build indeks:

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.firestore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressDocuments": {
          "workCompleted": "219327",
          "workEstimated": "2198182"
        }
       },
    },
    ...

Saat operasi selesai, deskripsi operasi akan berisi "done": true. Lihat nilai kolom state untuk menemukan hasil operasi. Jika kolom done tidak ditetapkan dalam respons, maka nilainya adalah false. Jangan bergantung pada keberadaan nilai done untuk operasi yang sedang berlangsung.

Error dalam mem-build indeks

Anda mungkin mengalami error dalam mem-build indeks saat mengelola indeks gabungan dan pengecualian indeks satu kolom. Operasi pengindeksan dapat gagal jika Cloud Firestore menemukan masalah dengan data yang diindeks. Biasanya, ini berarti Anda mencapai batas indeks. Misalnya, operasi mungkin telah mencapai jumlah entri indeks maksimum per dokumen.

Jika pembuatan indeks gagal, Anda melihat pesan error di konsol. Setelah memverifikasi bahwa Anda tidak mencapai batas indeks, coba lagi operasi indeks.