fix(firestore): smart filtering of name fields in index listings #8860

TorbenWetter · 2025-07-17T12:28:48Z

Problem

The recent fix for #7629 introduced a regression where firebase deploy --only firestore fails with "409 index already exists" errors. The original fix was too aggressive, preserving ALL __name__ fields instead of filtering intelligently.

Root Cause

The previous implementation completely removed the filtering logic for __name__ fields. While this fixed the duplicate index issue (#7629), it introduced deployment conflicts because:

The API returns indexes with explicit __name__ fields
User spec files typically don't include implicit __name__ fields
The comparison logic treated these as different indexes
Deployment attempted to create "new" indexes that already existed

Solution

This PR implements smart filtering that:

Keeps __name__ fields with DESCENDING order (explicit/meaningful)
Removes __name__ fields with ASCENDING order (implicit/default)
Fixes both duplicate index issues (Incorrect firebase firestore:indexes output generated #7629) and deployment conflicts (firebase deploy --only firestore fails with 409 error on existing indexes in firebase-tools v14.11.0 #8859)

Implementation

The fix modifies the listIndexes method in src/firestore/api.ts to filter __name__ fields intelligently:

const fields = index.fields.filter((field: types.IndexField) => {
  if (field.fieldPath !== "__name__") {
    return true;
  }
  return field.order === types.Order.DESCENDING;
});

Changes

Enhanced listIndexes method with intelligent __name__ field filtering
Added 5 comprehensive test cases covering all scenarios
Updated changelog with user-facing documentation

Testing

All existing tests pass with no regressions
New test suite IndexListingWithNameFields validates the fix
Covers filtering, preservation, and edge cases
Handles various index configurations correctly

Impact

This change is backward compatible and isolated to index listing logic. It resolves the critical deployment failures in v14.11.0 while maintaining the semantic meaning of indexes.

Fixes #7629, #8859

google-cla · 2025-07-17T12:28:52Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

gemini-code-assist

Summary of Changes

Hello @TorbenWetter, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a crucial fix for Firestore index deployments by refining how __name__ fields are handled during index listing. It introduces a 'smart filtering' mechanism that differentiates between explicit and implicit __name__ fields, thereby resolving deployment conflicts and duplicate index errors. The change is backward compatible and isolated to the index listing logic, ensuring more robust and reliable Firestore deployments.

Highlights

Firestore Index Listing Fix: Addresses a critical regression that caused firebase deploy --only firestore to fail with "409 index already exists" errors, stemming from an overly aggressive previous fix for duplicate index issues.
Intelligent __name__ Field Filtering: The listIndexes method in src/firestore/api.ts has been enhanced to intelligently filter __name__ fields. It now preserves __name__ fields with DESCENDING order (which are explicitly defined and meaningful) while removing those with ASCENDING order (which are implicit and default).
Comprehensive Test Coverage: Five new, comprehensive test cases have been added to src/firestore/indexes.spec.ts under a new IndexListingWithNameFields suite. These tests validate the intelligent filtering logic across various scenarios, including handling of both ASCENDING and DESCENDING __name__ fields, and ensuring correct distinction between indexes.
Problem Resolution: This change successfully resolves both the duplicate index issue (#7629) and the deployment conflicts (#8859) by ensuring that the comparison logic for Firestore indexes accurately reflects user specifications and API responses.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request addresses a regression by intelligently filtering __name__ fields from Firestore index listings. The core logic change in src/firestore/api.ts is correct and aligns with the PR description.

I've provided two main pieces of feedback:

A suggestion to refactor the implementation in src/firestore/api.ts for better type safety and conciseness.
A more critical point regarding the new tests in src/firestore/indexes.spec.ts. The tests currently duplicate the production logic, which means they aren't actually testing the implementation. I've recommended a refactoring approach to ensure the tests are correctly verifying the production code.

Overall, the fix is good, but the testing approach needs to be improved to ensure long-term maintainability.

src/firestore/indexes.spec.ts

src/firestore/api.ts

Preserve __name__ fields with DESCENDING order while filtering out implicit ASCENDING ones to fix deployment conflicts. - Fixes duplicate index issues (firebase#7629) - Fixes deployment conflicts (firebase#8859) - Add comprehensive test coverage Fixes firebase#7629, firebase#8859

Refactored __name__ field filtering from listIndexes into static method FirestoreApi.processIndexes() to ensure tests verify production code rather than duplicating the implementation.

Simplified the filter expression in processIndexes() to a single boolean expression as suggested in PR feedback for better readability and conciseness.

aalej · 2025-07-17T15:42:39Z

Thanks for opening up this PR @TorbenWetter!

I'm testing the changes and it seems like the error is still occurring. Tried with indexes

firestore.indexes.json

{
  "indexes": [
    {
      "collectionGroup": "widgets",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "foo", "arrayConfig": "CONTAINS" },
        { "fieldPath": "bar", "mode": "DESCENDING" }
      ]
    },
    {
      "collectionGroup": "widgets",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "foo", "arrayConfig": "CONTAINS" },
        { "fieldPath": "bar", "mode": "ASCENDING" }
      ]
    }
  ]
}

Run firebase deploy --only firestore:indexes

$ firebase deploy --only firestore:indexes

=== Deploying to 'PROJECT_ID'...

i  deploying firestore
i  firestore: reading indexes from firestore.indexes.json...
i  cloud.firestore: checking firestore.rules for compilation errors...
✔  cloud.firestore: rules file firestore.rules compiled successfully
i  firestore: deploying indexes...
✔  firestore: deployed indexes in firestore.indexes.json successfully for (default) database

✔  Deploy complete!

Wait a couple of minutes to let the indexes build
- Status can be checked in https://console.firebase.google.com/project/PROJECT_ID/firestore/databases/-default-/indexes
Run firebase deploy --only firestore:indexes again

$ firebase deploy --only firestore:indexes

=== Deploying to 'PROJECT_ID'...

i  deploying firestore
i  firestore: reading indexes from firestore.indexes.json...
i  cloud.firestore: checking firestore.rules for compilation errors...
✔  cloud.firestore: rules file firestore.rules compiled successfully
i  firestore: deploying indexes...
i  firestore: The following indexes are defined in your project but are not present in your firestore indexes file:
        (widgets) -- (foo,CONTAINS) (bar,DESCENDING)
✔ Would you like to delete these indexes? Selecting no will continue the rest of the deployment. No

Error: Request to https://firestore.googleapis.com/v1/projects/PROJECT_ID/databases/(default)/collectionGroups/widgets/indexes had HTTP Error: 409, index already exists

joehan

Taking a closer look at the issue @aalej found.

CHANGELOG.md

joehan · 2025-07-17T16:24:53Z

Hmmm, it seems like the behavior here is tricker than we initially realized - in the example @aalej shared, the 'implied' direction for name is decending when the other fields are descending

I'm gonna test out some minor changes to this PR to make it follow that behavior, and check with someone on the firestore team to confirm this behavior.

joehan · 2025-07-17T16:27:20Z

Ahhh, turns out we documented it - https://firebase.google.com/docs/firestore/query-data/index-overview#default_ordering_and_the_name_field the default ordering follows the ordering of the last field in the index.

aalej · 2025-07-17T16:43:39Z

I think in issue #7629, there's an instance where the default ordering for __name__ did not follow the last field in the index.

There's also a case where the indexes deployed changed, here's a repro - #8758 (comment)

github-project-automation bot added this to [Cloud] Extensions + Functions Jul 17, 2025

gemini-code-assist bot reviewed Jul 17, 2025

View reviewed changes

src/firestore/indexes.spec.ts Outdated Show resolved Hide resolved

src/firestore/api.ts Outdated Show resolved Hide resolved

TorbenWetter force-pushed the fix/firestore-name-field-filtering branch from 9120ded to f127fba Compare July 17, 2025 12:41

TorbenWetter added 2 commits July 17, 2025 15:04

refactor(firestore): extract index filtering logic to static method

5290d41

Refactored __name__ field filtering from listIndexes into static method FirestoreApi.processIndexes() to ensure tests verify production code rather than duplicating the implementation.

refactor(firestore): simplify processIndexes filter logic

fce1b90

Simplified the filter expression in processIndexes() to a single boolean expression as suggested in PR feedback for better readability and conciseness.

TorbenWetter mentioned this pull request Jul 17, 2025

firebase deploy --only firestore fails with 409 error on existing indexes in firebase-tools v14.11.0 #8859

Closed

joehan approved these changes Jul 17, 2025

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

github-project-automation bot moved this to Approved [PR] in [Cloud] Extensions + Functions Jul 17, 2025

Update CHANGELOG.md

7a21aaa

joehan mentioned this pull request Jul 17, 2025

Correct handling of __name__ in firestore indexes #8862

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(firestore): smart filtering of name fields in index listings #8860

fix(firestore): smart filtering of name fields in index listings #8860

Uh oh!

TorbenWetter commented Jul 17, 2025

Uh oh!

google-cla bot commented Jul 17, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

aalej commented Jul 17, 2025

Uh oh!

joehan left a comment •

edited

Loading

Uh oh!

Uh oh!

joehan commented Jul 17, 2025

Uh oh!

joehan commented Jul 17, 2025

Uh oh!

aalej commented Jul 17, 2025

Uh oh!

Uh oh!

fix(firestore): smart filtering of __name__ fields in index listings #8860

Are you sure you want to change the base?

fix(firestore): smart filtering of __name__ fields in index listings #8860

Uh oh!

Conversation

TorbenWetter commented Jul 17, 2025

Problem

Root Cause

Solution

Implementation

Changes

Testing

Impact

Uh oh!

google-cla bot commented Jul 17, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

aalej commented Jul 17, 2025

Uh oh!

joehan left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

joehan commented Jul 17, 2025

Uh oh!

joehan commented Jul 17, 2025

Uh oh!

aalej commented Jul 17, 2025

Uh oh!

Uh oh!

fix(firestore): smart filtering of name fields in index listings #8860

fix(firestore): smart filtering of name fields in index listings #8860

joehan left a comment •

edited

Loading