SQL中关联过滤条件

在实际的使用场景中，我们经常需要在 SQL 语句中嵌入一些where条件，并且这些where条件是根据用户的交互动态生成的。基于此，在Sugar BI中，我们已经支持了多种常用的「过滤条件」（日期、单选、多选等等），并且支持将这些过滤条件的取值动态嵌入到 SQL 模型的语句中，例如：

关联过滤条件

Sugar BI中关联过滤条件需要按照特定的伪语法格式来书写，格式为 {field = [conditions.key]}

• 其中field是 SQL 中的字段名（根据您的数据表结构来决定的，和具体 SQL 有关）；
• =号是 SQL 判断逻辑词，可以支持不写判断逻辑，Sugar BI会根据不同的过滤条件类型自动补全；
• 过滤条件必须要使用[]包围，并且必须输入conditions关键词，key是指过滤条件的「查询 key 值」

按照这样的规则就可以将过滤条件嵌入到 SQL 模型的伪 SQL 语句中，Sugar BI在运行时会自动的将相应的部分替换成当前的过滤条件取值。值得注意的一点时，如果 SQL 语句中嵌入了这样的语法，但是过滤条件中并没有传递该参数，Sugar BI会将嵌入的部分自动替换为1=1的恒等式。 如下图中我们传递了date过滤条件，但没传递name过滤条件：

不同类型的过滤条件在替换伪 SQL 语法时有细微的差别，下面就一一描述在 SQL 中关联各种类型的过滤条件（下面的各个截图都是图表数据的『调试』时所展示的，左侧是原始的伪 SQL，右侧是关联了过滤条件之后生成的真正要在数据库上执行的 SQL 语句）：

日期

• 如果没有判断逻辑，会自动补全为 =
• 如果日期上没加单引号，会自动加上单引号，当然，用户也可以加数据库所支持的双引号
• 支持扩充语法(number)，可以将日期转化为Ymd的格式
• 支持扩充语法(timestamp)，可以将日期转化为时间戳的格式
• 支持扩充语法(+/-N)，可在日期的取值上加减天数，如 (-2) (+1) 等
• 支持扩充语法(year)、(month)、(day)分别获取年月日
• 扩充语法可联合使用，如 (-2.number)、(-2.timestamp)、(+30.month)、(+365.year)等
• 注意：下图中的 date 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

日期范围

• 如果没有判断逻辑，会自动补全为 between and
• 使用日期范围中两个值时不需要加单引号
• 支持扩充语法(number)，可以将日期转化为Ymd的格式
• 支持扩充语法(timestamp)，可以将日期转化为时间戳的格式
• 支持取日期范围中的单个日期值，可以使用(0)、(1)，也可以使用(first)、(last)
• 单个日期值，如果没有判断逻辑，会自动补全为 =，并且会自动补全单引号
• 单个日期值也支持(number)、(timestamp)语法，如：(0.number)
• 单个日期也支持(+/-N)语法，如：(first.-1)，当然也支持如：(last.+1.number)、(last.+1.timestamp)等
• 注意：下图中的 dateRange 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

单选列表、下拉单选

• 如果没有判断逻辑，会自动补全为 =
• 如果没加单引号，会自动加上单引号
• 支持扩充语法(number)，将内容转换为数字（当然，取值必须能转化成数字才行）
• 支持扩充语法(splitComma)，可以将取值按照英文逗号进行分割，从而支持 SQL 中的In逻辑
• 注意：下图中的 select、list、select1 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

多选列表、下拉多选

• 如果没有判断逻辑，会自动补全为 in
• 不需要加单引号
• 支持扩充语法(number)，当然只有传入的值真的是数值才会生效
• 判断逻辑是like时，会自动生成多个or...like模式，见下图
• 支持扩充语法(raw)，一般用于过滤条件的硬嵌入，见下一章节
• 支持扩充语法(rawWithDoubleQuot)，一般用于过滤条件的硬嵌入，在 API 方式绑定图表数据的高级配置中，可以自定义 POST 发送的数据内容，可以结合这个语法来实现发送 JSON 数组类型的字段数据
• 支持扩充语法(rawWithSingleQuot)，同上，只是将双引号包裹改为单引号包裹
• 注意：下图中的 multiSelect 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

时间

• 如果没有判断逻辑，会自动补全为 =
• 如果时间上没加单引号，会自动加上单引号
• 支持扩展语法获取时间中的 日期、时间、年、月、日、时、分、秒 部分
• 支持扩充语法(timestamp)，可以将时间转化为时间戳的格式
• 通过(date)获取的日期部分，还支持(+/-N)语法来对日期做加减
• 对于年月日时分秒，支持 number 语法将 01 转化为 1，并且除掉默认的单引号
• 注意：下图中的 dateTime 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

时间范围

• 如果没有判断逻辑，会自动补全为 between and
• 使用时间范围中两个值时不需要加单引号
• 支持扩充语法(timestamp)，可以将时间转化为时间戳的格式
• 支持取时间范围中的单个时间值，可以使用(0)、(1)，也可以使用(first)、(last)
• 单个时间值，如果没有判断逻辑，会自动补全为 =，并且会自动补全单引号
• 获取到单个时间之后，也可以继续获取日期部分和时间部分，并支持进一步的扩充语法，可见上面章节
• 注意：下图中的 dtr 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

输入框

• 如果没有判断逻辑，会自动补全为 =
• 如果没加单引号，会自动加上单引号
• 支持扩充语法(number)，将内容转换为数字
• 支持扩充语法(splitComma)，可以将输入值按照英文逗号进行分割，从而支持 SQL 中的In逻辑
• 注意：下图中的 text和text1 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

树形选择

• 如果没有判断逻辑，会自动补全为 in
• 不需要加单引号
• 支持扩充语法(number)，当然只有传入的值真的是数值才会生效
• 判断逻辑是like时，会自动生成多个or...like模式，见下图
• 支持扩充语法(raw)，一般用于硬嵌入
• 注意：下图中的 _selectTree 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

多重逻辑

• 多重逻辑因为本身就具有判断逻辑，因此不允许添加任何=等判断逻辑词
• 支持扩充语法(number)
• 注意：下图中的 _logic、_logic1、_logic2 只是示例，在具体使用时，需要替换为过滤条件的「查询 key 值」

SQL 中硬嵌入过滤条件

和上面描述的「SQL 语句中关联过滤条件」有所不同，Sugar BI还支持将过滤条件的取值直接嵌入到 SQL 语句中，不仅是where条件语句中，还可以将过滤条件的取值嵌入到 SQL 语句的任何地方（如 select 中，以及 from 的表名等）。

硬嵌入过滤条件的语法是 {conditions.key} :

• key是指过滤条件的「查询 key 值」
• 不同类型的过滤条件，和关联过滤条件相同，都支持扩充语法，如日期类过滤条件的 conditions.date(+1.number)，每种具体的过滤条件语法可参见上面的「关联过滤条件」
• 和关联过滤条件不同，如果 SQL 语句中有硬嵌入的语法，但是过滤条件并没有传递相应的值，那么该硬嵌入的语法会被替换为空字符串，而不是上节中的1=1
• 另外，硬嵌入查询条件其实本质就是字符串替换，所以并不会像上节中那样会自动给字符串取值加上单引号之类，具体可见下图的第 7 行，我们需要手动加上单引号

示例如下图（过滤条件中：multiSelect是一个多选，选中了 col1 和 col2；date是日期过滤条件，取值为2018-08-07；text为输入框，取值是 haha）：

过滤条件的豁免

前面我们大篇幅的说过，伪 SQL 语句中可以嵌入过滤条件，如果伪 SQL 的语法中写了但是过滤条件没传递对应的值，那么我们会自动在伪 SQL 中替换为 1=1 的恒等或空字符串；那么反过来，如果过滤条件传递了值，但是伪 SQL 中却没有用到，会怎么样？

这种情况下，Sugar BI会报错提示过滤条件传递了但是 SQL 中没使用，这样做是有原因的，因为如果用户添加了一个新的过滤条件，但是在图表中却忘记了修改相应的伪 SQL 语句，这时 SQL 并没有任何的语法错误，会照样查询到数据，但是这时的数据结果可能是不正确的，因为忽略了一个过滤条件。所以Sugar BI不允许这样的情况出现，我们会主动报错，提醒用户修改 SQL 语句，此时用户除了修改 SQL 语句外，还有另外一个选择，那就是豁免该过滤条件对当前图表的影响，如下图在绑定图表的数据时可以选择要豁免的条件。