Parameters

Parameters are one of the core features in HENGSHI SENSE that enable flexibility and dynamism in data analysis. Through parameterized design, users can create reusable and configurable data analysis assets, significantly enhancing analysis efficiency and application adaptability.

Overview

The parameter mechanism addresses the limitation of "one-time analysis, fixed results" in traditional data analysis, enabling dynamic interaction capabilities in data analysis. By introducing parameters at key stages, the need to repeatedly create multiple versions of analytical content is eliminated, and different analytical requirements for various scenarios can now be achieved simply by modifying parameter values.

Core Values

• Enhance Reusability: A set of parameterized analytical logic can adapt to various business scenarios, avoiding repetitive development.
• Increase Flexibility: Quickly adapt to different data ranges, time periods, or business conditions by adjusting parameter values.
• Simplify Maintenance: Unified parameter management reduces the complexity of maintaining multiple versions.
• Improve User Experience: Provide an interactive analytical experience for end users through parameter controls.

Application Levels

Parameters play a role across multiple levels of data analysis:

• Data Level

  • Dynamic filter conditions for data source queries
  • Dynamic field and metric calculations in datasets
  • Configuration of association conditions across datasets

• Permission Level

  • Row-level permission control based on parameters
  • Dynamic management of data access scope

• Presentation Level

  • Dynamic switching of chart content
  • Interactive control of dashboards
  • Drill-down analysis of multidimensional data

Technical Features

• Rich Types: Supports four basic types: text, number, date, and time
• Flexible Configuration: Provides three value options: arbitrary values, list values, and range values
• Clear Scope: Parameter scope is limited to the associated app or dataset
• Expression Support: Parameters can be flexibly used in SQL queries and filter expressions

Typical Application Scenarios

The core application scenarios of parameters include:

• Dataset Parameterization: Using parameters to control data content in SQL queries, simple filters, and expression filters.
• Dynamic Permission Control: Implementing row-level permission management based on conditions through parameters.
• Dynamic Content Changes: Creating dynamic fields and metrics that update with parameter value changes.
• Chart Interaction Control: Using parameters to control displayed content during chart creation.
• Dashboard Interaction: Providing users with an interactive analysis experience through parameter controls.

Usage Tips

1. Parameters can be created in App Creation or in Datamart.
2. The scope of parameters is limited to the app or data package where they are created.
3. For detailed application scenarios and best practices, refer to Parameter Application Scenarios.

Parameter Management

Create a New Parameter

1. Navigate to your App or Dataset page, and click on the Parameter tab at the top to enter the parameter management page.
2. Click the Create Parameter button in the upper right corner to open the new parameter dialog box.
   
3. After filling in the Relevant Configuration, click OK to complete the creation of the parameter.

Edit Parameters

Click the three-dot menu in the parameter list, and select Edit Parameters from the pop-up menu to open the edit parameter dialog box and modify the parameters.

Note If the parameter is already in use, you may encounter the following situations when editing it again:

• Modifying the parameter name will cause an error in places where the parameter is used, displaying Parameter xxx does not exist.
• Changing the type or value type (e.g., from single value to multiple values) will result in errors in places where the parameter is used.
• Simply modifying the default value, updating the list of options, or adjusting the value range will not cause errors.

Delete Parameter

Click the three-dot menu in the parameter list, and select Delete from the pop-up menu to delete the parameter.

Batch Delete

Click the batch operation button in the toolbar to enter batch operation mode. Checkboxes will appear in the first column of the list, allowing you to select multiple parameters you want to delete. After selecting, click delete to perform batch deletion.

Parameter Grouping

Parameters support grouped display, allowing related business-related parameters to be organized into groups for easier search and usage during data analysis.

Click Parameter Grouping to open the Parameter Grouping window. Click Create Group, enter the group name, and press Enter to create a parameter group. Select the group, add parameters to the group on the right side, and finally click the Confirm button to complete the parameter grouping.

On the parameter page, you can see the grouping information for each parameter. A parameter may belong to multiple groups and have multiple group tags.

When searching for parameters, you can quickly locate fields with related business meanings through grouping.

Parameter Settings

Each parameter consists of four parts: parameter name, parameter type, allowed values, and default value.

Parameter Types

Parameter types support 4 kinds:

• Text
• Number
• Date
• Time

Allowed Values

Allowed values support 3 types:

• Any
• List
  • Fixed List
  • Dynamic List
• Range

Any

When the allowed value is set to "Any," you can use any value as the default based on the parameter type.

List

When allowing value selection from a list, it means the parameter must take values from the list during use. The parameter list includes values and display values. Display values are used for presentation, while actual operations use the values. Display values can be optionally configured; if not configured, the values themselves are displayed.

The list supports both fixed and dynamic configuration methods.

Fixed List

A fixed list refers to a list whose content remains unchanged, supporting manual input and value extraction from fields.

• Manual Addition: Manually edit the values and display values of the list. Note that values and display values cannot be duplicated.
• Add Values from Fields: Select corresponding types of fields from the dataset as list values, supporting the addition of one or more fields. Values added to the list can be edited and modified. After the values are added, the display values need to be manually edited.

Tip

Fixed lists do not support null values. If your dataset contains null values, even when adding values from fields, null values will be converted to strings.

Sorting

The fixed list supports value sorting. Click the sort button to open the sorting popup, where you can set the sorting criteria and order.

Dynamic List

A dynamic list selects the corresponding type of field from the dataset as the list value, supporting only the addition of one field. After adding a value, you can add a display value. The display value is selected from another field in the same dataset, and it requires the field to correspond one-to-one with the content of the value field.

Tip

The values and display values in the dynamic list are field contents from the dataset. If row-level permissions are set for the dataset, users with different permissions will see different parameter values.

Multi-value Parameters

When a parameter allows values as a list, the multi-value feature can be enabled for the parameter. You can set the delimiter, start and end characters, as well as prefixes and suffixes for the multi-value parameter. Once the multi-value feature is enabled, multiple default values can be set.

Scope

When the allowed value of a parameter is a range, it means the parameter value meets the range requirements. Text parameters do not have this type.

Number Range

The range values of numeric parameters can be set with a minimum value, maximum value, and step size.

The minimum and maximum values allow positive numbers, negative numbers, and decimals.

The step size represents the difference between two valid values. It can be optionally set, with a default value of 1, and cannot exceed the difference between the maximum and minimum values. As shown in the figure, when the minimum value is 5, the maximum value is 100, and the step size is 1, the valid values within the parameter range are 5, 6, 7, 8... 100. If the step size is 95, the valid values within the parameter range only include 5 and 100.

Currently, the step size for numeric ranges only supports positive integers and does not support decimals.

Date Range, Time Range

The range values for date and time parameters require setting granularity, start, end, and step size.

• The granularity and step size options for date parameters are day, week, month, quarter, year.
• The granularity and step size options for time parameters are second, minute, hour, day, week, month, quarter, year.

The unit of step size defaults to follow the granularity but can also be set to a unit larger than the granularity.

Default Values

Depending on the combination of type and allowed values, default values can be categorized as no default value, fixed, relative, or dynamic. Below are the allowed values for different types and combinations:

• Text
  • Any
    • Fixed value, dynamic value, no default value
  • List
    • Fixed options, dynamic options, dynamic value, no default value
• Number
  • Any
  • Range
    • Fixed value, dynamic value, no default value
  • List
    • Fixed options, dynamic options, dynamic value, no default value
• Date
  • Any
  • Range
    • Fixed date, relative date, dynamic value, no default value
  • List
    • Fixed date, dynamic options, dynamic value, no default value
• Time
  • Any
  • Range
    • Fixed time, relative time, dynamic value, no default value
  • List
    • Fixed options, dynamic options, dynamic value, no default value

Fixed Value

Manually edit specific values as parameter values, with the default value remaining unchanged during parameter usage.

When the allowed value is a range, you need to input a value within the range as the default value. If the input value exceeds the range, it will automatically be adjusted to the boundary value.

If a step size is set, and the input value is not within the range but falls between the minimum and maximum values, it will automatically be adjusted to the previous range value.

Fixed Options

Select fixed option content from the list, range (number, date, time) as the default value. When (list) enables multiple values, you can also select multiple values as the default.

Dynamic Options

Specify the Nth item in the list as the default value, and the default value changes as the list order changes. When multiple values are enabled, it specifies the first N items.

Dynamic Value

Select the corresponding type of field from all datasets in the application as the default value. When the dataset field value changes, the parameter default value changes accordingly. As shown in the figure, select the Customer Price field from the Sales Metrics dataset in the application as the default value. The default value is 7001. When the dataset is updated or accessed by users with different permissions, the default value will also vary.

Relative Date, Relative Time

The default values for date parameters and time parameters can be set to relative values. Relative refers to values relative to the system's current date and time, which change over time. As shown in the figure, the default value of the time parameter is set to the relative date 1 day ago. When the system date is January 2nd, the default parameter value is January 1st; when the system date is January 3rd, the default parameter value is January 2nd.

When the allowed value for date and time is a range:

• If no step size is set, the relative date can be adjusted by time units, as shown in the figure. If the default value is not within the time range, it will be automatically corrected.
• After setting the step size, the relative date is adjusted based on the step size. If it exceeds the time range, it will be automatically corrected.

FAQ

1. Can the default value of a parameter be specified to select a particular item from a field when it is a dynamic value?

   When the default value of a parameter is a dynamic value, only the first item of the field or metric can be selected as the default value.

2. Why does a chart suddenly report an error indicating no suitable scope value when using a parameter?

   When the allowed values of a parameter are "List" or "Range," the parameter value may fall outside the list or exceed the specified range over time. This can cause the dataset or chart using the parameter to report an error.

3. Why do different users see different parameter values for the same parameter?

   The values of dynamic list parameters are derived from dataset fields, so the parameter values dynamically change with the field content. If row-level permissions are applied to the dataset, different users may see different parameter values due to varying permissions.

4. Why do different users see different default values for the same parameter?

   When the default value is of the dynamic value type, it selects the content of a field in the dataset as the default value. If row-level permissions are applied to the dataset, different users may see different default values due to varying permissions.