Google is committed to advancing racial equity for Black communities. See how.

Manage indexes in Cloud Firestore

Cloud Firestore ensures query performance by requiring an index for every query. The indexes required for the most basic queries are automatically created for you. As you use and test your app, Cloud Firestore generates error messages that help you create additional indexes your app requires. This page describes how to manage your single-field and composite indexes.

Create a missing index through an error message

If you attempt a compound query with a range clause that doesn't map to an existing index, you receive an error. The error message includes a direct link to create the missing index in the Firebase console.

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

Use the Firebase console

To manually create a new index from the Firebase console:

image of the
firestore indexing interface in the firebase console

  1. Go to the Cloud Firestore section of the Firebase console.
  2. Go to the Indexes tab and click Add Index.
  3. Enter the collection name and set the fields you want to order the index by.
  4. Click Create.

Indexes can take a few minutes to build, depending on the size of the query. After you create them, you can see your indexes and their status in the Composite Indexes section. If they're still building, the Firebase console includes a building status bar.

Remove indexes

To delete an index:

  1. Go to the Cloud Firestore section of the Firebase console.
  2. Click the Indexes tab.
  3. Hover over the index you want to delete and select Delete from the context menu.
  4. Confirm that you want to delete it by clicking Delete from the alert.

Use the Firebase CLI

You can also deploy indexes with the Firebase CLI. To get started, run firebase init firestore in your project directory. During setup, the Firebase CLI generates a JSON file with the default indexes in the correct format. Edit the file to add more indexes and deploy it with the firebase deploy command. If you only want to deploy indexes, add the --only firestore:indexes 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.

Index build time

Index creation takes at least few minutes and can take a substantial amount of time depending on how much data needs to be updated. The more documents that match the fields being indexed, the longer creation takes. Thus index builds are long-running operations. Also, for each unique collection ID, you can have only one index build in progress. Multiple index builds on the same collection ID complete sequentially.

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

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 datastore operations list

Check operation status

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

gcloud datastore 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. These metrics are returned for the number of documents. 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.

Divide workCompleted by workEstimated for a rough progress estimate. The estimate might be inaccurate because it depends on delayed statistics collection.

For example, here is the progress status of an index build:

{
  "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 is done, 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 its value is false. Do not depend on the existence of the done value for in-progress operations.

Index building errors

You might encounter index building errors when managing composite indexes and single-field index exemptions. An indexing operation can fail if Cloud Firestore encounters a problem with the data it's indexing. Most commonly, this means you hit an index limit. For example, the operation may have reached the maximum number of index entries per document.

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.