变量

变量是 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(),但后续使用的是日期筛选控制器传递过来的日期格式化字符串,这种情况下值类型设为日期,但默认值使用表达式作为默认值即可

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

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

关联权限主体-1

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

关联权限主体-2

关联权限主体-3

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

2.1.2 删除变量

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

2.2 专有变量设置

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

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

专有变量设置

3. 变量使用

3.1 在 SQL 语句中引用变量

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

SQL引用

3.1.1 语法

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

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

语法-1
语法-2

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

语法-3
语法-4

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

语法-5
语法-6

3.1.2 条件语句

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

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

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

条件语句-1

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

条件语句-2

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

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