Docs Menu

Docs HomeLaunch & Manage MongoDBMongoDB Atlas

Run Aggregation Pipelines

On this page

  • Required Roles
  • Access the Aggregation Pipeline Builder
  • Create an Aggregation Pipeline
  • Export an Aggregation Pipeline to Driver Language
  • Configure Aggregation Pipeline Settings

You can use the Atlas UI to process your data by building aggregation pipelines. Aggregation pipelines transform your documents into aggregated results based on selected pipeline stages.

The Atlas aggregation pipeline builder is primarily designed for building pipelines, rather than executing them. The pipeline builder provides an easy way to export your pipeline to execute in a driver.

To create and execute aggregation pipelines in the Atlas UI, you must have the Project Data Access Read Only role or higher.

To utilize the $out stage in your pipeline, you must have the Project Data Access Read/Write role.


The main panel and Namespaces on the left side list the collections in the datatabse.

Screenshot highlighting databases in the Atlas UI.
click to enlarge

The main panel displays the Find, Indexes, and Aggregation views.


When you first open the Aggregation view, Atlas displays an empty aggregation pipeline.

Initial view of aggregation pipeline builder.
click to enlarge

Select an aggregation stage from the Select dropdown in the bottom-left panel.

Screenshot showing selecting a pipeline stage.
click to enlarge

The toggle to the right of the dropdown dictates whether the stage is enabled.


Fill in your stage with the appropriate values. If Comment Mode is enabled, the pipeline builder provides syntactic guidelines for your selected stage.

As you modify your stage, Atlas updates the preview documents on the right based on the results of the current stage.

Aggregation pipelines that do not contain a write stage (such as $out or $merge) are automatically postfixed with a $limit stage that restricts output to 10 documents by default. You can change the number of documents allowed through the $limit stage by updating the value field for Number of Preview Documents in the Aggregation Pipeline Settings.

Screenshot showing a pipeline stage result.
click to enlarge

There are two ways to add additional stages to your pipeline:

  • Click the Add Stage button at the bottom of the pipeline to add a new stage at the end of your pipeline:

  • Click the button on a stage to add a new stage directly after the stage where the button was clicked.

Screenshot highlighting add stage button.

To delete a pipeline stage, click Delete on the desired stage.


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

To specify a collation document, click Collation at the top of the pipeline builder.

A collation document has the following fields:

locale: <string>,
caseLevel: <boolean>,
caseFirst: <string>,
strength: <int>,
numericOrdering: <boolean>,
alternate: <string>,
maxVariable: <string>,
backwards: <boolean>

The locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.

You can import aggregation pipelines from plain text into the pipeline builder to easily modify and verify your pipelines.

To import a pipeline from plain text:

  1. Click the arrow next to the plus icon at the top of the pipeline builder.

  2. Click New Pipeline from Text.

    Screenshot opening the new pipeline from text dialog.
    click to enlarge

Your pipeline must match the syntax of the pipeline parameter of the db.collection.aggregate() method.


To return your pipeline to the initial blank state, click the plus icon at the top of the pipeline builder.

You can use the aggregation pipeline builder to export your finished pipeline to one of the supported driver languages; Java, Node, C#, and Python 3. Use this feature to format and export pipelines for use in your applications.

To export your aggregation pipeline:


For instructions on creating an aggregation pipeline, see Create an Aggregation Pipeline.


In the Export Pipeline To dropdown, select your desired language.

The My Pipeline pane on the left displays your pipeline in mongosh syntax.

The pane on the right displays your pipeline in the selected language.


(Optional): Check the Include Import Statements option to include the required import statements for the language selected.


Click the Copy button at the top-right of the pipeline to copy the pipeline for the selected language to your clipboard. You can now integrate your pipeline into your application.


You can configure aggregation pipeline settings in the Atlas UI.

Atlas limits the number of input documents for previews of the following stages to 100,000:

This limit allows the preview to run faster. Atlas doesn't apply a limit when the pipeline runs.

You can't change the limit for preview input documents in the Atlas UI. To change the limit for input documents with Compass, see Aggregation Pipeline Builder Settings.

To modify the aggregation pipeline builder settings:

Screenshot highlighting pipeline settings button.

You can modify the following settings in the Atlas UI:

Comment Mode

When enabled, Atlas adds helper comments to each stage.


Changing this setting only affects new stages and does not modify stages which have already been added to your pipeline.

Number of Preview Documents

Number of documents to show in the preview for each stage.


You can only preview a maximum of 20 documents for each stage.

← Create, View, Drop, and Hide Indexes