> This page location: /docs.md > /docs/development.md > /docs/charts.md > /docs/charts/embed-charts-and-dashboards.md > /docs/charts/embedding-charts.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: unauthenticated, verified-signature
-->

# Filter Embedded Charts

You can customize your embedded charts 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 dashboard, even though using them is optional. If specified, pre-filters always run after the chart views and before the dashboard's queries and filters.

**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](https://www.mongodb.com/docs/charts/embedding-charts.md#std-label-embedding-charts)

You can filter embedded charts and charts on [embedded dashboards.](https://www.mongodb.com/docs/charts/embedding-dashboards.md#std-label-embedding-dashboards)

## Specify Filterable Fields

A chart [Author](https://www.mongodb.com/docs/charts/dashboards/dashboard-access/dashboard-permissions.md#std-label-dashboard-roles) specifies the fields that can be included in pre-filters and 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 pre-filtered or filtered. By default, no fields are allowed, meaning the chart cannot be pre-filtered or filtered until you explicitly allow at least one field.

To define filterable fields for pre-filters and filters:

1. Navigate to the [dashboard](https://www.mongodb.com/docs/charts/dashboards.md#std-label-dashboards) that contains the chart where you wish to define filterable fields.

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

3. In the Allowed filter fields 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.

   To specify on which fields chart viewers can pre-filter or filter data, you can:

   - Use the dropdown to select the fields.

   - Manually type values to add fields not listed in the dropdown.

   - Select Allow all fields in the data source used in
     this chart.

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

Chart [viewers](https://www.mongodb.com/docs/charts/dashboards/dashboard-access/dashboard-permissions.md#std-label-dashboard-roles) and applications which render the chart can now use pre-filters and 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 [Allowed filter fields](https://www.mongodb.com/docs/charts/filter-embedded-charts.md#std-label-specify-filter-fields) list, Atlas Charts returns an [error.](https://www.mongodb.com/docs/charts/embedded-chart-error-codes.md#std-label-embedded-errors)

### 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:

```json
{
  "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 Charts 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 do the following:

- Filter the data early, to reduce the query running time.

- Apply filters before the query execution for chart queries that contain aggregations.

Pre-filters behave exactly as filters and use the same syntax. Their only difference is that they run after the chart views and before the start of the charts queries and filters. To learn more about the order of pipeline segments, see [aggregation pipeline.](https://www.mongodb.com/docs/charts/aggregation-pipeline-generation.md#std-label-aggregation-pipeline-generation)

Use the `preFilter` query parameter to filter data before the chart query starts running, for the chart embedded in an iframe.

You can specify an MQL document as your `preFilter` query parameter provided that the fields used in your filter are in the [list of allowed filterable fields.](https://www.mongodb.com/docs/charts/filter-embedded-charts.md#std-label-specify-filter-fields)

### Pre-Filter Example

The following example illustrates how chart views, queries in the query bar, filters, and pre-filters work together.

Consider the following scenario:

- Charts View contains:

  ```none
  [ { $project: { accommodates: 1, "bedrooms": 1, "address.country": 1 } } ]
  ```

- Query bar contains:

  ```none
  [ { $match: { accommodates: { $gte: 3 } } }, { $project: { address: 0 } } ]
  ```

- The filter in an embedded chart contains:

  ```none
  { "bedrooms": { $lte: 3 } }
  ```

- The pre-filter in an embedded chart contains:

  ```none
  { "address.country": "Australia" }
  ```

In the previous example, before the chart's query starts to run, the pre-filter is applied, to only look for apartments in Australia. After that, the chart's query runs, to identify all apartments that accommodate more than three people.

## Filter Data on Charts Embedded in an iframe

Use the `filter` query parameter to only display data that matches a specified MQL (MongoDB Query Language) 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](https://www.mongodb.com/docs/charts/dashboards/dashboard-access/dashboard-permissions.md#std-label-dashboard-roles) 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.](https://www.mongodb.com/docs/charts/filter-embedded-charts.md#std-label-specify-filter-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:

### Unauthenticated External Sharing

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.](https://www.mongodb.com/docs/charts/filter-embedded-charts.md#std-label-specify-filter-fields)

Your filter must match the format used in a [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) query and be either a:

- Top level query

  **Example:**

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

- Or within boolean expressions ( [`$and`](https://www.mongodb.com/docs/manual/reference/operator/query/and.md#mongodb-query-op.-and), [`$nor`](https://www.mongodb.com/docs/manual/reference/operator/query/nor.md#mongodb-query-op.-nor), [`$or`)](https://www.mongodb.com/docs/manual/reference/operator/query/or.md#mongodb-query-op.-or)

  **Example:**

  ```json
  { $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`:

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

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

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

## Pre-Filter Data on Charts Embedded with the SDK

You can add a [preFilter](https://www.mongodb.com/docs/charts/filter-embedded-charts.md#std-label-embed-options-pre-filter) to an embedded chart with the `preFilter` option. Pre-filtering allows the chart author to run a filter after the chart views and before the chart query execution and chart's filters.

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

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

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

## Filter Data on Charts Embedded with the SDK

You can add a [filter](https://www.mongodb.com/docs/charts/filter-embedded-charts.md#std-label-embed-options-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 (MongoDB Query Language) filter.

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

```javascript
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 Injected function 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 Embed Chart dialog, set the Injected function 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:

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