AI 助理
备案控制台
文档
输入文档关键字查找
首页 智能商业分析 Quick BI 操作指南 数据建模 占位符

占位符

更新时间：
产品详情
我的收藏

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

操作步骤

创建入口

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

  1. 在SQL代码编辑页面，单击占位符管理。

    image.png

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

    image.png

入口二：数据集编辑页面

  1. 单击数据集编辑页上方菜单栏中image.png图标，进行占位符管理。image.png

  2. 单击新建占位符，可通过手动输入的方式创建占位符。

    image.png

入口三：仪表板编辑页面

  1. 在仪表板编辑页面，按照以下方式新建占位符。

    1. 单击image.png图标，新建占位符。

      image.png

    2. 在占位符管理界面新建占位符。image.png

  2. 在新建占位符界面输入变量名、变量类型和查询默认值。image.png

配置项及说明

配置项

说明

变量名

占位符的名称，可自定义修改。

类型

占位符的类型，分为表达式占位符和值占位符，类型不支持修改。

变量类型

支持文本、数值、日期-年、日期-年季、日期-年月、日期-年周、日期-年月日、日期-年月日时分秒。

查询默认值

默认值生效范围支持仅数据集和全局生效两种模式：

  • 仅数据集：只在数据集编辑页生效。

  • 全局生效：在仪表板、电子表格等下游也生效。

输入框输入最多150个字符。

说明

表达式占位符的默认值需填写完整的表达式，比如：area = "东北"。

操作

单击图标image.png删除占位符。

值占位符

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

说明

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

格式：'$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}

查询控件配置如下：

image

应用场景

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

场景描述

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

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

操作步骤

  1. 新建占位符

    1. 在自定义SQL编辑页或数据集编辑页单击占位符管理->新建占位符。image.png

    2. 输入变量名Price，类型为值占位符，变量类型为数值，查询默认值为全局生效，默认值为100（选填）。

      说明

      用到计算字段的占位符必须有全局生效的默认值。

      image.png

  2. 新建计算字段。

    1. 在数据集编辑页面，单击新建字段，按照图示方式新建订单规模字段。

      image

      字段表达式示例：

      case when [price]>$val{Price}
then '大订单'
else '小订单'
end

    2. 单击确定并保存数据集。

  3. 创建可视化图表和查询控件。

    1. 单击开始分析->创建仪表板。

    2. 在仪表板编辑页面，按照图示方式添加柱图。image.png

    3. 将订单规模字段拖入类别轴/维度，将price字段拖入值轴/度量，并单击更新，此时柱图展示效果如下：

      image.png

      此时，我们可以看到，度量字段price按照占位符Price的默认值100，区分出大订单和小订单。

    4. 按照图示方式新建查询控件。

      image.png

    5. 在查询条件设置界面，将占位符Price设置为查询条件。image.png

  4. 查看效果。

    此时，您可以通过输入查询控件的数值来调整大小订单的衡量标准。

    比如查询控件数值为100时，大订单金额为60.72万；查询控件数值为150时，大订单金额为52.5万。

    53.gif

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

场景描述

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

以切换指标维度为例。

操作步骤

  1. 新建占位符。

    1. 在自定义SQL编辑页或数据集编辑页单击占位符管理->新建占位符。image.png

    2. 输入变量名指标，类型为值占位符，变量类型为文本，查询默认值为全局生效，默认值为单价。image.png

  2. 新建计算字段。

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

      字段表达式示例：

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

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

    2. 单击确定并保存数据集。

  3. 创建可视化图表和查询控件。

    1. 单击开始分析->创建仪表板。

    2. 在仪表板编辑页面，按照图示方式添加柱图。

      image.png

    3. 将区域字段拖入类别轴/维度，将数据段拖入值轴/度量，并单击更新，此时柱图展示效果如下：image.png

    4. 按照图示方式新建查询控件。image.png

    5. 在查询条件设置界面，将占位符指标设置为查询条件，选项值来源选择手工输入并配置手工录入的值。image.png

  4. 查看效果。

    此时，您可以通过筛选查询控件的值切换不同的指标。

    10.gif

场景3-动态调整辅助线

场景描述

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

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

操作步骤

  1. 新建占位符

    说明

    辅助线里的占位符只支持数值类型。

    1. 在仪表板编辑页面，按照图示方式新建占位符。image.png

    2. 输入变量名Target，变量类型为数值，查询默认值为全局生效，默认值为4000000。

      说明

      辅助线中使用的占位符必须有全局生效的默认值。

      image.png

  2. 设置辅助线。

    1. 在分析页签，找到辅助线并单击右侧笔形图标。image.png

    2. 按照图示方式设置添加辅助线，并设置值为占位符Target。image.png

      此时您可以看到辅助线400万显示在图表上。image.png

  3. 新建查询控件。

    1. 按照图示方式新建查询控件。image.png

    2. 设置占位符Target为查询条件并单击确定。image.png

  4. 查看效果。

    您可以通过切换查询控件的值来调整辅助线的位置。

    11.gif

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

场景描述

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

操作步骤

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

    image.png

  2. 输入SQL代码后

    image.png

    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}

  3. 单击占位符管理。

    image.png

  4. 进入占位符管理界面并输入默认值。

    image.png

    说明

    如果占位符应用在select语句后面，必须设置全局生效的默认值。

    本例中，占位符“profit_range”必须设置全局生效的默认值。

  5. 单击运行，可以看到运行结果。

    image.png

  6. 单击确认编辑并保存数据集。

  7. 创建可视化图表和查询控件。

    1. 单击开始分析->创建仪表板。

    2. 在仪表板编辑页面，按照图示方式添加饼图。

      image.png

    3. 按照图示方式新建查询控件。

      image.png

    4. 查看效果

      此时，您可以通过输入查询控件的数值来调整利润范围的衡量标准。

      52.gif

上一篇：自定义SQL下一篇：系统内置函数
文档推荐