Zarządzanie indeksami w Cloud Firestore

Cloud Firestore zapewnia wydajność zapytań, wymagając indeksu dla każdego zapytania. Indeksy wymagane do najprostszych 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.

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

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.

Role i uprawnienia

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

(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:

obraz interfejsu indeksowania Firestore w konsoli Firebase

  1. Otwórz sekcję Cloud Firestorekonsoli 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 pojawi się pasek stanu.

Usuwanie indeksów

Aby usunąć indeks:

  1. Otwórz sekcję Cloud Firestorekonsoli Firebase.
  2. Kliknij kartę Indeksy.
  3. Najedź kursorem na indeks, który chcesz usunąć, i w menu kliknij Usuń.
  4. Potwierdź, że chcesz usunąć alert, klikając Usuń.

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, aby zaktualizować również lokalny plik 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_indexgoogle_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 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 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.

Po rozpoczęciu kompilowania indeksu usługa Cloud Firestore przypisuje operacji unikalną nazwę. Nazwy działań mają 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 wartość 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, spróbuj ponownie przeprowadzić operację indeksowania.