Filter Dashboard Data

• 8 minutes to read

Dashboard parameters allow users to generate different dashboard views using the same underlying template without changes. For example, users can apply a country parameter to populate dashboard tiles only with records from that specified region.

Before you begin, create and configure the countryParameter dashboard parameter. Users can change its value in the Dashboard Parameters dialog. To supply the value only in code, use a hidden parameter.

In this topic…

• Parameter-Based Data Filter Levels
• Tile-Level Filter
  • Step 1 — Open the Filter Editor
  • Step 2 — Build a Filter
• Data Source-Level Filter
  • Step 1 — Create a Query Parameter
  • Step 2 — Add a Query Filter
• Filter Web Service Data at the Source
• Related Tutorial
• Related GitHub-Hosted Sample Projects

Parameter-Based Data Filter Levels

Dashboard parameters allow you to filter out data at different app hierarchy levels. Choose a technique based on your usage scenario and software configuration.

Tile-level filter

The dashboard component filters tile data once all records are loaded from a data source. Tile-level filtering is data source-agnostic and supports complex calculations.

Data source-level filter

The data source filters records before they reach the dashboard. Data source-level data filtering improves performance and reduces app memory footprint for large datasets but requires support for SQL queries and stored procedures (available only for relational databases).

URL-level filter

The dashboard passes parameter values to a web service through the request URL or headers. The web service filters dashboard data on the server to reduce network traffic. URL-level data filtering is available only for web-hosted JSON data sources.

Tile-Level Filter

Tile-level filtering is data source-agnostic and supports complex calculations. You must apply this filter to each dashboard tile individually.

Follow the steps below to filter the dashboard tile by country:

Step 1 — Open the Filter Editor

1. In the Dashboard Designer, click the tile you want to filter.

2. Click the Filters icon in the tile toolbar.

   

3. Choose a filter type:

   • ITEM FILTER filters the tile’s underlying data before calculations and aggregation. Calculated values, such as sales percentages, are recalculated every time the dashboard parameter is changed.
   • VISIBLE DATA FILTER filters only the data displayed in the tile. The filter does not affect underlying data or calculated values.

   

4. Click the pencil icon in the input field to open the Filter Editor dialog.

   

Step 2 — Build a Filter

In the Filter Editor dialog, add a condition that compares the ShipCountry field to the countryParameter parameter value:

1. Hover the And group, click the Plus button, and select Add condition from the drop-down menu:

   

   Tip

   Enable Advanced Mode to enter a raw text query rather than navigate through menus. To reference a dashboard parameter, prefix the parameter name with ? (for example, ?countryParameter).

   

2. Click the left operand and select the data field from the drop-down menu:

   

3. If you need a different comparison operator (for example, to compare against a multi-value parameter), click the central part of the filter condition and select an operator from the drop-down menu:

   

4. Click the arrow icon next to the right operand and select Parameter from the drop-down menu:

   

5. Click the parameter name in the right operand and select countryParameter from the drop-down menu:

   

6. Click the OK button to save the filter:

   

Data Source-Level Filter

Reference a parameter in the dashboard’s query or a stored procedure to filter records before the dashboard component renders tiles. A data source-level filter affects all tiles simultaneously.

Note

Data source-level filters only support SQL data sources but offer higher performance for large datasets. For other data source types, apply filter criteria to records at the tile level.

Follow the steps below to configure a data source to return only records for the selected country (countryParameter):

Step 1 — Create a Query Parameter

A query parameter is a placeholder that receives a dynamic value (such as a calculated expression or user input) when the query runs. In this tutorial, the query parameter receives its value from the countryParameter dashboard parameter and uses it to filter records by country.

1. Open the Dashboard Designer menu and click Data Sources:

   

2. Locate the dashboard data source and click the Pencil icon in the header to open the Dashboard Data Source Wizard:

   

3. Run the Query Builder:

   

4. Create a query parameter. Expand the PARAMETERS section and click the Plus button:

   

5. Expand the query parameter and bind it to the countryParameter dashboard parameter:

   

   Name (1)

   Specify a unique name to reference the parameter in the query.

   Type (2)

   Select Expression to calculate the parameter value every time the query runs.

   Result Type (3)

   Specify the value type returned from the query parameter expression.

   Value (4)

   Click the ellipsis button and create an expression that calculates the query parameter value from dashboard parameter values.

   

Step 2 — Add a Query Filter

In the Filter Editor dialog, add a condition that compares the ShipCountry data source field to the countryParameter parameter value:

1. Expand Query Properties and click the ellipsis button in the Filter field to open the Filter Editor dialog:

   

   Tip

   Enable Advanced Mode to enter a raw text query rather than navigate through menus. To reference a query parameter, prefix the parameter name with ? (for example, ?countryQueryParameter).

   

2. Hover the And group, click the Plus button, and select Add condition from the drop-down menu:

   

3. Click the left operand and select the data source field from the drop-down menu:

   

4. If you need a different comparison operator (for example, to compare against a multi-value parameter), click the central part of the filter condition and select an operator from the drop-down menu:

   

5. Click the arrow next to the right operand and select Parameter from the drop-down menu:

   

   Tip

   The first query parameter is selected automatically. To use another parameter, click the parameter name in the right operand and select the parameter from the drop-down menu.

6. Click the OK button in the Filter Editor dialog to save the filter condition.

7. Click the OK button in the Query Builder to apply changes to the query.

8. Click the Finish button to close the Data Source Wizard:

   

Filter Web Service Data at the Source

If your dashboard connects to a web service endpoint, you can filter data server-side. The dashboard component passes parameter values to the API through a URL path, query string, or HTTP header. Server-side data filtering reduces network traffic and speeds up dashboard rendering because the web service returns only explicitly requested records.

Note

The dashboard only sends parameter values and does not affect remote web service behavior. The web service must accept request parameters/headers and process/apply filter criteria on the server.

Follow the steps below to build an endpoint URL based on dashboard parameter values:

1. Open the Dashboard Designer menu and click Data Sources:

   

2. Click Add above the data source list:

   

3. Create a new JSON data source:

   

4. Configure the web service endpoint:

   

5. Expand the PARAMETERS section and click the Plus button to create a parameter binding:

   

6. Select how to pass the parameter to the web service:

   Path Parameter

   Inserts the parameter value into the endpoint URL path.

   Query Parameter

   Appends the parameter value to the URL query string.

   Header

   Sends the parameter value within an HTTP request header.

   

7. Click the Function button (1) next to the parameter value and then click the ellipsis button (2) to create an expression that fetches the dashboard parameter value:

   

8. Expand the Parameters node and double-click the parameter name to add it to the expression. Use operators and functions to combine or compare parameter references with other data:

   

9. Click Finish to save the connection.

Related Tutorial

The following tutorial creates a parameter, assigns its value, and passes the value to a data source:

Read Tutorial: Bind a Dashboard to a Parameterized Stored Database Procedure

Follow this tutorial to create an application that obtains data from a stored database procedure and passes a dashboard parameter as a procedure parameter.

Related GitHub-Hosted Sample Projects

This section lists all public GitHub repositories (DevExpress-Examples) that demonstrate primary usage scenarios for dashboard parameters:

View Example: Generate Dashboards in a Backend/Service Application

This example filters dashboard data by country name.

View Example: Pass a Hidden Dashboard Parameter to a SQL Query

This example displays sales data for a selected country. The example passes the country to the underlying SQL query as a hidden dashboard parameter.

Related Compiled Demo

To see the dashboard export functionality in action, run the BI Dashboards Designer/Viewer demo in the VCL Demo Center installed with compiled DevExpress VCL demos. Select any demo in the sidebar on the left, click the Export button, and use any export option listed in the menu.

Download: Compiled VCL Demos

Compiled DevExpress demos ship with source code installed in the Public Documents folder (%PUBLIC%) for all users (default). You can find all project and source code files for the BI Dashboards Designer/Viewer demo in the following folder:

Default Installation Path

%PUBLIC%\Documents\DevExpress VCL Demos\MegaDemos\Product Demos\ExpressDashboards\

Tip

Project and source code files for all compiled DevExpress VCL Demos are maintained in a public repository hosted on GitHub:

View Example: DevExpress VCL Demos