Docs Menu
Docs Home
/
Atlas Charts
/
Embedding
/
Embed a Dashboard

Filter Embedded Dashboards

On this page

  • Specify Filterable Fields
  • Specify Filterable Sub-Fields for Fields with Embedded Documents
  • Pre-Filter Data on Dashboards Embedded in an iframe
  • Filter Data on Dashboards Embedded in an iframe
  • Filter Syntax
  • Pre-Filter Data on Dashboards Embedded with the SDK
  • Filter Data on Dashboards Embedded with the SDK
  • Inject User-Specific Filters

You can customize your embedded dashboards by adding:

  • Pre-filters. Use the preFilter option with the Charts Embedding SDK or append various query parameters to your iframe URLs.

  • Filters. Use the filter option with the Charts Embedding SDK or append various query parameters to your iframe URLs.

You can use both pre-filters and filters in the same chart, even though using them is optional. Pre-filters, if specified, always run after views and before the dashboard's query and filters. To learn more about the order of pipeline segments, see aggregation pipeline.

Specify Filterable Fields

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

To define filterable fields:

  1. For the desired dashboard, click the button and select Embed from the dropdown.

  2. In the Allowed filter fields section, click the button.

    Note

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

    You can specify on which fields dashboard viewers can filter data by:

    • Using the dropdown to select the fields

    • Manually typing values to add fields not listed in the dropdown

    • Selecting Allow all fields in the data source used in this dashboard

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

Dashboard viewers and applications which render the dashboard can now use filters based on the specified fields to display subsets of the original dashboard data. If a viewer attempts to use a filter for a field not included in the Allowed filter fields list, Atlas Charts returns an error.

Specify Filterable Sub-Fields for Fields with Embedded Documents

When you add a field to the Allowed filter fields list whose value is an embedded document, you must also specify each individual sub-field you want 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.

Pre-Filter Data on Dashboards Embedded in an iframe

Use pre-filters for embedded charts and dashboards with large numbers of collections. Pre-filters run at an earlier stage in the embedded chart's pipeline and allow you to achieve the following results:

  • Filter the data early, to reduce the query running time

  • Apply filters after views and before the query execution and filters for queries that contain aggregations

Pre-filters behave exactly as filters and use the same syntax. Their only difference is that they run after views and before the start of the queries and filters. To learn more about the order of pipeline segments, see aggregation pipeline.

Filter Data on Dashboards Embedded in an iframe

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

You can only use the filter query parameter on the Unauthenticated dashboard. With unauthenticated dashboards, the dashboard Author specifies the fields that can be included in filters set by the embedding application code or added by dashboard viewers. To learn how to specify filterable fields, see Specify Filterable Fields.

Filter Syntax

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 dashboard which only displays documents with an imdb.rating greater than or equal to 8:

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

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

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

Pre-Filter Data on Dashboards Embedded with the SDK

You can add a preFilter to an embedded dashboard with the preFilter option. Pre-filtering allows the dashboard author to run a filter before the query execution.

In the Embed modal, you must specify fields you want to include in the pre-filter. The Embed modal contains a dropdown menu of fields on which to allow filtering.

The following uses the preFilter option to represent only documents in Australia:

createDashboard({
  baseUrl: '<your-base-url>',
  dashboardId: '<your-chart-id>',
  width: 500,
  height: 500,
  preFilter: { "address.country": "Australia" }
})

Filter Data on Dashboards Embedded with the SDK

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

In the Embed modal, you must specify fields you want to include in the filter. The Embed 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:

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

Inject User-Specific Filters

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

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

Note

If you use an Atlas App Services authentication provider, context.token contains the App Services user object to filter. For example, if you enable Custom User Data for App Services users, the user object is available in context.token.custom_data.

To inject a filter specific to each user, in the Authenticated tab of the Embed dialog, set the Injected function`setting to :guilabel:`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 };
}

Back

iframe

Next

Embedding SDK