Home Mac app guides Index Advisor GUI

Index Advisor GUI

Last updated on Oct 23, 2026

Purpose

Index Advisor deterministically compares a Firestore query shape against loaded local or workspace index definitions and can parse captured query-index failure text. Deterministic checks are mandatory; AI explanations are optional overlay content.

Version 1.2: local analysis

Index Advisor is enabled in version 1.2 for local, read-only analysis. It does not fetch deployed indexes, create indexes, or change Firebase data. Local analysis is available in Free mode; persisted index caching requires Pro.

  1. Open Firestore in Simple mode and enter a collection path, filters, and ordering.
  2. Choose Analyze Index to carry the query into the Advisor without running it or waiting for an error.
  3. Open JSON and paste your firestore.indexes.json into Firestore Indexes JSON, or use Load Local Indexes with a linked workspace.
  4. Choose Analyze, then Table to inspect local coverage, field order, sort directions, and suggestions. Tree, JSON, and Logs expose the supporting details.
  5. After changing your index definitions, load or paste the updated JSON and analyze again.

No local match means the loaded definitions did not match the simplified query shape. It does not prove an index is missing from your Firebase project. Compare suggestions with deployed configuration before creating an index in Firebase Console. Live sync and verified backend missing-index handoff remain outside this release scope.

Index Advisor local query analysis

Inputs

Index Advisor works from:

  • current Firestore query shape
  • captured query/index errors
  • loaded local or workspace index definitions
  • manually entered query/index data

Outputs

  • TABLE: query clauses, required fields, and index comparison rows
  • TREE: structured query shape and index coverage explanation
  • JSON: raw index specs, parsed error data, and diagnostics
  • LOGS: load, parse, compare, warning, and error logs

Actions

Users can:

  • send the current Firestore Simple query shape from the Firestore module
  • load local or workspace index definitions when available
  • inspect why a query requires an index
  • compare filters/order clauses to loaded index definitions
  • open a captured backend index-creation URL when available
  • copy an index spec
  • verify again after index definitions change
  • review proactive warnings for likely composite-index requirements

Index Advisor should make the deterministic evidence visible before any explanation. Show the query path, filters, order clauses, loaded index set, missing fields, and Firebase error text so users can verify why a recommendation was produced.

Current-query handoff does not require a backend missing-index error: the Firestore module can send its active Simple query path, filters, and ordering to Index Advisor for deterministic analysis against the currently loaded index JSON. Backend missing-index errors can still enrich the handoff with creation URLs and raw Firebase error details when available.

Matching is deterministic and order-sensitive. An existing composite index is not treated as covering a query merely because it contains the same fields; the required field sequence must match the index prefix and orderBy directions must match. Extra trailing fields may still be present after the required prefix.

Use AI-assisted wording only as an optional overlay. The core result must remain reproducible from loaded index definitions and the query shape, which is what makes the module safe for production troubleshooting and support handoff.

Safety

  • Index loading and diagnosis are local and read-only. Live remote sync is unavailable in 1.2.
  • Index creation/deploy-style workflows are Pro-gated or routed through Workspace Link when they mutate project configuration.
  • Explanations should preserve raw deterministic evidence so users can verify the recommendation.

Source Anchors

  • Sources/FirestructApp/Features/IndexAdvisor/UI/IndexAdvisorView.swift
  • Sources/FirestructApp/Features/IndexAdvisor/Services/AppModel+IndexAdvisorActions.swift
  • Sources/FirestructApp/Features/IndexAdvisor/Model/IndexAdvisorStore.swift
  • Sources/FirestructCore/IndexAdvisorService.swift
  • Sources/FirestructCore/FirestoreIndexCreationLinkSummary.swift