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.

Query Parameter Order for Verified Signatures

If you are using a Verified Signature to render your chart, you must specify the query parameters of your payload in the following order, or else your signature verification will fail:

Parameter Position Name Description
1 id id parameter from the Embed Chart snippet.
2 tenant tenant parameter from the Embed Chart snippet.
3 timestamp Current time.
4 expires-in (Optional) Number of seconds for which the signature is valid. If omitted, the signature is valid for 24 hours after it is created.
5 filter (Optional) MQL document to filter rendered documents. See Specify a Filter.
6 autorefresh (Optional) Interval in seconds at which the chart refreshes. See Specify a Refresh Interval.

The code examples on the MongoDB Charts Embedding Examples GitHub page provide sample payload generations with properly-formatted query parameters.

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. If you do not specify this 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 Filter

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

Important

For security reasons, the filter query parameter can only be used on charts embedded with a Verified Signature. You should generate your filter in your server-side code, rather than receiving it from the client. Generating the filter from the server prevents the client from modifying the filter and potentially accessing restricted data.

Syntax

Specify an MQL document as your filter query parameter. Use the same syntax used in the query bar in the Chart Builder.

MQL queries contain characters that must be URL-encoded before your server-side code calculates the verified 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}}

The server-side code creates a payload with the necessary information to render the chart, including the filter. The payload ensures that the verified signature is valid before rendering the chart.