Filtering & Personalization
Set metric filters from the token
Lock a metric filter to a value your backend puts in the guest token.
A metric app filter takes its value from params.appFilters in the guest token. Viewers cannot change it.
Before you start
- You have a metric in a dashboard that a data app shares.
- Your backend creates guest tokens. See Guest token API.
Steps
- Open the metric and add a metric filter.
- In Filter Name, enter a name, for example
country. This name is the key in the token. - In the Apply On section, turn on App Filter.
- Save the filter and the metric.
- Copy the metric ID. See Metric ID.
- In your backend, add the filter to
params.appFilterswhen you create the guest token:
{
"clientId": "acme-corp",
"dataAppName": "Customer Analytics",
"params": {
"appFilters": [
{
"metricId": "YOUR_METRIC_ID",
"values": {
"country": ["USA", "Canada"],
"paid_orders": true,
"amount": 500
}
}
]
}
}The metric now runs with these values for the life of the token.
Values you can pass
| Filter type | Value |
|---|---|
| Single select | One string, number or boolean, for example "USA" |
| Multi select | An array, for example ["USA", "Canada"] |
| Preset date filter | The preset label, for example "Last 7 days". It must be one of the filter’s presets. |
| Values from SQL | An 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 on the metric’s datasource 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.
If the SQL query fails or returns no rows, the metric 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 must equal the Filter Name exactly. Case and spaces count. Databrain removes spaces at the start and end of the name when you save it. Dashboard app filters are different: they ignore case.
Defaults from the component
metric-filter-options on <dbn-metric> sets a default value. Viewers can change a default. Use the token when the value must not change. See Options.
If something goes wrong
The token request fails with HTTP 400 and code APP_FILTER_PARAM_ERROR. The message tells you why:
Invalid metric Id: <id> in appFilter. The metric ID is wrong, or the metric is not in a workspace of this data app.Invalid app filter name: <name>. No filter has this exact name, or App Filter is off for it.Invalid select query in app filter: <name>. The SQL in the value is not one validSELECTstatement.Invalid preset date option in app filter: <name>. The label is not one of the filter’s presets.