Home Mac app guides Firestore GUI

Firestore GUI

Last updated on Jul 12, 2026

Purpose

The Firestore module is the primary data exploration and guarded mutation workspace. It covers simple queries, JavaScript queries, table/tree/json/log output, emulator-proven document and collection CRUD/import/export/transfer/backups, live request-shape guardrails, schema analysis, and context actions.

Current status note: emulator-backed query, CRUD, import/export, transfer, table editing, column split/unsplit, table context/pasteboard/range selection, tree traversal/subcollection CRUD, direct tree context-menu create/delete, and lifecycle overwrite permutations have focused emulator proof. Phase 1 still tracks backend missing-index link rendering as partial because parser/app affordance tests exist, but real backend missing-index reproduction and UI proof require an approved live Firebase project. Phase 2 live single-document write work has service-level REST request-shape proof plus GUI/AppModel target labels, production confirmation guards, task queueing, and missing-credential task failure evidence; approved disposable live read-back/cleanup proof remains open. Live import now has JSON/CSV REST request-shape, preview, typed-confirmation, task-counter, missing-credential, and invalid-source guard evidence, but approved disposable live import read-back/cleanup remains open. Live export has GUI/AppModel source-scope preview and Pro-gate proof plus CLI request-shape/task/artifact evidence under stubbed live transport; approved disposable live export and cleanup remain open.

Query Modes

Simple Query

The simple query builder supports:

  • collection, subcollection, and document paths
  • collection group queries
  • multiple where clauses
  • multiple orderBy clauses
  • nested-field autocomplete
  • document reference values in filters
  • explicit limit, including zero for all documents
  • query validation before execution
  • saved queries
  • vector nearest-neighbor query mode when the vector search flag is enabled
  • local embedding provider configuration persistence and GUI/CLI management
  • GUI and CLI custom HTTP embedding generation for emulator collections through the task queue

Supported operators:

< <= == > >= != array-contains array-contains-any in not-in starts-with

starts-with is a prefix-search abstraction. Firestore index error parsing and UI affordances exist, and the Firestore module can send the current Simple query shape to Index Advisor without waiting for a backend error. Local embedding provider configuration is persisted per project as validated metadata only, and GUI plus CLI embedding-config set/show/delete management is available. The Vector GUI and CLI can run a custom HTTP embedding batch against Firestore emulator collections: they read the current/requested collection path, POST { "model": "...", "inputs": [...] } to the configured endpoint, write the returned numeric embedding arrays to the configured field through Firestore REST arrayValue, and report progress through Tasks. Native Firestore vector-value writes, OpenAI/Vertex execution, Firebase-proven vector ranking, and live Firestore embedding writes remain planned. Real backend missing-index link proof remains pending until an approved live Firebase run is completed.

JS Query

JS Query runs local JavaScript with an async run() entrypoint and Firestruct's Admin SDK-style local shim. It supports Firestore reads, local runtime writes/deletes/batches, emulator write-through when explicitly confirmed, count aggregation, structured returns, logs, and utility packages exposed by the bundled runtime. Live JavaScript write-through remains open until approved live Firebase verification exists.

Output Modes

  • TABLE: editable grid, column controls, inline values, selections, context actions
  • TREE: hierarchical document/collection navigation, including remembered subcollections
  • JSON: read-only structured result view
  • LOGS: transport, app, warning, error, and script logs

Table and Column Controls

Target behavior:

  • show, hide, search, and reorder columns
  • drag columns in the columns panel
  • toggle system columns such as Doc ID, createTime, updateTime, and readTime
  • split nested map fields into columns and unsplit them
  • persist column configuration in saved tab/query state
  • quick-filter visible rows
  • copy/paste cells
  • use keyboard navigation
  • multi-select rows with shift-click
  • copy field values and field names from context menus

Data Editing

Document workflows:

  • create document
  • edit fields inline
  • edit whole document as JSON
  • duplicate document
  • copy document
  • move document
  • rename document ID
  • delete document
  • reveal/open current collection or document in Firebase Console

Collection workflows:

  • create collection
  • rename collection through recursive copy and cleanup
  • duplicate/copy/move collections across projects
  • delete collections
  • include nested subcollections in recursive copy/move/rename flows

Bulk field workflows:

  • add a field with a constant value to a collection/query/selection
  • rename a field across documents
  • delete a field across documents

Move, rename, duplicate, and copy dialogs show source project/path, target project/path, source and target database/environment labels, overwrite warning, recursive subcollection behavior, estimated root count, operation semantics, and same-project path validation. Production source or target transfer plans require typing TRANSFER <source-project-id> TO <target-project-id> before queueing can proceed. Live transfer tasks resolve source and target credentials independently; approved disposable live execution and cleanup evidence remains required before production transfer parity is claimed.

Import, Export, Transfer, Backup

Export supports:

  • JSON
  • newline-delimited JSON
  • CSV
  • archive backups
  • query-result exports
  • path-scoped exports
  • document ID and resource path inclusion
  • subcollection inclusion
  • pre-export preview
  • source-scope summary with project, environment, database, path/query, limit, subcollection mode, and destination
  • optional reveal in file manager

Import supports:

  • JSON array/object roots
  • Firefoo special type syntax such as __time__, __lat__, __lon__, __ref__, bytes, and double markers
  • CSV type mapping
  • column normalization
  • root-level import from absolute document path column
  • Latin1 files
  • JSON, CSV, and archive file selection
  • target project and target path validation
  • target project/environment/database/path, overwrite mode, document count, and sample-row preview logs
  • typed live import confirmation before any live-target enqueue attempt
  • JSON and CSV live REST request-shape support with task progress; approved live read-back and cleanup remain required before completion is claimed

Transfer supports:

  • project-to-project and project-to-emulator transfers
  • selected collections
  • include/exclude subcollections
  • optional target clean first
  • document reference transformation
  • saved transfer definitions
  • context-driven direct copy/move across projects
  • copy-before-delete move semantics with separate copy/delete logs

Large imports, exports, backups, recursive mutations, and transfers run through Tasks.

Schema and Inspection Tools

The schema analyzer can inspect collection structure and generate:

  • tree schema
  • TypeScript
  • Dart
  • Kotlin
  • Java
  • Swift
  • Objective-C
  • JSON Schema

Tree tools include expand all, collapse all, and CSV export. Result views include generated header metadata.

Visualization support includes GeoPoint maps, latitude/longitude field maps, and image URL previews.

Safety

  • Read-only projects block Firestore writes and destructive actions.
  • Pro access gates writes, deletes, imports, exports, transfers, saved queries/scripts, and script execution.
  • Production mutations require confirmation.
  • Overwrite and delete behavior is never hidden.
  • Firestore production write/import/transfer support is not broadly complete yet. Single-document create/update/delete can queue for live targets through the task engine after Pro/read-only/production-confirmation checks, but approved disposable live verification is still required before live success is claimed.

Source Anchors

  • Sources/FirestructApp/Features/Firestore/UI/FirestoreModuleView.swift
  • Sources/FirestructApp/Features/Firestore/UI/FirestoreModuleView+QueryControls.swift
  • Sources/FirestructApp/Features/Firestore/UI/FirestoreModuleView+Controls.swift
  • Sources/FirestructApp/Features/Firestore/UI/FirestoreModuleView+ImportExportControls.swift
  • Sources/FirestructApp/Features/Firestore/UI/FirestoreModuleView+Outputs.swift
  • Sources/FirestructApp/Features/Firestore/Services/
  • Sources/FirestructCore/FirestoreSimpleQueryService.swift
  • Sources/FirestructCore/FirestoreDocumentWriteService.swift
  • Sources/FirestructCore/FirestoreSchemaAnalyzerService.swift
  • Sources/FirestructCore/JavaScriptQueryService.swift