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.

Embedded Chart Options

You can customize your embedded charts by appending various query parameters to their iframe URLs.

Note

To embed charts from your dashboards, you must configure embedding options on your data sources. For instructions, see Embed Charts in Your Web Application.

Filter Data on Embedded Charts

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

You can use the filter query parameter on both Unauthenticated charts and charts which require a Verified Signature. 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.

Specify Filterable Fields (Unauthenticated Charts Only)

A chart Author specifies the fields that can be included in filters set by the embedding application code or added by chart viewers. Use these fields to restrict the data that viewers can access. By default, no fields are whitelisted, meaning the chart cannot be filtered until you explicitly whitelist 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 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 specify filters based on the whitelisted fields to display subsets of the original chart data. If a viewer attempts to specify a filter using a field not in the whitelist, an error is returned.

Filters for Embedded Documents

When you whitelist a field whose value is an embedded document, you must specify each individual sub-field you wish to add to the whitelist.

Example

Consider the following document:

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

If you only add the favorites field to the whitelist, 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 individually to the whitelist by specifying favorites.color, favorites.animal, or favorites.season.

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 whitelist of 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&
tenant=3397ee6d-5079-4a20-b097-cedd475220b5&
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&
tenant=3397ee6d-5079-4a20-b097-cedd475220b5&
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}}

Specify a Refresh Interval

Use the autorefresh query parameter to define the interval, in seconds, at which the chart refreshes with the latest data from its data source. Use the options on the Unauthenticated tab on the Embed Chart dialog to customize the autorefresh value in the iframe snippet.

If you do not specify the autorefresh option, your embedded chart loads once when the iframe loads and does not automatically refresh.

Example

The following iframe embeds a chart which automatically refreshes every 30 seconds as defined by the autorefresh=30 query parameter:

<iframe style="border: none;border-radius: 2px;box-shadow: 0 2px
10px 0 rgba(70, 76, 79, .2);" width="640" height="480" src="
{charts-host}/embed/charts?id=b3ca720f-4b4a-40b4-a726-e7dc0c49aa1c&
tenant=c184f559-a6d6-4c17-a524-fde31193e498&autorefresh=30"></iframe>

Considerations

  • The minimum automatic refresh interval is 10 seconds. If you specify an autorefresh value less than 10, the chart refreshes every 10 seconds.

  • If you specify an autorefresh value which is not an integer or less than 0, an error is returned.

  • If your data source requires a Verified Signature, the signature validity (including the expiry date) is checked on each refresh. If the signature’s expiry date passed, the host web page must regenerate a new signature to continue rendering charts. For code examples using verified signatures, see MongoDB Charts Embedding Examples on GitHub.

    Example

    If you specify an automatic refresh interval of one minute and the expiry date of the signature is in 1 hour, the chart refreshes every minute for an hour. Once one hour has elapsed, the chart will not render and an error will be displayed as the signature is no longer valid. The host web page must regenerate a new signature to resume rendering the chart.

Specify a Display Theme

Use the theme query parameter to select a display theme:

  • light: chart axes and text are optimized for presentation against a light or white background.
  • dark: chart axes and text are optimized for presentation against a dark or black background.

Choosing a theme value only updates the iframe snippet you use to embed the chart in your application. The chart is not saved with a theme value. The chart renders with the light theme by default. Embedded charts that do not include the theme parameter also render with the light theme.

Note

Choosing the light or dark theme does not change the color palette that chart data elements use. All bars and marks display using the default palette or the custom palette the chart author chose.

For example, if you choose a chart bar to render in black, choosing the dark theme does not change the color of this bar to make it more visible against a dark background.

Customization

MongoDB Charts adds inline style properties to the iframe snippet you copy from the UI that add a background color and a border with a box shadow to the embedded chart based on the theme you selected:

  • light theme background: #FFFFFF
  • dark theme background: #21313C
  • border: none
  • border-radius: 2px
  • box-shadow: 0 2px 10px 0 rgba(70, 76, 79, .2)
  • width: 640
  • height: 480

Change the values of the inline style properties to change how the embedded chart displays in your application:

  • Change the value of the background property to any value supported by the background CSS property to display the chart against it. See background in the MDN Web Docs for more information.

  • Remove the background property to display the chart with a transparent background, allowing your application’s background to display through the chart.

  • Modify or remove the following properties to customize or remove the chart border:

    • border
    • border-radius
    • box-shadow
  • You can change the value of the theme query parameter in the iframe snippet after you paste it into your application. If you do, make sure you adjust the iframe’s inline style properties to match the theme you choose.

    Example

    If you change the theme from light to dark, adjust the value of the background property in the iframe snippet to display the chart against a dark background.

    Chart using light theme with default light theme background of #FFFFFF:

    Chart displayed using the light theme with light theme style.

    Chart using dark theme with default light theme background of #FFFFFF:

    Chart displayed using the dark theme with light theme style.

    Chart using dark theme with default dark theme background of #21313C:

    Chart displayed using the dark theme with dark theme style.

Example

The following iframe embeds a chart with the dark theme with the default dark theme inline style properties. The code is formatted for readability.

<iframe style="
background: #21313C;border: none;border-radius: 2px;
box-shadow: 0 2px 10px 0 rgba(70, 76, 79, .2);"
width="640" height="480" src="
https://charts.mongodb.com/charts-crllr/embed/charts?id=a1b2c3d4-a1b2-c3d4-9766-47b0b2daaff3&
tenant=a1b2c3d4-a1b2-a1b2-a1b2-bb7f36c9def6&
theme=dark
"></iframe>