Navigation
This documentation refers to the MongoDB Charts service in MongoDB Atlas. Read the on-premises documentation to learn how to use the MongoDB Charts on site.

Filter Documents in the Visualization

Filters display a subset of results that match a given criteria. MongoDB Charts provides two ways to filter your data. You can either use:

Filter Tab

The chart builder contains a filter tab where you can drag and drop fields to specify filters based on those fields. To filter data using the filter tab:

  1. Click the center tab in the chart builder:

    Image showing how to access filter tab

  2. Drag a field from the Fields on the left to the Chart Filters section of the tab.

The data type of the selected field dictates the available filtering options. You can filter fields with the following data types:

Note

You cannot use the same field for multiple filters.

Filter Numeric Fields

When you drag a numeric field to the filter panel, you can filter based on minimum and/or maximum values for that field.

To specify a minimum value: To specify a maximum value:
  1. Toggle Min to On.
  2. Specify the desired minimum value.
  3. Select whether this is an inclusive minimum value.
  1. Toggle Max to On.
  2. Specify the desired maximum value.
  3. Select whether this is an inclusive maximum value.

Example

If you have a minimum value of 5 with the Inclusive setting on, MongoDB Charts shows documents where the field is greater than or equal to 5.

Alternatively, if Inclusive is off, MongoDB Charts shows documents where the field is greater than 5.

Filter String and ObjectId Fields

When you drag a string or ObjectId field to the filter panel, MongoDB Charts displays a list of up to 20 distinct field values. If more than 20 distinct values exist, MongoDB Charts displays 20 randomly selected values.

The list also includes:

  • NULL / MISSING for documents with null values for the field or are missing the field.
  • Empty String for documents with "" values for the string field. (String fields only.)

Select the values to display in the chart. By default, all values are selected.

Tip

If all values are selected, you can click Deselect All at the top of the list to hide all values.

If not all values are selected, you can click Select All to return to the default state of having all values displayed.

Display Strings and ObjectIds Not in the List

To display a specific value not included in the list, add the value by clicking Add Value.

Important

For ObjectId fields, value you input must be a well-formed ObjectId, or else MongoDB Charts does not accept the value.

To display all other values not included in the list, check All other values.

  • If All other values is checked, MongoDB Charts filters out any unchecked list items by using a $nin query.
  • If All other values is unchecked, MongoDB Charts only includes the checked list items by using an $in query.

Filter Date Fields

When you drag a date field to the filter panel, you can filter based on a specified date range. This range can either be:

  • A relative date range, which specifies a range relative to the time the chart is rendered (e.g., the last six months).
  • An absolute date range, which is a range between specific beginning and end dates.

Relative Date Filter

Relative date filters specify a range relative to the time the chart is rendered. To define the date range, specify a period of time in the past and/or a period of time in the future relative to the current date. Relative is the default date filtering option.

To set a lower bound for a relative date filter:

  1. Turn on the From toggle.
  2. Set the lower bound for your relative date. This timespan is relative to the current date.

To set an upper bound for a relative date filter:

  1. Turn on the Until toggle.
  2. Set the upper bound for your relative date. This timespan is relative to the current date.

Example

The following relative date filter only shows documents with a Workout Date (As Date) field that is more recent than one year ago from the current date:

Image showing relative date filter

Absolute Date Filter

Absolute date filters use absolute dates to define their upper and lower bounds. To define an absolute date range, select Absolute at the top of your date filter card. The dates specified in the filter are assumed to be in UTC, matching the raw data in the collection.

To define a lower bound for your absolute date filter:

  1. Turn on the From toggle.
  2. Enter a date for your lower bound, or select a date from the calendar below the input field.
  3. Enter a time for your lower bound, or select a time from the list below the input field.
  4. Set Inclusive to dictate whether to include the specified date.

To define an upper bound for your absolute date filter:

  1. Turn on the To toggle.
  2. Enter a date for your upper bound, or select a date from the calendar below the input field.
  3. Enter a time for your upper bound, or select a time from the list below the input field.
  4. Set Inclusive to dictate whether to include the specified date.

Example

The following absolute date filter only shows documents with a Workout Date (As Date) field from the year 2018:

Image showing absolute date filter

The filter returns all documents with a Workout Date (As Date) field from January 1, 2018 12:00:00 AM inclusively, to January 1, 2019 12:00:00 AM exclusively.

Note

The date and time formats used in your bounds depend on your location, as determined from your browser settings.

Filter Boolean Fields

You can filter the chart data based on the boolean value of a specific field. Drag a boolean field to the filter panel to view the available options:

  • True displays documents where the field value is true.
  • False displays documents where the field value is false.
  • NULL / MISSING displays documents where the field is null or does not exist.

All options are selected by default. The chart preview updates as you modify the selected options. Deselecting all options renders a blank chart.

Example

A chart using the following filter only displays documents where the passed field is true. The chart does not display documents where the passed field is false, null, or does not exist.

Image showing boolean filter

Query Bar

The Query bar supports more complex queries than the filter panel. Additionally, you can use the query bar to create aggregation pipelines to process your data before it is rendered.

Filter Data using the Query Bar

To filter data using the Query bar:

  1. In the Query bar, input a filter document. Use the same syntax used in the query portion of the db.collection.find() method. Your filter document must be in curly brackets.
  2. Click Apply.

Considerations

  • Filters on large collections may encounter performance issues if the collection is not appropriately indexed.

  • The date functions utilized in the MongoDB Charts query bar are consistent and compatible with the date functions used in the mongo shell. As a result, you can use:

    • new Date(),
    • ISODate(), or
    • new ISODate().

    The Date() function (as opposed to the new Date() constructor) returns the current date as a string, so it cannot be used for querying dates in Charts.

Element Query Example

The following chart shows the average Metacritic ratings of movies over time binned by 5 year periods.

Example query comparison

The chart utilizes the following query:

{ 'writers.1': { $exists: true }}

writers is an array where each element is a writer who contributed to the movie. This filter ensures that only documents with at least two writers are factored into the mean Metacritic rating by checking that the second array element exists.

Regular Expression (RegEx) Query Example

Use the $regex query operator to filter using a regular expression:

{ <field>: { $regex: "pattern", $options: "<options>" } }

Note

You must enclose the pattern in quotes. You cannot use the /pattern/ syntax.

For example, to find all documents where the jobs field begins with the letter A, you would write the following in the Query bar:

{ "jobs" : { $regex : "^A" } }

To find all documents where the jobs field begins with the letter A or a, you would write the following in the Query bar:

{ "jobs" : { $regex : "^A", $options : "i" } }

Date Query Example

The following chart shows total sale amounts from an office supply company, categorized by purchase method:

Example date query

The chart utilizes the following query:

{
  $and: [
  {
    saleDate: { $gte: new Date("2017-01-01") }
  },
  {
    'items.4': { $exists: true }
  } ]
}

Each document in the collection represents a single sale. items is an array where each element is an item purchased during a sale.

This query restricts the documents shown to only those with a saleDate equal to or more recent than January 1, 2017 with at least 5 elements in the items array.

Create Aggregation Pipelines

Aggregation pipelines transform your documents into an aggregated set of results. In MongoDB Charts, aggregation pipelines are commonly used to visualize new fields created from calculated results of pre-existing fields, but also have many other applications.

To create an aggregation pipeline in the Query bar:

  1. In the Query bar, input an aggregation pipeline. Your pipeline must be in square brackets.
  2. Click Apply to execute your pipeline.

Aggregation Pipeline Example

The following chart shows total sale amounts from an office supply company, categorized by store location. The chart utilizes the following aggregation pipeline in the Query bar:

[
  {
    $unwind: "$items"
  },
  {
    $addFields: {
      saleAmount: {
        $multiply: [ "$items.price", "$items.quantity" ]
      }
    }
  }
]

This aggregation pipeline processes the collection data using the following stages:

  1. The $unwind stage unwinds the items array and outputs a new document for each item in the array. Each element in the items array contains a single item sold during a transaction.
  2. The $addFields stage adds a new field to the documents called saleAmount. The $multiply expression sets the value of saleAmount to the product of items.price and items.quantity. You can see this new field highlighted in the following screenshot:
Example Aggregation Pipeline

Once the data has been processed using the pipeline, the chart displays the the Sum of all saleAmounts categorized by store location.

Limitations

The $lookup operator is not supported in the aggregation pipeline builder.