Docs Menu

Docs HomeMongoDB Compass

Aggregation Pipeline Builder

On this page

  • Tasks
  • Limitations
  • Create an Aggregation Pipeline
  • Save a Pipeline
  • Open a Saved Pipeline
  • Set maxTimeMS for Aggregation Queries
  • Set the Documents Limit or Auto Preview Documents
  • View or Change Pipeline Settings
  • Explain Plan for Pipelines
  • Specify Custom Collation
  • Export Aggregation Results
  • Create a View from Pipeline Results
  • Refresh Document Counts

New in version 1.14.0.

The Aggregation Pipeline Builder in MongoDB Compass lets you create aggregation pipelines to process documents from a collection or view and return computed results. For example, you can use aggregation pipelines to:

  • Group values from multiple documents together.

  • Perform operations on the grouped data to return a single result.

  • Analyze data changes over time.

To build an aggregation pipeline, choose a collection and click the Aggregations tab. Compass displays a blank aggregation pipeline. The Preview of Documents in the Collection section shows 20 documents randomly sampled from the chosen collection.

Note

Atlas Search Stages

When you connect Compass to a MongoDB deployment hosted on Atlas, additional Atlas-only stages $search and $searchMeta are available in the Aggregation Pipeline Builder. Use these stages to perform full-text search on Atlas collections.

You can use the Compass Aggregation Pipeline Builder to:

MongoDB Compass provides different modes to create aggregation pipelines:

  • Stage View Mode, a visual pipeline editor that preloads pipeline syntax based on your selected stages.

  • Stage Wizard, a feature of Stage View Mode that provides a set of templates for simple aggregation stage use cases. The Stage Wizard only includes simple use cases to help you get started with your aggregation pipeline.

  • Focus Mode, a feature of Stage View Mode where you edit one pipeline stage at a time. Focus Mode helps you manage complex or deeply nested aggregation pipeline stages.

  • Text View Mode, a text-based pipeline editor that accepts raw pipeline syntax.

To see how to create an aggregation pipeline, select the tab corresponding to your chosen view mode:

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

To save your pipeline:

1

Click the Save dropdown button at the top of the pipeline builder. Click on Save pipeline as...

Save pipeline as
2
Name your pipeline
3
  1. Click the Folder icon at the top left of the pipeline builder.

    Saved Pipeline Icon
  2. Hover over the pipeline you want to open and click Open.

    Saved Pipelines List
  3. In the modal, click Open Pipeline.

Note

Starting in MongoDB Compass 1.31, you can view your saved queries and aggregation pipelines on the My Queries view once connected to your cluster.

To learn more, see viewing saved aggregations for details.

Use the maxTimeMS parameter on the Aggregations tab to specify an upper time limit in milliseconds on the aggregation pipelines that run in Compass.

To enable maxTimeMS for aggregation operations:

1

On the Aggregations tab, click More Options.

Toggle more options
2

Enter a value next to Max Time MS to set a maximum amount of time in milliseconds that an aggregation pipeline can run. For a 5 second limit, enter 5000.

Enter a maximum timeout value

If your aggregation operation goes over the time limit, Compass raises the following error:

Operation timeout error

Use the toggles at the top of the pipeline builder to set the limit on the number of sampled documents or to enable auto preview.

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.

To view and change pipeline settings:

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

  2. Change any of the following pipeline settings.

    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
    Limit
    When Sample Mode is enabled, specifies the number of documents passed to $group, $bucket, and $bucketAuto stages. Lower limits improve pipeline running time, but may miss documents.
    100000
  3. Click Apply to save changes and close the Settings panel.

Use the Explain button to view the explain plan that helps you understand the performance of your pipelines. You can view the explain plan at any point while creating or editing your pipeline.

To view your pipeline explain plan, click Explain in the right corner of your pipeline toolbar.

Aggregation Pipeline Builder Explain Plan

Your results are presented in this format:

Aggregation Pipeline Builder Explain Results

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:

  1. Click More Options in the top right corner of the pipeline builder.

    Collation Option
  2. Enter your collation document.

To export results from your aggregation pipeline:

  1. Connect to the deployment containing the collection you wish to export data from.

    To learn how to connect to a deployment, see Connect to MongoDB.

  2. Navigate to your target collection.

    You can either select the collection from the Collections tab or click the collection in the left-hand pane.

  3. Create an aggregation pipeline and run for results.

    To learn how to create an aggregation pipeline, see Create an Aggregation Pipeline.

  4. Click Export.

  5. Choose the appropriate file type.

    Under Select Export File Type, select either JSON or CSV. If you select JSON, your data is exported to the target file as an array of JSON objects.

  6. Under Output, choose where to export the file to.

    Export Aggregation Data
  7. Click Export.

Note

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

To create a view from your pipeline results:

  1. Click the arrow next to the Save button at the top of the pipeline builder.

  2. Click Create a View.

  3. Enter a name for your view.

  4. Click Create.

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

When you delete or add a document, the count results value on the Aggregations tab does not automatically update to reflect the new document count.

To update the count results:

1

(Optional) If the results have not been counted, click the count results link.

Click the count results link
2
Click the refresh button

Compass updates the count results and displays the updated number of documents in the collection.

Show current document counts
←  Embedded MongoDB ShellImport Pipeline from Text →
Share Feedback
© 2023 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.