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.
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.ownerroles/datastore.indexAdminroles/editorroles/owner
Jeśli masz zdefiniowane role niestandardowe, przypisz wszystkie te uprawnienia do tworzenia indeksów:
datastore.indexes.createdatastore.indexes.deletedatastore.indexes.getdatastore.indexes.listdatastore.indexes.update
Korzystanie z konsoli Firebase
Aby ręcznie utworzyć nowy indeks w konsoli Firebase:
- Otwórz sekcję Cloud Firestore w konsoli Firebase.
- Otwórz kartę Indeksy i kliknij Dodaj indeks.
- Wpisz nazwę kolekcji i ustaw pola, według których indeks ma być sortowany.
- 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:
- Otwórz sekcję Cloud Firestore w konsoli Firebase.
- Kliknij kartę Indeksy.
- Najedź kursorem na indeks, który chcesz usunąć, i w menu kliknij Usuń.
- 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.
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.