Sugar BI 宏定义功能拓展

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

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

宏定义变量使用场景

功能模块	使用场景
数据模型	嵌入到计算字段的表达式中
数据模型	嵌入到自定义SQL视图中
API	嵌入到数据拉取的API地址中
API	嵌入到API高级设置的请求参数中
SQL模型	嵌入到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 视图中的使用

详见数据模型中使用自定义 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有免费试用的活动，不仅可以进行数据自动补全，还可以制作许多精美的报表和大屏、体验各种智能化功能，大家快去薅羊毛免费尝试尝试吧！

数据可视化Sugar BI