Управление индексами в Cloud Firestore

Cloud Firestore обеспечивает высокую производительность запросов, требуя создания индекса для каждого запроса. Индексы, необходимые для самых простых запросов, создаются автоматически . По мере использования и тестирования вашего приложения Cloud Firestore генерирует сообщения об ошибках, которые помогут вам создать дополнительные индексы, необходимые вашему приложению. На этой странице описано, как управлять автоматическими , ручными и векторными индексами.

Создание отсутствующего индекса на основании сообщения об ошибке

Если вы попытаетесь выполнить составной запрос с условием диапазона, которое не соответствует существующему индексу, вы получите ошибку. Сообщение об ошибке содержит прямую ссылку для создания отсутствующего индекса в консоли Firebase.

Follow the generated link to the Firebase console, review the automatically populated info, and click Create .

In the case that a vector index is required, the error message will include a Google Cloud CLI command to create the missing vector index. Run the command to create the missing index.

Роли и права доступа

Before you can create an index in Cloud Firestore , make sure that you are assigned either of the following roles:

  • roles/datastore.owner
  • roles/datastore.indexAdmin
  • roles/editor
  • roles/owner

If you have defined custom roles, assign all of the following permissions to create indexes:

  • datastore.indexes.create
  • datastore.indexes.delete
  • datastore.indexes.get
  • datastore.indexes.list
  • datastore.indexes.update

Используйте консоль Firebase.

To manually create a new index from the Firebase console:

image of the Firestore indexing interface in the Firebase console

  1. In the Firebase console, go to Databases & Storage > Firestore .
  2. На вкладке «Индексы» нажмите «Добавить индекс» .
  3. Введите название коллекции и укажите поля, по которым вы хотите упорядочить индекс.
  4. Нажмите «Создать» .

Index fields must conform to the constraints on field paths .

Создание индексов может занять несколько минут, в зависимости от размера запроса. После создания индексов и их состояния вы можете увидеть в разделе «Составные индексы» . Если процесс создания индексов еще не завершен, в консоли Firebase отобразится индикатор выполнения.

Удалить индексы

Чтобы удалить индекс:

  1. In the Firebase console, go to Databases & Storage > Firestore .
  2. In the Indexes tab, hover over the index you want to delete and select Delete from the context menu.
  3. Confirm that you want to delete it by clicking Delete from the alert.

Используйте Firebase CLI

Вы также можете развернуть индексы с помощью Firebase CLI . Для начала выполните команду firebase init firestore в каталоге вашего проекта. Во время настройки Firebase CLI сгенерирует JSON-файл с индексами по умолчанию в правильном формате. Отредактируйте файл, чтобы добавить больше индексов, и разверните его с помощью команды firebase deploy .

To deploy Cloud Firestore indexes and rules only, add the --only firestore flag.

If you make edits to the indexes using the Firebase console, make sure you also update your local indexes file. Refer to the JSON index definition reference .

Используйте Terraform

Creating indexes in the database

Базы данных Cloud Firestore могут включать как однопольные (автоматические), так и составные (ручные) индексы. Вы можете отредактировать файл конфигурации Terraform, чтобы создать индекс для вашей базы данных. Автоматические и ручные индексы используют разные типы ресурсов Terraform ( google_firestore_index и google_firestore_field ).

Single-field (automatic) index

The following example Terraform configuration file creates a single-field index on the name field in the chatrooms collection:

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 {}
}
  • Replace project-id with your project ID. Project IDs must be unique.
  • Замените 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"
  }

}
  • Replace project-id with your project ID. Project IDs must be unique.
  • Замените database-id на идентификатор вашей базы данных.

Векторный индекс

The following example Terraform configuration file creates a vector index on the embedding field in the chatrooms collection:

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 {}
    }
  }
}
  • Replace project-id with your project ID. Project IDs must be unique.
  • Replace database-id with your database ID.

Index build time

To build an index, Cloud Firestore must set up the index and then backfill the index with existing data. Index build time is the sum of setup time and backfill time:

  • Настройка индекса занимает несколько минут. Минимальное время построения индекса составляет несколько минут, даже для пустой базы данных.

  • Время заполнения индекса зависит от объема существующих данных, которые должны быть включены в новый индекс. Чем больше значений полей соответствует определению индекса, тем дольше будет занимать заполнение индекса.

Index builds are long-running operations .

After you start an index build, Cloud Firestore assigns the operation a unique name. Operation names are prefixed with projects/[PROJECT_ID]/databases/(default)/operations/ , for example:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

However, you can leave out the prefix when specifying an operation name for the describe command.

Listing all long-running operations

Для вывода списка длительно выполняющихся операций используйте команду gcloud firestore operations list . Эта команда отображает текущие и недавно завершенные операции. Операции отображаются в течение нескольких дней после завершения:

gcloud firestore operations list

Check operation status

Вместо перечисления всех длительных операций вы можете указать подробности одной конкретной операции: 

gcloud firestore operations describe operation-name

Estimating the completion time

В процессе выполнения операции отслеживайте значение поля 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 для операций, находящихся в процессе выполнения.

Index building errors

При управлении индексами, созданными вручную, и автоматическими исключениями из индексации могут возникать ошибки при построении индексов. Операция индексации может завершиться неудачей, если Cloud Firestore обнаружит проблему с индексируемыми данными. Чаще всего это означает, что вы достигли лимита индекса . Например, операция могла достичь максимального количества записей индекса на документ.

If index creation fails, you see the error message in the console. After you verify that you are not hitting any index limits , re-try your index operation.