> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Filter-only fields

> Define filter-only fields in your Omni model that appear exclusively as dashboard or query filters without showing in results.

## Filter-only fields

```yaml theme={null}
filters:
  order_date:
    type: timestamp
  status:
    type: string
    suggest_from_field: order_items.status
```

```yaml theme={null}
filters:
  rolling_window:
    type: string
    suggestion_list:
      - value: "6"
        label: 7 days
      - value: "13"
        label: 14 days
    default_filter:
      is: "6"
    filter_single_select_only: true
```

```yaml theme={null}
filters:
  timeframe_selector:
    type: string
    suggest_from_field: date_spine.date_string
    suggest_from_topic: opp_line_items
```

Refer to the [Filter syntax reference](/modeling/filters) for more information about filter synatx.

### `aliases:`

```yaml theme={null}
filter_name:
  aliases: [old_filter_name]
```

Similar to table level aliases, occasionally a field name may change in your database, which can cause content to break. To fix this, we can add `aliases:` to the field in question pointing references from the old field name to the updated field name, restoring content and eliminating content related errors. This behaves similar to table level aliases, as shown

### `bind_to:`

```yaml theme={null}
filters:
  date_filter:
    type: timestamp
    bind_to: [created_at, updated_at]
```

List of field names that this filter-only field's filter expression should be applied to. When a filter is applied to this filter-only field, the filter expression will be applied to each field in this list—filters on dimensions go to the WHERE clause, filters on measures go to the HAVING clause.

For more information, see [Templated filters](/modeling/templated-filters).

### `default_filter:`

```yaml theme={null}
status_templated_filter:
  type: string
  default_filter:
    is: "Completed"
  suggestion_list:
    - value: Compeleted
    - value: Returned

# note the [] will default to any value here
templated_filter_default_anything:
  type: string
  default_filter:
    is: []

rolling_window:
  type: string
  suggestion_list:
    - value: "6"
      label: 7 days
    - value: "13"
      label: 14 days
  default_filter:
    is: "6"
  filter_single_select_only: true
```

* `default_filter` will automatically populate the filter value in the templated object
* This is often paired with `filter_single_select_only` and `suggestion_list` when a single-selection is required
* For setting the filter arguments, use the [filter syntax](/modeling/filters)

### `description:`

```yaml theme={null}
status_templated_filter:
  type: string
  default_filter:
    is: "Completed"
  suggestion_list:
    - value: Compeleted
    - value: Returned
  description: This is for filtering stuff in the status fact table
```

* Metadata about the field, made available in the workbook/dashboard table UI upon hovering over a field with a description, or on right click from the field picker
* Omni expects unquoted text (quotes will be removed / ignored)

### `display_order:`

```yaml theme={null}
status_templated_filter:
  type: string
  default_filter:
    is: "Completed"
  suggestion_list:
    - value: Compeleted
    - value: Returned
  description: This is for filtering stuff in the status fact table
  display_order: 1

other_status_templated_filter:
  type: string
  default_filter:
    is: "Completed"
  suggestion_list: [Compeleted, Returned]
  description: This is for filtering stuff in the other status fact table
  display_order: 2
```

* Omni expects a whole number
* This will override the sort order for the field picker, inside the field's grouping (i.e. inside a given view)
  * `display_order` will supersede alphabetical sorting
* For example, if the two fields above in users are given `display_order:` they will float to the top of the field list in users, and the remaining fields would be sorted alphabetically
* To rearrange views, `display_order` can be used at the view level
* For fields inside groups using `group_label`, the group will be ranked with the min of all the fields in the group (i.e. if there are 3 fields with `display_order` of 4, 5 and \{empty}, the group will have a `display_order` of 4)

### `filter_single_select_only:`

```yaml theme={null}
filters:
  rolling_window:
    type: string
    suggestion_list:
      - value: "6"
        label: 7 days
      - value: "13"
        label: 14 days
    default_filter:
      is: "6"
    filter_single_select_only: true
```

* This argument will require the filter field to use a choose-one dropdown rather than the default flexible filter modal
* Recommended with templated filters that require one-and-only-one object

### `group_label:`

```yaml theme={null}
rolling_window:
  group_label: Time Filters
  type: string
  filter_single_select_only: true
```

* This will nest a group of fields in the field picker for curated organization
* Omni expects unquoted text (quotes will be removed / ignored)
* Note measures and dimensions will still be in separate sections in the field picker under each view
* Fields can be nested under timeframes using the group label - the text rather than the field should be used (i.e. `Created At` not `created_at`)

### `hidden:`

```yaml theme={null}
rolling_window:
  hidden: true
```

* Remove the field from the UI. Still referenceable in the model, but hidden in the workbook UI.
* Expects 'true' or 'false'

### `ignored:`

Likely should not be used with filters, can just delete or comment out if it's not desired in the model

### `label:`

```yaml theme={null}
status:
  type: string
  label: Status Filterer
  suggestion_list:
    - value: "Completed"
    - value: "Returned"
```

* Label will override the field name for all UI appearances of the field
* Omni expects unquoted text (quotes will be removed / ignored)

### `required_access_grants:`

You can also conditionally allow access by using pipes (`|`) and ampersands (`&`) to create `OR` and `AND` conditions.

```yaml theme={null}
required_access_grants: [grant_one]

# Grant access if conditions are met for either access grant
required_access_grants: [grant_one|grant_two]

# Grant access if conditions are met for:
# (grant_one OR grant_two)
# AND
# grant_three
required_access_grants: [grant_one|grant_two&grant_three]
```

### `suggestion_list:`

```yaml theme={null}
filters:
  rolling_window:
    type: string
    suggestion_list:
      - value: "6"
        label: 7 days
      - value: "13"
        label: 14 days
  status:
    type: string
    suggestion_list:
      - value: "Completed"
      - value: "Returned"
```

* Suggestion list will explicitly set the suggestions on

### `suggest_from_field:`

```yaml theme={null}
filters:
  timeframe_selector:
    type: string
    suggest_from_field: date_spine.date_string
    suggest_from_topic: opp_line_items
```

```yaml theme={null}
filters:
  status_picker:
    type: string
    suggest_from_field: order_items.status
```

* This argument can be used to populate a filter with another field's values
* Commonly used with the filter is injected in sql with a corresponding modeled field

### `suggest_from_topic:`

```yaml theme={null}
filters:
  timeframe_selector:
    type: string
    suggest_from_field: date_spine.date_string
    suggest_from_topic: opp_line_items
```

* This needs to be paired with `suggest_from_field` and can tune the specific topic (ie access-filters and default filters) for a given suggestion

### `type:`

```yaml theme={null}
filters:
  order_date:
    type: timestamp
  status:
    type: string
```

* Currently, filter-only fields can only be defined in the IDE. They require a name, and a type. The accepted types for a filter-only field are:

  * `boolean`
  * `column` (returns unquoted text, can be used to substitute in column names in query views)
  * `number` *most common*
  * `string` *most common*
  * `timestamp` *most common*

### `view_label:`

```yaml theme={null}
filters:
  order_date:
    type: timestamp
    view_label: Filters
  status:
    type: string
    view_label: Filters
```

* This will nest a given field under a different view than it's default parent view, for example, grouping `user_facts` fields under the `users` view for better organization and discovery
* Note that filters will always be below dimensions and measures
* Sometimes can be valuable to pull all filters into a separate pseudo-view, would do that with the `view` argument as seen here