From 15dc2779b7f70b23b5aaca80d3e502d113507b91 Mon Sep 17 00:00:00 2001 From: royendo <67675319+royendo@users.noreply.github.com> Date: Fri, 9 Jan 2026 09:37:41 -0500 Subject: [PATCH] default filters canvas YAML, and docs for both canvas and explore (https://github.com/rilldata/rill/pull/8501) --- docs/docs/build/dashboards/customization.md | 18 ++++ .../project-files/canvas-dashboards.md | 62 +++--------- runtime/parser/schema/project.schema.yaml | 97 ++++--------------- 3 files changed, 50 insertions(+), 127 deletions(-) diff --git a/docs/docs/build/dashboards/customization.md b/docs/docs/build/dashboards/customization.md index 8f3be34ca6c..646f9d90124 100644 --- a/docs/docs/build/dashboards/customization.md +++ b/docs/docs/build/dashboards/customization.md @@ -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 diff --git a/docs/docs/reference/project-files/canvas-dashboards.md b/docs/docs/reference/project-files/canvas-dashboards.md index 41e113afa1c..7e91dea5a75 100644 --- a/docs/docs/reference/project-files/canvas-dashboards.md +++ b/docs/docs/reference/project-files/canvas-dashboards.md @@ -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. @@ -118,21 +120,15 @@ _[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')" ``` @@ -140,43 +136,11 @@ _[object]_ - defines the defaults YAML struct - **`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` diff --git a/runtime/parser/schema/project.schema.yaml b/runtime/parser/schema/project.schema.yaml index 02925c27aae..6d77c8d833a 100644 --- a/runtime/parser/schema/project.schema.yaml +++ b/runtime/parser/schema/project.schema.yaml @@ -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. @@ -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: @@ -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