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 语句中使用
- 创建 SQL 模型,使用宏定义变量定义 SQL 语句
- 如果未在图表中配置宏定义变量,点击图表的「调试」按钮,可以看到宏定义变量被替换成了默认值
订单
-
在需要绑定该 SQL 模型的图表右侧控制面板「基础」标签页中找到「宏定义变量」设置,进行设置后点击保存按钮
注意: 在图表中配置的宏定义变量优先级最高,它将覆盖页面级别和空间级别的同名宏定义变量
- 点击图表的「调试」按钮,就能看到宏定义变量被替换之后真正执行的 SQL 中,宏定义变量被替换成了图表中配置的值
sale_order
:
在编辑 SQL 的字段模型表达式和展示名称中使用
1.创建 SQL 模型,使用宏定义变量定义 SQL 语句,并使用宏定义变量编辑 SQL 的字段模型表达式和展示名称
假设系统中已经定义了宏定义变量${_NAME}
,取值为数量
,那么可以用宏定义变量${_NAME}
来定义字段模型表达式和展示名称,如下图所示:
注意:字段或表达式中不支持{DATE} {YEAR}等日期宏定义
2.在图表中绑定想要展示的字段名
3.点击图表的「调试」按钮,就能看到,在 SQL 查询结果中,${_NAME}
字段已经被替换成了对应的取值数量
在数据模型中的使用
在使用数据模型方式绑定图表或过滤条件数据时,可以这样使用宏定义变量:
在计算字段中的使用
- 创建数据模型,并新建一个计算字段,使用宏定义变量定义计算字段的 SQL 表达式
- 在图表中绑定上一步新增的带有宏定义变量的计算字段:
- 点击图表的「调试」按钮,就能看到宏定义变量被替换之后真正执行的 SQL 中,宏定义变量被替换成了默认值
2
:
-
在需要绑定该数据模型的图表右侧控制面板「基础」标签页中找到「宏定义变量」设置,进行设置后点击保存按钮
注意: 在图表中配置的宏定义变量优先级最高,它将覆盖页面级别和空间级别的同名宏定义变量
- 点击图表的「调试」按钮,就能看到宏定义变量被替换之后真正执行的 SQL 中,宏定义变量替换成了图表中配置的值
3
:
在自定义 SQL 视图中的使用
过滤条件关联宏定义变量
在输入框,单选,日期时间,日期过滤组件中,支持关联图表宏定义,设置关联后,对于设置了宏定义变量的图表,可实现过滤组件与图表联动,在浏览报表/大屏页面的时候动态的改变宏定义变量的取值。
注意:过滤条件关联宏定义变量方式的优先级最高,比上面三种宏定义变量的定义方式都要高
具体使用方法如下:
在绑定数据模型计算字段图表中的使用
- 选择输入框过滤组件,在右侧控制面板「基础」标签页中找到「是否关联图表宏定义」开关并启用,在下方配置关联的图表宏定义 key 值,点击保存,在输入框中输入筛选条件,例如:1000,点击查询
- 点击折线图,查看调试数据,可以看到生成的 SQL 语句中,宏定义变量被替换成了输入框中输入的值
场景实例
此实例使用「Sugar 官方示例数据源」来演示以下内容:
- 如何生成显示全国各个省份利润率的地图视图
- 如何创建将低利润率省份与高利润率省份区分开来的计算字段
- 如何创建和动态调整低利润率与高利润率阈值,来动态查看全国各个省份利润率高低的地图视图
- 在工具栏中选择「色彩地图」-「中国省份色彩」拖入编辑区,再拖入一个过滤组件,比如「输入框」,命名为:高利润率标准值
- 进入「数据模型」,点击「创建数据模型」,数据源选择
Sugar官网示例数据源
,输入一个数据模型名称,点击「确定」
- 进入数据模型编辑页面,拖入一张数据表,比如
sale_order
,Sugar BI自动将表中的字段区分为维度
和度量
分别展示
- 下面先创建 1 个计算字段用来计算
利润率
,点击「新建计算度量」,输入计算字段的名称和表达式,点击「确定」
- 下面再创建 1 个计算字段用来区分
高利润率
与低利润率
- 回到地图编辑页面,进入右侧「控制面板」-「数据」,在数据模型列表中选择刚才创建的数据模型,按下图拖入维度和度量
-
进入右侧「控制面板」-「高级」,在「颜色映射设置」中选择「颜色分段」,并指定每段的颜色
注意,这里设置值的时候,参考刚才在数据模型计算字段中,「高利润率」计算字段的返回值
例如本例中「高利润率」返回 1,低利润率返回 0,那么这里应该如下设置:
- 点击刷新图表,就可以看到如下的
利润率
地图中,根据阈值0.15
用不同颜色区分出了高利润率和低润率的省份
-
但将高利润率定义为大于 15% 是武断的 , 之所以选择该值,原因是它以大致平均的方式划分了全国各个省份的利润率,作为替代,您可以自定义该阈值,为此,您将使用到上方的过滤组件。
点击过滤组件「输入框」,进入右侧「控制面板」-「基础」,启用「是否关联图表宏定义」,并输入关联的图表宏定义 key 值,点击「保存」
注意: 这个 key 值就是计算字段表达式中需要关联的宏定义变量名
- 这时,在过滤组件中输入的值,将替换数据模型计算字段
高利润率
中设置的宏定义变量默认值0.15
进行查询,例如输入0.16
,可以看到地图发生变化
- 点击地图,查看调试数据,可以看到生成的 SQL 语句中,宏定义变量被替换成了输入框中输入的值
在绑定 SQL 模型图表中的使用
- 选择输入框过滤组件,在右侧控制面板「基础」标签页中找到「是否关联图表宏定义」开关并启用,在下方配置关联的图表宏定义 key 值,点击保存,在输入框中输入筛选条件,例如:
类别
,点击查询
- 点击折线图,查看调试数据,可以看到生成的 SQL 语句中,宏定义变量被替换成了输入框中输入的值
在使用 API 方式绑定数据的图表中的使用
- 选择输入框过滤组件,在右侧控制面板「基础」标签页中找到「是否关联图表宏定义」开关并启用,在下方配置关联的图表宏定义 key 值,点击保存,在输入框中输入筛选条件,例如:'http://127.0.0.1:8085',点击查询
- 点击上图中的「调试」按钮,就能看到宏定义变量被替换之后真正访问的 url 中,宏定义变量被替换成了输入框中输入的值
日期宏定义
一些固定的日期宏定义,主要包含:
{YEAR}
表示当前年{MONTH}
表示当前月{DAY}
表示当前日{HOUR}
表示当前小时{MINUTE}
表示当前分钟{SECOND}
表示当前秒{MONTH}
、{DAY}
、{HOUR}
、{MINUTE}
、{SECOND}
支持(number)
语法,将01
转换成1
{DATE}
表示当前日期 格式如:2018-04-22{DATE}
支持+/-N
语法,并且支持(number)
语法{TIMESTAMP}
表示当前时间戳,采用 unix 秒格式{TIMESTAMP}
支持+/-N
语法{TODAYZEROTIMESTAMP}
表示当天零点的时间戳,采用 unix 秒格式{TODAYZEROTIMESTAMP}
支持+/-N
语法{$MONDAY}
表示周一,支持+/-N
语法{$MONTHFIRSTDAY}
表示本月第一天,支持+/-N
语法{$LASTMONTHFIRSTDAY}
表示上月第一天,支持+/-N
语法{$QUARTERFIRSTDAY}
表示本季度第一天,支持+/-N
语法{$YEARFIRSTDAY}
表示本年第一天,支持+/-N
语法{$LASTYEARFIRSTDAY}
表示去年第一天,支持+/-N
语法
如下图是图表数据的『调试』时所展示的,左侧是原始的伪 SQL,右侧是生成的真正的 SQL 语句:
最近Sugar BI有免费试用的活动,不仅可以进行数据自动补全,还可以制作许多精美的报表和大屏、体验各种智能化功能,大家快去薅羊毛免费尝试尝试吧!