Buka konsol

Jenis indeks di Cloud Firestore

Indeks merupakan faktor penting dalam performa database. Hampir sama seperti indeks buku yang memetakan topik dalam sebuah buku ke nomor halaman, indeks database memetakan item dalam database ke masing-masing lokasinya di dalam database. Saat kueri dikirim ke database, database dapat menggunakan indeks untuk dengan cepat menemukan lokasi item yang diminta.

Halaman ini berisi penjelasan mengenai dua jenis indeks yang digunakan Cloud Firestore, yaitu indeks kolom tunggal dan indeks gabungan.

Indeks di balik setiap kueri

Jika tidak ada indeks untuk sebuah kueri, kebanyakan database akan meng-crawl kontennya item demi item. Proses ini berjalan lambat dan akan semakin lambat seiring bertambahnya ukuran database. Cloud Firestore menjamin peningkatan performa kueri dengan menggunakan indeks untuk semua kueri. Hasilnya, performa kueri bergantung pada ukuran kumpulan hasil, dan bukan pada jumlah item dalam database.

Semakin sedikit pengelolaan indeks, semakin banyak pengembangan aplikasi

Cloud Firestore menyertakan fitur yang dapat mengurangi waktu yang diperlukan untuk mengelola indeks. Indeks yang diperlukan untuk kueri paling dasar dibuat otomatis untuk Anda. Saat Anda menggunakan dan menguji aplikasi, Cloud Firestore membantu Anda mengidentifikasi dan membuat indeks tambahan yang diperlukan aplikasi.

Jenis indeks

Cloud Firestore menggunakan dua jenis indeks, yaitu kolom tunggal dan gabungan. Selain jumlah kolom yang diindeks, cara pengelolaan kolom tunggal dan gabungan juga berbeda.

Indeks kolom tunggal

Indeks kolom tunggal menyimpan pemetaan yang diurutkan dari semua dokumen dalam koleksi yang berisi kolom tertentu. Setiap entri pada indeks kolom tunggal mencatat nilai dokumen untuk kolom tertentu dan lokasi dokumen tersebut di database. Cloud Firestore menggunakan indeks ini untuk menjalankan banyak kueri dasar. Anda dapat mengelola indeks kolom tunggal dengan mengonfigurasi setelan pengindeksan otomatis dan pengecualian indeks database Anda.

Pengindeksan otomatis

Secara default, Cloud Firestore otomatis mempertahankan indeks kolom tunggal untuk setiap kolom dalam dokumen dan setiap subkolom dalam peta. Cloud Firestore menggunakan setelan default berikut untuk indeks kolom tunggal:

  • Untuk setiap kolom bukan array dan bukan peta, Cloud Firestore menentukan dua indeks kolom tunggal dengan cakupan koleksi, satu dalam mode menaik dan satu dalam mode menurun.

  • Untuk setiap kolom peta, Cloud Firestore membuat satu indeks menaik dan satu indeks menurun dengan cakupan koleksi untuk setiap subkolom bukan array dan bukan peta dalam peta.

  • Untuk setiap kolom array dalam dokumen, Cloud Firestore membuat dan mempertahankan indeks yang dimuat di array dengan cakupan koleksi.

  • Indeks kolom tunggal dengan cakupan grup koleksi tidak dipertahankan secara default.

Pengecualian indeks kolom tunggal

Anda bisa mengecualikan kolom dari setelan pengindeksan otomatis dengan membuat pengecualian indeks kolom tunggal. Pengecualian pengindeksan mengganti setelan indeks otomatis di seluruh database. Pengecualian dapat mengaktifkan indeks kolom tunggal yang sebaliknya akan dinonaktifkan oleh setelan pengindeksan otomatis. Selain itu, pengecualian juga dapat menonaktifkan indeks kolom tunggal yang sebaliknya akan diaktifkan oleh pengindeksan otomatis. Untuk kasus ketika pengecualian dapat berguna, baca praktik terbaik pengindeksan.

Jika Anda membuat pengecualian indeks kolom tunggal untuk kolom peta, maka subkolom peta akan mewarisi setelan tersebut. Namun, Anda dapat menentukan pengecualian indeks kolom tunggal untuk subkolom tertentu. Jika Anda menghapus pengecualian untuk suatu subkolom, maka subkolom tersebut akan mewarisi setelan pengecualian indukya, jika ada, atau setelan seluruh database jika tidak ada pengecualian induk.

Untuk membuat dan mengelola pengecualian indeks kolom tunggal, baca bagian Mengelola Indeks di Cloud Firestore.

Indeks gabungan

Indeks gabungan menyimpan pemetaan yang diurutkan dari semua dokumen dalam koleksi yang berisi beberapa kolom tertentu, bukan hanya satu.

Cloud Firestore menggunakan indeks gabungan untuk mendukung kueri yang belum didukung oleh indeks kolom tunggal.

Cloud Firestore tidak membuat indeks gabungan secara otomatis seperti yang dilakukannya pada indeks kolom tunggal karena banyaknya kemungkinan kombinasi kolom. Sebagai gantinya, Cloud Firestore membantu Anda mengidentifikasi dan membuat kueri gabungan yang diperlukan saat Anda membuat aplikasi.

Jika Anda mencoba kueri di atas tanpa terlebih dahulu membuat indeks yang diperlukan, Cloud Firestore akan menampilkan pesan error yang berisi link yang bisa Anda ikuti untuk membuat indeks yang tidak ada. Ini terjadi setiap kali Anda mencoba kueri yang tidak didukung oleh sebuah indeks. Anda juga dapat menentukan dan mengelola indeks gabungan secara manual menggunakan konsol atau Firebase CLI.Untuk mengetahui informasi lebih lanjut mengenai cara membuat dan mengelola indeks gabungan, Mengelola Indeks.

Mode indeks dan cakupan kueri

Anda mengonfigurasi indeks kolom tunggal dan gabungan secara berbeda, tetapi keduanya mengharuskan Anda mengonfigurasi mode indeks dan cakupan kueri untuk indeks Anda.

Mode indeks

Saat Anda menentukan indeks, pilih mode indeks untuk setiap kolom yang diindeks. Mode indeks setiap kolom mendukung klausa kueri tertentu pada kolom tersebut. Anda dapat memilih dari mode indeks berikut:

Mode indeks Deskripsi
Menaik arrow_upward Mendukung klausa kueri <, <=, ==, >=, dan > pada kolom dan mendukung pengurutan hasil secara menaik berdasarkan nilai kolom ini.
Menurun arrow_downward Mendukung klausa kueri <, <=, ==, >=, dan > pada kolom dan mendukung pengurutan hasil secara menurun berdasarkan nilai kolom ini.
Dimuat di array Mendukung klausa kueri array_contains pada kolom.

Cakupan kueri

Setiap indeks dicakup untuk koleksi maupun grup koleksi. Hal ini dikenal sebagai cakupan kueri indeks:

Cakupan koleksi
Cloud Firestore membuat indeks dengan cakupan koleksi secara default. Indeks ini mendukung kueri yang menampilkan hasil dari satu koleksi.

Cakupan grup koleksi
Grup koleksi mencakup semua koleksi dengan ID koleksi yang sama. Untuk menjalankan kueri grup koleksi yang menampilkan hasil yang difilter atau diurutkan dari grup koleksi, Anda harus membuat indeks yang sesuai dengan cakupan grup koleksi.

Contoh pengindeksan

Dengan membuat indeks kolom tunggal untuk Anda secara otomatis, Cloud Firestore memungkinkan aplikasi Anda untuk mendukung kueri database yang paling dasar dengan cepat. Dengan indeks kolom tunggal, Anda dapat menjalankan kueri sederhana berdasarkan nilai kolom dan pembanding <, <=, ==, >=, dan >. Untuk kolom array, Anda dapat menjalankan kueri array_contains.

Sebagai ilustrasi, periksa contoh berikut ini dari perspektif pembuatan indeks. Cuplikan berikut membuat beberapa dokumen city dalam koleksi cities dan menetapkan kolom name, state, country, capital, population, dan tags untuk setiap dokumen:

Web
var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000,
    regions: ["west_coast", "norcal"] });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000,
    regions: ["west_coast", "socal"] });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000,
    regions: ["east_coast"] });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000,
    regions: ["kanto", "honshu"] });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000,
    regions: ["jingjinji", "hebei"] });

Dengan asumsi setelan pengindeksan otomatis adalah default, Cloud Firestore memperbarui satu indeks kolom tunggal menaik per kolom bukan array, satu indeks kolom tunggal menurun per kolom bukan array, dan satu indeks kolom tunggal yang dimuat di array untuk kolom array. Setiap baris dalam tabel berikut mewakili entri dalam indeks kolom tunggal:

Koleksi Kolom yang diindeks Cakupan kueri
cities arrow_upward name Koleksi
cities arrow_upward state Koleksi
cities arrow_upward country Koleksi
cities arrow_upward capital Koleksi
cities arrow_upward population Koleksi
cities arrow_downward name Koleksi
cities arrow_downward state Koleksi
cities arrow_downward country Koleksi
cities arrow_downward capital Koleksi
cities arrow_downward population Koleksi
cities array-contains regions Koleksi

Kueri yang didukung oleh indeks kolom tunggal

Dengan menggunakan indeks kolom tunggal yang dibuat secara otomatis ini, Anda dapat menjalankan kueri sederhana seperti berikut ini:

Web
citiesRef.where("state", "==", "CA")
citiesRef.where("population", "<", 100000)
citiesRef.where("name", ">=", "San Francisco")

Indeks array_contains memungkinkan Anda mengirim kueri pada kolom array regions

Web
citiesRef.where("regions", "array-contains", "west_coast")

Anda juga dapat membuat kueri gabungan berdasarkan kesetaraan (==):

Web
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("country", "==", "USA").where("capital", "==", false).where("state", "==", "CA").where("population", "==", 860000)

Jika Anda perlu menjalankan kueri gabungan yang menggunakan perbandingan rentang (<, <=, >, atau >=) atau jika Anda perlu melakukan pengurutan berdasarkan kolom yang berbeda, Anda harus membuat indeks gabungan untuk kueri tersebut.

Kueri yang didukung oleh indeks gabungan

Cloud Firestore menggunakan indeks gabungan untuk mendukung kueri gabungan yang belum didukung oleh indeks kolom tunggal. Misalnya, Anda memerlukan indeks gabungan untuk kueri berikut:

Web
citiesRef.where("country", "==", "USA").orderBy("population", "asc")
citiesRef.where("country", "==", "USA").where("population", "<", 3800000)
citiesRef.where("country", "==", "USA").where("population", ">", 690000)

Kueri ini memerlukan indeks gabungan di bawah. Perhatikan bahwa karena kueri menggunakan kesetaraan untuk kolom country, mode indeks kolom dapat menaik atau menurun. Secara default, kueri ketidaksetaraan akan menerapkan pengurutan menaik untuk kolom dalam klausa ketidaksetaraan.

Koleksi Kolom yang diindeks Cakupan kueri
cities arrow_upward (atau arrow_downward) country, arrow_upward population Koleksi

Jika ingin menjalankan kueri yang sama tetapi dengan pengurutan menurun, Anda memerlukan indeks gabungan tambahan dalam arah menurun untuk population:

Web
citiesRef.where("country", "==", "USA").orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", "<", 3800000)
         .orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", ">", 690000)
         .orderBy("population", "desc")
Koleksi Kolom yang diindeks Cakupan kueri
cities arrow_upward country, arrow_upward population Koleksi
cities arrow_upward country, arrow_downward population Koleksi

Anda juga harus membuat indeks gabungan jika ingin menggabungkan kueri array_contains dengan klausa tambahan.

Web
citiesRef.where("regions", "array_contains", "east_coast")
         .where("capital", "==", true)
Koleksi Kolom yang diindeks Cakupan kueri
cities tag array-contains, arrow_upward (atau arrow_downward) capital Koleksi

Kueri yang didukung oleh indeks grup koleksi

Untuk menunjukkan indeks dengan cakupan grup koleksi, bayangkan Anda menambahkan sub-koleksi landmarks ke beberapa dokumen city:

Web
var citiesRef = db.collection("cities");

citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Bridge",
    category : "bridge" });
citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Park",
    category : "park" });

citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Gallery of Art",
    category : "museum" });
citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Mall",
    category : "park" });

Dengan menggunakan indeks kolom tunggal dengan cakupan koleksi berikut, Anda dapat membuat kueri untuk lokasi terkenal park dalam satu kota:

Koleksi Kolom yang diindeks Cakupan kueri
landmark arrow_upward (atau arrow_downward) category Koleksi
Web
citiesRef.doc("SF").collection("landmarks").where("category", "==", "park")

Sekarang, bayangkan Anda tertarik dengan lokasi terkenal park di semua kota. Untuk menjalankan kueri ini pada grup koleksi yang terdiri dari semua koleksi landmarks, Anda harus mengaktifkan indeks kolom tunggal landmarks dengan cakupan grup koleksi:

Koleksi Kolom yang diindeks Cakupan kueri
landmark arrow_upward (atau arrow_downward) category Grup koleksi

Dengan mengaktifkan indeks ini, Anda dapat membuat kueri grup koleksi landmarks:

Web
var landmarksGroupRef = db.collectionGroup("landmarks");

landmarksGroupRef.where("category", "==", "park")

Untuk menjalankan kueri grup koleksi yang menampilkan hasil yang difilter atau diurutkan, Anda harus mengaktifkan indeks kolom tunggal atau gabungan yang sesuai dengan cakupan grup koleksi. Namun, kueri grup koleksi yang tidak memfilter atau mengurutkan hasil tidak memerlukan definisi indeks tambahan.

Misalnya, Anda dapat menjalankan kueri grup koleksi berikut tanpa mengaktifkan indeks tambahan:

Web
db.collectionGroup("landmarks").get()

Indeks dan harga

Indeks berkontribusi pada biaya penyimpanan aplikasi. Untuk mengetahui lebih lanjut tentang penghitungan ukuran penyimpanan untuk indeks, lihat Ukuran entri indeks.

Memanfaatkan penggabungan indeks

Meskipun menggunakan sebuah indeks untuk setiap kueri, Cloud Firestore tidak selalu memerlukan satu indeks per kueri. Untuk kueri dengan beberapa klausa kesetaraan (==) dan, secara opsional, klausa orderBy, Cloud Firestore dapat menggunakan ulang indeks yang ada. Cloud Firestore dapat menggabungkan indeks tersebut sehingga terbentuk filter kesetaraan sederhana untuk membuat indeks gabungan yang diperlukan untuk mengelola kueri kesetaraan yang lebih besar.

Anda dapat mengurangi biaya pengindeksan dengan mengidentifikasi situasi saat penggabungan indeks bisa dimanfaatkan. Misalnya, bayangkan koleksi restaurants untuk aplikasi pemberian rating restoran:

  • collections_bookmark restaurants

    • class burgerthyme

      name : "Burger Thyme"
      category : "burgers"
      city : "San Francisco"
      editors_pick : true
      star_rating : 4

Sekarang, bayangkan aplikasi ini menggunakan kueri seperti salah satu di bawah. Perhatikan bahwa aplikasi menggunakan kombinasi klausa kesetaraan untuk category, city, dan editors_pick sekaligus selalu mengurutkan star_rating secara menaik:

Web
db.collection("restaurants").where("category", "==", "burgers")
                            .orderBy("star_rating")

db.collection("restaurants").where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==" "San Francisco")
                            .where("editors_pick", "==", true )
                            .orderBy("star_rating")

Anda dapat membuat indeks untuk setiap kueri:

Koleksi Kolom yang diindeks Cakupan kueri
restaurants arrow_upward category, arrow_upward star_rating Koleksi
restaurants arrow_upward city, arrow_upward star_rating Koleksi
restaurants arrow_upward category, arrow_upward city, arrow_upward star_rating Koleksi
restaurants arrow_upward category, arrow_upward city, arrow_upward editors_pick, arrow_upward star_rating Koleksi

Sebagai solusi yang lebih baik, Anda dapat mengurangi jumlah indeks dengan memanfaatkan kemampuan Cloud Firestore dalam menggabungkan indeks untuk klausa kesetaraan:

Koleksi Kolom yang diindeks Cakupan kueri
restaurants arrow_upward category, arrow_upward star_rating Koleksi
restaurants arrow_upward city, arrow_upward star_rating Koleksi
restaurants arrow_upward editors_pick, arrow_upward star_rating Koleksi

Selain lebih kecil, kumpulan indeks ini juga mendukung kueri tambahan:

Web
db.collection("restaurants").where("editors_pick", "==", true)
                            .orderBy("star_rating")

Batas pengindeksan

Batasan berikut berlaku pada indeks. Untuk semua kuota dan batas, lihat Kuota dan Batas.

Batas Detail
Jumlah maksimum indeks gabungan untuk database 200
Jumlah maksimum pengecualian indeks kolom tunggal untuk database 200

Jumlah maksimum entri indeks untuk setiap dokumen

40.000

Jumlah entri indeks adalah jumlah dari hal berikut untuk dokumen:

  • Jumlah entri indeks kolom tunggal
  • Jumlah entri indeks gabungan
Ukuran maksimum entri indeks

7,5 KiB

Untuk melihat bagaimana Cloud Firestore menghitung ukuran entri indeks, lihat ukuran entri indeks.

Jumlah maksimum ukuran entri indeks pada dokumen

8 MiB

Ukuran total adalah jumlah dari hal berikut untuk dokumen:

  • Jumlah ukuran entri indeks kolom tunggal pada dokumen
  • Jumlah ukuran entri indeks gabungan pada dokumen
  • Ukuran maksimum nilai kolom yang diindeks

    1.500 byte

    Nilai kolom di atas 1.500 byte akan terpotong. Kueri yang mencakup nilai kolom terpotong dapat menampilkan hasil yang tidak konsisten.

    Praktik terbaik pengindeksan

    Untuk sebagian besar aplikasi, Anda dapat mengandalkan pengindeksan otomatis dan link pesan error untuk mengelola indeks Anda. Namun, Anda mungkin ingin menambahkan pengecualian kolom tunggal dalam kasus berikut:

    Kasus Deskripsi
    Kolom string berukuran lebar

    Jika Anda memiliki kolom string yang biasanya memuat nilai string yang panjang, yang tidak digunakan untuk mengirim kueri, Anda dapat menghemat biaya penyimpanan dengan mengecualikan kolom itu dari pengindeksan.

    Tingkat operasi tulis yang tinggi ke koleksi yang berisi dokumen dengan nilai berurutan

    Jika Anda mengindeks kolom yang naik atau turun secara berurutan di antara dokumen dalam koleksi, seperti stempel waktu, maka tingkat operasi tulis maksimum untuk koleksi itu adalah 500 per detik. Jika Anda tidak mengirim kueri berdasarkan kolom yang memuat nilai berurutan, Anda dapat mengecualikan kolom itu dari pengindeksan untuk mengabaikan batas ini.

    Dalam kasus penggunaan IoT dengan tingkat operasi tulis yang tinggi, misalnya, koleksi yang berisi dokumen dengan kolom stempel waktu mungkin akan mendekati batas 500 operasi tulis per detik.

    Kolom peta atau array berukuran lebar

    Kolom array atau peta berukuran lebar dapat mendekati batas entri indeks sebesar 20.000 per dokumen. Jika Anda tidak mengirim kueri berdasarkan kolom peta atau array berukuran lebar, sebaiknya Anda mengecualikannya dari pengindeksan.