Index management in Firebase - Commands & Configuration

Introduction

When you store data in Firebase Firestore, queries can be slow if indexes are missing. Index management helps create and maintain indexes so your app finds data quickly and works smoothly.

When your app needs to search or sort data by multiple fields in Firestore.

When Firestore tells you a query requires a composite index to run.

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

When you add new query patterns that Firestore does not support by default.

When you want to keep your Firestore indexes organized and up to date.

Config File - firestore.indexes.json

firestore.indexes.json

{
  "indexes": [
    {
      "collectionGroup": "orders",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "status", "order": "ASCENDING" },
        { "fieldPath": "createdAt", "order": "DESCENDING" }
      ]
    },
    {
      "collectionGroup": "users",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "lastName", "order": "ASCENDING" },
        { "fieldPath": "firstName", "order": "ASCENDING" }
      ]
    }
  ],
  "fieldOverrides": []
}

This file defines composite indexes for Firestore queries.

indexes: Lists collections and fields to index together for faster queries.

collectionGroup: The collection name to index.

fields: Fields and their sort order to include in the index.

queryScope: Limits the index to the collection only.

Commands

Lists all current indexes in your Firestore database so you can see what is already set up.

Terminal

firebase firestore:indexes

Expected Output

Name: projects/my-project/databases/(default)/collectionGroups/orders/indexes/abc123

State: READY



Name: projects/my-project/databases/(default)/collectionGroups/users/indexes/def456

State: READY

Uploads and applies the indexes defined in firestore.indexes.json to your Firestore database.

Terminal

firebase deploy --only firestore:indexes

Expected Output

=== Deploying to 'my-project'...



✔  firestore:indexes: Successfully deployed indexes.



Project Console: https://console.firebase.google.com/project/my-project/firestore/indexes



✔  Deploy complete!

→

--only - Deploys only the specified Firebase feature, here indexes.

Shows a detailed list of all indexes currently active in Firestore after deployment.

Terminal

firebase firestore:indexes:list

Expected Output

Collection Group: orders

  Fields:

    status (ASCENDING)

    createdAt (DESCENDING)

  State: READY



Collection Group: users

  Fields:

    lastName (ASCENDING)

    firstName (ASCENDING)

  State: READY

Key Concept

If you remember nothing else from this pattern, remember: Firestore needs indexes for complex queries, and you manage them by defining and deploying index files.

Common Mistakes

Not deploying the index file after creating or updating it.

Firestore will not use the new indexes until they are deployed, causing queries to fail or be slow.

Always run 'firebase deploy --only firestore:indexes' after changing your index definitions.

Trying to run queries that require composite indexes without creating those indexes first.

Firestore rejects queries without the needed indexes, returning an error with a link to create the index.

Use the error link to create the required index or add it manually in firestore.indexes.json and deploy.

Summary

Use firestore.indexes.json to define composite indexes for your Firestore collections.

Deploy indexes with 'firebase deploy --only firestore:indexes' to make them active.

Check existing indexes with 'firebase firestore:indexes' or 'firebase firestore:indexes:list'.