Firestore Single Field Index Exemption

Introduction

By default, Firestore automatically creates single-field indexes for every field in every document. For each non-array and non-map field, Firestore creates:

• One ascending index
• One descending index

While this makes querying flexible, there are two main reasons why you should use index exemptions:

1. Reduce Cost of Unwanted Indexes

This is the primary reason to use index exemptions. Every index consumes storage and adds write latency:

• Storage costs - Each index entry takes up space. For large collections with millions of documents, indexing unused fields wastes significant storage.
• Write latency - Index fanout (updating multiple indexes on every write) is the main contributor to write latency. Fewer indexes = faster writes.
• Billing impact - You pay for index storage. Exempting fields you never query can reduce your Firestore bill substantially.

Example: A products collection with 1 million documents, each having a description field (never queried). That’s 2 million unnecessary index entries (ascending + descending) just for one field.

2. The “Too Many Index Entries” Error

One common issue you may encounter is the error:

Too many index entries for entity

Firestore has a limit of 40,000 index entries per document. When a document exceeds this limit, writes will fail with this error.

What Causes It

Since Firestore automatically creates single-field indexes for all fields (including nested maps and array items), index entries can accumulate quickly:

• Deeply nested field structures - Each nested field in a map gets indexed
• Large arrays - Each array element creates separate index entries
• Accumulated data over time - Documents that grow (like analytics, logs, or history) can eventually hit the limit
• Composite indexes - These multiply index entries further

Example Scenario

A document storing user activity with nested data:

{
  userId: "user123",
  activities: [
    { type: "login", timestamp: ..., metadata: { device: ..., location: ... } },
    { type: "purchase", timestamp: ..., metadata: { items: [...], total: ... } },
    // ... hundreds more activities
  ]
}

Each activity and its nested fields generate multiple index entries, quickly approaching the 40,000 limit.

Solution

Add an exemption to exclude problematic fields from indexing:

{
  "fieldOverrides": [
    {
      "collectionGroup": "users",
      "fieldPath": "activities",
      "indexes": []
    }
  ]
}

Or via Firebase Console:

1. Go to Firestore > Indexes > Single field
2. Click “Add exemption”
3. Enter the collection ID and field path to exclude
4. Select query scope and confirm

For more details, see: Too Many Index Entries for Entity

When to Exempt Fields

You should exempt fields from automatic indexing when:

1. Large string fields - Fields containing long text, URLs, or descriptions
2. Large array or map fields - Complex nested data structures
3. High write-rate documents - Documents that are updated frequently
4. Fields never used in queries - Metadata, logs, or tracking fields
5. Fields only used for display - Not filtered or sorted

Common Fields to Exempt

- description, content, body (long text)
- metadata, settings, config (large maps)
- logs, history, audit trails
- base64 encoded data
- URLs, file paths
- Timestamps only used for display (not querying)

How to Configure Index Exemptions

Using firestore.indexes.json

Add exemptions in the fieldOverrides section:

{
  "indexes": [
    // Your composite indexes
  ],
  "fieldOverrides": [
    {
      "collectionGroup": "products",
      "fieldPath": "description",
      "indexes": []
    },
    {
      "collectionGroup": "orders",
      "fieldPath": "metadata",
      "indexes": []
    },
    {
      "collectionGroup": "logs",
      "fieldPath": "*",
      "indexes": []
    }
  ]
}

Exemption Options

Disable all indexing for a field:

{
  "collectionGroup": "products",
  "fieldPath": "description",
  "indexes": []
}

Disable only descending and array indexing (recommended default):

{
  "collectionGroup": "products",
  "fieldPath": "someField",
  "indexes": [
    { "order": "ASCENDING", "queryScope": "COLLECTION" }
  ]
}

Collection-level exemption for all fields:

{
  "collectionGroup": "logs",
  "fieldPath": "*",
  "indexes": []
}

Using Firebase Console

1. Go to Firebase Console > Firestore Database > Indexes
2. Click on “Single Field” tab
3. Click “Add exemption”
4. Select collection and field
5. Choose indexing settings

Best Practices

1. Audit Your Collections

Before exempting, identify:

• Which fields are actually used in queries
• Which fields have large values
• Which collections have high write rates

2. Recommended Default Strategy

For most applications, disable Descending & Array indexing by default, keeping only Ascending:

{
  "collectionGroup": "yourCollection",
  "fieldPath": "fieldName",
  "indexes": [
    { "order": "ASCENDING", "queryScope": "COLLECTION" }
  ]
}

3. Exempt Log Collections Entirely

For logging collections that are rarely queried:

{
  "collectionGroup": "webhookLogs",
  "fieldPath": "*",
  "indexes": []
},
{
  "collectionGroup": "apiLogs",
  "fieldPath": "*",
  "indexes": []
},
{
  "collectionGroup": "errorLogs",
  "fieldPath": "*",
  "indexes": []
}

4. Keep Essential Indexes

Always keep indexes for fields used in:

• where() clauses
• orderBy() clauses
• Composite index requirements

When Index is Required

Query Pattern	Index Needed?
Single field where()	Auto-indexed (can exempt if not used)
where() + orderBy() different fields	YES (composite)
Multiple where() with inequality	YES (composite)
where() same field as orderBy()	Auto-indexed

Example Configuration

Here’s a comprehensive example for a typical Shopify app:

{
  "indexes": [
    {
      "collectionGroup": "orders",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "shopId", "order": "ASCENDING" },
        { "fieldPath": "createdAt", "order": "DESCENDING" }
      ]
    }
  ],
  "fieldOverrides": [
    {
      "collectionGroup": "shops",
      "fieldPath": "settings",
      "indexes": []
    },
    {
      "collectionGroup": "shops",
      "fieldPath": "accessToken",
      "indexes": []
    },
    {
      "collectionGroup": "products",
      "fieldPath": "description",
      "indexes": []
    },
    {
      "collectionGroup": "products",
      "fieldPath": "images",
      "indexes": []
    },
    {
      "collectionGroup": "webhookLogs",
      "fieldPath": "*",
      "indexes": []
    },
    {
      "collectionGroup": "syncLogs",
      "fieldPath": "*",
      "indexes": []
    }
  ]
}

Deploying Index Changes

After updating firestore.indexes.json, deploy with:

firebase deploy --only firestore:indexes

FAQs

Will exempting indexes break existing queries?

Yes, if you exempt a field that is used in a query’s where() or orderBy() clause, that query will fail. Always check your codebase before exempting.

Can I re-enable indexing after exempting?

Yes, simply remove the exemption from fieldOverrides or update the indexes array. The field will revert to automatic indexing.

How much storage can I save?

This varies by your data. For collections with large text fields or high document counts, savings can be significant (10-30% of index storage costs).

Does this affect read performance?

No, exemptions only affect which queries are possible. Reads of exempted fields work normally.

See Also

Firestore Guides:

• Firestore TTL Guide - Auto-delete old documents to reduce storage costs

Google Cloud Functions:

• Google Cloud - Further Dive - Video tutorials on Pub/Sub, Cron jobs, Firestore Triggers
• Pub/Sub Events
• Scheduled Functions
• Firestore Trigger Events
• Cloud Storage Events
• Task Functions (Cloud Tasks)

References

• Firebase Index Types Documentation
• Manage Indexes in Firestore
• Firestore Best Practices
• Too Many Index Entries for Entity - Common error when documents have too many indexed fields