宏定义变量
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语法（如：{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 语句：
