## Usage
```
explore: explore_name {
always_filter: {
filters: [field_name: "filter expression", field_name: "filter expression", ...]
}
}
```
|---|---|
| Hierarchy [Model File](https://docs.cloud.google.com/looker/docs/reference/param-model.md.txt) [`explore`](https://docs.cloud.google.com/looker/docs/reference/param-explore-explore.md.txt) `always_filter` | Default Value None
Accepts A field name and a [Looker filter expression](https://docs.cloud.google.com/looker/docs/filter-expressions.md.txt) |
## 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`](https://docs.cloud.google.com/looker/docs/reference/param-explore-sql-always-where.md.txt).
- 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`](https://docs.cloud.google.com/looker/docs/reference/param-explore-access-filter.md.txt).
In the `always_filter` parameter, the field that's referenced in the `filters` subparameter can be a [dimension](https://docs.cloud.google.com/looker/docs/reference/param-dimension-filter-parameter-types.md.txt), [measure](https://docs.cloud.google.com/looker/docs/reference/param-measure-types.md.txt), [filter](https://docs.cloud.google.com/looker/docs/reference/param-field-filter.md.txt), or [parameter](https://docs.cloud.google.com/looker/docs/reference/param-field-parameter.md.txt). 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](https://docs.cloud.google.com/looker/docs/filter-expressions.md.txt), 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) and the Boolean (`type: yesno`) **Is Complete** field (with a case-sensitive default value of `"No"`):
explore: order {
always_filter: {
filters: [created_date: "7 days", is_complete: "No"]
}
}
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
### Boolean filter values in `always_filter` are case-sensitive
When filtering on a [`type: yesno`](https://docs.cloud.google.com/looker/docs/reference/param-dimension-filter-parameter-types.md.txt#yesno) field in the `always_filter` parameter, the [Boolean filter expression](https://docs.cloud.google.com/looker/docs/filter-expressions.md.txt#boolean) is case-sensitive and must be capitalized (`"Yes"` or `"No"`). This differs from the [`filters`](https://docs.cloud.google.com/looker/docs/reference/param-field-filters.md.txt) subparameter for measures, which isn't case-sensitive for Boolean values.
### 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](https://docs.cloud.google.com/looker/docs/sharing-data.md.txt) 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`](https://docs.cloud.google.com/looker/docs/reference/param-field-default-value.md.txt) 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`.