Cloud Firestore, her sorgu için bir dizin gerektirerek sorgu performansını sağlar. En temel sorgular için gereken dizinler sizin için otomatik olarak oluşturulur. Uygulamanızı kullanıp test ederken Cloud Firestore, uygulamanızın ihtiyaç duyduğu ek dizinleri oluşturmanıza yardımcı olan hata mesajları oluşturur. Bu sayfada otomatik, manuel ve vektör dizinlerinizi nasıl yöneteceğiniz açıklanmaktadır.
Hata mesajı aracılığıyla eksik dizin oluşturma
Mevcut bir dizine eşlenmeyen bir aralık yan tümcesi içeren bileşik sorgu denerseniz hata alırsınız. Hata mesajında, Firebase konsolunda eksik dizini oluşturmak için doğrudan bir bağlantı bulunur.
Oluşturulan bağlantıyı kullanarak Firebase konsoluna gidin, otomatik olarak doldurulan bilgileri inceleyin ve Oluştur'u tıklayın.
Vektör dizini gerekiyorsa hata mesajında, eksik vektör dizinini oluşturmak için bir Google Cloud CLI komutu yer alır. Eksik dizini oluşturmak için komutu çalıştırın.
Roller ve izinler
Cloud Firestore içinde dizin oluşturabilmek için aşağıdaki rollerden birine atanmış olmanız gerekir:
roles/datastore.ownerroles/datastore.indexAdminroles/editorroles/owner
Özel roller tanımladıysanız dizin oluşturmak için aşağıdaki izinlerin tümünü atayın:
datastore.indexes.createdatastore.indexes.deletedatastore.indexes.getdatastore.indexes.listdatastore.indexes.update
Firebase konsolunu kullanma
Firebase konsolundan manuel olarak yeni bir dizin oluşturmak için:
- Firebase konsolunda Databases & Storage (Veritabanları ve Depolama) > Firestore'a gidin.
- Dizinler sekmesinde Dizin Ekle'yi tıklayın.
- Koleksiyon adını girin ve dizini sıralamak istediğiniz alanları ayarlayın.
- Oluştur'u tıklayın.
Dizin alanları, alan yollarıyla ilgili kısıtlamalara uymalıdır.
Sorgunun boyutuna bağlı olarak dizinlerin oluşturulması birkaç dakika sürebilir. Dizinlerinizi oluşturduktan sonra, dizinlerinizi ve durumlarını Bileşik Dizinler bölümünde görebilirsiniz. Derleme işlemi devam ediyorsa Firebase konsolunda bir derleme durum çubuğu gösterilir.
Dizinleri kaldırma
Bir dizini silmek için:
- Firebase konsolunda Databases & Storage (Veritabanları ve Depolama) > Firestore'a gidin.
- Dizinler sekmesinde, silmek istediğiniz dizinin üzerine gelin ve bağlam menüsünden Sil'i seçin.
- Uyarıda Sil'i tıklayarak silme işlemini onaylayın.
Firebase CLI'yı kullanma
Dizinleri Firebase CLI ile de dağıtabilirsiniz.
Başlamak için proje dizininizde firebase init firestore komutunu çalıştırın.
Kurulum sırasında Firebase CLI, varsayılan dizinleri içeren bir JSON dosyasını doğru biçimde oluşturur. Daha fazla dizin eklemek için dosyayı düzenleyin ve firebase deploy komutuyla dağıtın.
Yalnızca Cloud Firestore dizinlerini ve kurallarını dağıtmak için --only firestore işaretini ekleyin.
Dizinlerde Firebase konsolunu kullanarak düzenleme yaparsanız yerel dizin dosyanızı da güncellediğinizden emin olun. JSON dizini tanım referansına bakın.
Terraform'u kullanma
Veritabanında dizin oluşturma
Cloud Firestore veritabanları hem tek alanlı (otomatik) hem de bileşik (manuel) dizinler içerebilir. Veritabanınız için dizin oluşturmak üzere Terraform yapılandırma dosyasını düzenleyebilirsiniz. Otomatik ve manuel dizinler, farklı Terraform kaynak türleri (google_firestore_index ve google_firestore_field) kullanır.
Tek alanlı (otomatik) dizin
Aşağıdaki örnek Terraform yapılandırma dosyası, chatrooms koleksiyonundaki name alanında tek alanlı bir dizin oluşturur:
firestore.tf
resource "random_id" "variable"{
byte_length = 8
}
resource "google_firestore_field" "single-index" {
project = "project-id"
database = "database-id"
collection = "chatrooms_${random_id.variable.hex}"
field = "name"
index_config {
indexes {
order = "ASCENDING"
query_scope = "COLLECTION_GROUP"
}
indexes {
array_config = "CONTAINS"
}
}
ttl_config {}
}
- project-id yerine proje kimliğinizi yazın. Proje kimlikleri benzersiz olmalıdır.
- database-id yerine veritabanı kimliğinizi yazın.
Birleşik (manuel) dizin
Aşağıdaki örnek Terraform yapılandırma dosyası, chatrooms koleksiyonundaki name alanı ve description alanı kombinasyonu için bileşik dizin oluşturur:
firestore.tf
resource "google_firestore_index" "composite-index" {
project = "project-id"
database = "database-id"
collection = "chatrooms"
fields {
field_path = "name"
order = "ASCENDING"
}
fields {
field_path = "description"
order = "DESCENDING"
}
}
- project-id yerine proje kimliğinizi yazın. Proje kimlikleri benzersiz olmalıdır.
- database-id yerine veritabanı kimliğinizi yazın.
Vektör dizini
Aşağıdaki örnek Terraform yapılandırma dosyası, chatrooms koleksiyonundaki embedding alanında bir vektör dizini oluşturur:
firestore.tf
resource "google_firestore_index" "vector-index" {
project = "project-id"
database = "database-id"
collection = "chatrooms"
fields {
field_path = "__name__"
order = "ASCENDING"
}
fields {
field_path = "embedding"
vector_config {
dimension = 128
flat {}
}
}
}
- project-id yerine proje kimliğinizi yazın. Proje kimlikleri benzersiz olmalıdır.
- database-id yerine veritabanı kimliğinizi yazın.
Dizin oluşturma süresi
Dizin oluşturmak için Cloud Firestore, dizini oluşturmalı ve ardından mevcut verilerle dizini doldurmalıdır. Dizin oluşturma süresi, kurulum süresi ile dolgu süresinin toplamıdır:
Dizin oluşturma işlemi birkaç dakika sürer. Boş bir veritabanı için bile dizin oluşturma süresi en az birkaç dakikadır.
Geriye dönük doldurma süresi, yeni dizine ait mevcut veri miktarına bağlıdır. Dizin tanımıyla eşleşen alan değerlerinin sayısı arttıkça dizinin doldurulması daha uzun sürer.
Dizin derlemeleri uzun süreli işlemlerdir.
Dizin oluşturma işlemini başlattıktan sonra Cloud Firestore, işleme benzersiz bir ad atar. İşlem adlarının önüne projects/[PROJECT_ID]/databases/(default)/operations/ eklenir.
Örneğin:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Ancak describe komutu için işlem adı belirtirken ön eki kullanmayabilirsiniz.
Tüm uzun süreli işlemleri listeleme
Uzun süreli işlemleri listelemek için gcloud firestore operations list komutunu kullanın. Bu komut, devam eden ve yakın zamanda tamamlanan işlemleri listeler. İşlemler, tamamlandıktan sonra birkaç gün boyunca listelenir:
gcloud firestore operations list
Faaliyet durumunu kontrol etme
Tüm uzun süreli işlemleri listelemek yerine tek bir işlemin ayrıntılarını listeleyebilirsiniz:
gcloud firestore operations describe operation-name
Tamamlanma süresi tahmin ediliyor
İşleminiz çalışırken işlemin genel durumu için state alanının değerine bakın.
Uzun süreli bir işlemin durumuna yönelik istek, workEstimated ve workCompleted metriklerini de döndürür. Bu metrikler, doküman sayısı için döndürülür. workEstimated, bir işlemin işleyeceği tahmini toplam doküman sayısını gösterir. workCompleted
Şu ana kadar işlenen doküman sayısını gösterir. İşlem tamamlandıktan sonra workCompleted, gerçekte işlenen toplam belge sayısını yansıtır. Bu sayı, workEstimated değerinden farklı olabilir.
Yaklaşık ilerleme tahmini için workCompleted değerini workEstimated değerine bölün. Tahmin, gecikmeli istatistik toplamaya bağlı olduğundan yanlış olabilir.
Örneğin, bir dizin derlemesinin ilerleme durumu şu şekildedir:
{
"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"
}
},
},
...
İşlem tamamlandığında işlem açıklamasında "done":
true ifadesi yer alır. İşlemin sonucu için state alanının değerine bakın. Yanıtta done alanı ayarlanmamışsa değeri false olur. Devam eden işlemler için done değerinin varlığına güvenmeyin.
Dizin oluşturma hataları
Manuel dizinleri ve otomatik dizin muafiyetlerini yönetirken dizin oluşturma hatalarıyla karşılaşabilirsiniz. Cloud Firestore, dizine eklediği verilerle ilgili bir sorunla karşılaşırsa dizine ekleme işlemi başarısız olabilir. Bu durum genellikle dizin sınırına ulaştığınız anlamına gelir. Örneğin, işlem, doküman başına maksimum dizin girişi sayısına ulaşmış olabilir.
Dizin oluşturma işlemi başarısız olursa konsolda hata mesajı gösterilir. Dizin sınırlarına ulaşmadığınızı doğruladıktan sonra dizin işleminizi yeniden deneyin.