Navigation

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


Aggregation Builder select stage

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:


Aggregation Builder match stage example
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:

Aggregation Builder exclude stage example
4

Optional. Use custom collation.

  1. Click the Expand icon to the left of the Folder icon.

  2. 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:

  1. Name your pipeline using the Enter a pipeline name input at the top of the Aggregations view.
  2. 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:

  1. Click the Folder icon to the left of the pipeline name input.
  2. Hover over the pipeline you want to open and click Open.
  3. 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:

Aggregation Builder 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:

Aggregation Builder Full Example

Copy the Pipeline to the Clipboard

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

Aggregation Builder Full Example

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:

use test

The following command executes the pipeline created in MongoDB Compass:

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

The pipeline returns the following document:

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