Cloud Firestore zapewnia wydajność zapytań, wymagając indeksu dla każdego zapytania. Indeksy wymagane w przypadku 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 automatycznymi, ręcznymi 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 powiązana z istniejącym indeksem, 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 wektorowy, komunikat o błędzie będzie zawierać Google Cloud CLI polecenie służące do utworzenia brakującego indeksu wektorowego. 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 móc tworzyć 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:
- 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 sortować 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 zobaczyć wraz z ich stanem w sekcji Indeksy złożone. Jeśli indeksy są nadal tworzone, w konsoli Firebase wyświetla się pasek stanu tworzenia.
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 kontekstowym wybierz Usuń.
- 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 wiersz 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 edytujesz indeksy w konsoli Firebase, pamiętaj, aby zaktualizować też lokalny plik indeksów. Zapoznaj się z dokumentacją definicji indeksu w formacie JSON.
Użyj Terraform
Tworzenie indeksów w bazie danych
Cloud Firestore bazy danych mogą zawierać indeksy pojedynczego pola (automatyczne) i indeksy złożone (ręczne). Aby utworzyć indeks dla bazy danych, możesz edytować plik konfiguracji Terraform. 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 pojedynczego 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 (ręczny)
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 kompilacji indeksu
Aby utworzyć indeks, Cloud Firestore musi go skonfigurować, a następnie uzupełnić go istniejącymi danymi. Czas tworzenia indeksu to suma czasu konfiguracji i czasu uzupełniania:
Konfigurowanie indeksu trwa kilka minut. Minimalny czas tworzenia indeksu to kilka minut, nawet w przypadku pustej bazy danych.
Czas uzupełniania zależy od tego, ile istniejących danych należy umieścić w nowym indeksie. 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ące operacje.
Po rozpoczęciu tworzenia indeksu 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
Podczas określania nazwy operacji w poleceniu describe możesz jednak pominąć prefiks.
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ę operacji w toku i ostatnio zakończonych. 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 pojedynczej operacji:
gcloud firestore operations describe operation-name
Szacowanie czasu zakończenia
Podczas wykonywania operacji sprawdzaj wartość pola state field
aby poznać ogólny stan operacji.
Prośba o stan długo trwającej operacji zwraca też dane workEstimated i workCompleted. Te dane są zwracane w przypadku liczby dokumentów. workEstimated pokazuje szacunkową łączną liczbę dokumentów, które zostaną przetworzone przez operację. workCompleted
pokazuje liczbę dokumentów, które zostały już przetworzone. Po zakończeniu operacji workCompleted odzwierciedla łączną liczbę dokumentów, które zostały faktycznie przetworzone. Może się ona różnić od wartości workEstimated.
Aby uzyskać przybliżone oszacowanie postępu, podziel workCompleted przez workEstimated. Oszacowanie może być niedokładne, 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 się zakończy, jej opis będzie zawierać "done":
true. Aby poznać wynik operacji, sprawdź 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 tworzenia indeksu
Podczas zarządzania indeksami ręcznymi i wykluczeniami indeksów automatycznych mogą wystąpić błędy tworzenia indeksu. 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 indeksu. Operacja mogła na przykład osiągnąć maksymalną liczbę wpisów indeksu na dokument.
Jeśli utworzenie indeksu się nie powiedzie, w konsoli zobaczysz komunikat o błędzie. Po sprawdzeniu, że nie osiągasz żadnych limitów indeksu, spróbuj ponownie wykonać operację na indeksie.