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

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

Mevcut bir dizinle eşlenmeyen bir aralık ifadesi içeren bileşik bir sorgu denerseniz hata alırsınız. Hata mesajında, Firebase konsolunda eksik dizini oluşturmak için doğrudan bir bağlantı yer alır.

Not: Cloud Firestore öğesini Firebase konsolundan veya Google Cloud Platform Console'dan 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 gerektiğinde hata mesajı, eksik vektör dizinini oluşturmak için Google Cloud CLI komutunu içerir. Eksik dizini oluşturmak için komutu çalıştırın.

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

Roller ve izinler

Cloud Firestore içinde dizin oluşturabilmek için aşağıdaki rollerden birinin size atanmış olması 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 yeni bir dizini manuel olarak oluşturmak için:

1. Firebase konsolunun Cloud Firestore bölümüne gidin.
2. Dizinler sekmesine gidin ve Dizin 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 uymalıdır.

Sorgunun boyutuna bağlı olarak, dizinlerin oluşturulması birkaç dakika sürebilir. Oluşturduktan sonra, birleşik dizinlerinizi ve durumlarını Birleşik Dizinler bölümünde görebilirsiniz. Hâlâ oluşturuluyorsa Firebase konsolunda bir oluşturma durumu çubuğu gösterilir.

Dizinleri kaldırma

Bir dizini silmek için:

1. Firebase konsolunun Cloud Firestore bölümüne gidin.
2. Dizinler sekmesini tıklayın.
3. Silmek istediğiniz dizinin üzerine gelin ve bağlam menüsünden Sil'i seçin.
4. Uyarıda Sil'i tıklayarak silmek istediğinizi 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, doğru biçimde varsayılan dizinleri 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 dizinlerini ve kurallarını dağıtmak için --only firestore işaretini ekleyin.

Firebase konsolunu kullanarak dizinlerde düzenlemeler yaparsanız yerel dizinler dosyanızı da güncellediğinizden emin olun. JSON dizin 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ız için bir dizin oluşturmak üzere Terraform yapılandırma dosyasını düzenleyebilirsiniz. Tek alanlı ve birleşik dizinler, farklı Terraform kaynak türlerini (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.

Bileşik dizin

Aşağıdaki örnek Terraform yapılandırma dosyası, chatrooms koleksiyonundaki name alanı ve description alanının birleşimi için birleş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 dizini mevcut verilerle doldurmalıdır. Dizin oluşturma süresi, kurulum süresi ve 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, yeni dizinde ne kadar mevcut veri olduğuna bağlıdır. Dizin tanımıyla eşleşen alan değerleri ne kadar fazlaysa dizinin doldurulması o kadar uzun sürer.

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

Önemli Terim: Cloud Firestore, tamamlanması uzun zaman alabilen çeşitli yönetim işlemlerini destekler. Bu işlemlere uzun süren işlemler adı verilir. 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.

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 işlem adı belirtirken öneki atlayabilirsiniz.

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

gcloud firestore operations list

İşlem durumunu kontrol etme

Uzun süreli işlemlerin tamamını 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 görün.

Uzun süreli bir işlemin durumuyla ilgili istekler 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, workEstimated değerinden farklı olabilecek, gerçekten işlenen toplam belge sayısını yansıtır.

Kabaca bir ilerleme tahmini için workCompleted değerini workEstimated değerine bölün. Tahmin, istatistiklerin toplanması geciktiğinden yanlış olabilir.

Örneğin, bir dizin oluşturma işleminin ilerleme durumu şöyledir:

{
  "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 görün. Yanıt içinde done alanı ayarlanmamışsa değeri false olur. Devam eden işlemler için done değerinin varlığına bağlı kalmayın.

Dizin oluşturma hataları

Birleşik dizinleri ve tek alanlı dizin muafiyetlerini yönetirken dizin oluşturma hatalarıyla karşılaşabilirsiniz. Dizine ekleme işlemi, Cloud Firestore dizine eklediği verilerle ilgili bir sorunla karşılaşırsa başarısız olabilir. Bu durum en sık olarak bir dizin sınırına ulaştığınız anlamına gelir. Ö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ını görürsünüz. Herhangi bir dizin sınırına ulaşmadığınızı doğruladıktan sonra dizin oluşturma işleminizi yeniden deneyin.