Firestore queries and indexes in GCP - Commands & Configuration

Introduction

Firestore stores data in documents and collections. To find data quickly, Firestore uses queries. Some queries need indexes to work fast and correctly.

When you want to find documents with specific field values in a collection.

When you need to sort query results by one or more fields.

When you want to filter documents using multiple conditions on different fields.

When you want to paginate query results for a better user experience.

When Firestore tells you an index is missing for your query.

Config File - firestore.indexes.json

firestore.indexes.json

{
  "indexes": [
    {
      "collectionGroup": "my-collection",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "status", "order": "ASCENDING" },
        { "fieldPath": "createdAt", "order": "DESCENDING" }
      ]
    }
  ],
  "fieldOverrides": []
}

This file defines a composite index for the collection named my-collection. It indexes the status field in ascending order and the createdAt field in descending order. Firestore uses this index to speed up queries that filter or sort by these fields.

Commands

This command creates a composite index for the collection group 'my-collection' on the fields 'status' ascending and 'createdAt' descending. It enables Firestore to run queries filtering or sorting by these fields efficiently.

Terminal

gcloud firestore indexes create --collection-group=my-collection --field-config=fieldPath=status,order=ASCENDING --field-config=fieldPath=createdAt,order=DESCENDING

Expected Output

Creating index... This may take a few minutes.



Index created successfully.

→

--collection-group - Specifies the collection group to index.

→

--field-config - Defines each field and its sort order in the index.

Lists all Firestore indexes in your project so you can verify the new index exists.

Terminal

gcloud firestore indexes list

Expected Output

NAME: projects/my-project/databases/(default)/collectionGroups/my-collection/indexes/abcd1234

STATE: READY

FIELDS:

  - status (ASCENDING)

  - createdAt (DESCENDING)

Deletes the Firestore index with ID 'abcd1234' if you no longer need it to save resources.

Terminal

gcloud firestore indexes delete abcd1234

Expected Output

Deleting index abcd1234...

Index deleted successfully.

Key Concept

If you remember nothing else from this pattern, remember: Firestore needs indexes to run complex queries fast and you must create those indexes before running such queries.

Common Mistakes

Running a query that filters or sorts on multiple fields without creating the required composite index.

Firestore will reject the query and show an error asking for an index, causing your app to fail or hang.

Create the composite index using the gcloud command or Firestore console before running the query.

Creating an index with incorrect field order or missing fields.

The index won't match the query requirements, so Firestore will still reject the query.

Match the index fields and their order exactly to the query's filter and sort fields.

Summary

Create composite indexes to support Firestore queries with multiple filters or sorting.

Use the gcloud CLI to create, list, and delete Firestore indexes.

Always verify your indexes exist and match your query patterns to avoid query errors.