---
url: /v6.2/parameter.md
---
# 参数

参数是 HENGSHI SENSE 中实现数据分析灵活性和动态性的核心功能之一。通过参数化设计，用户可以创建可复用、可配置的数据分析资产，大幅提升分析效率和应用的适应性。

## 概述

参数机制解决了传统数据分析中"一次分析，固定结果"的局限性，让数据分析具备了动态交互能力。通过在关键环节引入参数，原本需要重复创建多个版本的分析内容，现在只需要修改参数值即可实现不同场景的分析需求。

### 核心价值

* **提升复用性**：一套参数化的分析逻辑可以适应多种业务场景，避免重复开发
* **增强灵活性**：通过调整参数值，快速适应不同的数据范围、时间周期或业务条件
* **简化维护**：统一的参数管理减少了多版本维护的复杂性
* **改善体验**：通过参数控件为最终用户提供交互式的分析体验

### 应用层次

参数在数据分析的多个层次发挥作用：

* **数据层面**
  * 数据源查询的动态过滤条件
  * 数据集的动态字段和指标计算
  * 跨数据集的关联条件配置

* **权限层面**
  * 基于参数的行级权限控制
  * 动态的数据访问范围管理

* **展示层面**
  * 图表内容的动态切换
  * 仪表盘的交互式控制
  * 多维度数据的钻取分析

### 技术特性

* **类型丰富**：支持文本、数字、日期、时间四种基础类型
* **配置灵活**：提供任意值、列表值、范围值三种取值方式
* **作用域明确**：参数作用范围限定在所属应用或数据包内
* **表达式支持**：在SQL查询和过滤表达式中灵活使用参数

### 典型应用场景

参数的核心应用场景包括：

* **[数据集参数化](parameter-scenarios.md#数据集创建过程)**：在SQL查询、简单过滤、表达式过滤中使用参数控制数据内容
* **[权限动态控制](parameter-scenarios.md#数据集行权限控制)**：通过参数实现基于条件的行级权限管理
* **[内容动态变更](parameter-scenarios.md#数据集内容变更)**：创建动态字段和指标，随参数值变化而更新
* **[图表交互控制](parameter-scenarios.md#数据集制作图表)**：在图表制作中使用参数控制显示内容
* **[仪表盘交互](parameter-control.md)**：通过参数控件为用户提供交互式分析体验

> \[!TIP] 使用提示
>
> 1. 参数可以在[应用创作](app-creation.md)中创建，也可以在[数据集市](datamart.md)中创建
> 2. 参数作用范围限定在创建它的应用或数据包内
> 3. 详细的使用场景和最佳实践请参考[参数使用场景](parameter-scenarios.md)

## 参数管理

### 新建参数

1. 进入你的`应用`或`数据包`页面，点击顶部标签页中的`参数`进入参数管理页面。
2. 点右上角`新建参数`按钮，弹出新建参数对话框。
   ![](/images/parameter/parameter-new.png)
3. 填写[相关配置](#参数设置)后，点击确定参数即创建完成。

### 编辑参数

点击参数列表中的三点菜单，在弹出菜单中选择`编辑参数`，就可以弹出编辑参数弹窗，对参数进行修改。

![](/images/parameter/parameter-edit.png)

**注意**如果参数已经被使用，重新编辑时可能会遇到以下情况：

* 修改**参数名称**将会导致使用该参数的地方报错`参数 xxx 不存在`。
* 修改**类型**、**值类型**（单值变多值）时，使用参数的地方会出错。
* 只是修改参数默认值、更新列表候选项、范围取值，则不会报错。

### 删除参数

点击参数列表中的三点菜单，在弹出菜单中选择`删除`，可以删除参数。

#### 批量删除

点击工具栏中的批量操作按钮，进入批量操作模式，列表首列将会出现勾选框，可以勾选多个想要删除的参数后，点击删除进行批量删除。

![](/images/parameter/parameter-batch-delete.png)

### 参数分组

参数支持分组展示，将相关业务含义的参数分成一组，方便数据分析过程中查找和使用。

点击`参数分组`，弹出`参数分组`窗口，点击`新建分组`，输入分组名称回车后，创建一个参数分组。 选中分组，在右侧为该分组添加参数，最后点击确定按钮后，完成参数分组。
![](/images/parameter/parameter-group.png)

在参数页面可以看到每个参数的分组信息，一个参数可能会分到多个组中，有多个分组标签。

查找参数时可以通过分组快速查找到相关业务含义的字段。

![](/images/parameter/parameter-group-list.png)

## 参数设置

每个参数由四部分组成：参数名称、参数类型、允许值和默认值。

### 参数类型

参数类型支持 4 种：

* 文本
* 数字
* 日期
* 时间

### 允许值

允许值支持 3 种：

* 任意
* 列表
  * 固定列表
  * 动态列表
* 范围

#### 任意

允许值选择任意时，可以按参数类型取任意值作为默认值。

#### 列表

允许值选择列表时，表示参数使用时需要从列表中取值。参数列表包含值和显示值。展示时使用显示值，实际运算过程中使用值的内容。显示值可以选择配置，不配置时，展示的是值的内容。

列表支持固定和动态两种配置方式。

##### 固定列表

固定列表即列表内容是固定不变的，支持手动输入和从字段中取值。

![](/images/parameter/parameter-list-static.png)

* 手动添加： 即手动编辑列表的值和显示值，需要注意值与显示值不可以重复。
* 从字段中添加值：从数据集中选择相应类型的字段作为列表值，支持添加一个或多个字段。添加到列表中的值支持编辑和修改。 值添加完成后，显示值需要手动编辑。

> \[!TIP] 提示
> 固定列表不支持 null 值，当你的数据集数据中含有 null 值时，即使是从字段中添加值，null 值也会被转为字符串

###### 排序

固定列表支持值排序，点击排序按钮弹窗排序弹窗，可以设置排序依据和顺序。

![](/images/parameter/parameter-list-sort.png)

##### 动态列表

动态列表是从数据集中选择相应类型的字段作为列表值，仅支持添加一个字段。值添加后，可以添加显示值。 显示值是从同一数据集中的其他字段中选择一个字段，并且要求该字段与值的字段内容一一对应。

![](/images/parameter/parameter-list-dynamic.png)

> \[!TIP] 提示
> 动态列表中的值和显示值是数据集中的字段内容，如果该数据集设置了行权限，不同权限的用户看到的参数值不同。

##### 参数多值

当参数允许值为列表时，参数可以开启多值功能。可以设置参数多值的分隔符、起止符、前后缀。参数多值开启后，可以设置多个默认值。

![](/images/parameter/parameter-list-multiple.png)

#### 范围

当参数的允许值是范围时，表示参数的取值满足范围要求。文本参数无该类型。

##### 数字范围

数字参数的范围值可以设置最小值、最大值和步长。

最小值最大值允许正数、负数、小数。

步长表示两个合法值之间的差值，可以选择设置，默认值为1，不能超过最大值与最小值的差。如图所示，最小值为5，最大值为100，步长为1时，参数范围内的合法值为5、6、7、8... 100。 如果步长为95，则参数范围内的合法值仅包含5和100。
![](/images/parameter/parameter-number-range.png)

数字范围的步长目前只支持正整数，不支持小数。

##### 日期范围、时间范围

日期、时间参数的范围值需要设置粒度、开始、结束和步长。

* 日期参数的粒度和步长可选值为`天、周、月、季度、年`。
* 时间参数的粒度和步长可选值为`秒、分、时、天、周、月、季度、年`。

![](/images/parameter/parameter-date-range.png)

步长的单位默认跟随粒度，也可以设置为比粒度更大的单位。

### 默认值

根据类型和允许值的组合不同，默认值有无默认值、固定、相对、动态四种，以下是不同类型不同允许值组合下的允许值：

* 文本
  * 任意
    * 固定值、动态值、无默认值
  * 列表
    * 固定选项、动态选项、动态值、无默认值
* 数字
  * 任意
  * 范围
    * 固定值、动态值、无默认值
  * 列表
    * 固定选项、动态选项、动态值、无默认值
* 日期
  * 任意
  * 范围
    * 固定日期、相对日期、动态值、无默认值
  * 列表
    * 固定日期、动态选项、动态值、无默认值
* 时间
  * 任意
  * 范围
    * 固定时间、相对时间、动态值、无默认值
  * 列表
    * 固定选项、动态选项、动态值、无默认值

#### 固定值

由手动编辑具体值作为参数值，参数使用时默认值固定不变。

当允许值是范围时，需要输入范围内的值作为默认值，如果输入值超出范围会自动修正到边界值。

如果设置了步长，输入值不在范围内，但在最小值和最大值之间时会自动修正到前一个范围值。

#### 固定选项

从列表、范围（数字、日期、时间）中选择固定的选项内容作为默认值。当（列表）开启多值时，也可以选择多个值作为默认值。

#### 动态选项

指定列表中的第 N 项作为默认值，列表顺序变化时默认值也随着变化。当开启多值时，则是指定前 N 项。

#### 动态值

从该应用中所有数据集中选取相应类型的字段作为默认值，当数据集字段的取值变化时，参数默认值随之发生变化。如图所示，选取该应用中`销售指标`数据集中的`客单价`字段作为默认值，默认值为`7001`，当数据集更新时，或不同权限的用户使用时，默认值也会不一样。
![](/images/parameter/parameter-any-field-value.png)

#### 相对日期、相对时间

日期参数和时间参数的默认值可以设置相对值。`相对`是指相对于系统的当前日期、时间，会随着时间而变化。如图所示，时间参数的默认值设置为相对日期`前1天`。当系统日期为1月2日时，参数默认值为1月1日，当系统日期为1月3日时，参数默认值为1月2日。
![](/images/parameter/parameter-relative-date.png)

在日期时间允许值是范围时：

* 未设置步长时，相对日期设置时可以调整时间单位，如图所示。如果默认值不在时间范围内会自动修正。
* 设置步长后，相对日期设置以步长为单位，超出时间范围会自动修正。

## 常见问题

1. 参数默认值为动态值时，能够指定选取字段的哪一项吗？

   参数默认值为动态值时，只能选取字段或指标的`第一项`做为默认值。

2. 使用参数时，图表突然报错显示没有合适范围值 ？

   当参数的允许值为“列表”或“范围”时，随着时间的迁移，参数值可能会不在列表之内或者超出了指定范围，使用该参数的数据集或图表会报错。

3. 同一个参数，不同用户看到的参数取值不同？

   动态列表参数的取值是数据集字段，所以参数值会随着字段内容动态变化，如果对数据集进行了行权限控制，因为不同的用户权限不同，所以看到的参数值也不同。

4. 同一个参数，不同用户看到的默认值不同？

   默认值为动态值类型时会选取数据集中字段的内容作为默认值，如果对数据集进行了行权限控制，因为不同的用户权限不同，所以看到默认值也不同。