diff --git a/get-started/exploring-data/dashboards.mdx b/get-started/exploring-data/dashboards.mdx index 7fb5f5e0..31a9b517 100644 --- a/get-started/exploring-data/dashboards.mdx +++ b/get-started/exploring-data/dashboards.mdx @@ -160,16 +160,14 @@ You can also see all of the saved dashboards in your project by clicking on `Bro ## Add filters -Now let's add some filters to your dashboard. First, start by editing your dashboard by clicking on the `Edit dashboard` button. +Filters let you narrow down the data displayed across your dashboard charts. You can add filters while editing your dashboard or apply temporary filters while viewing. - - - +To add a saved filter that all viewers will see: -Click on the `Add filter` button to add a new filter to your dashboard by selecting a field and a value to filter by. +1. Click `Edit dashboard` +2. Click `Add filter` +3. Select a field and optionally set a default value +4. Click `Apply`, then `Save` -Select a value to filter by and hit `Apply`. You can add as many filters as you like. - - - - - -Now that you've added a filter, you can see the filter applied to your dashboard. - - - - - -Hit `Save` to save your dashboard with the new filter. - - -### Leaving filters empty - -You might want to add an empty-value filter so that your dashboard viewers can choose their own value and explore the data based on their own criteria. Your dashboard viewers might also want to add their own filters to your dashboard. - - -#### Adding an empty-value filter - -Just edit your filter and ensure that you don't provide a default value. - - - - - - -#### Marking a filter as required - -You can mark a filter as required for the dashboard to run. This means that the dashboard will not run unless a value is selected for the filter. Just edit your filter and check the "Require value for dashboard to run" checkbox. - - - - - -Until viewers have set a value for the filter, the dashboard will not run. - - - - - -To learn more about adding filters to your dashboards, check out our guide on [using filters](/guides/limiting-data-using-filters). +For detailed information on filter types, temporary vs saved filters, required filters, and advanced filtering options, see the [using filters guide](/guides/limiting-data-using-filters). ## Add tabs diff --git a/guides/limiting-data-using-filters.mdx b/guides/limiting-data-using-filters.mdx index c333bdd9..ab93b98a 100644 --- a/guides/limiting-data-using-filters.mdx +++ b/guides/limiting-data-using-filters.mdx @@ -4,315 +4,194 @@ sidebarTitle: Filters descritpion: Filters appear at the top of the Explore view or dashboard and allow users to change the data being pulled into your charts. --- -For example, if I built a chart showing the revenue over time, but I wanted it to only have the revenue I made in France, I could add a filter for `country is equal to France`. - -You can [add filters to your charts individually in the Explore view](#adding-filters-in-the-explore-view), or [across all of your charts in your dashboard](#adding-filters-to-your-dashboard). Don't worry, we'll walk you through both and you'll be a filter pro in no time! +Filters let you narrow down the data displayed in your charts. For example, if you built a chart showing revenue over time, you could add a filter for `country is equal to France` to see only French revenue. +You can add filters to individual charts in the Explore view or apply them across all charts in a dashboard. -If you're a developer, you can add permanent filters to tables using the `sql_filter` yaml option. For more information see [Table configuration](/references/tables#sql-filter) +Developers can add permanent filters to tables using the `sql_filter` yaml option. See [Table configuration](/references/tables#sql-filter) for details. -## General filters tips - -Here are some general tips about filters that apply to using them in both the Explore view and in dashboards. +## Quick start -### If you want to have multiple filters, just click `+ Add filter` +### Adding filters in Explore view -In the Explore view: +Add filters to charts in three ways: - - - +- **From the Filters tab**: Click the Filters toggle, then `add filter` +- **From the sidebar**: Click the options menu on any field and select `add filter` +- **From the results table**: Click the three-dot menu on a column or click directly on a value +### Adding filters to dashboards -Or in a dashboard: - - - - +**Temporary filters** (visible only to you): +- Click `add filter` while viewing the dashboard +- Or use cross-filtering by clicking on chart values +**Saved filters** (visible to everyone): +- Enter edit mode by clicking `Edit Dashboard` +- Click `add filter` and configure your filter +- Click `Save` to apply the filter for all users -### If you add multiple filters, you can choose to have `ALL` or `ANY` of the conditions match +## Filter capabilities reference -To choose which option you want, just click on the drop-down menu on the top-left of the filters. +### Multiple filters - - - - - -Selecting `ALL` conditions to match means you'd add an `AND` between your conditions in SQL. So, the example in the Explore view above would give us compiled SQL that looks like: - -```sql -WHERE ( - (pages.source) IN ('lightdash_demo', 'lightdash_documentation') - AND (pages.path) = '/20%crunchbase' -``` +| Feature | How to use | +|---------|-----------| +| Add multiple filters | Click `+ Add filter` | +| Combine with AND logic | Select `ALL` conditions from the dropdown | +| Combine with OR logic | Select `ANY` conditions from the dropdown | +| Add multiple values | Press `enter` between each value | -Selecting `ANY` conditions to match means you'd add an `OR` between your conditions in SQL. So, the example in the Explore view above would give us compiled SQL that looks like: +### Nested filters -```sql -WHERE ( - (pages.source) IN ('lightdash_demo', 'lightdash_documentation') - OR (pages.path) = '/20%crunchbase' -``` +Create complex filter groups by converting a filter to a group: -### If you want to include multiple values in your filter, just hit `enter` between each value entry in your list - - - - - - -The listed values are separated by an OR statement in the compiled SQL. E.g. the above would give us: - -```sql -WHERE ( - (pages.source) = 'lightdash_demo' - OR (pages.source) = 'lightdash_documentation' -) -``` - -### To learn about the types of filters we have available, check out the filters reference doc. - -Check out our [filters reference doc here](/references/filters) to see a list of all available filters and their uses. - -## Adding filters in the Explore view - -There are a couple of ways that you can add filters in the Explore view. - -### Adding a filter from within the `Filters` tab - -In the Explores view, you can add filters from within the `Filters` tab. Just click to open the toggle, then click `add filter`. - - - - - - -Select the field you would like to filter from the drop-down list, then select the filtering options. - -### Adding a filter from the sidebar - -It's easy to add filters directly from the list of fields in the sidebar. Just click on the `options` for a field, then click `add filter`. - - - - - - -### Adding a filter from the results table - -Once you have some results in your results table, you can add filters by clicking on the three-dot menu of the column you want to filter on, or by clicking on the value you want to filter by. - - - - - - -### Adding nested filters - -You can add nested filters by clicking on the options button on the right-hand side of the filter and then click on `convert to group`. +1. Click the options button on the right side of any filter +2. Select `convert to group` +3. Add additional filters within the group +### Filter types -Then, you can add a new filter to the nested filter by clicking `add filter`. +For a complete list of available filter operators and their uses, see the [filters reference documentation](/references/filters). - - - +## Dashboard filters -## Adding filters to your dashboard +### Temporary vs saved filters -There are a couple of ways that you can add filters to your Dashboards. +| Filter type | Visibility | When to use | +|------------|-----------|-------------| +| **Temporary** | Only visible to you | Quick exploration without affecting others | +| **Saved** | Visible to all dashboard viewers | Set default filters for the entire team | -### Adding temporary filters to your dashboard + +Temporary filter values are reverted when entering dashboard edit mode. + -If you add a temporary filter to your dasboard, then only you will see the filters you've applied (you won't be changing the dashboard for everyone who comes to look at it). If you want to save the dashboard filters you're adding, then check out [adding saved filters to your dashboard](#adding-saved-filters-to-your-dashboard). +### Adding temporary filters -There are two ways to add temporary filters to your dashboard. +**Using the add filter button:** -##### Adding temporary filters using the `add filters` button +1. Click `add filter` while viewing the dashboard +2. Select the field and value to filter by +3. Optionally adjust which tiles the filter applies to in the `Tiles` tab -1. Open up your dashboard. -2. Click `add filter`, then specify the field that you want to filter on and the value you want to filter by. - - - +**Using cross-filtering:** + +Click on any value in a chart to filter the entire dashboard by that value. -3. If you want, you can adjust which tiles the filter is applied to by clicking on the `Tiles` tab. - + -You can remove the filter from a certain tile, or you can change which field the filter is applied to in a tile. +### Adding saved filters - - - +1. Click `Edit Dashboard` to enter edit mode +2. Click `add filter` and select your field +3. Configure the filter: + - **Leave value blank**: Dashboard viewers can set their own values + - **Set a default value**: Toggle 'Default value' and specify the value +4. Adjust tile application in the `Tiles` tab if needed +5. Click `Apply`, then `Save` -4. And voilà! Your filters will pop up on the top of your dashboard. - + -Values for temporary and overriden saved filters are reverted when entering Dashboard edit mode. +You must be an editor or admin to add saved filters. -##### `Cross filtering` your dashboard using values in your tiles +### Marking filters as required -Cross-filtering lets you interact with one chart and apply that interaction as a filter to other charts in the dashboard. You can filter the dashboard using cross filtering by: +You can require users to set a filter value before the dashboard runs: -1. Clicking on one of the values in the chart. -2. Selecting the value you want to filter on from the drop-down list. - - - +1. Edit your filter +2. Check "Require value for dashboard to run" +3. Save the dashboard -3. Now, your filter will pop up on the top of your dashboard. - + +Until a value is set, the dashboard will remain locked. -### Adding saved filters to your dashboard - -If you add a saved filter to your dashboard, then anyone that opens the dashboard will see the saved filters applied. - -To add saved filters, you just: - -1. Open up your dashboard. -2. Make sure you're in `edit` mode (if you're not, you should see the option to click `Edit Dashboard`) - + -3. Click `add filter`, then specify the dimension or metric that you want to filter on. - - - - -4. You can leave the value blank, or you can specify a value that you want to filter by: - -If you leave the value blank, then no filter will be applied to the tiles in your dashboard. Importantly, this provides dashboard viewers the option to define a value in the filter, enabling them to tailor the results to their needs. - - - +### Controlling filter scope -If you want to specify a value, ensure you toggle 'Default value' so that you can apply a filter to the tiles in your dashboard. - - - +Use the `Tiles` tab in the filter configuration to: +- Remove the filter from specific tiles +- Change which field the filter applies to in each tile -5. If you want, you can adjust which tiles the filter is applied to by clicking on the `Tiles` tab. +### SQL Runner chart filters -You can remove the filter from a certain tile, or you can change which field the filter is applied to in a tile. - - - - - -6. Click `apply`, and your filters will pop up on the top of your dashboard. - - - - -7. Once you have all of the filters you want, just hit `save` to save your filter settings. - - - +Dashboard filters work with SQL Runner charts in two ways: -Now, whenever someone opens the dashboard, they'll see your saved filters applied! - - - +**Mixed dashboards** (Explorer + SQL Runner charts): +- Create filters normally by selecting a field +- In the `Chart tiles` tab, apply the filter to SQL chart tiles and choose the column -And if they want to drill-down into the data, they can always change the filters by clicking on the filter and adjusting the values. - - - +**SQL-only dashboards**: +- Choose a column from all available columns across charts +- Provide a filter label for clarity +- Select your operator and values +- By default, applies to all columns with the same name -To add saved filters to your dashboard, you must be an `editor` or an `admin` for your project. +Filters only apply to dimensions (non-aggregated columns) in SQL Runner charts. -### Filtering charts created in the SQL Runner - -Dashboard filters can be applied to SQL Runner-based charts as well as charts from the Explorer. There are two different ways this can be done: - -- On a dashboard with both Explorer and SQL Runner charts, filters are created the same way as above — you choose a field and create a filter. - Then, in the **Chart tiles** tab, you can apply the filter to a SQL chart tile and choose the column you want that filter to apply to. - -- On a dashboard with **only** SQL Runner-based tiles, filters are created a little differently since SQL charts are based on columns instead of semantic fields. - -#### To create a filter on a dashboard with only SQL charts: +## Dashboard filter behavior -1. Choose a column from the list of all columns available across all charts. -2. Choose a filter label to give your filter a recognizable name. -3. Choose your filter operator and values as you would for any other filter. +### Filter visibility -By default, the new filter will be applied to every column on the dashboard that has the same name as the filtered column. -You can also choose, in the **Chart tiles** tab of the filter dropdown, exactly which tiles and columns to apply it to. - -Note that as with Explorer-chart filters, you can only apply fitlers to dimensions (in this case, non-aggregated columns). - -### Some things worth mentioning about dashboard filters - -##### Sharing your dashboard with overrides - -You might want to share a dashboard with someone with custom filters applied. To do this, you have to be in _view mode_. Then, you can either/or: - -1. Apply temporary filters to your dashboard and share the link with the filters applied. -2. Apply changes(overrides) to your saved filters and share the link with the filters applied. - -Rules for sharing dashboards with filters applied: - -* In view mode and when adding a temporary filter, you can change the field, value, operator, and tiles this is applied to. But, you can't change the filter type (e.g. from `temporary filter` to `saved filter`). -* In view mode and when overriding a saved filter, you can only change the value and operator, so the field and tile configuration will remain the same. -* In edit mode, when changing a saved filter (with an override present), once you save the changes (click "Apply"), the override for that filter will be removed. - -The same behaviour applies when exporting dashboards or sending them to email or Slack in [scheduled deliveries](/guides/how-to-create-scheduled-deliveries). - -##### You can easily see which dashboard tiles have which filters applied to them - -If a tile in a dashboard has a filter applied to it, you'll see the text `dashboard filter applied` on the tile. - -You can also hover over this to see **_which_** filters have been applied to that tile. +Tiles with filters applied show `dashboard filter applied` text. Hover over this to see which specific filters are active. +### Filter precedence -##### Dashboard filters override filters applied in a saved chart on the same field +Dashboard filters override saved chart filters on the same field. -For example, if I had a chart for Sales in Asia and I filtered to `country` **is** `China`, `India`, `Japan`. Then, on my dashboard I added a filter `country` **is** `India`. My saved chart's filter would be removed, and my new dashboard filter would be applied instead, so the tile in the dashboard would be filtered to: `country` **is** `India`. +**Example**: A saved chart filtered to `country is China, India, Japan` with a dashboard filter of `country is India` will only show India data. -Here's another example using a date filter: If my original saved chart was filtered to only include orders completed on or after April 3rd, 2024\. But, I add a date filter to my dashboard to include orders completed on or after August 1st, 2024, then the dashboard filter would override the saved chart filter and I'll end up with the chart filtered by orders completed on or after August 1st, 2022. +**When exploring from a dashboard**: +- `Explore from here` preserves dashboard filter overrides +- `Edit` shows the original chart filters -**How charts work in this context:** +### Sharing with filter overrides -* When you **Explore from here** from a dashboard, the chart will include the same filters you saw on the Dashboard version. Any filters overriden in the dahsboard will be overriden in the **Explore from here** view. Filters NOT overriden in the dashboad will be the same as they were in the original chart. -* If you 'Edit' the chart instead of explore from here, you will see the original chart filters. +Share dashboards with custom filter values from view mode: +- Apply temporary filters or override saved filters +- Copy the URL to share with filters applied -Here's another example using a date filter: If my original saved chart was filtered to only include orders completed on or after April 3rd, 2022\. But, I add a date filter to my dashboard to include orders completed on or after August 1st, 2022, then the dashboard filter would be added to the saved chart filter and I'll end up with the chart filtered by orders completed on or after August 1st, 2022. +**Override rules**: +- **Temporary filters**: Can change field, value, operator, and tiles +- **Saved filter overrides**: Can only change value and operator +- Saving changes in edit mode removes overrides -##### Dashboard filters autocomplete +This behavior applies to scheduled deliveries and exports. -When determining possible values for a dashboard filter, the system will take into account all relevant filters, including those applied to fields from joined tables. +### Filter autocomplete -Example with payments and orders models: +Filter autocomplete considers all relevant filters from joined tables. +**Example**: ```yaml - name: customers --- @@ -331,8 +210,7 @@ Example with payments and orders models: sql_on: ${customers.customer_id} = ${orders.customer_id} ``` -Following this example: - -* when filtering on a field from the `payments` model, the system will consider the filters applied to fields from the `payments`, `orders` and `customers` models -* when filtering on a field from the `orders` model, the system will consider the filters applied to fields from the `orders` and `customers` models -* when filtering on a field from the `customers` model, the system will consider the filters applied to fields from the `customers` model +When filtering: +- `payments` fields: considers filters from payments, orders, and customers +- `orders` fields: considers filters from orders and customers +- `customers` fields: considers filters from customers only diff --git a/images/Screenshot2025-10-07at3.48.21PM.png b/images/Screenshot2025-10-07at3.48.21PM.png new file mode 100644 index 00000000..7a05038b Binary files /dev/null and b/images/Screenshot2025-10-07at3.48.21PM.png differ diff --git a/images/Screenshot2025-10-07at3.49.42PM.png b/images/Screenshot2025-10-07at3.49.42PM.png new file mode 100644 index 00000000..bbb80607 Binary files /dev/null and b/images/Screenshot2025-10-07at3.49.42PM.png differ diff --git a/images/Screenshot2025-10-07at3.51.28PM.png b/images/Screenshot2025-10-07at3.51.28PM.png new file mode 100644 index 00000000..f32166cc Binary files /dev/null and b/images/Screenshot2025-10-07at3.51.28PM.png differ diff --git a/images/Screenshot2025-10-07at3.59.28PM.png b/images/Screenshot2025-10-07at3.59.28PM.png new file mode 100644 index 00000000..dda0e324 Binary files /dev/null and b/images/Screenshot2025-10-07at3.59.28PM.png differ diff --git a/images/Screenshot2025-10-07at4.01.54PM.png b/images/Screenshot2025-10-07at4.01.54PM.png new file mode 100644 index 00000000..0943c623 Binary files /dev/null and b/images/Screenshot2025-10-07at4.01.54PM.png differ diff --git a/images/Screenshot2025-10-07at4.03.21PM.png b/images/Screenshot2025-10-07at4.03.21PM.png new file mode 100644 index 00000000..38d8e7e0 Binary files /dev/null and b/images/Screenshot2025-10-07at4.03.21PM.png differ diff --git a/images/Screenshot2025-10-07at4.07.34PM.png b/images/Screenshot2025-10-07at4.07.34PM.png new file mode 100644 index 00000000..24f201d3 Binary files /dev/null and b/images/Screenshot2025-10-07at4.07.34PM.png differ