Cloud Firestore'da dizinleri yönetin

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. Cloud Firestore, uygulamanızı kullanırken ve test ederken uygulamanızın ihtiyaç duyduğu ek dizinleri oluşturmanıza yardımcı olan hata mesajları oluşturur. Bu sayfada, tek alanlı, birleşik ve vektor dizinlerinizi nasıl yöneteceğiniz açıklanmaktadır.

Hata mesajı aracılığıyla eksik bir dizin oluşturma

Mevcut bir diziyle eşleşmeyen bir aralık yan tümcesi içeren birleşik sorgu oluşturmaya çalışırsanız hata alırsınız. Hata mesajında, eksik dizini Firebase Konsolu'nda oluşturmaya yönelik doğrudan bir bağlantı bulunur.

Not: Cloud Firestore'i Firebase konsolu veya Google Cloud Platform Konsolu üzerinden yönetebilirsiniz ancak bu bağlantılar her zaman Firebase konsolunda açılır.

Oluşturulan bağlantıyı kullanarak Firebase konsoluna gidin, otomatik olarak doldurulan bilgileri inceleyin ve Oluştur'u tıklayın.

Not: Dizi ve harita olmayan alanlar için, sıralama amacıyla alana ihtiyacınız olmasa bile artan veya azalan sıralamayı seçmeniz gerekir. Seçiminiz, sorgudaki eşitliklerin davranışını etkilemez.

Vektör dizini gerekiyorsa hata mesajında, eksik vektör dizesini oluşturmak için bir Google Cloud CLI komutu yer alır. Eksik dizini oluşturmak için komutu çalıştırın.

Not: Şu anda Firebase Console veya Google Cloud Platform Console'da vektör dizini oluşturulamaz.

Roller ve izinler

Cloud Firestore'te dizin oluşturabilmek için aşağıdaki rollerden birine atanmış olmanız gerekir:

Not: Aşağıdaki roller Kimlik ve Erişim Yönetimi (IAM) aracılığıyla yönetilir. Roller ve ilişkili izinler hakkında daha fazla bilgi için Önceden tanımlanmış roller başlıklı makaleyi inceleyin.

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

Özel roller tanımladıysanız dizin oluşturmak için aşağıdaki izinlerin tümünü atayın:

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

Firebase konsolunu kullanma

Firebase konsolundan manuel olarak yeni bir dizin oluşturmak için:

1. Firebase konsolunun Cloud Firestore bölümüne gidin.
2. Dizine ekleme sekmesine gidin ve Dizine ekle'yi tıklayın.
3. Koleksiyon adını girin ve dizini sıralamak istediğiniz alanları ayarlayın.
4. Oluştur'u tıklayın.

Dizin alanları alan yollarındaki kısıtlamalara uygun olmalıdır.

Sorgunun boyutuna bağlı olarak dizin oluşturma işlemi birkaç dakika sürebilir. Oluşturduğunuz dizinleri ve durumlarını Kompozit Dizinler bölümünde görebilirsiniz. Uygulama hâlâ derleniyorsa Firebase konsolunda bir derleme durumu çubuğu gösterilir.

Dizinleri kaldırma

Bir dizini silmek için:

1. Firebase konsolunun Cloud Firestore bölümüne gidin.
2. Dizine eklemeler sekmesini tıklayın.
3. Fareyle, silmek istediğiniz dizinin üzerine gelin ve bağlam menüsünden Sil'i seçin.
4. Uyarıdan Sil'i tıklayarak silmek istediğinizi onaylayın.

Firebase CLI'yi kullanma

Dizinleri Firebase CLI ile de dağıtabilirsiniz. Başlamak için proje dizininizde firebase init firestore komutunu çalıştırın. Firebase CLI, kurulum sırasında varsayılan dizinleri doğru biçimde içeren bir JSON dosyası oluşturur. Daha fazla dizin eklemek için dosyayı düzenleyin ve firebase deploy komutuyla dağıtın.

Yalnızca Cloud Firestore dizine ekleme ve kural dağıtmak için --only firestore işaretini ekleyin.

Firebase konsolunu kullanarak dizinlerde 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ı hem de birleşik dizinler içerebilir. Veritabanınıza dizin oluşturmak için Terraform yapılandırma dosyasını düzenleyebilirsiniz. Tek alanlı ve birleşik dizinler farklı Terraform kaynak türleri (google_firestore_index ve google_firestore_field) kullanır.

Tek alanlı 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 dizin

Aşağıdaki örnek Terraform yapılandırma dosyası, chatrooms koleksiyonundaki name alanı ile description alanının kombinasyonu için birleşik bir 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

Cloud Firestore, dizin oluşturmak için dizini ayarlamalı ve ardından dizini mevcut verilerle doldurmalıdır. Dizin oluşturma süresi, ayarlama süresi ile doldurma süresinin toplamıdır:

• Dizin oluşturma işlemi birkaç dakika sürer. Boş bir veritabanı için bile bir dizinin minimum oluşturma süresi birkaç dakikadır.

• Doldurma süresi, mevcut verilerin yeni dizinde ne kadar yer kapladığına bağlıdır. Dizin tanımı ile eşleşen alan değeri ne kadar fazlaysa dizini doldurmak o kadar uzun sürer.

Dizin oluşturma işlemleri uzun süreli işlemlerdir.

Anahtar Terim: Cloud Firestore, tamamlanması uzun zaman alabilen çeşitli idari işlemleri destekler. Bu işlemlere uzun süreli işlemler denir. Cloud Firestore, uzun süreli işlemleri yürütme ve yönetme özelliklerini içerir. Desteklenen uzun süreli işlemler arasında dizin oluşturma ve dışa aktarma işlemleri yer alır.

Bir 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/ ön eki eklenir. Örneğin:

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

Ancak describe komutu için bir işlem adı belirtirken ön eki çıkarabilirsiniz.

Tüm uzun süreli işlemleri listeleme

Uzun süren 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 birkaç gün sonra listelenir:

gcloud firestore operations list

İşlem 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üresini tahmin etme

İşleminiz çalışırken işlemin genel durumu için state alanının değerini inceleyin.

Uzun süren bir işlemin durumuyla ilgili 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 belge 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 doküman sayısını yansıtır. Bu değer, workEstimated değerinden farklı olabilir.

Yaklaşık bir ilerleme tahmini için workCompleted değerini workEstimated değerine bölün. Tahmin, gecikmeli istatistik toplama işlemine bağlı olduğundan yanlış olabilir.

Örneğin, bir dizin oluşturma işleminin ilerleme durumu aşağıda verilmiştir:

{
  "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"
        }
       },
    },
    ...

Bir işlem tamamlandığında işlem açıklamasında "done": true yer alır. İşlemin sonucu için state alanının değerini inceleyin. 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ı

Kompozit dizinleri ve tek alan dizini 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 bir dizin sınırına ulaştığınızı gösterir. Örneğin, işlem belge 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örürsünüz. Herhangi bir dizin sınırına ulaşmadığınızı doğruladıktan sonra dizine ekleme işleminizi yeniden deneyin.