Skip to Content

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

  1. Open the metric and add a metric filter.
  2. In Filter Name, enter a name, for example country. This name is the key in the token.
  3. In the Apply On section, turn on App Filter.
  4. Save the filter and the metric.
  5. Copy the metric ID. See Metric ID.
  6. In your backend, add the filter to params.appFilters when 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 typeValue
Single selectOne string, number or boolean, for example "USA"
Multi selectAn array, for example ["USA", "Canada"]
Preset date filterThe preset label, for example "Last 7 days". It must be one of the filter’s presets.
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 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 valid SELECT statement.
  • Invalid preset date option in app filter: <name>. The label is not one of the filter’s presets.

Next, set dashboard filters from the token.