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 .
- Перейдите на вкладку «Индексы» и нажмите «Добавить индекс» .
- Введите название коллекции и задайте поля, по которым вы хотите упорядочить индекс.
- Нажмите «Создать» .
Поля индекса должны соответствовать ограничениям на пути полей .
Построение индексов может занять несколько минут, в зависимости от размера запроса. После создания индексов вы можете увидеть их состояние в разделе «Составные индексы». Если процесс построения всё ещё продолжается, в консоли 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 столкнётся с проблемой индексируемых данных. Чаще всего это означает, что достигнут предел индекса . Например, операция могла достичь максимального количества записей индекса на документ.
Если создание индекса не удалось, вы увидите сообщение об ошибке в консоли. Убедившись, что вы не достигли ограничений индекса , повторите операцию по его созданию.