Zarządzanie indeksami w Cloud Firestore

Cloud Firestore zapewnia wydajność zapytań, wymagając indeksu dla każdego zapytania. Indeksy wymagane w przypadku najbardziej podstawowych zapytań są tworzone automatycznie. 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 wektorowymi.

Tworzenie brakującego indeksu na podstawie 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, pojawi się błąd. Komunikat o błędzie zawiera bezpośredni link do utworzenia brakującego indeksu w konsoli Firebase.

Uwaga: Cloud Firestore możesz zarządzać w konsoli Firebase lub w konsoli Google Cloud Platform, ale te linki 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ć kolejność rosnącą lub malejącą, nawet jeśli nie potrzebujesz tego pola do sortowania. Twój wybór nie ma wpływu na działanie równości w zapytaniu.

Jeśli wymagany jest indeks wektorowy, komunikat o błędzie będzie zawierać polecenie Google Cloud CLI, które pozwoli utworzyć brakujący indeks wektorowy. Uruchom polecenie, aby utworzyć brakujący indeks.

Uwaga: obecnie nie można tworzyć indeksów wektorowych w konsoli Firebase ani w konsoli Google Cloud Platform.

Role i uprawnienia

Zanim utworzysz indeks w Cloud Firestore, musisz mieć przypisaną jedną z tych ról:

Uwaga: tymi rolami zarządza się 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.

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

Jeśli masz zdefiniowane role niestandardowe, przypisz wszystkie te uprawnienia, aby utworzyć 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ę kolekcji 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.

Tworzenie indeksów może potrwać kilka minut w zależności od rozmiaru zapytania. Po utworzeniu indeksów możesz je wyświetlić wraz z ich stanem w sekcji Indeksy złożone. Jeśli nadal trwa tworzenie, w konsoli Firebase pojawi się pasek stanu tworzenia.

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 kontekstowym wybierz Usuń.
4. Potwierdź, że chcesz go usunąć, klikając Usuń w alercie.

Korzystanie z wiersza poleceń Firebase

Indeksy możesz też wdrażać za pomocą wiersza poleceń Firebase. Aby rozpocząć, w katalogu projektu uruchom polecenie firebase init firestore. Podczas konfiguracji interfejs Firebase CLI generuje plik JSON z domyślnymi indeksami w prawidłowym formacie. Edytuj 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 edytujesz indeksy w konsoli Firebase, pamiętaj, aby zaktualizować też lokalny plik indeksów. Zapoznaj się z dokumentacją definicji indeksu JSON.

Użyj Terraform

Tworzenie indeksów w bazie danych

Bazy danych Cloud Firestore mogą zawierać indeksy jedno- i wielopolowe. Możesz edytować plik konfiguracji Terraform, aby utworzyć indeks dla bazy danych. Indeksy pojedynczych pól i indeksy złożone 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 jednego pola 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 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 wektorowy

Ten przykładowy plik konfiguracji Terraform tworzy indeks wektorowy w 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 tworzenia indeksu

Aby utworzyć indeks, musisz go skonfigurować, a następnie wypełnić go istniejącymi danymi.Cloud Firestore Czas tworzenia indeksu to suma czasu konfiguracji i czasu uzupełniania:

• Konfigurowanie indeksu zajmuje kilka minut. Minimalny czas tworzenia indeksu wynosi kilka minut, nawet w przypadku pustej bazy danych.

• Czas wypełniania wstecznego zależy od ilości istniejących danych, które mają się znaleźć w nowym indeksie. Im więcej wartości pól pasuje do definicji indeksu, tym dłużej trwa wypełnianie indeksu.

Tworzenie indeksu to długo trwająca operacja.

Kluczowe pojęcie: Cloud Firestore obsługuje kilka operacji administracyjnych, których wykonanie może zająć dużo czasu. Te operacje nazywamy operacjami długotrwałymi. Cloud Firestore zawiera funkcje do wykonywania długotrwałych operacji i zarządzania nimi. Obsługiwane długo trwające operacje to tworzenie indeksów i operacje eksportowania.

Po rozpoczęciu tworzenia indeksu Cloud Firestore przypisuje operacji unikalną nazwę. Nazwy działań mają prefiks projects/[PROJECT_ID]/databases/(default)/operations/, np.:

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

Podczas określania nazwy operacji w przypadku polecenia describe możesz jednak pominąć prefiks.

Wyświetlanie listy 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 listę trwających i niedawno zakończonych operacji. Operacje są wyświetlane przez kilka dni po zakończeniu:

gcloud firestore operations list

Sprawdzanie stanu operacji

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

gcloud firestore operations describe operation-name

Szacowanie czasu ukończenia

Podczas działania operacji sprawdzaj wartość pola state, aby poznać ogólny stan operacji.

Żądanie stanu długo trwającej operacji zwraca też dane workEstimated i workCompleted. Te dane są zwracane w przypadku liczby dokumentów. workEstimated – szacowana łączna liczba dokumentów, które zostaną przetworzone w ramach operacji. workCompleted wyświetla liczbę przetworzonych do tej pory dokumentów. Po zakończeniu operacji wartość workCompleted odzwierciedla łączną liczbę faktycznie przetworzonych dokumentów, która może się różnić od wartości workEstimated.

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

Oto na przykład stan postępu 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"
        }
       },
    },
    ...

Gdy operacja zostanie zakończona, w jej opisie pojawi się "done": true. Sprawdź wartość pola state, aby poznać wynik operacji. Jeśli w odpowiedzi nie ustawiono pola done, jego wartość to false. Nie polegaj na istnieniu wartości done w przypadku operacji w toku.

Błędy tworzenia indeksu

Podczas zarządzania indeksami złożonymi i wykluczeniami indeksów jednopola mogą wystąpić błędy tworzenia indeksu. 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 mogła osiągnąć maksymalną liczbę wpisów indeksu w dokumencie.

Jeśli tworzenie indeksu się nie powiedzie, w konsoli pojawi się komunikat o błędzie. Po sprawdzeniu, czy nie osiągasz żadnych limitów indeksowania, spróbuj ponownie wykonać operację indeksowania.