How to set up a text filter to query text fields-Quick BI(Quick BI)-阿里云帮助中心

Text filters allow report viewers to dynamically query and filter data by entering or selecting text field values. This helps them focus on relevant information by filtering chart data based on specific text conditions.

The main advantages of text filters are as follows:

High flexibility: Offers three display types (drop-down list, text input box, and tree drop) with extensive configuration options for various business scenarios.
High precision: The filter supports multiple matching conditions, such as contains, does not contain, starts with, and ends with, for precise data filtering.

Quick BI supports three display types for text filters: drop-down list, text input box, and tree drop. This topic describes the use cases and configuration for each type.

Prerequisites

You have created a dashboard that contains charts with text fields.
You have added an empty filter to the dashboard. For more information, see Create a filter.

Configure the filter

Go to the dashboard edit page. For instructions, see Create a dashboard.
In the dashboard list, find and click the target dashboard.
The charts on the dashboard must contain text fields to set up a text filter. This topic uses a line chart as an example. For more information, see Line chart.
Follow the steps in the figure to add a filter.
Configure the filter.
1. Set the filter name to Level Query.
2. Select the associated chart Line Chart and the associated field Order Level.
3. Set the display type and complete the filter configuration.
  1. If you set Display type to Drop-down list, see the example in Drop-down list.
  2. If you set Display type to Text input box, see the example in Text input box.
  3. If you set Display type to Tree drop, see the example in Tree drop.
Click OK.

Drop-down list

The drop-down list display type presents predefined options for selection. When you set the Display type to drop-down list, you can set the option source to Automatic parsing, single dataset, or Manual input.

Automatic parsing

When you select automatic parsing as the option source, Quick BI automatically populates the filter with a union of all values from the associated fields.

Note

If the charts selected in the Associated charts and fields section are from the same dataset, automatic parsing obtains the values from that dataset.
If the chart selected in the Associated Charts and Fields area is based on multiple datasets, selecting Auto Parse means that the system automatically retrieves the values from these datasets. That is, the values in the drop-down list are a union of the values from the associated datasets.

Parameter	Description	Example
Selection mode	Supports single choice and multiple choice.	Selection mode: Select multiple choice. Query time: Select click to query. Set filter defaults: Set Order Level to Advanced, Province to Guangdong Province, and Product Type to Furniture Products.
Query time	Supports click to query and pre-query. click to query: Default value. A conditional query is triggered when the query button is clicked. pre-query: Fetches the drop-down list content before the dashboard opens. This ensures that list values and defaults are displayed according to each user's row-level permissions. The pre-query mode is suitable for datasets with row-level permissions and small data volumes, as it can otherwise slow down dashboard loading.
Show null enum values in filter	When this option is selected, (Null) appears in the filter if the source field contains null values. If this option is not selected, null values in the drop-down list are filtered out and not displayed. Note This parameter is available only when Configure in each query condition whether to show null values is selected in the Report configuration settings at the organization level.
Set filter defaults	If you select this option, the filter box displays Please select. Click the filter box to configure default values in the Field dialog box. In this dialog box, you can perform the following operations: Search for a value and click it in the results to move it to the Added list. Click Add all field values on the left to add all field values from the left to the Added list on the right. Select field values on the left to add them to the Added list on the right. Click Exclude to exclude the field values added to the Added list on the right. Note If you select to exclude a field value when setting the default and then switch the drop-down list style to tiled, selecting that field value in the filter will exclude it from the query. If you first configure the tiled style and then select to exclude a field value when setting the default, the normal tiled style will be replaced with a tiled-exclude style. Click Clear to remove all field values from the Added list. Note If there are more than 1,000 filter options, the first 1,000 are displayed by default. You can search for options beyond this limit.

In this example, the following configuration is used:

Multiple associated fields from different datasets are selected in the Associated charts and fields section. As a result, the filter's drop-down list displays a union of all associated field values.
Selection mode is set to multiple choice, allowing multiple options to be selected in the filter.
Query time is set to click to query, which requires the report viewer to click the query button to trigger the conditional query.
The filter defaults are set to Advanced, Guangdong Province, and Furniture Products. When a user opens the report, it is pre-filtered by these values.

The result is as follows:

Single dataset

When sourcing options from a single dataset, the filter is populated with values from a specific field within that dataset.

Parameter	Description	Example
Select dataset	You can select any dataset within the current dashboard's workspace. We recommend using the chart's source dataset.	Select dataset: This example selects the data source dataset: `company_sales_record`. Query value field: Order Level. Display name field: Order Level. Sort field: Order Date. Selection mode: Select multiple choice. Query time: Select click to query. Set filter defaults: Select this option and set the default value to Advanced.
Query value field	The field from the selected dataset whose values are used for the actual query. It must correspond to the associated field in the chart.
Display name field	The field whose values are displayed as options in the filter. This can be used to display user-friendly names instead of raw data values. Same as query value field: If the values of the query value field are clear and easy to understand, you can set the display name field to be the same as the query field. In this case, after selecting the query value field, the system automatically populates the display name field. Different from query value field: Use this to show user-friendly labels (e.g., "Active") instead of raw codes (e.g., "1"). The actual query is still based on the query value field. In this case, you need to manually change the display name field after selecting the query value field.
Sort field	Allows sorting by a selected field. This parameter is optional. If not specified, the data is sorted by the default order in the dataset. If you need to sort by a specific field, you can select a sort field from the drop-down list, such as a measure or a date field. The supported sorting methods are Ascending, Descending, and Custom sorting. When you select custom sorting, you can drag and drop field values to arrange their order in the Custom sorting dialog box. This setting affects the sorting of the filter's drop-down list but does not affect the sorting of dimension values within the chart. The sorting of dimension values within the chart is controlled by the dataset or the chart's data panel.
Selection mode	Supports single choice and multiple choice.
Query time	Supports click to query and pre-query. click to query: Default value. A conditional query is triggered when the query button is clicked. pre-query: Fetches the drop-down list content before the dashboard opens. This ensures that list values and defaults are displayed according to each user's row-level permissions. Note The pre-query mode is suitable for datasets with row-level permissions and small data volumes, as it can otherwise slow down dashboard loading.
Show null enum values in filter	When you select Show null enum values for query conditions, if the drop-down list contains null values, they are displayed as (Null) when a user views the report. If this option is not selected, null values in the drop-down list are filtered out and not displayed. Note This parameter is available only when Configure in each query condition whether to show null values is selected in the Report configuration settings at the organization level.
Set filter defaults	If you select this option, the filter displays preset values. Note If there are more than 1,000 filter options, the first 1,000 are displayed by default. You can search for options beyond this limit. When query time is set to click to query, you can set a default filter value. When query time is set to pre-query, you can use Manual setting or a Dynamic function. Dynamic functions support setting Maximum value of query field, Minimum value of query value field, and First item of query value field. Note If a Sort field is set, the First item of query value field is the first value from the sorted list. If no sort field is set, the First item of query value field is the first value of that query field in the dataset. If the field has a sort order in the dataset (such as ascending, descending, or custom), the first value will be taken according to that sort order. Dynamic functions and "Query Condition Association" affect each other. The default value of a dynamic function is filtered by cascading conditions and is mutually exclusive with bidirectional query condition association configurations.

In this example, the following configuration is used:

The system-recommended dataset, company_sales_record, is used, which is the source dataset for the current chart.
The Query value field is set to Order Level, which is the same as the associated field and provides the option values for the query.
The display name field is also set to Order Level.
Order Date is selected as the Sort field to sort the filter options.
Selection mode is set to multiple choice, allowing the report viewer to select multiple option values in the filter.
Query time is set to click to query, which requires the report viewer to click the query button to trigger the conditional query.
The filter default is set to Advanced. When a report viewer opens the report, it defaults to showing results for the Advanced order level.

The result is as follows:

Manual input

When you select manual input, the report creator manually enters the filter options, which should correspond to the values of the associated field.

Parameter	Description	Example
Manual input	Click Manual input. In the Manual input dialog box, enter the Query value and Display Name. Query value: The actual data value used in the query. This must match a value in the associated field. In this example, the selected field is Order Level, and its values are Advanced, Intermediate, Basic, and Other. Display Name: The text displayed for the query value in the drop-down list. Note When you enter values manually for the first time and the query value is the same as the display name, you only need to enter the query value and click OK. The system automatically populates the display name. When you enter values manually for the first time and the query value is different from the display name, you must manually enter both. Ensure that the number of lines for query values and display names is the same, so they correspond one-to-one. If it is not the first time you are entering values manually, you must enter both the new query value and display name. Entering only the query value will result in the following prompt.	Manual input: In this example, the field values and their corresponding display names are: Advanced-Grade A; Intermediate-Grade B; Basic-Grade C; Other-Grade D. Selection mode: multiple choice Set filter defaults: Select this option and set the default value to Grade A (which corresponds to Advanced).
Selection mode	Supports single choice and multiple choice.
Set filter defaults	If you select this option, the filter displays preset values.

In this example, the following configuration is used:

The Order Level field values are manually mapped to corresponding display names: Advanced maps to Grade A, Intermediate to Grade B, Basic to Grade C, and Other to Grade D.
Selection mode is set to multiple choice, allowing the report viewer to select multiple options.
The default filter value is set to Grade A. When a report viewer opens the report, it defaults to showing results for the Advanced order level.

The result is as follows:

Search

You can search within the filter to quickly find specific option values.

If you cannot find the desired option value, you can try Search from Database.
By default, the list displays up to 1,000 options. To find other values, use the search bar or click Search from Database.

Note

The Search from Database feature is available only when Display type is set to drop-down list and the option source is set to Automatic parsing or Single dataset.

Text input box

The text input box allows users to enter keywords for precise and flexible data queries. When you set the Display type to text input box, the Conditional form setting supports Single condition, OR condition, or AND condition. This topic uses the OR condition as an example.

Parameter	Description	Example
Conditional form	Supports Single condition, OR condition, and AND condition. Single condition: Satisfies a single condition. For example, Product Type is Ruler. OR condition: Matches records that satisfy at least one of the specified conditions. For example, Product Type is Ruler or Pencil. AND condition: Matches records that satisfy all specified conditions simultaneously. For example, Order Amount is greater than 100 and less than 200.	Conditional form: Select OR condition. Set default value: The character contains 'ruler', or Starts with Desk. Lock filter condition: Select this option.
Set default value	The available options depend on the selected conditional form. The following list describes the available matching rules and their corresponding SQL syntax when setting a default value for the Product Type field. Exact match: `product_sub_type = 'Ruler'` Does not match: `product_sub_type != 'Ruler'` contains: `product_sub_type LIKE '%Ruler%'` does not contain: `product_sub_type NOT LIKE '%Ruler%'` starts with: `product_sub_type LIKE 'Ruler%'` ends with: `product_sub_type LIKE '%Ruler'` is null: `product_sub_type IS NULL` is not null: `product_sub_type IS NOT NULL` Is empty string: `product_sub_type = ''` Is not empty string: `product_sub_type != ''`
Lock filter condition	If selected, users cannot change the conditional form on the report page. Note This option is available only when Set default value is selected.

In this example, the following configuration is used:

Conditional form is set to OR condition, meaning data that meets any of the query conditions will be displayed.
The default value is set so that the field either contains the string Ruler, or starts with the string Table. When a report viewer opens the report, it defaults to showing results where the product type contains "Ruler" or starts with "Table".
Lock filter condition is selected, which prevents report viewers from changing the conditional form on the report page.

The result is as follows:

Tree drop

The tree drop display type allows report viewers to filter data with parent-child relationships, such as organizational structures, geographical regions (Country > Province > City), or product categories (Main Category > Subcategory). Users can navigate the hierarchy to locate and select items for filtering.

Note

When the associated charts use a dataset combination and multiple associated fields are selected, the tree drop display type cannot be used.

Parameter	Description		Example
Select dataset	You can select any dataset within the current dashboard's workspace. We recommend using the chart's source dataset.		Select dataset: This example selects the current chart's source dataset, `company_sales_record`. Tree structure design: Configure the Region field for Level 1 and the Province field for Level 2. Display form: Select Tiled display. Selection mode: Select multiple choice. Query time: Select click to query. Set default value: Set the default value to Northeast > Liaoning. Quick association: Select this option.
Tree structure design	Click Start Configuration. In the Tree structure design dialog box, configure the Query Field, Display name field, Sort field, and Sort rule for each level of the filter. Query Field: This field is used for the actual query. Report viewers can select one or more of its values to query data. Display name field: When the query field contains business IDs or codes that are difficult to understand, you can set a display name field to make the filter options more user-friendly. Sort field: Allows sorting by a selected field. This parameter is optional. If not specified, the data is sorted by the default order in the dataset. Sort rule: Supports ascending, descending, and custom sorting. When you select custom sorting, you can drag and drop field values to arrange their order in the custom sorting dialog box. Example: For example, if you create a tree filter with a "Region-Province-City" hierarchy and set an ascending sort rule for each query field: The filter options will be sorted in ascending order for each level (Region, Province, and City): Note When you select a Query value field, the system automatically populates the Display name field. By default, the display name field is the same as the query value field. If they are different, you must manually change it. A tree drop filter supports up to ten levels of queries.
Display form	Supports Tree display and Tiled display. Note If the filter will have more than 1,000 options, we recommend using Tiled display.	Tree display with single choice Tree display with multiple choice Tiled display with single choice Tiled display with multiple choice
Selection mode	Supports single choice and multiple choice.
Query time	Supports click to query and pre-query. click to query: A conditional query is triggered only when the query button is clicked. pre-query: Fetches the drop-down list content before the dashboard opens. This ensures that list values and defaults are displayed according to each user's row-level permissions. Note The pre-query mode is suitable for datasets with row-level permissions and small data volumes, as it can otherwise slow down dashboard loading.
Show null enum values in filter	When you select Show null enum values for query conditions, if the drop-down list contains null values, they are displayed as (Null) when a user views the report. If this option is not selected, null values in the drop-down list are filtered out and not displayed. Note If an intermediate node's value is null, the entire branch, including the null node and all its children, will not be displayed, even if the child nodes have non-null values. Note This parameter is available only when Configure in each query condition whether to show null values is selected in the Report configuration settings at the organization level.
Set default value	Select this option and set the relevant values. The filter will display these preset values when the report page loads. Note The default value here corresponds to the display name field in the tree structure design.
Quick association	After you select Quick association, the child-level fields in the tree structure are automatically added to the Associated charts and fields section for charts from the same dataset. This streamlines the configuration process. For example, in the following figure, when setting up the associated charts and fields for the second-level Province field, the system has automatically populated the Province field into the associated fields of the line chart and column chart, which are from the same dataset. The associated field for the pie chart, which is from a different dataset, needs to be entered manually. Note Automatic synchronization of child-level fields only applies to charts that were associated at the top level of the tree. You can click Associated charts in the tree structure or click the name of a child level in the left-side query items to associate the child levels with charts and fields from other datasets.

In this example, the following configuration is used:

The chart's source dataset, company_sales_record, is selected for the Select dataset parameter.
The Tree structure design is configured with the Region field at Level 1 and the Province field at Level 2. Since the query field values are clear and easy to understand, the query field and display name field are kept the same.
Display form is set to Tiled display.
Selection mode is set to multiple choice, allowing the report viewer to select multiple option values in the filter.
Query time is set to click to query, which requires the report viewer to click the query button to trigger the conditional query.
The default value is set to Northeast > Liaoning. When a report viewer opens the report, it defaults to showing results for the Liaoning province in the Northeast region.
The Quick association option is selected.

The result is as follows: