Composite index requirements in Firebase - Commands & Configuration

Introduction

When you query a database with multiple conditions, it needs a special setup called a composite index to find data fast. Without this, your queries can be slow or fail. Composite indexes tell the database how to organize data for these complex searches.

When you want to search a collection by more than one field at the same time, like filtering users by age and city.

When you use queries that combine sorting and filtering on different fields.

When your app shows lists that need to be ordered by multiple criteria.

When Firestore tells you a query needs an index to run.

When you want to improve the speed of complex queries in your Firebase app.

Config File - firestore.indexes.json

firestore.indexes.json

{
  "indexes": [
    {
      "collectionGroup": "users",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "age", "order": "ASCENDING" },
        { "fieldPath": "city", "order": "ASCENDING" }
      ]
    }
  ]
}

This file defines a composite index for the users collection. It tells Firestore to index documents by age and city in ascending order. This setup allows queries filtering or sorting by these fields together to run efficiently.

Commands

This command uploads and applies the composite index configuration to your Firebase project so Firestore can use it for queries.

Terminal

firebase deploy --only firestore:indexes

Expected Output

=== Deploying to project example-project ===



✔  firestore: indexes deployed successfully



✔  Deploy complete!

→

--only firestore:indexes - Deploys only Firestore indexes without affecting other Firebase services.

This command lists all composite indexes currently configured in your Firebase project to verify your index is active.

Terminal

firebase firestore:indexes

Expected Output

Composite Indexes:

- Collection Group: users

  Fields:

    - age (ASCENDING)

    - city (ASCENDING)

  State: READY

Deletes the composite index named users_age_city if you no longer need it or want to update it.

Terminal

firebase firestore:indexes:delete users_age_city

Expected Output

Are you sure you want to delete the index users_age_city? (y/N) y

✔  Index users_age_city deleted.

Key Concept

If you run queries filtering or sorting by multiple fields, you must create a composite index to make those queries work and run fast.

Common Mistakes

Trying to run a query with multiple filters without creating the required composite index.

Firestore will reject the query and show an error because it cannot find an index to support it.

Create the composite index in firestore.indexes.json and deploy it before running the query.

Not deploying the index file after adding or changing composite indexes.

Changes stay local and Firestore does not know about the new index, so queries still fail.

Run 'firebase deploy --only firestore:indexes' to apply index changes.

Defining composite indexes with incorrect field order or missing fields.

The index won't match the query pattern, causing errors or slow queries.

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

Summary

Define composite indexes in firestore.indexes.json to support queries with multiple filters or sorts.

Deploy indexes using 'firebase deploy --only firestore:indexes' to activate them in your project.

Use 'firebase firestore:indexes' to check index status and 'firebase firestore:indexes:delete' to remove unused indexes.