how to set up a text query control for querying text fields - Quick BI

Report viewers can dynamically filter and query data by entering or selecting text field values in a text control. A text query control allows dashboard viewers to filter chart data based on specific text conditions and focus on key content.

The main advantages of a text query control are:

High flexibility: It supports three display types, such as drop-down list, text input box, and tree drop-down. It also provides extensive configuration options for different business scenarios and user preferences.
High precision: It supports multiple match conditions for entered content, such as contains, does not contain, starts with, and ends with. This allows for precise data retrieval.

Quick BI supports three types of text controls: Drop-down list, Text input box, and Tree drop-down. This topic describes the scenarios and configuration steps for each display type.

Prerequisites

You have created a dashboard, and the charts on it contain text fields.
You have added an empty query control to the dashboard. For more information, see Create a query control.

Configure query conditions

Navigate to the dashboard edit page. For more information, see Create a dashboard.
In the dashboard list, find and click the target dashboard.
The charts on the dashboard must contain text fields to configure a text query control. This topic uses a line chart as an example. For more information, see Line chart.
Add a query control as shown in the following figure.
Configure the query control.
1. Set the name of the query condition to Level Query.
2. Select the Line Chart and the foreign key field Order level.
3. Set the display type and complete the query condition 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, refer to Text input box for an example.
  3. If you set Display Type to Tree Drop-down, see the example in Tree drop-down.
Click OK.

Drop-down list

The drop-down list display type allows report creators to define a set of predefined options and present them in a list for viewers to select. When you set the display type to Drop-down List, the source of the option values can be Automatic Parsing, Single Dataset, or Manual Input.

Automatic parsing

When you select automatic parsing, Quick BI automatically identifies the values of all associated foreign key fields and displays them as a union of options for the query control.

Note

If charts in the Associated Chart And Field section use the same dataset, values are automatically parsed from it.
If the charts selected in the Associated Chart And Field section use multiple datasets, the system automatically parses values from all of them and displays their union in the drop-down list.

Configuration item	Description	Example
Query Mode	Supports Single Selection and Multiple Selection.	Query mode: Select Multiple selection. Query time: Select Click to query. Set default filter value: Set Order level to Advanced, Province to Guangdong Province, and Product type to Furniture product.
Query Time	Supports Click To Query and Pre-query. Click To Query: The default value. A conditional query is triggered when you click the query button. Pre-query: Pre-queries the values for the drop-down list before the dashboard opens. This allows the drop-down list values to be displayed based on the row-level permissions configured for each account. The default value for each person also varies based on their row-level permissions. Pre-query is suitable for scenarios where the target dataset has row-level permissions configured and the data volume is small. Otherwise, the overall report loading time is affected.
Set Default Filter Value	Select this option. The query condition box displays Please select. Click the query condition box to configure default values in the Field dialog box. In this dialog box, you can perform the following operations: Enter a keyword in the search box and click the keyword below to add the target field value from the left to the Added list on the right. Click Add All Field Values On The Left to add all field values from the left to the Added list on the right. Select the field values on the left to add them to the Added list on the right. Click Exclude to exclude the field values that are added to the Added list on the right. Note If you select a field value to exclude when configuring the default value and then switch the drop-down list style to tile, selecting that field value in the query control means excluding that field. If you first configure the tile style and then select a field value to exclude when configuring the default value, the normal tile style is replaced with the tile exclude style. Click Delete to clear the field values that are added to the Added list on the right. Note If the number of filter items is greater than 1,000, the first 1,000 option values are displayed by default. You can directly search for values that are not displayed.

In this example:

In the Associated Chart and Field section, different fields from multiple datasets are selected. The query control's drop-down list displays a union of all foreign key field values.
Query mode is set to Multiple selection, which means you can select multiple options in the query control.
Query time is set to Click to query, which means the report viewer must click the query button to trigger a conditional query.
Set default filter value is set to Advanced, Guangdong Province, and Furniture product. When a report viewer opens the report, the query results for an advanced order level, Guangdong province, and furniture product type are displayed by default.

The following figure shows the result. 112

Single dataset

When the option value source is a single dataset, the options in the query control depend on the values of a specific field in that dataset.

Configuration item	Description	Example
Select Dataset	You can select any dataset in the workspace where the current dashboard is located. We recommend that you select the dataset that is the data source for the chart.	Select dataset: In this example, select the dataset that is used as the data source: company_sales_record. Query value field: Order level. Display name field: Order level. Sort field: Order date. Query mode: Select Multiple selection. Query time: Select Click to query. Set default filter value: Select this option and set the default value to Advanced.
Query Value Field	The field in the selected dataset that must match the foreign key field. This field is used for the actual query. The report viewer can select one or more options from the values of this field to query data.
Display Name Field	The field whose values are displayed as options in the query control. This field is typically used to improve the user experience of the query control and help report viewers better understand the meaning of the option values. Same as the 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 you select the query value field, the system automatically fills in the display name field. Different from the query value field: If the value of the query value field is a numeric code or a code that is not easy to understand, you can set an easy-to-understand display name field in the data table to be used as the display option value in the query control. The actual query is still based on the query value field. In this case, after you select the query value field, you must manually modify the display name field.
Sort Field	Supports sorting by the selected field. This parameter is optional. If you do not specify this parameter, the data is sorted by the default order in the dataset. To sort by a specific field, you can select the sort field in the drop-down list. For example, you can sort by measure or by date. The supported sorting methods are Ascending, Descending, and Custom sorting. When you select custom sorting, you can drag the field values to change their order in the Custom sorting dialog box. After the settings take effect, they can affect the sorting of the drop-down list in the query control but do not affect the sorting of dimension values in the chart. The sorting of dimension values in the chart is still managed by the dataset or the data panel in each chart.
Query Mode	Supports Single Selection and Multiple Selection.
Query Time	Supports Click To Query and Pre-query. Click To Query: The default value. A conditional query is triggered when you click the query button. Pre-query: Pre-queries the values for the drop-down list before the dashboard opens. This allows the drop-down list values to be displayed based on the row-level permissions configured for each account. The default value for each person also varies based on their row-level permissions. Note Pre-query is suitable for scenarios where the target dataset has row-level permissions configured and the data volume is small. Otherwise, the overall report loading time is affected.
Set Default Filter Value	Select this option. The preset values are displayed in the query condition. Note If the number of filter items is greater than 1,000, the first 1,000 option values are displayed by default. You can directly search for values that are not displayed. 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 and Dynamic function. Pre-query is suitable for scenarios where data needs to be retrieved in advance, such as displaying different filter options based on each visitor's row-level permissions. The dynamic function supports setting Maximum query field value, Minimum query value field, and First query value field. Note If you set a Sort field, the First query value field is sorted by that field, and the first value from the sort is used. If you do not set a sort field, the First query value field retrieves the first value of that query value field from the dataset. If the field is sorted in the dataset (for example, in ascending or descending order, or using custom sorting), the first value according to that sort order is used.

In this example:

The Dataset is set to company_sales_record, which is the source dataset for the current chart.
The Query value field is set to Order level, which is the same as the foreign key field and will be used for the actual query.
The Display name field is also set to Order level.
The Sort field is set to Order date, which sorts the option values in the control.
Query mode is set to Multiple selection, which means the report viewer can select multiple option values in the query control.
Query time is set to Click to query, which means the report viewer must click the query button to trigger a conditional query.
Set default filter value is set to Advanced. When a report viewer opens the report, the query results for the advanced order level are displayed by default.

The following figure shows the result.

112

Manual input

When the option value source is manual input, the report creator can customize the options in the query control based on the field values used in the chart.

Configuration item	Description	Example
Manual Entry	Click Manual entry. In the Manual entry dialog box, enter the Query Value and Display Name. Query value: The value of the field selected in the chart. For example, the selected field in this example is Order level, and the corresponding values are Advanced, Intermediate, Low, and Others. Display name: The text displayed in the drop-down list that corresponds to the query value. Note When you perform a manual entry for the first time and the query value is the same as the display name, enter the query value and click OK. The system automatically enters the display name. When you perform a manual entry for the first time and the query value is different from the display name, you must manually enter the query value and display name. Make sure that the number of rows for the query value and display name is the same so they can correspond one-to-one. For subsequent manual entries, you must enter both the new query values and display names. If you enter only the query value, a prompt appears.	Manual entry: In this example, the field values and their corresponding display names are as follows: Advanced - A level; Intermediate - B level; Low - C level; Others - D level. Query mode: Multiple selection Set default filter value: Select this option and set the default value to A level (that is, Advanced).
Query Mode	Supports Single Selection and Multiple Selection.
Set Default Filter Value	Select this option. The preset values are displayed in the query condition.

In this example:

For Manual entry, the Order level field values are mapped to display values: Advanced to A level, Intermediate to B level, Low to C level, and Others to D level.
Query mode is set to Multiple selection, which allows the report viewer to select multiple options.
Set default filter value is set to Advanced. When a report viewer opens the report, the query results for the advanced order level are displayed by default.

The following figure shows the result.

112

Search

When you perform a filtered query, you can search for specific conditions to quickly locate the data you need.

If you cannot find the desired option value, you can select Search from database.
If there are more than 1,000 filter items, only the first 1,000 are displayed by default. You can search for items that are not displayed. If you still cannot find the desired option value, select Search from database.

Note

Searching from the database is supported only when Display type is set to Drop-down list and the option value source is Automatic parsing or Single dataset.

Text input box

The text input box display type allows report viewers to quickly retrieve the data they need by typing keywords into the query box. This makes data queries more precise and flexible. When you set the display type to Text Input Box, the supported conditions are Single Condition, Or Condition, and And Condition. The following example uses the Or Condition.

Configuration item	Description	Example
Conditional Form	Supports Single Condition, Or Condition, and And Condition. Single condition: Satisfies a single condition. For example, the product type is Ruler. Or condition: Satisfies any one of two conditions. For example, the product type is Ruler or Pencil. And condition: Satisfies both conditions at the same time. For example, the order amount is greater than 100 and less than 200.	Conditional form: Select Or Condition. Set default value: Set the character to include as Ruler, or the character for Starting With as Table. Lock filter condition: Select this option.
Set Default Value	The values vary based on the selected conditional form. For example, to set a default value for the Product type field, the rules and corresponding SQL syntax are as follows: Exact match: `product_sub_type='Ruler'` Not match: `product_sub_type!='Ruler'` Contains: `product_sub_type like '%Ruler%'` Does not contain: `product_sub_type not like '%Ruler%'` Starting with: `product_sub_type like 'Ruler%'` Ending with: `product_sub_type like '%Ruler'` Is empty: `product_sub_type is null` Is not empty: `product_sub_type is not null` Empty text: `product_sub_type=''` Non-empty text: `product_sub_type!=''`
Lock Filter Condition	If you enable this option, you cannot switch the conditional form on the preview page. Note This option appears only when Set Default Value is selected.

In this example:

When Conditional form is set to Or Condition, data that meets any of the query conditions is displayed.
Set default value is configured to Contain the character "Ruler", or Start with the character "Table". When a report viewer opens the report, the query results for product types that contain "Ruler" or start with "Table" are displayed by default.
Lock filter condition is selected. This prevents report viewers from switching the conditional form in the query control on the report page.

The following figure shows the result.

112

Tree drop-down

The tree drop-down display type allows report viewers to filter data that has a parent-child relationship, such as organizational structures, geographical areas (Country-Province-City), or product categories (Main Category-Subcategory). It allows users to locate and filter data in a hierarchical structure by expanding and selecting items at each level.

Note

If the associated chart uses a dataset union and multiple foreign key fields are selected, you cannot set the display type to tree drop-down.

Configuration item	Description		Example
Select dataset	You can select any dataset in the workspace where the current dashboard is located. We recommend that you select the dataset that is the data source for the chart.		Select dataset: In this example, select the current chart source dataset company_sales_record. Tree structure design: Configure the region field for level one and the province field for level two. Display form: Select Tile display. Query mode: Select Multiple selection. 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 and Display field for each level in the query control. Query field: This field is used for the actual query. The report viewer can select one or more options from the values of this field to query data. Display name field: When the query field is a business ID or code that is difficult to understand, you can set a display name field to make the options of the query field easier to understand. Note When you select the Query Value Field, the system automatically fills in the Display Name Field. The Display Name Field is the same as the Query Value Field by default. If they are different, you must manually modify them. The tree drop-down supports a maximum of four query levels.
Display form	Supports Tree display and Tile display. Note When the data exceeds 1,000 entries, we recommend that you select Tile Display as the display form.	Tree single-selection display Tree multiple-selection display Tile single-selection display Tile multiple-selection display
Query mode	Supports Single selection and Multiple selection.
Query time	Supports Click to query and Pre-query. Click to query: A conditional query is triggered only when you click the query button. Pre-query: Pre-queries the values for the drop-down list when the dashboard page opens. This allows the drop-down list values to be displayed based on the row-level permissions configured for each account. The default value for each person also varies based on their row-level permissions. Note Pre-query is suitable for scenarios where the target dataset has row-level permissions configured and the data volume is small. Otherwise, the overall report loading time is affected.
Set default value	Select this option and set the relevant values. The preset values are displayed in the query control when the report page loads. Note The default value here is the display name field in the tree structure design.
Quick association	After you select Quick Association, the sub-level fields in the tree structure are automatically added to the Associated chart and field section for charts from the same dataset. This improves the efficiency and accuracy of query control configuration. For example, in the following figure, when you configure the associated chart and field for the second-level Province, the system automatically fills the province field into the foreign key fields of the Line Chart and Column Chart from the same dataset. The foreign key field for the Pie Chart, which is from a different dataset, must be entered manually. Note Only the charts selected in the Associated chart and field section of the main level support automatic synchronization of sub-level fields. You can click Associated Chart in the tree structure or click the name of the sub-level in the query items on the left to associate the sub-level with charts and fields from other datasets.

In this example:

Select dataset is set to the current chart's source dataset, company_sales_record.
For the Tree structure design, the region field is configured for level one and the province field for level two. Because the query field values are clear and easy to understand, the query field and the display name field are set to the same fields.
Display form is set to Tile display.
Query mode is set to Multiple selection, which means the report viewer can select multiple option values in the query control.
Query time is set to Click to query, which means the report viewer must click the query button to trigger a conditional query.
Set default value is set to Northeast > Liaoning. When a report viewer opens the report, the query results for the Northeast region and Liaoning province are displayed by default.
Quick association is selected.

The following figure shows an example of the result.

112