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ą automatycznie tworzone. Podczas korzystania z aplikacji i jej testowania Cloud Firestore generuje komunikaty o błędach, które pomagają tworzyć dodatkowe indeksy wymagane przez aplikację. Na tej stronie dowiesz się, jak zarządzać indeksami jednopolowymi, złożonymi i wektorami.

Tworzenie brakującego indeksu za pomocą komunikatu o błędzie

Jeśli spróbujesz uruchomić zapytanie złożone z klauzulą zakresu, która nie jest mapowana na istniejący indeks, pojawi się 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 w konsoli Firebase lub konsoli Google Cloud Platform, ale te połączenia zawsze będą się otwierać w konsoli Firebase.

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

Uwaga: w przypadku pól, które nie są tablicami ani mapami, musisz wybrać sortowanie rosnące lub malejące, nawet jeśli nie potrzebujesz tego pola do sortowania. Twój wybór nie wpływa na działanie operatora równości w zapytaniu.

Jeśli wymagany jest indeks wektora, komunikat o błędzie będzie zawierać polecenie Google Cloud CLI służące do utworzenia brakującego indeksu wektora. Uruchom polecenie, aby utworzyć brakujący indeks.

Uwaga: obecnie indeksy wektorów nie mogą być tworzone w konsoli Firebase ani w Konsoli Google Cloud Platform.

Role i uprawnienia

Zanim utworzysz indeks w Cloud Firestore, upewnij się, że masz jedną z tych ról:

Uwaga: tymi rolami zarządzasz za pomocą usługi Identity and Access Management (IAM). Więcej informacji o rolach i powiązanych z nimi uprawnieniach znajdziesz w artykule Wstępnie zdefiniowane role

(w języku angielskim).

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

Jeśli masz zdefiniowane role niestandardowe, przypisz wszystkie te uprawnienia do tworzenia indeksów:

• 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ę kolekcji i ustaw pola, według których indeks ma być sortowany.
4. Kliknij Utwórz.

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

W zależności od rozmiaru zapytania tworzenie indeksów może potrwać kilka minut. Po utworzeniu indeksów możesz je wyświetlić wraz z ich stanem w sekcji Indeksy złożone. Jeśli są one nadal tworzone, w konsoli Firebase będzie widoczny pasek stanu.

Usuwanie indeksów

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 w menu kliknij Usuń.
4. Potwierdź, że chcesz go usunąć, klikając Usuń w ogłoszeniu.

Korzystanie z wiersza poleceń Firebase

Indeksy możesz też wdrażać za pomocą wiersza poleceń Firebase. Aby rozpocząć, uruchom firebase init firestore w katalogu projektu. Podczas konfiguracji interfejs wiersza poleceń Firebase generuje plik JSON z domyślnymi indeksami w odpowiednim formacie. Zmień plik, aby dodać więcej indeksów, i wdroź 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 też o zaktualizowaniu lokalnego pliku indeksów. Zapoznaj się z dokumentacją referencyjną definicji indeksu JSON.

Użyj Terraform

tworzenie indeksów w bazie danych.

Bazy danych Cloud Firestore mogą zawierać indeksy jedno- i wielokryterialne. Możesz edytować plik konfiguracji Terraform, aby utworzyć indeks bazy danych. Indeksy pojedynczych pól i kompleksowe używają różnych typów zasobów Terraform (google_firestore_index i google_firestore_field).

Indeks pojedynczego pola

Ten przykładowy plik konfiguracji Terraform tworzy indeks jednopolowy dla pola 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 pola name i pola 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.

Indeks wektorów

Ten przykładowy plik konfiguracji Terraform tworzy indeks wektorowy na polu embedding w kolekcji chatrooms:

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

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

Czas kompilacji indeksu

Aby utworzyć indeks, Cloud Firestore musi skonfigurować indeks, 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 tworzenia indeksu to kilka minut, nawet w przypadku pustej bazy danych.

• Czas tworzenia kopii zapasowej zależy od ilości danych, które mają zostać dodane do nowego indeksu. Im więcej wartości pól pasuje do definicji indeksu, tym dłużej trwa jego uzupełnianie.

Kompilacje indeksów to długo trwające operacje.

Kluczowy termin: Cloud Firestore umożliwia wykonywanie kilku operacji administracyjnych, które mogą zająć dużo czasu. Takie operacje nazywamy długotrwałymi operacjami. Cloud Firestore zawiera funkcje umożliwiające wykonywanie długotrwałych operacji i zarządzanie nimi. Obsługiwane długotrwałe operacje obejmują tworzenie indeksów i operacje eksportu.

Po rozpoczęciu kompilacji indeksu Cloud Firestore przypisuje operacji unikalną nazwę. Nazwa działania ma prefiks projects/[PROJECT_ID]/databases/(default)/operations/, na przykład:

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

Możesz jednak pominąć prefiks, podając nazwę operacji dla polecenia describe.

Wyświetlanie wszystkich długo trwających operacji

Aby wyświetlić listę długotrwałych operacji, użyj polecenia gcloud firestore operations list. To polecenie wyświetla trwające i niedawno zakończone operacje. Operacje są widoczne przez kilka dni po ich zakończeniu:

gcloud firestore operations list

Sprawdzanie stanu operacji

Zamiast wyświetlać wszystkie długotrwałe operacje, możesz wyświetlić szczegóły pojedynczej operacji:

gcloud firestore operations describe operation-name

Szacowanie czasu ukończenia

Podczas wykonywania operacji możesz sprawdzić wartość pola state, aby dowiedzieć się, jaki jest ogólny stan operacji.

Żądanie dotyczące stanu długo trwającej operacji zwraca też dane workEstimated i workCompleted. Te dane są zwracane dla liczby dokumentów. workEstimated pokazuje szacowaną łączną liczbę dokumentów, które zostaną przetworzone przez operację. workCompletedpokazuje liczbę przetworzonych do tej pory dokumentów. Po zakończeniu operacji workCompleted odzwierciedla łączną liczbę dokumentów, które zostały faktycznie przetworzone, co może być inne niż wartość workEstimated.

Aby uzyskać przybliżony szacowany postęp, podziel workCompleted przez workEstimated. Szacowana liczba może być niedokładna, ponieważ zależy od opóźnionego zbierania statystyk.

Oto na przykład stan tworzenia 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 zawiera "done": true. Aby sprawdzić wynik operacji, zobacz wartość pola state. Jeśli w odpowiedzi nie ma pola done, jego wartość to false. Nie polegaj na istnieniu wartości done w przypadku operacji w toku.

Błędy indeksowania

Podczas zarządzania indeksami złożonymi i wykluczeniami indeksów pojedynczych pól mogą wystąpić błędy tworzenia indeksów. Operacja indeksowania może się nie udać, jeśli Cloud Firestore napotka problem z indeksowanymi danymi. Najczęściej oznacza to, że osiągnięto limit indeksu. Na przykład operacja może osiągnąć maksymalną liczbę wpisów indeksu na dokument.

Jeśli tworzenie indeksu się nie powiedzie, w konsoli pojawi się komunikat o błędzie. Po sprawdzeniu, że nie przekraczasz żadnych limitów indeksowania, ponownie spróbuj przeprowadzić operację indeksowania.