宏定义变量

更新时间:2021-08-23

Sugar BI中的宏定义变量可以分为两类:

  • 数据宏定义:全局变量,可以自定义字段名和取值,在指定的位置使用。
  • 日期宏定义:Sugar BI中固定的日期宏定义,可以用来设置日期时间。

宏定义变量使用场景

功能模块 使用场景
数据模型 嵌入到计算字段的表达式中
嵌入到自定义SQL视图中
API 嵌入到数据拉取的API地址中
嵌入到API高级设置的请求参数中
SQL模型 嵌入到SQL语句中
嵌入到SQL建模的字段描述和展示名称中
图表 嵌入到文本,富文本内容中
嵌入到图表标题,图表简介中
嵌入到表格数据列表头名称和表头备注中
联动 在过滤条件中关联宏定义变量,与图表联动
定时推送 嵌入到邮件标题中

数据宏定义

在Sugar BI中,您可以自定义一些宏变量,这些宏定义可以在如下的场景中使用:

  • 嵌入到之后使用的 API 中,使用宏定义的目的是方便以后的 API 服务迁移,例如您的 API 从 A 域名变更到 B 域名,使用宏定义的话就会非常方便。
  • 嵌入到 SQL 模型的 SQL 语句中,这样可以通过一条 SQL 语句实现多个查询,例如您需要从不同的表中使用同一条 SQL 逻辑查询某个字段,使用宏定义可以避免写多条 SQL。
  • 嵌入到数据模型的计算字段中,在一个计算字段中编辑一条 SQL 表达式,可以实现多个 SQL 查询逻辑,例如您需要乘一个倍数,使用宏定义可以通过一个计算字段实现多种倍数求和。
  • 在过滤条件中关联宏定义变量,与图表联动。

数据宏定义的定义

Sugar BI提供三种方式来定义宏定义变量:

  • 空间级别的宏定义
  • 报表、大屏级别的宏定义
  • 图表级别的宏定义

注意:宏定义必须是大写字母和下划线。

图表级别的宏定义优先级 > 报表、大屏级别的宏定义优先级 > 空间级别的宏定义优先级

也就是说,图表级别的宏定义将覆盖报表、大屏级别的宏定义,报表、大屏级别的宏定义将覆盖空间级别的宏定义

空间级别数据宏定义

您可以在空间设置中自定义一些宏变量,这些宏变量可以在这个空间的任意大屏、报表的 API,数据模型的计算字段,SQL 模型的 SQL 语句,以及过滤条件中使用,设置如下:

图片

大屏、报表级别数据宏定义

您可以在大屏、报表的编辑页面中自定义一些宏变量,这些宏变量可以在当前大屏、报表中的任意图表的 API, 数据模型的计算字段,SQL 模型的 SQL 语句,以及过滤条件中使用。 设置如下图所示,点击大屏或报表标题,在右侧控制面板中找到「宏定义变量」设置,进行设置后点击保存按钮。

图片

图表级别数据宏定义

您可以在图表编辑页面中自定义一些宏变量,这些宏变量可以在当前图表的 API, 数据模型的计算字段,SQL 模型的 SQL 语句,以及过滤条件中使用。 设置如下图所示,点击图表,在右侧控制面板「基础」标签页中找到「宏定义变量」设置,进行设置后点击保存按钮。

图片

数据宏定义变量的使用

注意必须使用$开头,并使用花括号包裹宏定义变量和默认值,变量名和默认值之间使用||连接

例如${_HOST || default_value}${_CHART || default_value},其中default_value为宏定义变量_HOST_CHART的默认值

指定默认值的作用是,如果未在空间、大屏和报表、或图表中配置宏定义变量值,将使用指定的默认值default_value替换宏定义变量_HOST_CHART进行查询

当然,您也可以不指定默认值,例如这样使用${_HOST}${_CHART},但是我们非常建议您在使用宏定义变量时使用上述默认值语法,这样可以避免图表和过滤条件中 SQL 语句的报错

在 API 中的使用

在使用 API 方式绑定图表或过滤条件数据时,就可以这样使用:

图片

点击上图中的「调试」按钮,就能看到宏定义变量被替换之后真正访问的 url 中,宏定义变量${_HOSTA}被替换成了默认值http://127.0.0.1:8085}

图片

在图表中配置宏定义变量,如下图:

注意: 在图表中配置的宏定义变量优先级最高,它将覆盖页面级别和空间级别的同名宏定义变量

图片

点击「调试」按钮,就能看到宏定义变量被替换之后真正访问的 url 中,宏定义变量${_HOSTA}被替换成了配置的值http://www.baidu.com

图片

在 SQL 模型中的使用

在使用 SQL 模型方式绑定图表或过滤条件数据时,可以这样使用宏定义变量:

在 SQL 语句中使用
  1. 创建 SQL 模型,使用宏定义变量定义 SQL 语句

图片

  1. 如果未在图表中配置宏定义变量,点击图表的「调试」按钮,可以看到宏定义变量被替换成了默认值订单

图片

  1. 在需要绑定该 SQL 模型的图表右侧控制面板「基础」标签页中找到「宏定义变量」设置,进行设置后点击保存按钮

    注意: 在图表中配置的宏定义变量优先级最高,它将覆盖页面级别和空间级别的同名宏定义变量

图片

  1. 点击图表的「调试」按钮,就能看到宏定义变量被替换之后真正执行的 SQL 中,宏定义变量被替换成了图表中配置的值sale_order

图片

在编辑 SQL 的字段模型表达式和展示名称中使用

1.创建 SQL 模型,使用宏定义变量定义 SQL 语句,并使用宏定义变量编辑 SQL 的字段模型表达式和展示名称

假设系统中已经定义了宏定义变量${_NAME},取值为数量,那么可以用宏定义变量${_NAME}来定义字段模型表达式和展示名称,如下图所示:

图片

注意:字段或表达式中不支持{DATE} {YEAR}等日期宏定义

2.在图表中绑定想要展示的字段名

图片

3.点击图表的「调试」按钮,就能看到,在 SQL 查询结果中,${_NAME}字段已经被替换成了对应的取值数量

图片

在数据模型中的使用

在使用数据模型方式绑定图表或过滤条件数据时,可以这样使用宏定义变量:

在计算字段中的使用
  1. 创建数据模型,并新建一个计算字段,使用宏定义变量定义计算字段的 SQL 表达式

图片

  1. 在图表中绑定上一步新增的带有宏定义变量的计算字段:

图片

  1. 点击图表的「调试」按钮,就能看到宏定义变量被替换之后真正执行的 SQL 中,宏定义变量被替换成了默认值2

图片

  1. 在需要绑定该数据模型的图表右侧控制面板「基础」标签页中找到「宏定义变量」设置,进行设置后点击保存按钮

    注意: 在图表中配置的宏定义变量优先级最高,它将覆盖页面级别和空间级别的同名宏定义变量

图片

  1. 点击图表的「调试」按钮,就能看到宏定义变量被替换之后真正执行的 SQL 中,宏定义变量替换成了图表中配置的值3

图片

在自定义 SQL 视图中的使用

详见数据模型中使用自定义 SQL 视图

过滤条件关联宏定义变量

在输入框,单选,日期时间,日期过滤组件中,支持关联图表宏定义,设置关联后,对于设置了宏定义变量的图表,可实现过滤组件与图表联动,在浏览报表/大屏页面的时候动态的改变宏定义变量的取值。

注意:过滤条件关联宏定义变量方式的优先级最高,比上面三种宏定义变量的定义方式都要高

具体使用方法如下:

在绑定数据模型计算字段图表中的使用

  1. 选择输入框过滤组件,在右侧控制面板「基础」标签页中找到「是否关联图表宏定义」开关并启用,在下方配置关联的图表宏定义 key 值,点击保存,在输入框中输入筛选条件,例如:1000,点击查询

图片

  1. 点击折线图,查看调试数据,可以看到生成的 SQL 语句中,宏定义变量被替换成了输入框中输入的值

图片

场景实例

此实例使用「Sugar 官方示例数据源」来演示以下内容:

  • 如何生成显示全国各个省份利润率的地图视图

  • 如何创建将低利润率省份与高利润率省份区分开来的计算字段

  • 如何创建和动态调整低利润率与高利润率阈值,来动态查看全国各个省份利润率高低的地图视图

  • 在工具栏中选择「色彩地图」-「中国省份色彩」拖入编辑区,再拖入一个过滤组件,比如「输入框」,命名为:高利润率标准值

图片

  1. 进入「数据模型」,点击「创建数据模型」,数据源选择Sugar官网示例数据源,输入一个数据模型名称,点击「确定」

图片

  1. 进入数据模型编辑页面,拖入一张数据表,比如sale_order,Sugar BI自动将表中的字段区分为维度度量分别展示

图片

  1. 下面先创建 1 个计算字段用来计算利润率,点击「新建计算度量」,输入计算字段的名称和表达式,点击「确定」

图片

  1. 下面再创建 1 个计算字段用来区分高利润率低利润率

图片

  1. 回到地图编辑页面,进入右侧「控制面板」-「数据」,在数据模型列表中选择刚才创建的数据模型,按下图拖入维度和度量

图片

  1. 进入右侧「控制面板」-「高级」,在「颜色映射设置」中选择「颜色分段」,并指定每段的颜色

    注意,这里设置值的时候,参考刚才在数据模型计算字段中,「高利润率」计算字段的返回值

    例如本例中「高利润率」返回 1,低利润率返回 0,那么这里应该如下设置:

图片

  1. 点击刷新图表,就可以看到如下的利润率地图中,根据阈值0.15用不同颜色区分出了高利润率和低润率的省份

图片

  1. 但将高利润率定义为大于 15% 是武断的,之所以选择该值,原因是它以大致平均的方式划分了全国各个省份的利润率,作为替代,您可以自定义该阈值,为此,您将使用到上方的过滤组件。

    点击过滤组件「输入框」,进入右侧「控制面板」-「基础」,启用「是否关联图表宏定义」,并输入关联的图表宏定义 key 值,点击「保存」

    注意: 这个 key 值就是计算字段表达式中需要关联的宏定义变量名

图片

  1. 这时,在过滤组件中输入的值,将替换数据模型计算字段高利润率中设置的宏定义变量默认值0.15进行查询,例如输入0.16,可以看到地图发生变化

图片

  1. 点击地图,查看调试数据,可以看到生成的 SQL 语句中,宏定义变量被替换成了输入框中输入的值

图片

在绑定 SQL 模型图表中的使用

  1. 选择输入框过滤组件,在右侧控制面板「基础」标签页中找到「是否关联图表宏定义」开关并启用,在下方配置关联的图表宏定义 key 值,点击保存,在输入框中输入筛选条件,例如:类别,点击查询

图片

  1. 点击折线图,查看调试数据,可以看到生成的 SQL 语句中,宏定义变量被替换成了输入框中输入的值

图片

在使用 API 方式绑定数据的图表中的使用

  1. 选择输入框过滤组件,在右侧控制面板「基础」标签页中找到「是否关联图表宏定义」开关并启用,在下方配置关联的图表宏定义 key 值,点击保存,在输入框中输入筛选条件,例如:http://127.0.0.1:8085,点击查询

图片

  1. 点击上图中的「调试」按钮,就能看到宏定义变量被替换之后真正访问的 url 中,宏定义变量被替换成了输入框中输入的值

图片

日期宏定义

一些固定的日期宏定义,主要包含:

  • {YEAR}表示当前年
  • {MONTH}表示当前月
  • {DAY}表示当前日
  • {HOUR}表示当前小时
  • {MINUTE}表示当前分钟
  • {SECOND}表示当前秒
  • {MONTH}{DAY}{HOUR}{MINUTE}{SECOND}支持(number)语法,将01转换成1
  • {DATE}表示当前日期 格式如:2018-04-22
  • {DATE}支持+/-N语法(如:{DATE-1}表示昨天),并且支持(number)语法
  • {TIMESTAMP}表示当前时间戳,采用 unix 秒格式
  • {TIMESTAMP}支持+/-N语法
  • {TODAYZEROTIMESTAMP}表示当天零点的时间戳,采用 unix 秒格式
  • {TODAYZEROTIMESTAMP}支持+/-N语法
  • {$MONDAY}表示本周一,并支持年月日的加减语法,如 {$MONDAY-1Y} 表示一年前的本周一
  • {$MONTHFIRSTDAY}表示本月第一天,并支持年月日的加减语法,如 {$MONTHFIRSTDAY-1D} 表示上个月最后一天,{$MONTHFIRSTDAY-1M} 表示上个月第一天
  • {$LASTMONTHFIRSTDAY}表示上月第一天,并支持年月日的加减语法
  • {$QUARTERFIRSTDAY}表示本季度第一天,并支持年月日的加减语法,如 {$QUARTERFIRSTDAY+3M-1D} 表示本季度最后一天
  • {$YEARFIRSTDAY}表示本年第一天,并支持年月日的加减语法
  • {$LASTYEARFIRSTDAY}表示去年第一天,并支持年月日的加减语法

如下图是图表数据的『调试』时所展示的,左侧是原始的伪 SQL,右侧是生成的真正的 SQL 语句:

图片

图片

上一篇群机器人

本页内容