always_filter

Usage

explore: explore_name {
  always_filter:  {
    filters:  [field_name: "filter expression", field_name: "filter expression", ...]
  }
}

Definition

The always_filter parameter lets you require users to include a set of filters for an Explore. After you define the filters and their default values by using the always_filter parameter, then the Explore automatically displays your configured filter settings.

The filters that you specify in the always_filter parameter can't be removed from the Explore. However, your users can modify the filter by changing the filter's values or by changing the filter's condition from the condition drop-down menu. Your users can also remove all values from the filter, which has the same effect as removing the filter.

If you want an Explore to have filters that can't be modified or removed, use one of the following parameters instead:

• To configure filters that are the same for everyone and that can't be seen or changed in any way, you can use sql_always_where.
• To configure filters that are specific to each user and that can't be seen or changed in any way, you can use access_filter.

In the always_filter parameter, the field that's referenced in the filters subparameter can be a dimension, measure, filter, or parameter. If you need to reference a dimension or measure that is part of a joined view rather than part of this Explore, use view_name.field_name. For example:

explore: order {
  always_filter: {
    filters: [id: "123", customer.id: "789"]
  }
  join: customer {
    sql_on: ${order.customer_id} = ${customer.id} ;;
  }
}

Here the id filter refers to the id field from order. The customer.id filter refers to the id field from customer. This example also demonstrates that you can add multiple filters.

For each field_name: "filter expression" pair, the filter expression can be an absolute value or you can use Looker filter expressions, depending on the type of field that you're filtering on.

Examples

Configure a default filter for the Explore on the Order ID field (with a default value of "123"):

explore: order {
  always_filter: {
    filters: [id: "123"]
  }
}

Configure a default filter for the Explore on the Order Created Date field (with a default value of the previous seven days):

explore: order {
  always_filter: {
    filters: [created_date: "7 days"]
  }
}

Configure a default filter for the Explore on the Order ID field (default value of "123"), the Order City field (default value of "Chicago"), and the Customer Age field (default value of greater than or equal to 18):

explore: order {
  always_filter: {
    filters: [id: "123", city: "Chicago", customer.age: ">=18"]
  }
  join: customer {
    sql_on: ${order.customer_id} = ${customer.id} ;;
  }
}

Things to consider

Users can't remove a filter specified by always_filter

Although users may change the condition or the default value for their query, they can't remove a filter that has been added by always_filter. If you want to pre-load filters for an Explore in a way that lets users completely remove the filters, consider creating a query that includes suggested filters and then sharing the query with users so they can use the query and its filters as a starting point.

Setting a blank default value

If you want to create a default filter with a blank default value, you can do so by specifying "-EMPTY" in the filter values:

always_filter: {
  filters: [products.category: "-EMPTY"]
}

The always_filter parameter overrides a default_value filter setting

The always_filter parameter overrides the default_value setting for the field. If you declare a value with always_filter, that value will be the default in the Explore. If you don't declare a value with always_filter, then "is any value" is the filter default in the Explore.

always_filter affects existing Looks and dashboard tiles

Adding the always_filter parameter to an existing explore definition adds the set of filters with the default values to any Looks, Explores, or dashboard tiles that are based on that explore, including previously saved Looks and dashboard tiles that are based on the explore.