变量

变量是 datart 中一个重要的功能，其原理是向数据加工逻辑（SQL 语句）中加入参数，通过传入不同值来得到期望的查询结果。变量的两个典型使用场景是：

• 在仪表板中使用控制器筛选数据，或改变维度和聚合方式
• 针对不同用户返回不同的查询结果（数据行权限控制）

这些场景的共同特点是需要根据条件返回不同的查询结果，而变量正好给查询带来了动态的能力

1. 变量类型

变量从类型上分为查询变量和权限变量，分别适用于不同场景

1.1 查询变量

查询变量与仪表板筛选关联，通过筛选控制器传入不同的值来得到不同的查询结果，通常用于比字段筛选更灵活的筛选查询场景

1.2 权限变量

权限变量通过与角色或用户绑定之后预设值，从而达到使用不同角色或用户查询返回不同结果、起到数据行权限控制的作用

权限变量与查询变量不同在于，它的值是预设的、在其关联的同一权限主体下是固定的，而查询变量的值在使用中是可以改变的

datart 内置了一组包含用户信息的权限变量，可以在数据视图里直接使用它们

$DATART_USER_ID$           # 用户 ID
$DATART_USER_USERNAME$     # 用户名
$DATART_USER_EMAIL$        # 用户 Email
$DATART_USER_NAME$         # 用户姓名

2. 变量设置

管理者可以在组织中设置公共变量，公共变量可以被组织下的所有数据视图使用；这在给角色或成员设置一些固定属性时带来方便。另外开发者也可以在具体数据视图中创建专有变量，仅在数据视图中使用

2.1 公共变量设置

点击主导航栏上的设置 -> 公共变量设置，进入公共变量设置页面

2.1.1 新建&编辑变量

点击页面右上角新建按钮，弹出新建变量弹窗

需要配置以下内容

• 名称：在 SQL 中输入的变量名称
• 标题：用于组织成员自行编辑时显示的标题 （开发中）
• 类型
• 值类型：不同值类型在解析时会做不同处理，其中字符和日期类型值会自动添加引号作为字符处理
• 编辑权限：提供给组织成员自行编辑的权限设置 （开发中）
• 默认值：预设默认值，可以添加多个；输入之后需要回车或点击右侧 √ 按钮确认添加
• 使用表达式作为默认值：在一些场景下，需要使用 SQL 表达式作为默认值，但在变量值变化时保持原始值类型。这种场景主要发生在查询变量的使用上，比如一个日期变量，默认值为now()，但后续使用的是日期筛选控制器传递过来的日期格式化字符串，这种情况下值类型设为日期，但默认值使用表达式作为默认值即可

配置完成之后，点击确定完成新建

如果是一个查询变量，到这里就新建完成了；权限变量还需要关联权限主体并预设值，点击列表操作栏中的关联角色或用户按钮，弹出设置弹窗

可以关联角色或用户，勾选具体角色或用户设置值，默认情况下使用变量设置的默认值，如果不使用默认值，可以取消使用变量默认值勾选，并自行设置值，设置方法与变量默认值一致

最好点击确定按钮完成设置

2.1.2 删除变量

点击变量列表右侧的删除按钮，确认对话框后永久删除该变量

2.2 专有变量设置

专有变量在数据视图侧边栏的变量设置面板中进行设置。点击变量设置页签弹出面板，列表中会展示该组织下的所有公共变量以及该数据视图的专有变量，点击右上角加号按钮新建变量

新建和编辑方式与公共变量完全一致，唯一不同在于专有权限变量只能关联角色

3. 变量使用

3.1 在 SQL 语句中引用变量

已完成设置的变量可以在数据视图编辑器中直接引用，输入变量名称会有提示

3.1.1 语法

变量在 SQL 语句中以 $变量名称$ 形式显示

查询变量在确定变量值为单值的情况下，可以在 SQL 语句中直接引入变量

查询变量在变量值可能为多值的情况下，需要在 SQL 语句中做一些处理

权限变量无论是单值还是多值，都可以在 SQL 语句中直接引入，解析器会对相应情况作出不同处理。但在编辑界面无法看出权限变量作用效果，需要登录具体角色或成员进入可视化页面查看

3.1.2 条件语句

datart 使用 freemarker 来解析变量，因此可以使用 freemarker 的条件语法来达到一些动态效果

注意：变量在 if 语句中前后不要使用 $ 包裹

在变量值为单值时，可以这样使用

在变量值为多值时，可以这样使用

更详细的使用方式可以参考 freemarker 文档

3.2 在仪表板控制器中关联变量