Aggregation Pipeline Builder

Build powerful MongoDB aggregation pipelines with an intuitive visual interface. Choose from 37+ pipeline stages, configure them using simple forms or MongoDB editor, preview results at each stage, and execute complex data transformations without writing JSON from scratch.

Stage Palette

The stage palette on the left contains all available MongoDB aggregation stages, organized into four categories for easy discovery.

Filter Stages

Filter and limit the documents flowing through your pipeline:

• $match - Filter documents based on query conditions (like find queries)
• $limit - Restrict the number of documents passed to the next stage
• $skip - Skip a specified number of documents
• $sample - Randomly select a specified number of documents
• $count - Return a count of documents at this stage

Transformation Stages

Reshape, modify, and transform document fields:

• $project - Reshape documents by including, excluding, or computing new fields
• $addFields - Add new fields to documents without removing existing ones
• $set - Add or update fields in documents
• $unset - Remove specified fields from documents
• $sort - Reorder documents based on field values (ascending/descending)
• $unwind - Deconstruct array fields to output one document per array element
• $replaceRoot - Replace the entire document with a specified embedded document
• $replaceWith - Replace documents with the result of an expression
• $redact - Restrict document content based on document-stored information
• $densify - Fill in missing values in time series or sequence data
• $fill - Populate null and missing field values
• $setWindowFields - Perform window functions over a specified range of documents

Group Stages

Group and aggregate documents using various accumulator functions:

• $group - Group documents by an identifier and apply accumulator expressions ($sum, $avg, $max, $min, etc.)
• $bucket - Categorize documents into buckets based on boundaries you define
• $bucketAuto - Automatically categorize documents into a specified number of buckets
• $sortByCount - Group by a field value and sort by count in descending order

Other Stages

Advanced stages for joins, analytics, output, and special operations:

• $lookup - Perform left outer join with another collection in the same database
• $graphLookup - Perform recursive search on a collection (graph traversal)
• $unionWith - Combine documents from another collection into the pipeline
• $facet - Process multiple aggregation pipelines on the same input documents
• $out - Write pipeline results to a collection (must be the final stage)
• $merge - Write results to a collection with merge options (must be the final stage)
• $geoNear - Return documents sorted by proximity to a geospatial point
• $search - Perform full-text search using Atlas Search indexes
• $documents - Return literal documents as pipeline input
• $collStats - Return collection statistics
• $indexStats - Return statistics about index usage
• $planCacheStats - Return query plan cache information
• $listSearchIndexes - List Atlas Search indexes on the collection

Stage Palette Actions

• Search Stages: Use the search bar at the top of the palette to quickly find stages by name or type. The list filters in real-time as you type.
• Collapse Palette: Click the collapse button to minimize the palette and gain more space for the pipeline builder. Click again to expand it back.
• Drag to Add: Drag any stage from the palette and drop it into your pipeline. You can drop between existing stages or at the end of the pipeline.

Stage Configuration: Dual-Mode Interface

Every stage can be configured in two ways: Form Mode (guided UI) or MongoDB Editor (raw JSON). Switch between modes using the toggle in each stage card.

Form Mode

Form Mode provides a user-friendly interface with visual controls, dropdowns, and validation:

• Field Auto-Completion: Select fields from your collection using dropdowns (no need to remember field names)
• Visual Query Builder: Build query expressions using drag-and-drop components
• Data Type Validation: Inputs validate data types to prevent errors
• Expression Builder: Construct MongoDB expressions ($sum, $avg, etc.) with visual tools
• Operator Selection: Choose operators from dropdowns instead of typing syntax
• Beginner-Friendly: Ideal for users learning MongoDB or building simple pipelines

MongoDB Editor

MongoDB Editor gives you full control with raw JSON editing and syntax highlighting:

• Direct JSON Editing: Edit the stage configuration as MongoDB-formatted JSON
• Syntax Highlighting: Monaco editor with MongoDB-aware syntax highlighting
• Auto-Completion: IntelliSense for field names, operators, and MongoDB functions
• Error Detection: Real-time validation shows syntax errors as you type
• Advanced Control: Use complex expressions, nested documents, and MongoDB-specific types
• Power User Workflow: Paste existing queries, copy from documentation, or build complex logic

Pro Tip: You can switch between Form and MongoDB Editor modes at any time. Start with Form Mode to build the basic structure, then switch to MongoDB Editor to fine-tune complex expressions. Your preference is saved per stage, so each stage can use a different mode.

Common Stages in Detail

$match - Filter Documents

The $match stage filters documents based on query conditions, similar to the find() query. It's typically the first stage in a pipeline to reduce the number of documents early.

Form Mode Feature	Description
Query Builder	Drag-and-drop query builder with visual field selection and operator dropdowns
Field Auto-Complete	Dropdown lists showing all fields from your collection schema
AND/OR Logic	Combine multiple conditions with visual AND/OR grouping

Example Use Case: Filter orders where status is "completed" and total is greater than $100.

$group - Aggregate and Summarize

The $group stage groups documents by a specified identifier expression and applies accumulator expressions like $sum, $avg, $max, $min, $push, etc.

Configuration Field	Description
Group By (_id)	Field or expression to group by. Use null to group all documents into one.
Accumulator Fields	Add fields with accumulator operators: $sum, $avg, $max, $min, $first, $last, $push, $addToSet
Expression Builder	Visual builder for complex expressions and nested accumulators

Example Use Case: Group orders by customer_id and calculate total sales, average order value, and order count per customer.

$project - Reshape Documents

The $project stage reshapes documents by including, excluding, or computing new fields. It's useful for controlling output structure and calculating derived values.

Form Mode Feature	Description
Include Fields	Select which existing fields to include in the output
Exclude Fields	Select which fields to remove from the output
Computed Fields	Add new fields with expressions (math, string operations, date formatting, etc.)
Nested Fields	Include/exclude nested document fields using dot notation

Example Use Case: Include only name and email fields, exclude _id, and add a computed field "fullName" by concatenating firstName and lastName.

$lookup - Join Collections

The $lookup stage performs a left outer join with another collection in the same database, adding matching documents as an array field.

Field	Description
from	The target collection to join with
localField	Field from the input documents to match
foreignField	Field from the "from" collection to match against localField
as	Name of the new array field to add with matching documents

Example Use Case: Join orders with customers collection, matching order.customer_id with customer._id, adding matched customer documents in a "customerInfo" array.

$unwind - Deconstruct Arrays

The $unwind stage deconstructs an array field, outputting one document for each array element. Useful after $lookup or when working with embedded arrays.

Field	Description
path	Field path to the array you want to unwind (e.g., "$items")
preserveNullAndEmptyArrays	If true, output documents even if the array is missing, null, or empty
includeArrayIndex	Optional field name to include the array index of the element

Example Use Case: Unwind an "items" array in an order document to create one document per item for item-level analysis.

$sort - Order Documents

The $sort stage reorders documents based on one or more fields in ascending or descending order.

Form Mode Feature	Description
Sort Fields	Add multiple fields to sort by, with drag-to-reorder priority
Sort Direction	Toggle between ascending (1) and descending (-1) for each field
Multiple Criteria	Sort by multiple fields with different directions (e.g., category asc, price desc)

Example Use Case: Sort products by category (ascending) and then by price (descending) within each category.

Stage Preview Functionality

The stage preview panel shows you exactly what data looks like before and after each stage, making it easy to understand transformations and debug issues.

Preview Features

• Input/Output Split View: See the data before and after the selected stage side-by-side
• Auto-Preview Mode: Preview updates automatically as you modify stage configuration (toggle on/off)
• Sample Data Limit: Shows first 20 documents for quick feedback without heavy database load
• Resizable Panels: Drag the divider to adjust the width of input vs output views
• Tree View: Expand/collapse nested documents to explore structure
• Document Count: Shows how many documents are produced by the stage

Using Preview Tab

1. Select a stage in your pipeline to view its preview
2. Click the "Preview" tab at the bottom to show the preview panel
3. The left side shows input documents (results from previous stages)
4. The right side shows output documents (results after applying this stage)
5. If auto-preview is disabled, click "Run Preview" to manually refresh

Terminal Stages: Stages like $out and $merge write to collections and cannot be previewed. The preview panel will be disabled when these stages are selected.

Execution Controls & Settings

Control how your aggregation pipeline executes with various options and real-time monitoring.

Execution Actions

• Run Pipeline: Execute the entire aggregation pipeline (only enabled stages) and display results in the Results tab. Shows first 50 documents by default.
• Cancel Execution: Stop a running aggregation immediately. Useful for long-running queries or when you need to make changes.
• Auto-Preview Toggle: Enable/disable automatic preview updates. When on, preview refreshes as you edit stages. Turn off to reduce database load during editing.
• Pagination: Navigate through large result sets using First, Previous, Next, and Last buttons. Adjust documents displayed per page.

Settings & Options

Click the Settings button to access advanced execution options:

Setting	Description	Default
Allow Disk Use	Allow MongoDB to use disk for large aggregations that exceed memory limits	false
Max Time (seconds)	Maximum execution time before timeout. Prevents runaway queries.	300 (5 minutes)
Auto Collapse	Automatically collapse all stages except the selected one	false

Live Execution Monitor

When a pipeline is running, you'll see real-time information:

• Execution Timer: Live counter showing elapsed time in milliseconds
• Loading Indicator: Visual feedback that query is running
• Cancel Button: Stop the query at any time
• Result Count: Number of documents returned when execution completes

Save & Load Pipelines

Persist your aggregation pipelines for reuse, collaboration, and building a library of common transformations.

Save Options

• New Pipeline: Create a new aggregation activity with an empty pipeline. Opens a fresh pipeline builder in a new tab.
• Save: Save changes to the current pipeline (if it was previously saved). Updates the existing saved query.
• Save As: Save the current pipeline with a new name. Creates a copy in your saved queries library. Prompts for name, folder, and description.
• Load: Open the saved queries dialog to load a previously saved aggregation pipeline. Filter by connection, database, and collection.

Saved Query Features

• Folder Organization: Organize saved pipelines into folders for easy management
• Name & Description: Add descriptive names and documentation to saved pipelines
• Context Filters: Saved queries are tagged with connection, database, and collection for easy filtering
• Quick Load: Double-click a saved query to load it instantly
• Edit Metadata: Rename, move to different folders, or update descriptions later

Export Options

Export your pipelines or pipeline results in various formats for sharing, version control, or documentation.

Export Pipeline

• Export Pipeline to File: Export the pipeline stages as a MongoDB shell format file (.js). Includes collection name and full pipeline definition. Can be shared with team members or version controlled.
• Export Results Data: Execute the pipeline and export the results to a file. Opens the Export Data activity with the pipeline pre-configured. Choose from JSON, CSV, BSON, or SQL formats.
• Create Chart: Create a visualization chart from the pipeline results. Opens the Chart Builder with the aggregation pipeline pre-configured as the data source.
• Import Pipeline from File: Import a pipeline from a MongoDB shell format file. Replaces the current pipeline with the imported one. Supports files exported from VisualLeaf or written manually.

Shell Format Export

Exported pipelines use MongoDB shell format and can be run directly in mongosh or MongoDB Compass:

db.collection.aggregate([
  { $match: { status: "active" } },
  { $group: { _id: "$category", total: { $sum: "$amount" } } },
  { $sort: { total: -1 } }
])

Query Code View

Switch to the Query Code tab to view and edit your entire pipeline as MongoDB shell format code.

Code View Features

• Read-Only View: See your pipeline as MongoDB shell array syntax
• Syntax Highlighting: MongoDB-aware syntax coloring for better readability
• Auto-Generated: Code updates automatically as you modify stages in the pipeline builder
• Copy to Clipboard: Easy copying for use in mongosh, applications, or documentation
• Format Code: Click Format to pretty-print the pipeline with proper indentation
• Apply Changes: Edit the code directly and click Apply to update the pipeline stages

Code Actions

• Format Code: Pretty-print the pipeline code with proper indentation and line breaks. Validates the JSON syntax and normalizes formatting.
• Apply Code Changes: Parse the edited code and apply changes to the pipeline stages. Converts shell format back to stage objects and updates the builder.

Use Case: If you prefer writing pipelines by hand or have existing pipeline code, paste it into the Query Code view and click Apply. VisualLeaf will parse it and populate the stage cards, giving you the best of both worlds: code editing and visual configuration.

Keyboard Shortcuts

Shortcut	Action
Ctrl+Enter	Execute the aggregation pipeline
Ctrl+S	Save the current pipeline
Delete	Delete the selected stage (with confirmation)
Ctrl+D	Duplicate the selected stage
Esc	Close dialogs or cancel current operation
Ctrl+Space	Trigger auto-completion in MongoDB Editor

Note: On macOS, use Cmd instead of Ctrl

Stage Context Menu

Right-click on any stage in the pipeline to access quick actions:

• Enable/Disable Stage - Toggle whether the stage is included in execution (disabled stages are skipped)
• Duplicate Stage - Create a copy of the stage with the same configuration
• Delete Stage - Remove the stage from the pipeline (with confirmation)
• Move Up/Down - Reorder the stage within the pipeline
• Expand/Collapse - Show or hide the stage configuration form
• Copy Config - Copy the stage configuration JSON to clipboard

Pro Tips

1. Filter Early: Place $match stages at the beginning of your pipeline to reduce the amount of data processed by subsequent stages. This dramatically improves performance.
2. Use Preview to Debug: When your pipeline returns unexpected results, select each stage and check its preview to identify where the transformation goes wrong.
3. Disable vs Delete: Instead of deleting stages you're experimenting with, disable them. This lets you quickly toggle different configurations without losing your work.
4. Index Your Match Fields: For pipelines that start with $match on specific fields, ensure those fields are indexed in MongoDB for optimal performance.
5. Switch Modes Freely: Start in Form Mode to build the basic structure, then switch to MongoDB Editor to fine-tune complex expressions or paste code from documentation.
6. Save Reusable Patterns: Build a library of common aggregation patterns by saving pipelines with descriptive names. Load and modify them for similar use cases.
7. Use $project After $group: After grouping, use $project to reshape the output and remove the _id field if not needed, making results cleaner.
8. Limit Preview Auto-Refresh: For large datasets or complex pipelines, disable auto-preview to reduce database load. Manually run preview when needed.
9. Check Document Counts: Monitor how many documents each stage produces. A stage that outputs way more or fewer documents than expected often indicates a configuration issue.
10. Export for Documentation: Use the "Export Pipeline" feature to save pipelines as files. Include them in your project documentation or version control system.
11. Allow Disk Use for Large Sorts: If your pipeline includes $sort or $group on large datasets, enable "Allow Disk Use" in settings to prevent memory errors.
12. Collapse Results Panel: When focusing on pipeline building, collapse the results/preview panel to maximize the pipeline workspace. Re-expand when you need to check output.

Related Features

• Collection Activity - Browse and query the collections used in aggregations. Use Collection view to understand your data structure before building pipelines.
• VisuaSchema Designer - View relationships between collections to plan $lookup stages. See which fields are commonly used for joins.
• Index Management - Create indexes to optimize aggregation performance. Review index usage statistics to identify bottlenecks.
• Export Data - Export aggregation results to files in various formats. Use the "Export Results" action from the aggregation toolbar.
• Chart Builder - Create visual charts from aggregation pipeline results. Use the "Create Chart" action to visualize your data.
• Saved Queries - Manage your saved aggregation pipelines. Organize into folders, share with team members, and build a query library.
• Query History - Access previously executed aggregations. Quickly reload and modify past pipelines without rebuilding from scratch.