Cloud Firestore zapewnia wydajność zapytań, wymagając indeksu dla każdego zapytania. Indeksy wymagane w przypadku najbardziej podstawowych zapytań są tworzone automatycznie. Podczas używania i testowania aplikacji 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 automatycznymi, ręcznymi i wektorowymi.
Tworzenie brakującego indeksu za pomocą 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.
Kliknij wygenerowany link, aby przejść do konsoli Firebase, sprawdź automatycznie wypełnione informacje i kliknij Utwórz.
Jeśli indeks wektorowy jest wymagany, 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.
Role i uprawnienia
Zanim utworzysz indeks w Cloud Firestore, upewnij się, że masz przypisaną jedną z tych ról:
roles/datastore.ownerroles/datastore.indexAdminroles/editorroles/owner
Jeśli masz zdefiniowane role niestandardowe, przypisz wszystkie te uprawnienia, aby utworzyć indeksy:
datastore.indexes.createdatastore.indexes.deletedatastore.indexes.getdatastore.indexes.listdatastore.indexes.update
Korzystanie z konsoli Firebase
Aby ręcznie utworzyć nowy indeks w konsoli Firebase:
- W konsoli Firebase kliknij Databases & Storage (Bazy danych i miejsce na dane) > Firestore.
- Na karcie Indeksy kliknij Dodaj indeks.
- Wpisz nazwę kolekcji i ustaw pola, według których chcesz uporządkować indeks.
- 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 wieloskładnikowe. Jeśli nadal trwa ich tworzenie, w konsoli Firebase widoczny jest pasek stanu.
Usuwanie indeksów
Aby usunąć indeks:
- W konsoli Firebase kliknij Databases & Storage (Bazy danych i miejsce na dane) > Firestore.
- Na karcie Indeksy najedź kursorem na indeks, który chcesz usunąć, i w menu kontekstowym wybierz Usuń.
- Potwierdź, że chcesz usunąć, klikając Usuń w oknie alertu.
Korzystanie z wiersza poleceń Firebase
Indeksy możesz też wdrażać za pomocą interfejsu 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 prawidłowym formacie. Edytuj plik, aby dodać więcej indeksów, i wdróż go za pomocą polecenia firebase deploy.
Aby wdrożyć tylko indeksy i reguły Cloud Firestore, dodaj flagę --only firestore.
Jeśli wprowadzisz zmiany w indeksach za pomocą 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ć zarówno indeksy jednopolowe (automatyczne), jak i złożone (ręczne). Możesz edytować plik konfiguracji Terraform, aby utworzyć indeks bazy danych. Indeksy automatyczne i ręczne używają różnych typów zasobów Terraform (google_firestore_index i google_firestore_field).
Indeks pojedynczego pola (automatyczny)
Ten przykładowy plik konfiguracji Terraform tworzy indeks jednopolowy 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 (ręczny)
Ten przykładowy plik konfiguracji Terraform tworzy indeks wielopolowy dla kombinacji pól name i 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, Cloud Firestore musi go skonfigurować, a następnie wypełnić istniejącymi danymi. Czas tworzenia indeksu to suma czasu konfiguracji i czasu wypełniania:
Konfigurowanie indeksu zajmuje kilka minut. Minimalny czas tworzenia indeksu to kilka minut, nawet w przypadku pustej bazy danych.
Czas uzupełniania zależy od ilości istniejących danych, które należą do nowego indeksu. Im więcej wartości pól pasuje do definicji indeksu, tym dłużej trwa jego uzupełnianie.
Tworzenie indeksów to długo trwająca operacja.
Po rozpoczęciu tworzenia indeksu Cloud Firestore przypisuje operacji unikalną nazwę. Nazwy operacji są poprzedzone prefiksem projects/[PROJECT_ID]/databases/(default)/operations/, na przykład:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Możesz jednak pominąć prefiks, gdy podajesz nazwę operacji w poleceniu describe.
Wyświetlanie listy 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ę trwających i ostatnio zakończonych operacji. Operacje są wyświetlane przez kilka dni po ich 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 pojedynczej operacji:
gcloud firestore operations describe operation-name
Szacowanie czasu ukończenia
Podczas wykonywania operacji możesz sprawdzić 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 dla liczby dokumentów. workEstimated pokazuje szacowaną łączną liczbę dokumentów, które zostaną przetworzone w ramach operacji. workCompleted pokazuje liczbę dokumentów przetworzonych do tej pory. Po zakończeniu operacji workCompleted odzwierciedla łączną liczbę dokumentów, które zostały faktycznie przetworzone. Może ona być inna niż wartość workEstimated.
Aby uzyskać przybliżone oszacowanie postępu, podziel workCompleted przez workEstimated. Szacunkowa wartość może być niedokładna, ponieważ zależy od opóźnionego zbierania statystyk.
Oto przykład stanu 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"
}
},
},
...
Po zakończeniu operacji jej opis będzie zawierać "done":
true. Wynik operacji znajdziesz w polu state. Jeśli pole done nie jest ustawione w odpowiedzi, jego wartość to false. Nie polegaj na istnieniu wartości done w przypadku operacji w toku.
Błędy tworzenia indeksu
Podczas zarządzania indeksami ręcznymi i wykluczeniami indeksów automatycznych mogą wystąpić błędy tworzenia indeksów. Operacja indeksowania może się nie powieść, jeśli Cloud Firestore napotka problem z indeksowanymi danymi. Najczęściej oznacza to, że został osiągnięty limit indeksów. Operacja mogła na przykład osiągnąć maksymalną liczbę wpisów indeksu na dokument.
Jeśli utworzenie indeksu się nie powiedzie, w konsoli pojawi się komunikat o błędzie. Po sprawdzeniu, że nie przekraczasz żadnych limitów indeksowania, spróbuj ponownie wykonać operację indeksowania.