SQL关联联动参数

更新时间：2025-08-22

有关图表如何配置联动功能，详见图表的联动设置。

联动参数在哪里看

对于联动的下级图表，最重要的就是如何知道联动的参数有哪些？其实，在联动的下级图表的右侧控制面板中「数据」下，单击「调试」，就能看到上层图表传递给本图表的联动参数。例如，一个饼图点击联动一个折线图：

1、点击饼图的某一区域，触发联动

2、然后点击折线图，右侧控制面板中单击「调试」，如下图：

3、在「调试」窗口中就能看到dependence字段即联动参数，如下图：

SQL 中关联联动参数

如果图表被某个上级图表设置为了联动的下级图表，当上级图表触发联动时，Sugar BI在请求下级图表的数据时会额外附加上一些联动的具体信息。例如，如果图表的上级图表是一个饼图，点击每个扇形区域时，我们在拉取下级图表的数据时会加上dependence参数用来描述用户到底是点击了哪一区域。并且Sugar BI支持在伪 SQL 语句中嵌入这些联动的参数，从而使得下级图表的数据根据点击区域的不同而同步更新。

下级图表接受到的dependence参数格式如下：

                JavaScript
                
            

                "dependence": {
    "item": {
        "name": "数据1",
        "value": [
            560,
            1354
        ],
        "yVal": "123,457",
        "category": "点4",
        "_sugar_dd_default_": "点4"
    },
    "fireKey": ""
}
            

和下钻参数类似，伪 SQL 语句中支持关联联动参数，有两种关联格式，分别为简单模式和高级模式（下面的各个截图都是联动的下级图表数据的『调试』时所展示的，左侧是原始的伪 SQL，右侧是生成的真正要在数据库上执行的 SQL 语句）：

1.简单模式

简单模式时，使用的伪语法格式为：{field = [dependence]} 或者 {field = [dependence || default]}

其中field是 SQL 中的字段名（根据您的数据表结构来决定的，和具体 SQL 有关）；
=号是 SQL 判断逻辑词，可以支持不写判断逻辑，Sugar BI会自动补全为=，支持的逻辑词有：=, !=, <>, >=, <=, >, <, in, like, between, regexp等；
联动参数需要使用[]包围，并且必须输入dependence关键词；
default为默认值，当上层图表还没有触发联动操作时，联动的下层图表就获取不到联动参数，因此支持给一个默认值，这个默认值是您自己填写的，例如{field = [dependence || haha]}时的默认值就是haha
如果上层图表还没有触发联动操作，并且您也没有填写默认值，我们会用1=1替换整个表达式，保证 SQL 的正常运行；
使用简单模式时，我们默认取的是上图代码中的_sugar_dd_default_字段，这个参数是Sugar BI自动生成的，不同类型的图表在触发联动时，生成这个默认字段的策略不太一样，例如饼图在点击触发联动时，这个默认字段的取值是用户点击的饼图某一扇形区块的名称，再例如柱状图在触发联动时，这个默认字段的取值是用户点击的柱体对应的 X 轴取值。

针对上面代码示例，我们可以这样取其中的默认参数（下图是联动的下级图表数据的『调试』时所展示的，左侧是原始的伪 SQL，右侧是生成的真正的 SQL 语句）：

在 95%的情况下使用简单模式就能解决您的问题，但是也有可能你需要取联动参数中的其他数据（非_sugar_dd_default_字段），此时就需要用到下面的高级模式：

2.高级模式

高级模式时，使用的伪语法格式为：{field = [dependence.key || default]}

其中field是 SQL 中的字段名（根据您的数据表结构来决定的，和具体 SQL 有关）；
=号是 SQL 判断逻辑词，可以支持不写判断逻辑，Sugar BI会自动补全为=，支持的逻辑词有：=, !=, <>, >=, <=, >, <, in, like, between, regexp等；
联动参数需要使用[]包围，并且必须输入dependence关键词；
key为要取的数据在 item 中的字段名；
支持扩充语法(number)，(raw)；
联动参数 item 中的字段有可能是个数组，Sugar BI允许你嵌入该数组的任意一个元素，语法为： [dependence.key(1)]，其中的1表示数组的 index 号，他也支持扩充语法(number)，格式为[dependence.key(1,number)];
可以通过[dependence.sugar_fireKey]的方式取到联动的触发 ID，比如表格就可以判断是点击了哪列触发的联动;
default为默认值，当上层图表还没有触发联动操作或者在联动参数中找不到key配置的字段时，联动的下层图表就获取不到联动参数，因此支持给一个默认值，这个默认值是您自己填写的，例如{field = [dependence.key || haha]}时的默认值就是haha
如果上层图表还没有触发联动操作或者联动参数 key 对应的字段不存在，并且您也未配置默认值，我们会用1=1替换整个表达式，保证 SQL 的正常运行。

针对上面代码示例，我们可以这样取其中的联动参数（下图是联动的下级图表数据的『调试』时所展示的，左侧是原始的伪 SQL，右侧是生成的真正的 SQL 语句）：

和上面情况进行比较，例如上层图表还没有点击触发联动时，即联动参数不存，我们看一下有默认值与没有默认值的情况对比：

每种图表在点击触发联动时所传递到下层图表的参数格式不尽相同（例如父图表也是使用 SQL 方式绑定的数据，Sugar BI在一些情况下会额外增加一些参数的，如数据使用了数据值映射，Sugar BI会自动将映射之前的原始值也附加上，这样在展示时是使用的映射后的中文，而在联动时有可以将原始的英文或编码传递到后端），一定要善用图表的「调试」，通过联动的下级图表的“控制面板”中的“调试”按钮来查看此时联动的参数详情，从而可以很清晰的看到有哪些参数可以嵌入到自己的 SQL 语句中。

SQL 中硬嵌入联动参数

通常情况下，我们可以通过上面的内容将联动参数与 SQL 的 where 绑定在一起，例如{field = [dependence.key || default]}

如果我们希望联动参数的值直接嵌入到 SQL 语句中（例如嵌入到 select 或者 from 的后面），我们可以使用SQL中硬嵌入联动参数，语法如下：

1：{dependence}
2：{dependence || default}
3：{dependence.key || default}
4：{dependence.key(1) || default}
5：{dependence.sugar_fireKey}

大家会发现硬嵌入和上面的关联用法很类似，

必须输入dependence关键词并使用{}包裹表达式；
key为要取的数据在 item 中的字段名；
default为默认值，当联动参数不存在，或者在联动参数中找不到key配置的字段时，可以配置默认值让 sql 正常运行并拉取默认数据；
联动参数 item 中的字段有可能是个数组，Sugar BI允许你嵌入该数组的任意一个元素，语法为： {dependence.key(1)}，其中的1表示数组的 index 号
如果联动参数不存在且默认值也未配置时，则会用空字符串替换整个表达式，而不是之前的1=1；
可以通过{dependence.sugar_fireKey}的方式取到联动的触发 ID，比如表格就可以判断是点击了哪列触发的联动。

以本文上面的联动参数为例（下图是联动的下级图表数据的『调试』时所展示的，左侧是原始的伪 SQL，右侧是生成的真正的 SQL 语句）：