Aggregation Pipeline Builder¶

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 or view 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 or view 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:

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 enabled:

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:

Specify Custom Collation¶

Use custom collation to specify language-specific rules for string comparison, such as rules for letter case and accent marks.

To specify a custom collation:

Click the Collation button at the top of the pipeline builder.
Enter your collation document.

Limitations¶

The $out stage is not available if you are connected to a Data Lake.

Save a Pipeline¶

You can save a pipeline so that you can access it later. If you load a saved pipeline, you can modify it without changing the original saved copy. You can also create a view from your pipeline results.

To save your pipeline:

Click the Save button at the top of the pipeline builder.
Enter a name for your pipeline.
Click Save.

Create a View from Pipeline Results¶

Note

Creating a view from pipeline results does not save the pipeline itself.

To create a view from your pipeline results:

Click the arrow next to the Save button at the top of the pipeline builder.
Click Create a View.
Enter a name for your view.
Click Create.

Compass creates a view from your pipeline results in the same database where the pipeline was created.

Open a Saved Pipeline¶

Click the Folder icon at the top left of the pipeline builder.
Hover over the pipeline you want to open and click Open.
In the modal, click Open Pipeline.

Pipeline Options¶

The toggles at the top of the pipeline builder control the following options:

Option	Description
`Sample Mode`¶	(Recommended) When enabled, limits input documents passed to `$group`, `$bucket`, and `$bucketAuto` stages. Set the document limit with the `Limit` setting.
`Auto Preview`¶	When enabled, Compass automatically updates the preview documents pane to reflect the results of each active stage as the pipeline progresses.

Pipeline Settings¶

To view and modify pipeline settings:

Click the gear icon at the top right of the pipeline builder to open the Settings panel.

Modify the pipeline settings. The following settings can be modified:

Option	Description	Default
`Comment Mode`¶	When enabled, adds helper comments to each stage.	Enabled
`Number of Preview Documents`¶	Number of documents to show in the preview.	20
`Max Time`¶	Cumulative time limit in milliseconds for processing the pipeline. Use this option to prevent long hang times.	5000
`Limit`¶	When Sample Mode is enabled, number of documents passed to `$group`, `$bucket`, and `$bucketAuto` stages. Lower limits improve pipeline execution time, but may miss documents.	100000

Click Apply to save changes and close the Settings panel.

Example¶

The following example walks through creating and executing a pipeline for a collection containing airline data. You can download this dataset from the following link: air_airlines.json.

For instructions on importing JSON data into your cluster, see mongoimport. This procedure assumes you have the data in the example.air_airlines namespace.

Create the Pipeline¶

The following pipeline has two aggregation stages: $group and $match.

The $group stage groups documents by their active status and country. The stage also adds a new field called flightCount containing the number of documents in each group.
The $match stage filters documents to only return those with a flightCount value greater than or equal to 5.

Copy the Pipeline to the Clipboard¶

Click the Export to Language button at the top of the pipeline builder. The button opens the following modal:
Click the Copy button in the My Pipeline panel on the left. This button copies your pipeline to your clipboard in mongo shell syntax. You will use the pipeline in the following section.

Execute the Pipeline¶

Launch and connect to a mongod instance which contains the imported air_airlines.json dataset.
Switch to the example database where the air_airlines collection exists:
```
use example
```
Run the following command to execute the pipeline created in Compass:
```
db.air_airlines.aggregate([{
  $group: {
    _id: {
      active: '$active',
      country: '$country'
    },
    flightCount: {
      $sum: 1
    }
  }
}, {
  $match: {
    flightCount: {
      $gte: 5
    }
  }
}])
```

The following is an excerpt of the documents returned by the pipeline:

{ "_id" : { "active" : "Y", "country" : "Nigeria" }, "flightCount" : 5 }
{ "_id" : { "active" : "N", "country" : "Switzerland" }, "flightCount" : 46 }
{ "_id" : { "active" : "N", "country" : "Bahrain" }, "flightCount" : 8 }
{ "_id" : { "active" : "N", "country" : "Guinea-Bissau" }, "flightCount" : 8 }
{ "_id" : { "active" : "N", "country" : "Argentina" }, "flightCount" : 14 }
{ "_id" : { "active" : "N", "country" : "Moldova" }, "flightCount" : 17 }
{ "_id" : { "active" : "Y", "country" : "Israel" }, "flightCount" : 6 }
{ "_id" : { "active" : "N", "country" : "Finland" }, "flightCount" : 7 }

Give Feedback

← Embedded MongoDB Shell Import Pipeline from Text →