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
Вы также можете развертывать индексы с помощью Firebase CLI . Для начала запустите firebase init firestore в каталоге вашего проекта. Во время установки интерфейс командной строки Firebase генерирует файл 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 . Эта команда перечисляет текущие и недавно завершенные операции. Операции перечисляются в течение нескольких дней после завершения:
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 обнаружит проблему с индексируемыми данными. Чаще всего это означает, что вы достигли предела индекса . Например, операция могла достичь максимального количества записей индекса на документ.
Если создание индекса не удалось, вы увидите сообщение об ошибке в консоли. Убедившись, что ограничения индекса не превышены, повторите операцию с индексом.