Skip to Content

Filtering & Personalization

Set dashboard filters from the token

Lock a dashboard filter to a value your backend puts in the guest token.

A dashboard app filter takes its value from params.dashboardAppFilters in the guest token. Viewers cannot change it.

Before you start

  • You have a dashboard that a data app shares.
  • Your backend creates guest tokens. See Guest token API.

Steps

  1. Open the dashboard and select Add filter, then Select.
  2. In Step 1 of 2: Filter values, enter a Filter Name, for example country. This name is the key in the token.
  3. Choose the values source and select Next.
  4. In Step 2 of 2: Apply filter, keep Target on Apply on and choose the columns.
  5. Turn on App Filter, then select Save.
  6. Copy the dashboard ID. See Dashboard ID.
  7. In your backend, add the filter to params.dashboardAppFilters when you create the guest token:
{
  "clientId": "acme-corp",
  "dataAppName": "Customer Analytics",
  "params": {
    "dashboardAppFilters": [
      {
        "dashboardId": "YOUR_DASHBOARD_ID",
        "values": {
          "country": ["USA", "Canada"],
          "order date": { "startDate": "2026-01-01", "endDate": "2026-03-31" },
          "price": { "min": 100, "max": 900 }
        },
        "isShowOnUrl": false
      }
    ]
  }
}

The dashboard opens with these filter values for the life of the token.

Values you can pass

Filter typeValue
Single selectOne string, number or boolean, for example "USA"
Multi selectAn array, for example ["USA", "Canada"]
Date picker{ "startDate": "2026-01-01", "endDate": "2026-03-31" }
Preset date filterThe preset label, for example "Last 7 days". It must be one of the filter’s presets.
Number range{ "min": 100, "max": 900 }
Values from SQLAn object with sql and columnName (see below)

Values from a SQL query

Use a SQL query when the list is long. Databrain runs the query and uses the values in columnName.

"values": {
  "country": {
    "sql": "SELECT \"name\" FROM \"public\".\"countries\" WHERE is_enabled = true",
    "columnName": "name"
  }
}

The query must be one SELECT (or WITH) statement. On table tenancy, client_id_variable in the query becomes the token’s clientId.

If the SQL query fails or returns no rows, the dashboard loads without that filter by default. Ask Databrain to turn on “Stop the chart when a customer filter breaks” for your company if the filter guards data.

How the name is matched

The key matches the filter’s label or name, and case does not count. Country and country find the same filter.

Show or hide the value in the address bar

isShowOnUrl only matters when the dashboard writes filters to the page URL (options with "isModifyUrl": true). Leave it out or set false to keep token values out of the URL. Set true to show them.

Defaults from the component

global-filter-options on <dbn-dashboard> sets a default value. Viewers can change a default. Use the token when the value must not change. See Filter state.

If something goes wrong

The token request fails with HTTP 400 and code APP_FILTER_PARAM_ERROR. The message tells you why:

  • Invalid dashboard Id: <id> in dashboard appFilter. The dashboard ID is wrong, or the dashboard is not in this data app. Use the ID from the Embeds page, not the name.
  • No filter found: <id> in dashboard appFilter. The dashboard has no filters yet.
  • Invalid dashboard app filter name: <name>. No filter has this label or name, or App Filter is off for it.
  • Invalid select query in dashboard app filter: <name>. The SQL in the value is not one valid SELECT statement.
  • Invalid preset date option in dashboard app filter: <name>. The label is not one of the filter’s presets.

Next, see every token field.