Cloud Firestore обеспечивает производительность запросов, требуя индекс для каждого запроса. Индексы, необходимые для самых простых запросов, автоматически создаются для вас. По мере использования и тестирования вашего приложения Cloud Firestore генерирует сообщения об ошибках, которые помогают вам создавать дополнительные индексы, необходимые вашему приложению. На этой странице описывается, как управлять индексами с одним полем , составными и векторными индексами.
Создать отсутствующий индекс с помощью сообщения об ошибке
Если вы попытаетесь выполнить составной запрос с предложением диапазона, которое не сопоставляется с существующим индексом, вы получите ошибку. Сообщение об ошибке включает прямую ссылку для создания отсутствующего индекса в консоли Firebase.
Перейдите по сгенерированной ссылке в консоль Firebase, просмотрите автоматически заполненную информацию и нажмите «Создать» .
В случае, если требуется векторный индекс, сообщение об ошибке будет включать команду Google Cloud CLI для создания отсутствующего векторного индекса. Запустите команду для создания отсутствующего индекса.
Роли и разрешения
Прежде чем создать индекс в Cloud Firestore , убедитесь, что вам назначена одна из следующих ролей:
-
roles/datastore.owner -
roles/datastore.indexAdmin -
roles/editor -
roles/owner
Если вы определили пользовательские роли, назначьте все следующие разрешения для создания индексов:
-
datastore.indexes.create -
datastore.indexes.delete -
datastore.indexes.get -
datastore.indexes.list -
datastore.indexes.update
Используйте консоль Firebase
Чтобы вручную создать новый индекс из консоли Firebase:
- Перейдите в раздел Cloud Firestore консоли Firebase .
- Перейдите на вкладку «Индексы» и нажмите «Добавить индекс» .
- Введите название коллекции и укажите поля, по которым вы хотите упорядочить индекс.
- Нажмите «Создать» .
Поля индекса должны соответствовать ограничениям на пути полей .
Создание индексов может занять несколько минут, в зависимости от размера запроса. После их создания вы можете увидеть свои индексы и их статус в разделе Composite Indexes. Если они все еще строятся, консоль Firebase включает строку состояния построения.
Удалить индексы
Чтобы удалить индекс:
- Перейдите в раздел Cloud Firestore консоли Firebase .
- Перейдите на вкладку «Индексы» .
- Наведите указатель мыши на индекс, который вы хотите удалить, и выберите «Удалить» в контекстном меню.
- Подтвердите, что вы хотите удалить его, нажав «Удалить» в оповещении.
Используйте Firebase CLI
Вы также можете развернуть индексы с помощью Firebase CLI . Чтобы начать, запустите firebase init firestore в каталоге вашего проекта. Во время настройки Firebase CLI генерирует файл JSON с индексами по умолчанию в правильном формате. Отредактируйте файл, чтобы добавить больше индексов, и разверните его с помощью команды firebase deploy .
Чтобы развернуть только индексы и правила Cloud Firestore , добавьте флаг --only firestore .
Если вы вносите изменения в индексы с помощью консоли Firebase, убедитесь, что вы также обновили локальный файл индексов. Обратитесь к справочнику по определению индекса JSON .
Использовать Терраформ
Создание индексов в базе данных
Базы данных Cloud Firestore могут включать как индексы с одним полем, так и составные индексы. Вы можете отредактировать файл конфигурации Terraform, чтобы создать индекс для своей базы данных. Индексы с одним полем и составные индексы используют различные типы ресурсов Terraform ( google_firestore_index и google_firestore_field ).
Индекс одного поля
В следующем примере файла конфигурации Terraform создается индекс из одного поля по полю name в коллекции 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 {}
}
- Замените project-id на идентификатор вашего проекта. Идентификаторы проектов должны быть уникальными.
- Замените database-id на идентификатор вашей базы данных.
Композитный индекс
В следующем примере файла конфигурации Terraform создается составной индекс для комбинации поля name и поля description в коллекции 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"
}
}
- Замените project-id на идентификатор вашего проекта. Идентификаторы проектов должны быть уникальными.
- Замените database-id на идентификатор вашей базы данных.
Векторный индекс
В следующем примере файла конфигурации Terraform создается векторный индекс для поля embedding в коллекции 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 {}
}
}
}
- Замените project-id на идентификатор вашего проекта. Идентификаторы проектов должны быть уникальными.
- Замените database-id на идентификатор вашей базы данных.
Время построения индекса
Чтобы построить индекс, Cloud Firestore должен настроить индекс, а затем заполнить индекс существующими данными. Время построения индекса — это сумма времени настройки и времени заполнения:
Настройка индекса занимает несколько минут. Минимальное время построения индекса составляет несколько минут, даже для пустой базы данных.
Время обратного заполнения зависит от того, сколько существующих данных принадлежит новому индексу. Чем больше значений полей, соответствующих определению индекса, тем больше времени требуется для обратного заполнения индекса.
Создание индекса — это длительная операция .
После запуска построения индекса Cloud Firestore присваивает операции уникальное имя. Имена операций начинаются с projects/[PROJECT_ID]/databases/(default)/operations/ , например:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Однако вы можете опустить префикс при указании имени операции для команды describe .
Список всех длительных операций
Чтобы составить список долгосрочных операций, используйте команду gcloud firestore operations list . Эта команда выводит список текущих и недавно завершенных операций. Операции выводятся в течение нескольких дней после завершения:
gcloud firestore operations list
Проверить статус операции
Вместо того чтобы перечислять все длительные операции, вы можете перечислить подробности одной операции:
gcloud firestore operations describe operation-name
Оценка времени завершения
Во время выполнения операции смотрите значение поля state для получения общего статуса операции.
Запрос статуса длительной операции также возвращает метрики workEstimated и workCompleted . Эти метрики возвращаются для количества документов. workEstimated показывает предполагаемое общее количество документов, которые будет обработаны операцией. workCompleted показывает количество обработанных на данный момент документов. После завершения операции workCompleted отражает общее количество фактически обработанных документов, которое может отличаться от значения workEstimated .
Разделите workCompleted на workEstimated для приблизительной оценки прогресса. Оценка может быть неточной, поскольку она зависит от задержки сбора статистики.
Например, вот статус выполнения построения индекса:
{
"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"
}
},
},
...
Когда операция выполнена, описание операции будет содержать "done": true . Смотрите значение поля state для результата операции. Если поле done не задано в ответе, то его значение равно false . Не полагайтесь на существование значения done для выполняемых операций.
Ошибки построения индекса
Вы можете столкнуться с ошибками построения индекса при управлении составными индексами и исключениями индексов с одним полем. Операция индексирования может завершиться неудачей, если Cloud Firestore столкнется с проблемой с индексируемыми данными. Чаще всего это означает, что вы достигли предела индекса . Например, операция могла достичь максимального количества записей индекса на документ.
Если создание индекса не удается, вы увидите сообщение об ошибке в консоли. После того, как вы убедитесь, что не достигли никаких ограничений индекса , повторите операцию индекса.