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

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

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