Analyzing Firestore

Firestore Analysis Skill

Analyze and optimize Firestore databases with safe, read-only operations.

MANDATORY: Two-Phase Execution

You MUST follow this two-phase pattern. Skipping Phase 1 causes hallucinated collection/field names.

Phase 1: Discovery (ALWAYS run first)

#!/bin/bash

# 1. List Firestore databases
gcloud firestore databases list --project="$GCP_PROJECT"

# 2. List root collections
gcloud firestore indexes composite list --project="$GCP_PROJECT" --database="$DB_NAME" 2>/dev/null

# 3. List collection groups (via REST API)
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://firestore.googleapis.com/v1/projects/$GCP_PROJECT/databases/$DB_NAME/collectionGroups"

# 4. Sample documents from a collection
gcloud firestore export gs://"$BUCKET"/sample --collection-ids="my_collection" --project="$GCP_PROJECT" 2>/dev/null

# OR via REST API for direct document read
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://firestore.googleapis.com/v1/projects/$GCP_PROJECT/databases/(default)/documents/my_collection?pageSize=5"

Phase 1 outputs:

• Firestore databases and their modes (Native/Datastore)
• Root collections
• Sample documents to understand actual field names

Phase 2: Analysis (only after Phase 1)

Only reference collections, documents, and fields confirmed in Phase 1.

Shell Script Patterns

Helper Function

#!/bin/bash

# Firestore REST API helper — always use this
firestore_api() {
    local path="$1"
    local method="${2:-GET}"
    curl -s -X "$method" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        "https://firestore.googleapis.com/v1/projects/${GCP_PROJECT}/databases/${FIRESTORE_DB:-(default)}/$path"
}

# gcloud Firestore helper
firestore_cmd() {
    gcloud firestore "$@" --project="${GCP_PROJECT}" --database="${FIRESTORE_DB:-(default)}"
}

Anti-Hallucination Rules

• NEVER reference a collection without confirming it exists via API discovery
• NEVER reference field names without seeing them in sample documents
• NEVER assume document IDs — always list documents first
• NEVER guess index configurations — always check composite indexes
• NEVER assume database mode — check if Native or Datastore mode

Safety Rules

• READ-ONLY ONLY: Use only GET requests, gcloud list/describe commands
• FORBIDDEN: POST/PATCH/DELETE to documents, gcloud firestore delete, index creation without explicit user request
• ALWAYS use pageSize parameter to limit document reads
• Monitor read costs — each document read is billed
• Use field masks to read only necessary fields and reduce read costs

Common Operations

Database Overview

#!/bin/bash
echo "=== Firestore Databases ==="
gcloud firestore databases list --project="$GCP_PROJECT" --format="table(name,type,locationId,deleteProtectionState)"

echo ""
echo "=== Composite Indexes ==="
firestore_cmd indexes composite list --format="table(name,queryScope,state,fields)"

echo ""
echo "=== Field Indexes ==="
firestore_cmd indexes fields list --format="table(name,indexConfig)" 2>/dev/null

Collection Analysis

#!/bin/bash
COLLECTION="${1:-my_collection}"

echo "=== Sample Documents from $COLLECTION ==="
firestore_api "documents/$COLLECTION?pageSize=5" | jq '.documents[]? | {name: .name, fields: (.fields | keys), createTime, updateTime}'

echo ""
echo "=== Document Count (sampled) ==="
firestore_api "documents/$COLLECTION?pageSize=1&mask.fieldPaths=__name__" | jq '.documents | length'

Security Rules Review

#!/bin/bash
echo "=== Current Security Rules ==="
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://firestore.googleapis.com/v1/projects/$GCP_PROJECT/databases/(default)/documents:runQuery" \
    -X POST -d '{}' 2>/dev/null

# Download rules via Firebase CLI if available
firebase firestore:get-rules --project="$GCP_PROJECT" 2>/dev/null || echo "Firebase CLI not available"

Usage Metrics

#!/bin/bash
echo "=== Firestore Read/Write Metrics (last 1h) ==="
gcloud monitoring time-series list \
    --project="$GCP_PROJECT" \
    --filter='metric.type="firestore.googleapis.com/document/read_count"' \
    --interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
    --format="table(metric.labels,points.value)"

echo ""
echo "=== Active Connections ==="
gcloud monitoring time-series list \
    --project="$GCP_PROJECT" \
    --filter='metric.type="firestore.googleapis.com/network/active_connections"' \
    --interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
    --format="table(points.value)" 2>/dev/null

Output Format

Present results as a structured report:

Analyzing Firestore Report
══════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Common Pitfalls

• Billing on reads: Every document read (including list operations) is billed — use field masks and page limits
• No COUNT without reading: Firestore lacks native count — counting requires reading all documents (use aggregation queries in newer versions)
• Composite index limits: Maximum 200 composite indexes per database — plan indexes carefully
• Subcollection queries: Collection group queries require composite indexes — check before querying across subcollections
• Document size limit: 1MB per document — check for documents approaching this limit
• Security rules: Open rules (allow read, write: if true) are a security risk — always review