The Complete Production SOP: How to Deploy and Run MongoDB Aggregation Framework Pipeline Stages in Autonomous AI Agents
Step-by-step SOP to install and run MongoDB Aggregation Pipeline Stages in Codex, Claude Code, and Cursor. Master $match, $lookup, and indexing optimization.
Technical Overview & Architectural Context
Without structured procedural boundaries, autonomous LLM coding agents repeatedly generate suboptimal MongoDB aggregation pipelines. Common hallucinations include positioning unbounded $lookup stages before $match filters, omitting compound index prefix awareness, using inefficient $unwind operators on massive arrays, and neglecting pipeline memory boundaries. When executing queries over millions of documents, this produces severe table scans, Intermediate memory limit violations (100MB RAM cap), and runaway CPU consumption on MongoDB clusters. The 'mongodb-aggregation-pipeline-stages' skill constrains autonomous agents (Codex, Claude Code, Cursor, Windsurf) to rigorous database engineering standards. It enforces strict stage sequencing—prioritizing indexed $match and early $project pruning—mandates explain('executionStats') query plan audits, mandates declarative sub-pipeline joins with uncorrelated sub-queries, and forces the explicit configuration of allowDiskUse when data limits dictate. By anchoring the agent to a deterministic procedural pipeline, teams eliminate full collection scans and ensure production-grade database interactions.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your target agent runtime's procedural directory.
Autonomous coding assistants inspect predefined filesystem paths to discover agent skills. For Claude Code, skills mount under `.claude/skills/`. For Cursor and Windsurf, skills are recognized from `.cursor/rules/` or `.windsurf/rules/`. For Codex Desktop or universal CLIs, the standard path is `~/.agents/skills/`. Mounting this file equips the LLM with deterministic stage ordering rules for MongoDB queries.
mkdir -p ~/.agents/skills/mongodb-aggregation-pipeline-stages && curl -fsSL https://askills.dev/api/skills/mongodb-aggregation-pipeline-stages/raw -o ~/.agents/skills/mongodb-aggregation-pipeline-stages/SKILL.md---
name: "mongodb-aggregation-pipeline-stages"
description: "Construct multi-stage analytical aggregation pipelines in MongoDB with high index selectivity."
metadata:
author: "MongoDB"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "optimize mongodb aggregation"
- "use mongodb lookup and group"
- "explain mongodb aggregate pipeline"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# MongoDB Aggregation Framework Pipeline Stages
Designs MongoDB aggregation queries: optimizing $match, $lookup with sub-pipelines, $unwind, $group with accumulators, $facet for multi-dimensional dashboards, and explain plans with executionStats.
## When to Invoke
Invoke this skill whenever you need to:
- optimize mongodb aggregation
- use mongodb lookup and group
- explain mongodb aggregate pipeline
## Execution SOP & Rules
1. Always ensure $match precedes $lookup and $group to leverage compound indexes and minimize working set.
2. Use $project or $set to prune unused heavy embedded document arrays early in the pipeline.
3. Check execution metrics using db.collection.explain('executionStats').aggregate([...]).
4. Add allowDiskUse: true when processing intermediate datasets exceeding the 100MB RAM pipeline limit.
## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.In Cursor, symlink `.cursor/rules/mongodb-aggregation.md` to `~/.agents/skills/mongodb-aggregation-pipeline-stages/SKILL.md` to maintain a single source of truth across all runtimes without consuming duplicated workspace tokens.
Ensure `shell_exec: false` remains respected in agent configs. Aggregation pipeline design only requires reading existing schema files and writing query models inside the workspace.
Environment Secrets & Driver Dependency Validation
Configure database connection parameters securely without exposing connection credentials in LLM context windows.
Agents must never read direct credentials from prompts. Store connection URI parameters in `.env.local` or standard repository environment secrets. Confirm the aggregation testing harness or test suite uses dummy data or local read-only replicas.
test -f .env.local || echo 'MONGODB_URI="mongodb://localhost:27017/analytics_test"' > .env.localInstruct your agent to utilize `.env.example` schemas and access `process.env.MONGODB_URI` without hardcoding connection strings in pipeline tests.
Verify `.env.local` is explicitly committed into `.gitignore`. Running agent auto-commit without this check risks publishing database secrets.
Intent Matching & Trigger Invocation
Invoke the skill deterministically via standard triggers to construct optimized queries.
Provide the agent with explicit task prompts containing registered triggers such as 'optimize mongodb aggregation' or 'use mongodb lookup and group'. The agent's contextual planner loads the procedural rules and structures the aggregation pipeline stages with mandatory index-first constraints.
Specify target collection index schemas in the prompt (e.g., 'Compound index on { tenantId: 1, createdAt: -1 } exists') to let the agent choose the exact prefix for the initial $match stage.
Avoid ambiguous prompts like 'make a fast mongo query'. Always explicitly mention the target aggregation stages or executionStats goal to guarantee skill activation.
Verification, Linting & Output Quality Gate
Execute query dry-runs and verify execution plan metrics with executionStats.
The skill mandates that the agent verify the generated aggregation pipeline against MongoDB's explain plan, ensuring `totalDocsExamined` closely mirrors `nReturned` rather than triggering a COLLSCAN. Automated unit tests ensure syntax validity.
npm test -- tests/aggregations/ordersAnalytics.test.tsEnforce assertion of `executionStats.executionStages.stage !== 'COLLSCAN'` inside Jest/Vitest integration suites.
When aggregating against MongoDB Atlas Shared Tiers (M0/M2/M5), $facet and $lookup with nested sub-pipelines have tighter memory restrictions; enforce strict limit clauses inside sub-pipelines.
Real-World Scenario: Customer Order Metrics Aggregation with Foreign Lookup
“optimize mongodb aggregation to generate monthly sales reports from the 'orders' collection. We need to: use mongodb lookup and group to join customer metadata from 'customers', calculate total revenue per customer tier, filter out unfulfilled orders, and explain mongodb aggregate pipeline performance.”
Runtime Troubleshooting & Failure Modes
Root Cause: The aggregation pipeline includes an un-indexed $sort or an expansive $group operation on an intermediate dataset that exceeds MongoDB's 100MB internal RAM buffer limit.
// Pass allowDiskUse option to aggregate method options:
const results = await db.collection('orders').aggregate(pipeline, { allowDiskUse: true }).toArray();Root Cause: A $group stage attempted to aggregate raw root documents into a single document array using $push: '$$ROOT' or $push: '$items', exceeding the maximum BSON document boundary of 16MB.
// Replace raw root pushing with selective accumulator projections:
{ $group: { _id: '$customerId', totalSpent: { $sum: '$amount' }, orderCount: { $sum: 1 } } } // Do NOT use $push: '$$ROOT'Frequently Asked Questions (MongoDB Aggregation Framework Pipeline Stages SOP)
Q:Can I use MongoDB Aggregation Framework Pipeline Stages across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. You can place the file in root repository agent folders (.claude/skills, .cursor/rules, or ~/.agents/skills) to maintain consistent aggregation pipeline design standards across all developer environments.
Q:How does MongoDB Aggregation Framework Pipeline Stages prevent context window overflow during long agent sessions?
The skill provides concise, stage-specific SOP rules rather than monolithic schema definitions. It guides the LLM to output only relevant aggregation pipeline array stages and targeted explain plan verification snippets, saving context tokens for iterative test execution.
Q:Does this skill require escalated root or container permissions?
No. The skill is strictly declarative and scoped with a 98/100 security score. It requires only standard workspace file read/write permissions to generate repository code, with shell_exec set to false and net_access set to false.
Ready to equip your autonomous agent with MongoDB Aggregation Framework Pipeline Stages?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.