Aggregation Pipeline Builder¶

On this page

Create an Aggregation Pipeline
Save a Pipeline
Open a Saved Pipeline
Additional Pipeline Options
Example

New in version 1.14.0

The Aggregation Pipeline Builder in MongoDB Compass provides the ability to create aggregation pipelines to process data. With aggregation pipelines, documents in a collection pass through multiple stages where they are processed into a set of aggregated results. The particular stages and results can be modified depending on your application’s needs.

To access the aggregation pipeline builder, navigate to the collection for which you wish to create an aggregation pipeline and click the Aggregations tab. You are presented with a blank aggregation pipeline. The Preview of Documents in the Collection section of the Aggregations view displays 20 documents sampled from the current collection.

To populate the Aggregation Pipeline Builder, you can either:

Create a new Aggregation Pipeline in the UI,
Open a saved pipeline, or
Import a Pipeline from Plain Text

Create an Aggregation Pipeline¶

1

Add an aggregation pipeline stage.¶

In the aggregation pipeline pane in the bottom-left of the view, click the Select… dropdown and select the aggregation pipeline stage to use for the first stage of the pipeline:

Note

If Comment Mode is enabled, the pre-filled content of the pipeline stage changes based on the selected stage to provide syntactic guidelines.

2

Fill in the pipeline stage.¶

Fill in your selected stage. As you modify the pipeline stage, the preview documents shown in the pane to the right of the stage update automatically to reflect the results of your pipeline as it progresses, provided Auto Preview is enabed:

3

Add additional pipeline stages.¶

Add additional aggregation stages as desired by clicking the Add Stage button below your last aggregation stage. Repeat steps 1 and 2 for each additional stage.

Note

The toggle to the right of the name of each pipeline stage dictates whether that stage is included in the pipeline. Toggling a pipeline stage also updates the pipeline preview, which reflects whether or not that stage is included.

Example

The following pipeline excludes the first $match stage and only includes the $project stage:

4

Optional. Use custom collation.¶

Click the Expand icon to the left of the Folder icon.
Enter the desired collation document.

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

Aggregation Builder collation stage example

Save a Pipeline¶

To save a pipeline:

Name your pipeline using the Enter a pipeline name input at the top of the Aggregations view.
Click Save Pipeline.

Open a Saved Pipeline¶

Important

Opening a saved pipeline abandons any unsaved changes to the pipeline you are currently working on. If the circle at the top-right of the Aggregations view is orange, this means you have unsaved changes to your pipeline.

To open a previously saved pipeline:

Click the Folder icon to the left of the pipeline name input.
Hover over the pipeline you want to open and click Open.
In the ensuing dialog, click Open Pipeline.

Additional Pipeline Options¶

Click the … button to the right of the Save Pipeline button to access additional pipeline options:

The following additional options are available:

Option	Description
Export to Language	Format and export the current pipeline in the selected language. The languages currently supported are Java, Node, C#, and Python 3. For more information, see Export Pipeline to Specific Langague.
Clone Pipeline	Creates a new version of the current pipeline by appending `(copy)` to the current pipeline name, retaining the current pipeline state. This allows you to modify and save a new version of the pipeline.
New Pipeline	Resets the pipeline to its initial state. Important The New Pipeline option does not save your current pipeline state. If you wish to save your current pipeline, you must do so before selecting this option. If the circle at the top-right of the Aggregations view is orange, this means you have unsaved changes to your pipeline.

The following toggles provide additional pipeline options:

Option	Description
Comment Mode	When enabled, adds helper comments to each stage.
Sample Mode	(Recommended) When enabled, limits input documents to `100000` before $group, $bucket, and $bucketAuto stages.
Auto Preview	When enabled, Compass automatically updates the preview documents pane to reflect the results of each active stage as the pipeline progresses.

Example¶

The following example walks through creating and executing a pipeline for a collection containing airline flight statistics.

Create the Pipeline¶

The following pipeline has two aggregation stages: $match and $group. The $match stage returns documents with carrierFsCode equal to 1I, and the $group stage groups the documents returned from the previous stage by the departureAirportFsCode property:

Copy the Pipeline to the Clipboard¶

Using the Export to Language feature, select Node and copy the pipeline into the clipboard:

The aggregation pipeline syntax for Node applications is compatible with the Mongo shell. The next step uses the Mongo shell to execute the pipeline, though you could also use a Node application with the MongoDB NodeJS Driver to achieve a similar result.

Execute the Pipeline¶

Launch and connect to a mongod instance. Next, switch to the test database where the flightStats collection exists:

copy

use test

The following command executes the pipeline created in MongoDB Compass:

copy

db.flightStats.aggregate([
{
  $match: {
    carrierFsCode: "1I"
  }
},
{
  $group: {
    _id: "$departureAirportFsCode",
    flights: { $push: "$flightId" }
  }
}
])

The pipeline returns the following document:

copy

{ "_id" : "EWR", "flights" : [ 543184347, 544589251, 544589200, 543183182, 545515483, 544595864 ] }

← Validation Import Pipeline from Text →