Skip to content

cloudthinker-ai/CloudSkills / skills/connections/analyzing-firestore

analyzing-firestore

Unverified

Use when working with Firestore — google Cloud Firestore collection analysis, index management, security rules review, usage metrics, and query optimization.

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

ShortcutCounterWhy
"I'll skip discovery and check known resources"Always run Phase 1 discovery firstResource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"Follow the full discovery → analysis flowQuick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"Audit configuration explicitlyDefaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"Always check relevant metrics when availableAPI/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 errorAssumed 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
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall