Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

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, 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.

Makin sedikit pengelolaan indeks, makin 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, subkolom tersebut akan mewarisi setelan pengecualian induknya, 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 otomatis membuat indeks gabungan 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, baca bagian 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 Mendukung klausa kueri <, <=, ==, >=, dan> di kolom dan mendukung pengurutan hasil secara menaik berdasarkan nilai kolom ini.
    Menurun Mendukung klausa kueri <, <=, ==, >=, dan> di kolom dan mendukung pengurutan hasil secara menurun berdasarkan nilai kolom ini.
    Dimuat di array Mendukung klausa kueri array_contains di 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 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
    kota nama Koleksi
    kota negara bagian Koleksi
    kota negara Koleksi
    kota ibu kota Koleksi
    kota populasi Koleksi
    kota nama Koleksi
    kota negara bagian Koleksi
    kota negara Koleksi
    kota ibu kota Koleksi
    kota populasi Koleksi
    kota array-contains region 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 dapat Anda gunakan untuk mengirim kueri di bidang 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
    kota (atau ) negara, populasi 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
    kota negara, populasi Koleksi
    kota negara, populasi 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
    kota tag dimuat di array, (atau ) ibu kota 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 (atau ) kategori 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 landmarksdengan cakupan grup koleksi:

    Koleksi Kolom yang diindeks Cakupan kueri
    landmark (atau ) kategori 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 Ada. 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:

    • restaurant

      • 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
    restoran kategori, star_rating Koleksi
    restoran kota, star_rating Koleksi
    restoran kategori, kota, star_rating Koleksi
    restoran kategori, kota, editors_pick, 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
    restoran kategori, star_rating Koleksi
    restoran kota, star_rating Koleksi
    restoran editors_pick, 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.