SQL中关联过滤条件

更新时间：2025-08-22

在实际的使用场景中，我们经常需要在 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 语句外，还有另外一个选择，那就是豁免该过滤条件对当前图表的影响，如下图在绑定图表的数据时可以选择要豁免的条件。

SQL字段展示名称的动态化

大屏制作入门

百度数据可视化 SUGAR