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 语句

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

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

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

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

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

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

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

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

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

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

在数据模型中的使用

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

在计算字段中的使用

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

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

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

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

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

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

在自定义 SQL 视图中的使用

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

过滤条件关联宏定义变量

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

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

具体使用方法如下：

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

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

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

场景实例

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

• 如何生成显示全国各个省份利润率的地图视图
• 如何创建将低利润率省份与高利润率省份区分开来的计算字段
• 如何创建和动态调整低利润率与高利润率阈值，来动态查看全国各个省份利润率高低的地图视图

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2. 点击上图中的「调试」按钮，就能看到宏定义变量被替换之后真正访问的 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 语句：