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

Create a missing index through an error message

If you attempt acompound 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 themissing index in the Firebase console.

• 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

Use the Firebase console

To manually create a new index from the Firebase console:

1. Go to theCloud Firestore section of theFirebase console.
2. Go to theIndexes tab and clickAdd Index.
3. Enter the collection name and set the fields you want to order the index by.
4. ClickCreate.

Index fieldsmust conform to theconstraints on field paths.

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 theComposite Indexes section. If they're still building, the Firebase console includesa building status bar.

Remove indexes

To delete an index:

1. Go to theCloud Firestore section of theFirebase console.
2. Click theIndexes tab.
3. Hover over the index you want to delete and selectDelete from the context menu.
4. Confirm that you want to delete it by clickingDelete from the alert.

Use the Firebase CLI

You can also deploy indexes with theFirebase CLI.To get started, runfirebase init firestore in your project directory.During setup, the Firebase CLI generates a JSON file with the defaultindexes in the correct format. Edit the file to add more indexes and deploy itwith thefirebase deploy command.

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

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

Use Terraform

Creating indexes in the database

Cloud Firestore databases can include both single-field and composite indexes. You can edit the Terraform configuration file to create an index for your database.Single-field and composite indexes use distinct Terraform resource types(google_firestore_indexandgoogle_firestore_field).

Single-field index

The following example Terraform configuration file creates a single-field index on thename field in thechatrooms 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 {}}

• Replaceproject-id with your project ID. Project IDs must be unique.
• Replacedatabase-id with your database ID.

Composite index

The following example Terraform configuration file creates a composite index for a combination of thename field and thedescription field in thechatrooms collection:

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"  }}

• Replaceproject-id with your project ID. Project IDs must be unique.
• Replacedatabase-id with your database ID.

Vector index

The following example Terraform configuration file creates a vector index on theembedding field in thechatrooms 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 {}    }  }}

• Replaceproject-id with your project ID. Project IDs must be unique.
• Replacedatabase-id with your database ID.

Index build time

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

• Setting up an index takes a few minutes. The minimum buildtime for an index is a few minutes, even for an empty database.

• Backfill time depends on how much existing data belongs in the new index. Themore field values that match the index definition, the longer it takes tobackfill the index.

Index builds arelong-running operations.

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

To list long-running operations, use thegcloud firestore operations listcommand. 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 ofa single operation:

gcloud firestore operations describeoperation-name

Estimating the completion time

As your operation runs, see the value of thestate fieldfor the overall status of the operation.

A request for the status of a long-running operation also returns the metricsworkEstimated andworkCompleted. These metrics are returned for the numberof documents.workEstimated shows the estimated total number of documents anoperation will process.workCompletedshows the number of documents processed so far. After the operation completes,workCompleted reflects the total number of documents that wereactually processed, which might be different than the value ofworkEstimated.

DivideworkCompleted byworkEstimated for a rough progress estimate. Theestimate might be inaccurate because it depends on delayed statisticscollection.

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 thestate field forthe result of the operation. If thedone field is not set in the response,then its value isfalse. Do not depend on the existence of thedone valuefor in-progress operations.

Index building errors

You might encounter index building errors when managing composite indexes andsingle-field index exemptions. An indexing operation can fail ifCloud Firestore encounters a problem with the data it's indexing. Mostcommonly, this means you hit anindex limit. Forexample, the operation may have reached the maximum number of index entriesper document.

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