Skip to content

docs: default filters #8617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
royendo wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: default filters #8617

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/docs/build/dashboards/customization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,25 @@ defaults:

```

### Default Filters

You can set default filter expressions that apply when users first load the dashboard. Filters are specified as a map where keys are metrics view names and values are SQL-like filter expressions.

```yaml
defaults:
time_range: P7D
comparison_mode: time
filters:
sales_metrics: "region IN ('US', 'CA', 'UK')"
orders_metrics: "status = 'completed' AND amount > 100"
```

The filter expression syntax supports:
- Equality: `dimension = 'value'`
- IN lists: `dimension IN ('value1', 'value2')`
- Comparisons: `measure > 100`, `measure >= 50`
- Logical operators: `AND`, `OR`
- Combinations: `country IN ('US', 'CA') AND revenue > 1000`

## Time Ranges

Expand Down
62 changes: 13 additions & 49 deletions docs/docs/reference/project-files/canvas-dashboards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,10 +68,12 @@ _[integer]_ - Vertical gap in pixels of the canvas

### `filters`

_[object]_ - Indicates if filters should be enabled for the canvas.
_[object]_ - Configuration for filters on the canvas dashboard.

- **`enable`** - _[boolean]_ - Toggles filtering functionality for the canvas dashboard.

- **`pinned`** - _[array of string]_ - List of dimension names to pin as filters at the top of the canvas.

### `allow_custom_time_range`

_[boolean]_ - Defaults to true, when set to false it will hide the ability to set a custom time range for the user.
Expand Down Expand Up @@ -118,65 +120,27 @@ _[array of string]_ - Refers to the time zones that should be pinned to the top

### `defaults`

_[object]_ - defines the defaults YAML struct
_[object]_ - Default preset state for the canvas dashboard.
```yaml
defaults: #define all the defaults within here
defaults:
time_range: P1M
comparison_mode: dimension #time, none
comparison_dimension: filename
comparison_mode: time
comparison_dimension: region
filters:
dimensions:
- dimension: country
values: ["US", "CA"]
mode: in_list
measures:
- measure: revenue
operator: gt
values: ["1000"]
metrics_view_name: "dimension = 'value'"
another_metrics_view: "country IN ('US', 'CA')"
```


- **`time_range`** - _[string]_ - Refers to the default time range shown when a user initially loads the dashboard. The value must be either a valid [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) (for example, PT12H for 12 hours, P1M for 1 month, or P26W for 26 weeks) or one of the [Rill ISO 8601 extensions](https://docs.rilldata.com/reference/rill-iso-extensions#extensions)

- **`comparison_mode`** - _[string]_ - Controls how to compare current data with historical or categorical baselines. Options: `none` (no comparison), `time` (compares with past based on default_time_range), `dimension` (compares based on comparison_dimension values)

- **`comparison_dimension`** - _[string]_ - for dimension mode, specify the comparison dimension by name

- **`filters`** - _[object]_ - Default filter configuration

- **`dimensions`** - _[array of object]_ - List of default dimension filters

- **`dimension`** - _[string]_ - Name of the dimension to filter on

- **`values`** - _[array of string]_ - List of values to filter by

- **`limit`** - _[integer]_ - Maximum number of values to show in the filter

- **`removable`** - _[boolean]_ - Whether the filter can be removed by the user

- **`locked`** - _[boolean]_ - Whether the filter is locked and cannot be modified

- **`hidden`** - _[boolean]_ - Whether the filter is hidden from the UI

- **`mode`** - _[string]_ - Filter mode - select for dropdown, in_list for multi-select, contains for text search
- **`comparison_dimension`** - _[string]_ - For dimension mode, specify the comparison dimension by name

- **`exclude`** - _[boolean]_ - Whether to exclude the specified values instead of including them

- **`measures`** - _[array of object]_ - List of default measure filters

- **`measure`** - _[string]_ - Name of the measure to filter on

- **`by_dimension`** - _[string]_ - Dimension to group the measure filter by

- **`operator`** - _[string]_ - Operator for the measure filter (e.g., eq, gt, lt, gte, lte)

- **`values`** - _[array of string]_ - List of values to filter by

- **`removable`** - _[boolean]_ - Whether the filter can be removed by the user

- **`locked`** - _[boolean]_ - Whether the filter is locked and cannot be modified

- **`hidden`** - _[boolean]_ - Whether the filter is hidden from the UI
- **`filters`** - _[object]_ - Default filter expressions per metrics view. Keys are metrics view names, values are SQL-like filter expressions.
Example: `metrics_view_name: "country IN ('US', 'CA') AND revenue > 1000"`


### `theme`

Expand Down
97 changes: 19 additions & 78 deletions runtime/parser/schema/project.schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2137,11 +2137,16 @@ definitions:
minimum: 0
filters:
type: object
description: Indicates if filters should be enabled for the canvas.
description: Configuration for filters on the canvas dashboard.
properties:
enable:
type: boolean
description: Toggles filtering functionality for the canvas dashboard.
pinned:
type: array
description: List of dimension names to pin as filters at the top of the canvas.
items:
type: string
allow_custom_time_range:
type: boolean
description: Defaults to true, when set to false it will hide the ability to set a custom time range for the user.
Expand Down Expand Up @@ -2173,21 +2178,15 @@ definitions:
defaults:
type: object
description: |
defines the defaults YAML struct
Default preset state for the canvas dashboard.
```yaml
defaults: #define all the defaults within here
defaults:
time_range: P1M
comparison_mode: dimension #time, none
comparison_dimension: filename
comparison_mode: time
comparison_dimension: region
filters:
dimensions:
- dimension: country
values: ["US", "CA"]
mode: in_list
measures:
- measure: revenue
operator: gt
values: ["1000"]
metrics_view_name: "dimension = 'value'"
another_metrics_view: "country IN ('US', 'CA')"
```
properties:
time_range:
Expand All @@ -2201,74 +2200,16 @@ definitions:
- time
- dimension
comparison_dimension:
description: 'for dimension mode, specify the comparison dimension by name'
description: 'For dimension mode, specify the comparison dimension by name'
type: string
filters:
type: object
description: Default filter configuration
properties:
dimensions:
type: array
description: List of default dimension filters
items:
type: object
properties:
dimension:
type: string
description: Name of the dimension to filter on
values:
type: array
items:
type: string
description: List of values to filter by
limit:
type: integer
description: Maximum number of values to show in the filter
removable:
type: boolean
description: Whether the filter can be removed by the user
locked:
type: boolean
description: Whether the filter is locked and cannot be modified
hidden:
type: boolean
description: Whether the filter is hidden from the UI
mode:
type: string
enum: [select, in_list, contains]
description: Filter mode - select for dropdown, in_list for multi-select, contains for text search
exclude:
type: boolean
description: Whether to exclude the specified values instead of including them
measures:
type: array
description: List of default measure filters
items:
type: object
properties:
measure:
type: string
description: Name of the measure to filter on
by_dimension:
type: string
description: Dimension to group the measure filter by
operator:
type: string
description: Operator for the measure filter (e.g., eq, gt, lt, gte, lte)
values:
type: array
items:
type: string
description: List of values to filter by
removable:
type: boolean
description: Whether the filter can be removed by the user
locked:
type: boolean
description: Whether the filter is locked and cannot be modified
hidden:
type: boolean
description: Whether the filter is hidden from the UI
description: |
Default filter expressions per metrics view. Keys are metrics view names, values are SQL-like filter expressions.
Example: `metrics_view_name: "country IN ('US', 'CA') AND revenue > 1000"`
additionalProperties:
type: string
description: SQL-like filter expression for the metrics view
theme:
oneOf:
- type: string
Expand Down
Loading