Managing indexes

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.

Note: You can manage Cloud Firestore through the Firebase console or the Google Cloud Platform Console, but these links will always open in the Firebase console.

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

Note: For non-array and non-map fields, you must select ascending or descending ordering, even if you don't need the field for ordering. Your choice doesn't impact the behavior of equalities in the query.

Use the Google Cloud Platform Console

From the Google Cloud Platform Console, you can manage single-field indexing exemptions and composite indexes.

Create a composite index

To manually create a new composite index from the GCP console:

1. Go to the Composite Indexes section.

   Go to the Composite Indexes section

2. Click Create Index.

3. Enter a Collection ID. Add the names of the fields you want to index and an index mode for each field. Click Save Index.

Your new index will show up in the list of composite indexes and Cloud Firestore will begin creating your index. When your index is done creating, you will see a green check mark next to the index.

Delete a composite index

To delete a composite index:

1. Go to the Composite Indexes section.

   Go to the Composite Indexes section

2. In the list of your composite indexes, click the entry for the index you want to delete. Click Delete.

3. Confirm that you want to delete this index by clicking Delete Index from the alert.

Add a single-field index exemption

Single-field index exemptions allow you to override automatic index settings for specific fields in a collection. You can add a single-field exemptions from the console:

1. Go to the Single Field Indexes section.

   Go to the Single Field Indexes section

2. Click Add Exemption.

3. Enter a Collection ID and Field path.

4. Select new indexing settings for this field. Enable or disable automatically updated ascending, descending, and array-contains single-field indexes for this field.

5. Click Save Exemption.

Delete a single-field index exemption

To delete a single-field index exemption, do the following:

1. In the Cloud Firestore Viewer, Go to the Single Field Indexes section.

   Go to the Single Field Indexes section

2. Click Add Exemption.

3. Enter a Collection ID and Field name.

4. In the list of your single-field index exemptions, click the entry for the exemption you want to delete. Click Delete.

5. Confirm that you want to delete this exemption by clicking Delete Exemption from the alert.

When you delete a single-field exemption, the specified field or sub-field will use inherited indexing settings. Document fields revert to your database's automatic index settings. Sub-fields in a map inherit any exemptions on parent fields before inheriting automatic index settings.

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.

Index build time

Index creation takes a few minutes, depending on how much data needs to be updated. The more documents that match the fields being indexed, the longer creation takes. 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.

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.