Home Mac app guides Index Advisor GUI

Index Advisor GUI

Last updated on Jul 12, 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.

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 read-oriented; live remote sync remains open until approved backend evidence exists.
  • 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