占位符 - 智能商业分析 Quick BI

本文主要为您介绍占位符的使用场景和使用方法。

操作步骤

创建入口

入口一：自定义SQL编辑页面

在SQL代码编辑页面，单击占位符管理。
在占位符管理面板，系统会自动识别您在SQL中使用的占位符并展示在占位符管理面板中，您可以对占位符的变量类型、默认值进行修改，配置完成后单击确定。

入口二：数据集编辑页面

单击数据集编辑页上方菜单栏中图标，进行占位符管理。
单击新建占位符，可通过手动输入的方式创建占位符。

入口三：仪表板编辑页面

在仪表板编辑页面，按照以下方式新建占位符。
1. 单击图标，新建占位符。
2. 在占位符管理界面新建占位符。
在新建占位符界面输入变量名、变量类型和查询默认值。

配置项及说明

配置项	说明
变量名	占位符的名称，可自定义修改。
类型	占位符的类型，分为表达式占位符和值占位符，类型不支持修改。
变量类型	支持文本、数值、日期-年、日期-年季、日期-年月、日期-年周、日期-年月日、日期-年月日时分秒。
查询默认值	默认值生效范围支持仅数据集和全局生效两种模式：仅数据集：只在数据集编辑页生效。全局生效：在仪表板、电子表格等下游也生效。输入框输入最多150个字符。说明表达式占位符的默认值需填写完整的表达式，比如：area = "东北"。
操作	单击图标删除占位符。

值占位符

可通过仪表板上的查询控件传入一个值、一组值。

说明

当占位符是日期时，需要选择具体的日期格式，来控制传入值的格式。

格式：'$val{占位符名}'

SQL代码示例如下：

SELECT * FROM tablename
WHERE area in ('$val{area_ph}') -- 文本类型 多选
AND name = '$val{name_ph}' -- 文本类型 单选
AND number = $val{number_ph} -- 数值类型
AND report_date > '$val{report_date_ph.get(0)}' -- 日期类型 获取日期范围控件起始日期
AND report_date < '$val{report_date_ph.get(1)}' -- 日期类型 获取日期范围控件结束日期

表达式占位符

可通过仪表板上的查询控件传入一个条件。

当仪表板上的筛选条件中，用户可以自由修改筛选方式，需要使用表达式占位符，将整个筛选条件都传入SQL。

格式：$expr{物理字段名:占位符名}

SQL代码示例如下：

SELECT report_date,
 order_level,
 shipping_type,
 area,
 price,
 order_number
from company_sales_record
where $expr{report_date :report_date}
and $expr{order_level :order_level}
and $expr{order_number :order_number}

标签占位符

通过标签占位符获取当前访问用户的标签值。

格式： $tag{用户标签名}

例如，控制某员工只能看到华北大区的数据，只能看到商品A，商品B的数据，则配置某用户的标签：

区域：华北
商品：商品A, 商品B

SQL代码片段示例：

select * from table_name
where 
area = '$tag{区域}'
and
product in ('$tag{商品}')

当某用户访问数据时，系统会自动读取该用户的标签，运行时的SQL示例。

select * from table_name
where 
area = '华北'
and
product in ('商品A', '商品B')

系统占位符

使用方法和其他占位符一致，能够用在SQL、计算字段中，支持以下4种系统占位符：

用户名（登录账号）：$system{accountName}
用户昵称（组织内）：$system{userNick}
用户ID（Quick BI系统内）：$system{userId}
三方系统用户ID（阿里云ID）：$system{accountId}

SQL示例如下：

select
  *
from
  company_sales_record
where
  customer_name = '$system{accountName}'
  and customer_name = '$system{userNick}'

条件占位符

可通过仪表板上的树形下拉查询控件传入一组值。

格式：'$condition{一级字段, 二级字段: 占位符名}'

其中，字段数量最多限制10个，需要和查询控件树形结构保持一致。

SQL示例如下：

select
 *
from
 company_sales_record
where 
 $condition{product_type,product_sub_type,product_name :product_para}

查询控件配置如下：

应用场景

场景1-动态调整计算字段结果值

场景描述

设置计算字段，并在表达式中引用占位符，通过传占位符的值调整计算字段的值。

如：超过占位符值的为大订单，否则为小订单；可通过查询控件传占位符值，动态调整大订单和小订单的衡量标准，图表也随之刷新。

操作步骤

新建占位符
1. 在自定义SQL编辑页或数据集编辑页单击占位符管理->新建占位符。
2. 输入变量名Price，类型为值占位符，变量类型为数值，查询默认值为全局生效，默认值为100（选填）。
  说明
  用到计算字段的占位符必须有全局生效的默认值。
新建计算字段。
1. 在数据集编辑页面，单击新建字段，按照图示方式新建订单规模字段。
  字段表达式示例：
```
case when [price]>$val{Price}
then '大订单'
else '小订单'
end
```
2. 单击确定并保存数据集。
创建可视化图表和查询控件。
1. 单击开始分析->创建仪表板。
2. 在仪表板编辑页面，按照图示方式添加柱图。
3. 将订单规模字段拖入类别轴/维度，将price字段拖入值轴/度量，并单击更新，此时柱图展示效果如下：
  此时，我们可以看到，度量字段price按照占位符Price的默认值100，区分出大订单和小订单。
4. 按照图示方式新建查询控件。
5. 在查询条件设置界面，将占位符Price设置为查询条件。
查看效果。
此时，您可以通过输入查询控件的数值来调整大小订单的衡量标准。
比如查询控件数值为100时，大订单金额为60.72万；查询控件数值为150时，大订单金额为52.5万。

场景2-灵活切换指标或分析维度

场景描述

当您有多个指标、维度需要展示，但放在同一个图表会显得内容较多不够清晰，搭建多个图表又会导致内容冗余时，可通过该能力实现图表字段的灵活切换。

以切换指标维度为例。

操作步骤

新建占位符。
1. 在自定义SQL编辑页或数据集编辑页单击占位符管理->新建占位符。
2. 输入变量名指标，类型为值占位符，变量类型为文本，查询默认值为全局生效，默认值为单价。

新建计算字段。

单击新建字段，按照图示方式新建数据字段。

字段表达式示例：

case when '$val{指标}'='订单金额' then [订单金额]
when '$val{指标}'='利润金额' then [利润金额]
when '$val{指标}'='单价' then [单价]
when '$val{指标}'='运输成本' then [运输成本]
else 0
end

说明

文本类型占位符请用英文单引号引用，例如'$val{指标}'。

单击确定并保存数据集。

创建可视化图表和查询控件。
1. 单击开始分析->创建仪表板。
2. 在仪表板编辑页面，按照图示方式添加柱图。
3. 将区域字段拖入类别轴/维度，将数据段拖入值轴/度量，并单击更新，此时柱图展示效果如下：
4. 按照图示方式新建查询控件。
5. 在查询条件设置界面，将占位符指标设置为查询条件，选项值来源选择手工输入并配置手工录入的值。
查看效果。
此时，您可以通过筛选查询控件的值切换不同的指标。

场景3-动态调整辅助线

场景描述

将辅助线的值与占位符绑定，为占位符赋值时，辅助线跟随变化。

如：辅助线为每月的销售额KPI，每个月只需要通过查询控件调整即可动态更新辅助线的位置，不需要重新修改报表。

操作步骤

新建占位符
说明
辅助线里的占位符只支持数值类型。
1. 在仪表板编辑页面，按照图示方式新建占位符。
2. 输入变量名Target，变量类型为数值，查询默认值为全局生效，默认值为4000000。
  说明
  辅助线中使用的占位符必须有全局生效的默认值。
设置辅助线。
1. 在分析页签，找到辅助线并单击右侧笔形图标。
2. 按照图示方式设置添加辅助线，并设置值为占位符Target。
  此时您可以看到辅助线400万显示在图表上。
新建查询控件。
1. 按照图示方式新建查询控件。
2. 设置占位符Target为查询条件并单击确定。
查看效果。
您可以通过切换查询控件的值来调整辅助线的位置。

场景4-SQL代码中使用占位符实现字段结果值的动态调整以及过滤

场景描述

用SQL代码创建数据集时,代码中引用占位符，通过调整占位符的值实现字段结果值的动态调整以及过滤。

操作步骤

在数据集编辑页面，单击画布中的使用SQL代码创建第一张表或左侧面板中的SQL代码创建表。

输入SQL代码后

SQL示例如下：

SELECT report_date, order_level, shipping_type,price,order_number,area,
 case when profit_amt< ${profit_range} then'亏损' 
 when profit_amt> ${profit_range} then'盈利'
 else '持平'
 end '订单等级'
from company_sales_record
where $expr{report_date :report_date}
and $expr{order_level :order_level}
and $expr{order_number :order_number}

单击占位符管理。
进入占位符管理界面并输入默认值。
说明
如果占位符应用在select语句后面，必须设置全局生效的默认值。
本例中，占位符“profit_range”必须设置全局生效的默认值。
单击运行，可以看到运行结果。
单击确认编辑并保存数据集。
创建可视化图表和查询控件。
1. 单击开始分析->创建仪表板。
2. 在仪表板编辑页面，按照图示方式添加饼图。
3. 按照图示方式新建查询控件。
4. 查看效果
  此时，您可以通过输入查询控件的数值来调整利润范围的衡量标准。