本文主要为您介绍占位符的使用场景和使用方法。
操作步骤
创建入口
入口一：自定义SQL编辑页面
在SQL代码编辑页面，单击占位符管理。
在占位符管理面板，系统会自动识别您在SQL中使用的占位符并展示在占位符管理面板中，您可以对占位符的变量类型、默认值进行修改，配置完成后单击确定。
入口二：数据处理界面
在数据处理界面的工具栏里，单击新建占位符，输入变量名、变量类型和查询默认值后单击确定。
当数据集存在占位符时，您可以单击字段大纲->占位符右侧的
图标，进入占位符管理界面。
在占位符管理界面，单击新建占位符，通过手动输入的方式创建占位符。
入口三：仪表板编辑页面
在仪表板编辑页面，按照以下方式新建占位符。
单击
图标，新建占位符。
在占位符管理界面新建占位符。
在新建占位符界面输入变量名、变量类型和查询默认值。
配置项及说明
配置项 | 说明 |
变量名 | 占位符的名称，可自定义修改。 |
类型 | 占位符的类型，分为表达式占位符、值占位符和加速占位符，类型不支持修改。 |
变量类型 | 支持文本、数值、日期-年、日期-年季、日期-年月、日期-年周、日期-年月日、日期-年月日时分秒。 |
查询默认值 | 默认值生效范围支持仅数据集和全局生效两种模式：
输入框输入最多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}查询控件配置如下：
加速占位符
加速占位符用于抽取加速，适配自定义 SQL 中包含时间参数的场景。通过在 WHERE 条件中放置加速占位符，Quick 引擎可在抽取阶段动态替换时间窗口，并按配置进行增量离线抽取。
格式：$accel{物理字段名:占位符名}
SQL示例如下：
select
*
from
company_sales_record
where
$accel{report_date:report_date}仅加速占位符支持 Quick 引擎的抽取加速；其他占位符类型暂不支持抽取加速。
每个数据集当前仅支持添加 1 个加速占位符。
不支持在计算字段中使用加速占位符。
加速占位符仅在数据集层生效（用于自定义 SQL 运行与加速抽取）；在图表查询中不生效，查询控件中也不展示该占位符。
查询默认值：为避免自定义SQL运行超时，此处可为加速占位符设置默认值。
示例：加速占位符的默认值需为完整的过滤表达式，而非单独的日期值，例如report_date<'2025-04-01'
加速配置：对于已添加加速占位符的数据集，可在加速配置的日期字段中选择该占位符字段，设置抽取时间范围与增量粒度，完成加速任务的配置。
应用场景
场景1-动态调整计算字段结果值
场景描述
设置计算字段，并在表达式中引用占位符，通过传占位符的值调整计算字段的值。
如：超过占位符值的为大订单，否则为小订单；可通过查询控件传占位符值，动态调整大订单和小订单的衡量标准，图表也随之刷新。
操作步骤
新建占位符。
在自定义SQL编辑页或数据集编辑页单击占位符管理->新建占位符。
输入变量名Price，类型为值占位符，变量类型为数值，查询默认值为全局生效，默认值为100（选填）。
说明用到计算字段的占位符必须有全局生效的默认值。
新建计算字段。
在数据集编辑页面，单击新建字段，按照图示方式新建订单规模字段。
字段表达式示例：
case when [price]>$val{Price} then '大订单' else '小订单' end单击确定并保存数据集。
创建可视化图表和查询控件。
单击开始分析->创建仪表板。
在仪表板编辑页面，按照图示方式添加柱图。
将订单规模字段拖入类别轴/维度，将price字段拖入值轴/度量，并单击更新，此时柱图展示效果如下：
此时，我们可以看到，度量字段price按照占位符Price的默认值100，区分出大订单和小订单。
按照图示方式新建查询控件。
在查询条件设置界面，将占位符Price设置为查询条件。
查看效果。
此时，您可以通过输入查询控件的数值来调整大小订单的衡量标准。
比如查询控件数值为100时，大订单金额为60.72万；查询控件数值为150时，大订单金额为52.5万。
场景2-灵活切换指标或分析维度
场景描述
当您有多个指标、维度需要展示，但放在同一个图表会显得内容较多不够清晰，搭建多个图表又会导致内容冗余时，可通过该能力实现图表字段的灵活切换。
以切换指标维度为例。
操作步骤
新建占位符。
在自定义SQL编辑页或数据集编辑页单击占位符管理->新建占位符。
输入变量名指标，类型为值占位符，变量类型为文本，查询默认值为全局生效，默认值为单价。
新建计算字段。
单击新建字段，按照图示方式新建数据字段。
字段表达式示例：
case when '$val{指标}'='订单金额' then [订单金额] when '$val{指标}'='利润金额' then [利润金额] when '$val{指标}'='单价' then [单价] when '$val{指标}'='运输成本' then [运输成本] else 0 end说明文本类型占位符请用英文单引号引用，例如'$val{指标}'。
单击确定并保存数据集。
创建可视化图表和查询控件。
单击开始分析->创建仪表板。
在仪表板编辑页面，按照图示方式添加柱图。
将区域字段拖入类别轴/维度，将数据段拖入值轴/度量，并单击更新，此时柱图展示效果如下：
按照图示方式新建查询控件。
在查询条件设置界面，将占位符指标设置为查询条件，选项值来源选择手工输入并配置手工录入的值。
查看效果。
此时，您可以通过筛选查询控件的值切换不同的指标。
场景3-动态调整辅助线
场景描述
将辅助线的值与占位符绑定，为占位符赋值时，辅助线跟随变化。
如：辅助线为每月的销售额KPI，每个月只需要通过查询控件调整即可动态更新辅助线的位置，不需要重新修改报表。
操作步骤
新建占位符。
说明辅助线里的占位符只支持数值类型。
在仪表板编辑页面，按照图示方式新建占位符。
输入变量名Target，变量类型为数值，查询默认值为全局生效，默认值为4000000。
说明辅助线中使用的占位符必须有全局生效的默认值。
设置辅助线。
在分析页签，找到辅助线并单击右侧笔形图标。
按照图示方式设置添加辅助线，并设置值为占位符Target。
此时您可以看到辅助线400万显示在图表上。
新建查询控件。
按照图示方式新建查询控件。
设置占位符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”必须设置全局生效的默认值。
单击运行，可以看到运行结果。
单击确认编辑并保存数据集。
创建可视化图表和查询控件。
单击开始分析->创建仪表板。
在仪表板编辑页面，按照图示方式添加饼图。
按照图示方式新建查询控件。
查看效果
此时，您可以通过输入查询控件的数值来调整利润范围的衡量标准。
场景5-对包含加速占位符的数据集开启抽取加速
场景描述
通过在自定义 SQL 的 WHERE 条件中引入加速占位符，并在加速配置中设置分区大小，实现数据的动态离线抽取与增量写入。适用于底表数据量大，原先自定义 SQL 运行超时，无法配置抽取加速的情况。
操作步骤
新建占位符。
在自定义SQL的 WHERE 条件中，添加加速占位符。
您只需要关注核心的查询逻辑，时间过滤交给占位符处理。
示例：在 WHERE 条件中加入report_date加速占位符：where $accel{report_date:report_date}。
设置查询默认值。
为了让SQL在编辑和预览阶段能够快速运行，需要为占位符设置一个默认值。
您可以在数据集的占位符管理中，为加速占位符设置完整表达式作为默认值，例如：report_date < '2025-04-01'。
配置抽取加速。
数据集成功保存后，您可以配置抽取加速。
开启Quick 引擎。
抽取范围选择指定日期范围并选择日期字段为该加速占位符对应的字段（如 report_date）。
配置抽取日期范围、增量范围等，保存并启动加速任务。
验证查询与加速效果
