Zarządzanie indeksami w Cloud Firestore

Cloud Firestore zapewnia wydajność zapytań, wymagając indeksu dla każdego zapytania. Indeksy wymagane do wykonywania najbardziej podstawowych zapytań są utworzone automatycznie. Podczas używania i testowania aplikacji Cloud Firestore generuje komunikaty o błędach, które pomagają tworzyć dodatkowe indeksy wymagane przez daną aplikację. Na tej stronie dowiesz się, jak zarządzać indeksami z jednym polem i złożonym.

Tworzenie brakującego indeksu z poziomu komunikatu o błędzie

Jeśli spróbujesz wykonać zapytanie złożone z klauzulą zakresu, która nie jest mapowana na istniejący indeks, wystąpi błąd. Komunikat o błędzie zawiera bezpośredni link do utworzenia brakującego indeksu w konsoli Firebase.

Uwaga: możesz zarządzać Cloud Firestore za pomocą konsoli Firebase lub Google Cloud Platform, ale te linki zawsze otwierają się w konsoli Firebase.

Kliknij wygenerowany link do konsoli Firebase, sprawdź automatycznie wypełnione informacje i kliknij Utwórz.

Uwaga: w przypadku pól innych niż tablice i mapy musisz wybrać sortowanie rosnąco lub malejąco, nawet jeśli nie jest ono potrzebne do sortowania. Twój wybór nie ma wpływu na działanie równości w zapytaniu.

Role i uprawnienia

Zanim utworzysz indeks w Cloud Firestore, sprawdź, czy masz przypisaną jedną z tych ról:

Uwaga: poniższymi rolami zarządza się za pomocą Identity and Access Management (IAM). Więcej informacji o rolach i powiązanych uprawnieniach znajdziesz w artykule Wstępnie zdefiniowane role.

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

Jeśli masz zdefiniowane role niestandardowe, przypisz wszystkie z tych uprawnień, aby tworzyć indeksy:

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

Korzystanie z konsoli Firebase

Aby ręcznie utworzyć nowy indeks w konsoli Firebase:

1. Otwórz sekcję Cloud Firestore w konsoli Firebase.
2. Otwórz kartę Indeksy i kliknij Dodaj indeks.
3. Wpisz nazwę zbioru i ustaw pola, według których chcesz uporządkować indeks.
4. Kliknij Utwórz.

Pola indeksu muszą być zgodne z ograniczeniami dotyczącymi ścieżek pól.

W zależności od rozmiaru zapytania kompilowanie indeksów może potrwać kilka minut. Po utworzeniu indeksów i ich stan możesz zobaczyć w sekcji Indeksy złożone. Jeśli nadal są tworzone, konsola Firebase zawiera pasek stanu budynku.

Usuń indeksy

Aby usunąć indeks:

1. Otwórz sekcję Cloud Firestore w konsoli Firebase.
2. Kliknij kartę Indeksy.
3. Najedź kursorem na indeks, który chcesz usunąć, i wybierz Usuń z menu kontekstowego.
4. Aby potwierdzić, że chcesz go usunąć, w alercie kliknij Usuń.

Używanie interfejsu wiersza poleceń Firebase

Możesz też wdrażać indeksy za pomocą interfejsu wiersza poleceń Firebase. Zacznij od uruchomienia firebase init firestore w katalogu projektu. Podczas konfiguracji interfejs wiersza poleceń Firebase generuje plik JSON z indeksami domyślnymi i we właściwym formacie. Edytuj plik, aby dodać więcej indeksów, i wdróż go za pomocą polecenia firebase deploy.

Aby wdrożyć tylko indeksy i reguły Cloud Firestore, dodaj flagę --only firestore.

Jeśli wprowadzasz zmiany w indeksach za pomocą konsoli Firebase, pamiętaj o zaktualizowaniu także lokalnego pliku indeksów. Zapoznaj się z informacjami o definicji indeksu JSON.

Użyj Terraform

Tworzenie indeksów w bazie danych

Baza danych Cloud Firestore może zawierać indeks pojedynczego pola lub indeks złożony. Możesz zmodyfikować plik konfiguracji Terraform, aby utworzyć indeks dla bazy danych.

Indeks jednego pola

Ten przykładowy plik konfiguracji Terraform tworzy indeks z jednym polem w polu name w kolekcji chatrooms:

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 {}
}

• Zastąp project-id identyfikatorem projektu. Identyfikatory projektów muszą być unikalne.
• Zastąp database-id identyfikatorem bazy danych.

Indeks złożony

Ten przykładowy plik konfiguracji Terraform tworzy indeks złożony dla kombinacji pól name i description w kolekcji chatrooms:

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"
  }

}

• Zastąp project-id identyfikatorem projektu. Identyfikatory projektów muszą być unikalne.
• Zastąp database-id identyfikatorem bazy danych.

Czas kompilacji indeksu

Aby można było utworzyć indeks, Cloud Firestore musi go skonfigurować, a następnie uzupełnić go istniejącymi danymi. Czas kompilacji indeksu to suma czasu konfiguracji i czasu uzupełniania:

• Konfigurowanie indeksu może potrwać kilka minut. Minimalny czas kompilacji indeksu to kilka minut, nawet w przypadku pustej bazy danych.

• Czas uzupełniania zależy od tego, ile istniejących danych należy do nowego indeksu. Im więcej wartości pól pasują do definicji indeksu, tym dłużej trwa jego kopia.

Kompilacje indeksu to długo trwające operacje.

Kluczowy termin: Cloud Firestore obsługuje kilka operacji administracyjnych, których wykonanie może zająć dużo czasu. Operacje te są nazywane długo trwającymi operacjami. Cloud Firestore udostępnia funkcje pozwalające wykonywać długotrwałe operacje i nimi zarządzać. Obsługiwane długotrwałe operacje obejmują kompilacje indeksów i operacje eksportowania.

Po rozpoczęciu kompilacji indeksu Cloud Firestore przypisze operacji unikalną nazwę. Nazwy operacji mają prefiks projects/[PROJECT_ID]/databases/(default)/operations/, na przykład:

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

Możesz jednak pominąć ten prefiks podczas określania nazwy operacji w poleceniu describe.

Wyświetlam listę wszystkich długo trwających operacji

Aby wyświetlić listę długo trwających operacji, użyj polecenia gcloud Firestore Operations list. To polecenie zawiera listę bieżących i niedawno zakończonych operacji. Operacje są wyświetlane przez kilka dni po ich zakończeniu:

gcloud firestore operations list

Sprawdź stan operacji

Zamiast wyświetlać listę wszystkich długo trwających operacji, możesz podać szczegóły pojedynczej operacji:

gcloud firestore operations describe operation-name

Szacowanie czasu ukończenia

W trakcie wykonywania operacji sprawdź wartość w polu state, aby określić ogólny stan operacji.

Żądanie dotyczące stanu długo trwającej operacji zwraca też wskaźniki workEstimated i workCompleted. Te wskaźniki są zwracane dla liczby dokumentów. workEstimated pokazuje szacowaną łączną liczbę dokumentów, które zostaną przetworzone w ramach danej operacji. workCompleted wskazuje liczbę przetworzonych do tej pory dokumentów. Po jej zakończeniu workCompleted odzwierciedla łączną liczbę przetworzonych dokumentów. Może ona różnić się od wartości workEstimated.

Aby uzyskać przybliżone oszacowanie postępu, podziel workCompleted przez workEstimated. Oszacowanie może być niedokładne, ponieważ zależy od opóźnionego zbierania statystyk.

Oto na przykład stan postępu kompilacji indeksu:

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

Po zakończeniu operacji jej opis będzie zawierał ciąg "done": true. Sprawdź wartość pola state, aby uzyskać wynik operacji. Jeśli w odpowiedzi pole done nie jest ustawione, jego wartość wynosi false. Nie zależą od obecności wartości done w operacjach w toku.

Błędy tworzenia indeksu

Podczas zarządzania indeksami złożonymi i wykluczeniami indeksów jednego pola mogą wystąpić błędy tworzenia indeksów. Operacja indeksowania może się nie powieść, jeśli Cloud Firestore napotka problem z danymi, które indeksuje. Najczęściej oznacza to osiągnięcie limitu indeksowania. Na przykład operacja mogła osiągnąć maksymalną liczbę wpisów indeksu na dokument.

Jeśli nie uda się utworzyć indeksu, w konsoli zobaczysz komunikat o błędzie. Gdy upewnisz się, że nie osiągasz żadnych limitów indeksowania, spróbuj jeszcze raz przeprowadzić operację indeksowania.