Skip to content

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

analyzing-mongodb

Unverified

Use when working with Mongodb — mongoDB database analysis, performance tuning, query optimization, and health monitoring. Covers collection analysis, index recommendations, aggregation pipelines, replica set health, Atlas cluster management, and slow query investigation.

MongoDB Analysis Skill

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

MANDATORY: Two-Phase Execution

You MUST follow this two-phase pattern. Skipping Phase 1 causes hallucinated collection names and schema errors.

Phase 1: Discovery (ALWAYS run first)

// Run this discovery script first — NEVER skip
// Connect: mongosh "$MONGODB_URI" --quiet --eval "..."

// 1. List databases and sizes
db.adminCommand({ listDatabases: 1, nameOnly: false })
   .databases
   .forEach(d => print(d.name, d.sizeOnDisk));

// 2. List collections in target database
use targetDb;
db.getCollectionNames().forEach(c => {
    const stats = db[c].stats();
    print(c, stats.count, stats.storageSize, stats.totalIndexSize);
});

// 3. Sample schema (never assume field names)
db.collectionName.findOne();
db.collectionName.aggregate([{ $sample: { size: 5 } }]);

Phase 1 outputs:

  • List of databases and sizes
  • List of collections with document counts
  • Sample documents to understand actual field names

Phase 2: Analysis (only after Phase 1)

Only reference collections, databases, and field names confirmed in Phase 1.

Shell Script Patterns

Helper Function

#!/bin/bash

# Core MongoDB query runner — always use this
mongo_eval() {
    local db="$1"
    local script="$2"
    mongosh "$MONGODB_URI/$db" --quiet --eval "$script"
}

# Atlas CLI helper (if Atlas connection available)
atlas_cmd() {
    atlas "$@" --projectId "$MONGODB_ATLAS_PROJECT_ID" --output json
}

Anti-Hallucination Rules

  • NEVER reference a collection by name without confirming it exists via db.getCollectionNames()
  • NEVER reference a field name in queries without seeing it in a sample document
  • NEVER assume index names — always list indexes via db.collection.getIndexes()
  • NEVER assume Atlas cluster names — always run atlas clusters list first
  • ALWAYS use --quiet flag with mongosh to suppress connection banners

Safety Rules

  • READ-ONLY ONLY: Use only find, aggregate, explain, stats, currentOp, serverStatus
  • FORBIDDEN: insertMany, updateMany, deleteMany, drop, dropDatabase, createIndex without explicit user request
  • ALWAYS add .limit() to find queries — default cap at 100 documents
  • NEVER run db.collection.find() without a limit on large collections
  • Use explain() before running expensive aggregations on large collections

Common Operations

Database Health Overview

#!/bin/bash
echo "=== MongoDB Server Status ==="
mongo_eval admin "
    const s = db.serverStatus();
    print('Version:', s.version);
    print('Uptime (hours):', Math.round(s.uptime/3600));
    print('Connections active:', s.connections.current);
    print('Connections available:', s.connections.available);
    print('Ops/sec inserts:', s.opcounters.insert);
    print('Ops/sec queries:', s.opcounters.query);
    print('Ops/sec updates:', s.opcounters.update);
    print('Mem resident MB:', s.mem.resident);
    print('Mem virtual MB:', s.mem.virtual);
"

echo ""
echo "=== Replica Set Status ==="
mongo_eval admin "
    try {
        const rs = rs.status();
        rs.members.forEach(m => print(m.name, m.stateStr, m.health, m.optimeDate));
    } catch(e) { print('Not a replica set'); }
"

echo ""
echo "=== Databases ==="
mongo_eval admin "
    db.adminCommand({listDatabases:1}).databases
      .sort((a,b) => b.sizeOnDisk - a.sizeOnDisk)
      .forEach(d => print(d.name, Math.round(d.sizeOnDisk/1024/1024) + 'MB'));
"

Collection Analysis

#!/bin/bash
DB_NAME="${1:-myDatabase}"

echo "=== Collections in $DB_NAME ==="
mongo_eval "$DB_NAME" "
    db.getCollectionNames().forEach(c => {
        const stats = db[c].stats({scale: 1024*1024});
        print(c, stats.count + ' docs', Math.round(stats.storageSize) + 'MB data', Math.round(stats.totalIndexSize) + 'MB indexes');
    });
" | sort -t' ' -k3 -rn | head -20

echo ""
echo "=== Indexes per Collection ==="
mongo_eval "$DB_NAME" "
    db.getCollectionNames().forEach(c => {
        const idxs = db[c].getIndexes();
        print(c + ': ' + idxs.length + ' indexes');
        idxs.forEach(i => print('  -', JSON.stringify(i.key), i.unique ? '[UNIQUE]' : ''));
    });
"

Slow Query Analysis

#!/bin/bash
DB_NAME="${1:-myDatabase}"
SLOW_MS="${2:-100}"

echo "=== Slow Query Log (>=${SLOW_MS}ms) ==="
mongo_eval "$DB_NAME" "
    db.system.profile.find(
        { millis: { \$gte: ${SLOW_MS} } },
        { ns: 1, op: 1, millis: 1, command: 1, ts: 1 }
    )
    .sort({ millis: -1 })
    .limit(20)
    .forEach(q => {
        print(q.ts.toISOString().substr(0,19),
              q.op,
              q.ns,
              q.millis + 'ms',
              JSON.stringify(q.command || {}).substr(0,100));
    });
" 2>/dev/null || echo "Profiler not enabled. Enable with: db.setProfilingLevel(1, {slowms: ${SLOW_MS}})"

echo ""
echo "=== Currently Running Operations ==="
mongo_eval admin "
    db.currentOp({ active: true, secs_running: { \$gte: 1 } })
      .inprog
      .forEach(op => print(op.opid, op.secs_running + 's', op.op, op.ns, JSON.stringify(op.command || {}).substr(0,80)));
"

Index Effectiveness Analysis

#!/bin/bash
DB_NAME="$1"
COLLECTION="$2"

if [ -z "$DB_NAME" ] || [ -z "$COLLECTION" ]; then
    echo "Usage: $0 <database> <collection>"
    exit 1
fi

echo "=== Index Usage Stats for $DB_NAME.$COLLECTION ==="
mongo_eval "$DB_NAME" "
    // Index access stats (requires MongoDB 3.2+)
    db['$COLLECTION'].aggregate([
        { \$indexStats: {} }
    ]).forEach(i => {
        print(i.name, 'accesses:', i.accesses.ops, 'since:', i.accesses.since.toISOString().substr(0,10));
    });
"

echo ""
echo "=== Unused Indexes (0 accesses) ==="
mongo_eval "$DB_NAME" "
    db['$COLLECTION'].aggregate([{ \$indexStats: {} }])
        .toArray()
        .filter(i => i.accesses.ops == 0 && i.name != '_id_')
        .forEach(i => print('UNUSED:', i.name, JSON.stringify(i.key)));
"

echo ""
echo "=== Collection Size vs Index Size ==="
mongo_eval "$DB_NAME" "
    const s = db['$COLLECTION'].stats({scale: 1024*1024});
    print('Documents:', s.count);
    print('Data size:', Math.round(s.size) + 'MB');
    print('Storage size:', Math.round(s.storageSize) + 'MB');
    print('Index size:', Math.round(s.totalIndexSize) + 'MB');
    print('Index ratio:', Math.round(s.totalIndexSize/s.size*100) + '%');
"

Query Performance with explain()

#!/bin/bash
DB_NAME="$1"
COLLECTION="$2"

echo "=== Query Plan Analysis ==="
mongo_eval "$DB_NAME" "
    // ALWAYS use explain() before running expensive queries on large collections
    db['$COLLECTION'].find({ /* your filter here */ })
        .explain('executionStats')
        .executionStats
        |> ({
            nReturned: @.nReturned,
            executionTimeMs: @.executionTimeMillis,
            docsExamined: @.totalDocsExamined,
            keysExamined: @.totalKeysExamined,
            indexUsed: @.executionStages?.inputStage?.indexName || 'COLLSCAN'
        })
        |> print(JSON.stringify(@, null, 2));
" 2>/dev/null

# Simpler version for older mongosh
mongo_eval "$DB_NAME" "
    const plan = db['$COLLECTION'].find({}).explain('executionStats');
    const stats = plan.executionStats;
    print('Docs examined:', stats.totalDocsExamined);
    print('Docs returned:', stats.nReturned);
    print('Exec time ms:', stats.executionTimeMillis);
    print('Stage:', plan.queryPlanner.winningPlan.stage);
    if (plan.queryPlanner.winningPlan.inputStage) {
        print('Index used:', plan.queryPlanner.winningPlan.inputStage.indexName || 'NONE (COLLSCAN)');
    }
"

Atlas Cluster Management (if Atlas connection)

#!/bin/bash
echo "=== Atlas Clusters ==="
atlas clusters list 2>/dev/null | jq -r '.[] | "\(.name)\t\(.stateName)\t\(.mongoDBVersion)\t\(.providerSettings.instanceSizeName)"' || echo "Atlas CLI not configured"

echo ""
echo "=== Atlas Metrics (last 1h) ==="
CLUSTER_NAME=$(atlas clusters list 2>/dev/null | jq -r '.[0].name' || echo "")
if [ -n "$CLUSTER_NAME" ]; then
    atlas metrics process "$CLUSTER_NAME" \
        --granularity PT1M --period P1H \
        --type CONNECTIONS --type OPCOUNTER_CMD \
        2>/dev/null | jq -r '.measurements[] | "\(.name): \(.dataPoints[-1].value // 0)"'
fi

Aggregation Pipeline Examples

#!/bin/bash
DB_NAME="$1"
COLLECTION="$2"

echo "=== Document Count by Date (last 30 days) ==="
mongo_eval "$DB_NAME" "
    // Adapt date field name based on Phase 1 discovery
    db['$COLLECTION'].aggregate([
        {
            \$match: {
                createdAt: { \$gte: new Date(Date.now() - 30*24*60*60*1000) }
            }
        },
        {
            \$group: {
                _id: { \$dateToString: { format: '%Y-%m-%d', date: '\$createdAt' } },
                count: { \$sum: 1 }
            }
        },
        { \$sort: { _id: -1 } },
        { \$limit: 30 }
    ]).forEach(r => print(r._id, r.count));
" 2>/dev/null || echo "Adjust date field name after Phase 1 discovery"

Output Format

Present results as a structured report:

Analyzing Mongodb 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

  • Schema assumptions: MongoDB is schema-flexible — never assume field names without sampling documents
  • Missing --quiet: Without --quiet, mongosh outputs connection banners that corrupt script output
  • Large .find() without limit: Always add .limit(N) — collections can have millions of documents
  • explain() on production: Use explain('queryPlanner') for plan-only (no execution); explain('executionStats') runs the query
  • Replica set reads: Prefer readPreference: 'secondaryPreferred' for analytics to avoid impacting primary
  • Aggregation memory: Default 100MB memory limit per stage — add { allowDiskUse: true } for large aggregations
  • Timezone handling: ISODate stores in UTC — always convert user-specified times to UTC before querying
  • Atlas vs self-hosted: Atlas has different metric APIs than db.serverStatus() — check connection type in Phase 1
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexUnverifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall