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:
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 chcesz posortować indeks.
- 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
Możesz też wdrażać indeksy 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 wektorowy
Ten przykładowy plik konfiguracji Terraform tworzy indeks wektorów na polu embedding w zbiorze 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 wypełniania kopii zapasowej zależy od tego, ile dotychczasowych danych należy do nowego indeksu. Im więcej wartości pól pasuje do definicji indeksu, tym dłużej trwa jego uzupełnianie.
Generowanie indeksów to długo trwające operacje.
Po rozpoczęciu kompilacji indeksu usługa Cloud Firestore przypisuje 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ąć prefiks, podając nazwę operacji dla polecenia describe.
Wyświetlanie wszystkich długo trwających operacji
Aby wyświetlić listę długo trwających operacji, użyj polecenia gcloud firestore operations list. To polecenie wyświetla listę bieżących i niedawno zakończonych operacji. 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żone oszacowanie postępu, 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 będzie zawierać wartość "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 jednopolowych 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.