Manage indexes

This page describes how to manage your indexes. To learn more about indexes, see Indexes overview.

Before you begin

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

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

To grant a role, see Grant a single role. For more information about Firestore roles and associated permissions, see Predefined roles.

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

Create an index

To create an index, complete the following steps:

  1. In the Google Cloud console, go to the Databases page.

    Go to Databases

  2. Select a database from the list of databases.

  3. In the navigation menu, click Indexes.

  4. Click Create Index.

  5. Enter a Collection ID.

  6. Add one or more field paths and select an index option for each.

  7. Select a field presence option, either non-sparse or sparse..

  8. Optionally, set the multikey index option.

  9. Click Create.

Your new index is displayed in the list of indexes and Firestore with MongoDB compatibility begins creating your index. When your index is created, you will see a green check mark next to the index. If index is not created, see Index building errors for possible causes.

Delete an index

To delete an index, complete the following steps:

  1. In the Google Cloud console, go to the Databases page.

    Go to Databases

  2. Select the required database from the list of databases.

  3. In the navigation menu, click Indexes.

  4. In the list of indexes, choose Delete from the More button for the index you want to delete.

  5. Confirm that you want to delete this index by clicking Delete Index.

Index build time

To build an index, Firestore with MongoDB compatibility must create the index and then backfill the index entries with existing data. The time required to create an index is determined by the following:

  • The minimum build time for an index is a few minutes, even for an empty database.

  • The time required to backfill index entries depends on how much existing data belongs in the new index. The more field values that match the index definition, the longer it takes to backfill the index entries.

Manage long-running operations

Index builds are long-running operations. The following sections describe how to work with long-running operations for indexes.

After you start to create an index, Firestore with MongoDB compatibility assigns the operation a unique name. Operation names are prefixed with projects/PROJECT_ID/databases/DATABASE_ID/operations/, for example:

projects/PROJECT_ID/databases/DATABASE_ID/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

You can omit the prefix when specifying an operation name for the describe command.

List all long-running operations

To list long-running operations, use the gcloud firestore operations list command. This command lists ongoing and recently completed operations. Operations are listed for a few days after completion:

gcloud firestore operations list

Check operation status

Instead of listing all long-running operations, you can list the details of a single operation:

gcloud firestore operations describe operation-name

Estimating the completion time

As your operation runs, see the value of the state field for the overall status of the operation.

A request for the status of a long-running operation also returns the metrics workEstimated and workCompleted. workEstimated shows the estimated total number of documents an operation will process. workCompleted shows the number of documents processed so far. After the operation completes, workCompleted reflects the total number of documents that were actually processed, which might be different than the value of workEstimated.

To estimate an operation's progress, divide workCompleted by workEstimated.

The following is an example of the progress of creating an index:

{
  "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"
        }
       },
    },
    ...

When an operation completes, the operation description will contain "done": true. See the value of the state field for the result of the operation. If the done field is not set in the response, then the operation has not completed.