Navigation

Filter Embedded Charts

You can customize your embedded charts by appending various query parameters to their iframe URLs or using the filter option with the Charts Embedding SDK.

Note

To embed charts from your dashboards, you must configure embedding options on your data sources. For instructions, see:

Specify Filterable Fields

A chart Author specifies the fields that can be included in filters set by the embedding application code or added by chart viewers. A chart author can limit access to data by allowing only certain fields to be filtered. By default, no fields are allowed, meaning the chart cannot be filtered until you explicitly allow at least one field.

To define filterable fields:

  1. Navigate to the dashboard that contains the chart where you wish to define filterable fields.

  2. For the desired chart, click the ellipsis h icon button and select Embed Chart from the dropdown.

  3. In the User Specified Filters section, use the dropdown to select which fields chart viewers can use filter data in the chart. You can also manually type values to add fields not listed in the dropdown.

    Note

    This option only appears if you already have Unauthenticated or Authenticated embedding access enabled.

  4. When you have selected all desired fields, click Save below the dropdown.

Chart viewers and applications which render the chart can now use filters based on the specified fields to display subsets of the original chart data. If a viewer attempts to use a filter for a field not included in the User Specified Filters list, an error is returned.

Filters for Embedded Documents

When you add a field to the User Specified Filters list whose value is an embedded document, you must also specify each individual sub-field you wish to allow.

Example

Consider the following document:

{
  "name": "Alice",
  "favorites" :
  {
    "color": "green",
    "animal": "turtle",
    "season": "autumn"
  }
}

If you only add the favorites field to the list of allowed fields, it does not grant viewers permission to filter upon any of the sub-fields of favorites. Instead, you may add one or more of the sub-fields to the list individually by specifying favorites.color, favorites.animal, or favorites.season.

Filter Data on Charts Embedded in an iframe

Use the filter query parameter to only display data that matches a specified MQL filter in your chart embedded in an iframe.

You can use the filter query parameter on both Unauthenticated and Verified Signature charts. The filtering behavior differs with each authentication setting:

  • With unauthenticated charts, the chart Author specifies the fields that can be included in filters set by the embedding application code or added by chart viewers. To learn how to specify filterable fields, see Specify Filterable Fields.
  • With charts which require a Verified Signature, all document fields can be filtered upon, however you must generate the filter in the server-side code and include the filter as part of your signed payload.

Filter Syntax

Select the appropriate tab to see an example of how to filter data in an Unauthenticated chart and a Verified Signature chart:

You can specify an MQL document as your filter query parameter provided that the fields used in your filter are in the list of allowed filterable fields.

Your filter must match the format used in a $match query and be either a:

  • Top level query

    Example

    { "quantity": { $gte: 20 } }
    
  • Or within boolean expressions ( $and, $nor, $or)

    Example

    { $or: [ { quantity: { $lt: 20 } }, { price: 10 } ] }
    

Note

You must URL-encode special characters of the filter parameter.

Example

The following iframe src URL renders a chart which only displays documents with an imdb.rating greater than or equal to 8:

https://charts.mongodb.com/charts-atlasproject1-piocy/embed/charts?
id=93584ddb-1115-4a12-afd9-5129e47bbb0d&
filter={"imdb.rating":%20{$gte:%208}}&
autoRefresh=30

The URL uses an encoded filter parameter of {"imdb.rating":%20{$gte:%208}}. Decoded, this filter is:

{"imdb.rating": {$gte: 8}}

Specify an MQL document as your filter query parameter.

Your filter must match the format used in a $match query as shown in the following examples:

Example

{ "quantity": { $gte: 20 } }

Example

{ $or: [ { quantity: { $lt: 20 } }, { price: 10 } ] }

When using filters in a Verified Signature, MQL queries contain characters that must be URL-encoded before your server-side code calculates the signature. When Charts verifies the signature, it URL-encodes the filter again using the JavaScript encodeURIComponent function. You must use the same encoding algorithm to encode your filter.

Important

You must encode spaces in your filter as %20, rather than + or a raw space.

To see how correctly encode an MQL filter using different server-side programming languages, see MongoDB Charts Embedding Examples on GitHub.

Example

The following iframe src URL renders a chart which only displays documents with an imdb.rating greater than or equal to 8:

https://charts.mongodb.com/charts-atlasproject1-piocy/embed/charts?
id=93584ddb-1115-4a12-afd9-5129e47bbb0d&
timestamp=1564156636&
expires-in=300&
filter=%7B%22imdb.rating%22%3A%20%7B%24gte%3A%208%7D%7D&
autoRefresh=30&
signature=8e0d92b33934c928f6c6974e2f0102ace77f56d851cb0d33893e84c359ab1043

The URL uses an encoded filter parameter of %7B%22imdb.rating%22%3A%20%7B%24gte%3A%208%7D%7D. Decoded, this filter is:

{"imdb.rating": {$gte: 8}}

Filter Data on Charts Embedded with the SDK

You can add a filter to an embedded chart with the filter option. Filtering allows the chart author to only display data in the embedded chart which matches a specified MQL filter.

Any fields included in the filter must be specified in the Embed Chart modal. The Embed Chart modal contains a dropdown menu of fields on which to allow filtering.

The following uses the filter option to represent only documents in which the total field is greater than 100:

createChart({
  baseUrl: '<your-base-url>',
  chartId: '<your-chart-id>',
  width: 500,
  height: 500,
  filter: { "total": { "$gt": 100 } }
})

Inject User-Specific Filters

When you embed a chart that requires Authenticated access, you can use the Inject Filter Per User setting to inject a MongoDB filter document specific to each user who views the chart. The function has access to your Embedding Authentication Provider’s token via context.token, and can filter the chart data based on the token.

This filter ensures that viewers of an embedded chart see only their own data, which is useful when embedding charts with potentially sensitive information.

To inject a filter specific to each user, in the Authenticated tab of the the Embed Chart dialog, set the Inject Filter Per User setting to On. Specify a function and click Save.

Example

The following filter function only renders data where the ownerId field of a document matches the value of the Embedding Authentication Provider’s token’s sub field:

function getFilter(context) {
  return { ownerId: context.token.sub };
}