嵌入式 Dashboard 数据筛选：RLS 问题与 Jinja + urlParams 方案
本文梳理在 Embedded SDK（guest token） 场景下，通过自定义图表把「左侧选择」同步到右侧嵌入仪表盘时，使用 Guest Token 的 RLS（Row Level Security）做数据筛选为何容易报错或不稳定 ，以及项目最终采用 Jinja 模板 + 嵌入 URL 查询参数（urlParams） 的解决路径，便于排查类似问题与统一实现方式。
1. 业务场景与目标
- 父应用或自定义图表（如
superset-plugin-chart-selected-area/superset-plugin-chart-selected-department）在左侧做区域、部门等选择。 - 右侧通过
@superset-ui/embedded-sdk嵌入 Superset Dashboard，希望 仪表盘内图表随选择变化而过滤数据。 - 技术链路：
fetchGuestToken→ 拿到 JWT → 嵌入时通过dashboardUiConfig.urlParams把键值对挂到 iframe 的查询串上。
2. 初期方案：在 guest_token 中写入 RLS
Superset 的 Guest Token 载荷支持 rls 字段：一组带 clause（以及可选 dataset 等）的规则，后端在 访客用户 查询数据集时会把这些子句并入 SQL，达到行级过滤效果。
前端侧曾为拼接类似 column IN (...) 的子句，并在请求 /security/guest_token/ 时把 rls 一并提交，期望 不改每个图表定义 也能动态收窄数据范围。
3. 为什么采用 RLS 容易出现报错或「看起来随机失败」
下面几条在嵌入式、同源 iframe、多数据集仪表盘场景下叠加时，问题尤为突出。
3.1 RLS 子句本质是「拼进查询的 SQL 片段」
clause必须是当前数据集生成 SQL 后 在语法、方言、列名上仍合法 的布尔条件。- 列名若与物理表不一致（仅存在于语义层/别名）、或大小写/引号规则与数据库不一致，会在跑数阶段直接 SQL 报错，表现即为 Dashboard 图表加载失败或部分图表红字。
- 多值
IN (...)、逗号分隔字符串、字符串转义（单引号等）任一处理不当，都会变成 非法 SQL。
3.2 Guest RLS 与「按数据集绑定」的规则容易配错
后端只会把 guest token 里 未指定 dataset 或 dataset id 与当前查询数据集一致 的规则应用到该次查询（见 get_guest_rls_filters 一类逻辑）。
若仪表盘上多个图表对应多个数据集，而 token 里只写了一条「全局」子句或 dataset 对不上，会出现 部分图表有过滤、部分没有 ，或 子句引用的列在某个数据集上不存在 从而报错。
3.3 RLS 注入的谓词在生成 SQL 的「多个地方」重复出现
在前期联调里曾对照 **guest_token 里的 RLS** 与 实际下发到数据库的执行 SQL ：同一条由 RLS 拼进来的过滤条件，在 最终语句的多层结构里不止一次出现 （例如内层子查询的 WHERE 与外层又各挂一份相同或相近的谓词，或随图表类型在 CTE / 派生表 / JOIN 展开路径上被多次合并）。
这会带来两类典型现象：
- 语义与预期不一致 ：重复
AND看似等价，但若内层别名、列可见性或IN列表展开方式不一致，可能出现 有的图表正常、有的报错或结果突然变空，从现象上像「随机失败」。 - 排障困难 ：问题不在前端传的单个字符串本身，而在 查询构建器如何把 RLS 并入整条 SQL ；需抓最终 SQL 才能确认，与在数据集里手写一处
WHERE/Jinja 的可读性相差很大。
因此更倾向把筛选 收敛到 URL 参数 + 数据集侧一处明确的 Jinja 条件，避免由后端在多层查询里自动重复注入 RLS。
3.4 与数据集上配置的 RLS 规则叠加
若数据集在 Superset 里还配置了其它 RLS 规则，guest token 的 rls 会与之 同时参与 过滤语义。子句之间是否 AND、是否冲突、是否导致空结果，需要同时理解两套机制，联调成本高。
3.5 安全与维护：前端拼 SQL 子句风险高
即便做了列名白名单、仅允许数字 ID 等约束，本质上仍是在 前端侧维护可注入查询的片段 ；每增一种筛选维度或字段类型，都要重复审计，长期不如在 数据集侧用 Jinja 显式读取 URL 参数 清晰。
4. 最终方案：Jinja + urlParams
4.1 思路
- 不再 依赖 guest_token 的
rls数组做动态筛选（前端统一传**rls: []**）。 - 嵌入时仅通过 SDK 的
**dashboardUiConfig.urlParams** 把业务键值写入 iframe URL（如building_id、department_id、portfolio_view等）。 - 在需要过滤的 数据集 / 图表 中，开启模板处理（
ENABLE_TEMPLATE_PROCESSING），使用 Jinja 读取 URL 参数，例如：url_param('building_id')- 或结合默认值、类型转换、多值拆分等写入
WHERE条件。
这样：
- 过滤逻辑 写在数据集或图表定义里 ，与 SQL 方言、列名、JOIN 结构一致，错误在 Explore/SQL Lab 即可暴露，而不是等到嵌入页才炸。
- 不依赖 guest RLS 与 dataset id 的精细对应，多图表共用一个 url 参数 时语义直观。
- 与「同源 session vs guest」的纠缠更少：只要 URL 上有参数，Jinja 就能读到（在允许模板处理的前提下）。
4.2 配置前提（项目侧已文档化）
FEATURE_FLAGS中启用**ENABLE_TEMPLATE_PROCESSING**（或等价配置），允许在指标/自定义 SQL 等位置使用 Jinja。- 嵌入相关：
EMBEDDED_SUPERSET、guest 角色权限、GUEST_ROLE_NAME等仍按现有部署文档配置；与是否使用 RLS 无冲突。
4.3 前端插件侧（Customize）
- Explore Customize 中配置 多个 URL 键（perspectiveFields / 多选 tags） ，由插件根据左栏选择组装
**urlParams** 传入嵌入 SDK。 - 规则可与 BU 插件对齐：例如 第一个键始终出现在 query 上（可为空字符串） ，其余键 仅在有取值时写入，便于 Jinja 侧区分「未传」与「传空」。
5. 方案对比小结
| 维度 | Guest Token RLS | Jinja + urlParams |
|---|---|---|
| 失败形态 | SQL 片段错误、dataset 不匹配、身份上下文异常、RLS 在生成 SQL 多层结构中重复注入 | 多为模板语法或参数名不一致，易在开发阶段发现 |
| 与多数据集仪表盘 | 需严格对齐 dataset id / 全局子句 | 各数据集各自读 url_param，职责清晰 |
| 维护位置 | 前端拼 SQL + 后端 guest 规则 | 数据集/图表定义，贴近真实 SQL |
| 与同源 Cookie 嵌入 | 易受 guest/session 优先级影响 | 主要依赖 URL，相对独立 |
6. 结论
采用 Guest Token RLS 在嵌入式场景下容易因 SQL 片段合法性、数据集绑定、同源 Session 与 Guest 身份切换、以及 RLS 谓词在最终 SQL 多处被合并 等因素出现 报错或过滤不一致 ；项目最终将动态筛选下沉到 仪表盘侧 Jinja + 嵌入 urlParams ，由前端只负责 传参不传 RLS，链路更简单、可预期，也更利于长期维护。