Metabase 嵌入 SDK 的 SqlParameterValues 类型受控 SQL 参数值的完整解析【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase导读本文围绕 Metabase 嵌入 SDKEmbedding SDK中SqlParameterValues类型展开深入讲解如何在InteractiveQuestion组件中通过受控方式驱动原生 SQL 问题的参数值从类型定义的每个成员、值的语义null清除、数组多选到onSqlParametersChange回调的三种变更来源并结合仓库源码剖析其底层实现机制。读完本文你将能够在自己的 React 宿主应用中安全、类型完备地实现 SQL 参数的外部状态控制并理解 Metabase 如何处理受控值推送与应用值回传之间的双向同步。一、SqlParameterValues类型定义该类型在 SDK 公共 API 中以 TypeScript 类型别名形式公开定义如下type SqlParameterValues Record string, | string | number | boolean | (string | number | boolean | null)[] | null | undefined ;它在仓库中的实际定义位于 frontend/src/embedding-sdk-bundle/types/question.ts#L172-L180同时 SDK 公共入口enterprise/frontend/src/embedding-sdk-package/index.ts会将其随包导出供宿主应用通过import { type SqlParameterValues } from metabase/embedding-sdk-react使用。结构解读SqlParameterValues本质是一个以参数 slugslug为键、以多种合法取值为值的对象映射组成含义键stringSQL 问题的参数名slug即 SQL 模板变量template tag对应的名称如state、product_id值string/number/boolean单值参数如文本筛选、数字 ID、布尔开关值(string \| number \| boolean \| null)[]多值参数例如等于多个值的string/筛选可传入数组值null显式清除该参数——忽略参数默认值与上次使用的值等价于严格清空值undefined键存在但值为undefined与缺失该键的宽松语义类似需要特别注意的是键是 slug 而不是参数的 ID。例如一个 SQL 问题包含模板标签{{state}}则SqlParameterValues的键为state。这与受控参数值在内部参数 ID 键与外部slug 键之间的转换机制有关见下文源码机制一节。二、适用场景SQL 问题的受控参数SqlParameterValues只服务于原生 SQL 问题native/SQL question。SDK 的类型注释明确说明它用于SQL 参数名到参数值的映射例如{ product_id: 42 }。这一点在 frontend/src/embedding-sdk-bundle/types/question.ts#L121-L126 的LoadSdkQuestionParams中同样有印证——initialSqlParameters?: SqlParameterValues字段专门标注为For SQL questions only。在实际组件中SqlParameterValues主要出现在InteractiveQuestion的以下两个属性上受控模式sqlParameters: SqlParameterValues—— 宿主应用控制的 SQL 参数值onSqlParametersChange: (payload: SqlParameterChangePayload) void—— 每次参数值变化时向宿主回调用于反向同步本地状态。仓库给出的受控示例位于 docs/embedding/snippets/parameters/questions/controlled-sql-parameters.tsx是官方推荐的接入方式。三、受控 SQL 参数实战完整示例以下代码展示了如何在宿主应用中接管 SQL 参数的完整状态流源码见 docs/embedding/snippets/parameters/questions/controlled-sql-parameters.tsximport { InteractiveQuestion, type SqlParameterChangePayload, type SqlParameterValues, } from metabase/embedding-sdk-react; import { useState } from react; const questionId 1; const ExampleControlled () { const [sqlParameters, setSqlParameters] useStateSqlParameterValues({ state: NY, }); const handleSqlParametersChange (payload: SqlParameterChangePayload) { // 在每次已应用的变更后同步本地状态。 // payload.source 取值为 // initial-state —— 问题加载完成后的初始快照每个问题每次加载只触发一次 // manual-change —— 用户在参数控件中手动编辑 // auto-change —— 你推送的值被规范化后回传请用 payload.parameters 重新同步 setSqlParameters(payload.parameters); }; return ( InteractiveQuestion questionId{questionId} sqlParameters{sqlParameters} onSqlParametersChange{handleSqlParametersChange} / ); };这一模式的关键是单向数据流 回传闭环宿主持有sqlParameters状态SDK 负责把状态应用到 SQL 查询再通过onSqlParametersChange把真正被应用的值回传给宿主宿主据此更新本地状态。这样即便 SDK 内部对值做了规范化处理例如把NY归一为数组[NY]宿主状态也能与查询实际使用的值保持一致避免状态漂移。用null清除参数受控模式的另一个实用特性是把某个参数设置为null即可清除它且会忽略该参数的默认值。官方示例controlled-sql-parameters.tsx中的ExampleClear演示了这一点// 将 SQL 参数设置为 null 会清除它忽略参数的默认值。 InteractiveQuestion questionId{questionId} sqlParameters{{ state: null }} /这意味着宿主可以在使用默认值与严格无值之间显式区分——undefined/缺省键走默认值回退而null表示彻底清除。四、onSqlParametersChange回调的三种变更来源回调的载荷类型SqlParameterChangePayload定义于 frontend/src/embedding-sdk-bundle/types/question.ts#L195-L204type SqlParameterChangePayload { source: SqlParameterChangeSource; parameters: ParameterValues; // 当前已应用的值按 slug 键 defaultParameters: ParameterValues; // 各参数定义的默认值按 slug 键 };其中source是一个三值联合类型同文件 L190-L193准确描述这次变更的来源source 取值触发时机处理建议initial-state问题加载后第一次应用的状态快照每个问题每次加载只触发一次用它初始化宿主本地状态保证宿主与 SDK 首次渲染一致manual-change用户在嵌入页面的参数控件中手动编辑正常同步到本地状态auto-change宿主推送的值在路由过程中被规范化例如值形态与控件期望不符SDK 把归一化后的值回传务必用payload.parameters覆盖本地状态否则下一次推送会继续使用未经规范化的旧值形成循环偏差payload.parameters与payload.defaultParameters均以 slug 为键构建逻辑位于 frontend/src/embedding-sdk-bundle/lib/controlled-parameters.ts#L61-L96 的buildParametersPayloadparameters来自当前已应用值defaultParameters来自参数定义中的默认值填充结果供宿主做重置为默认之类的 UI 操作。五、源码机制受控值如何从宿主流向查询理解SqlParameterValues的完整生命周期需要看驱动它的 Hook use-sdk-controlled-sql-parameters.ts。它把受控逻辑拆成推与察两条链路1. 推送链路宿主 → 查询状态usePushControlledSqlParameters监听sqlParametersprop 的变化在满足条件时把值转换为内部以参数 ID 为键的ParameterValuesMap并派发调用updateParameterValues。转换由buildControlledParameters完成controlled-parameters.ts#L32-L39核心步骤是先经mapExplicitNullToEmpty把显式null翻译为空字符串见 controlled-parameters.ts#L15-L25——这是为了让 URL 查询串解析器把该值视为严格清除忽略默认值再通过getParameterValuesByIdFromQueryParams依据参数定义把 slug 键映射为参数 ID 键缺失的 slug 回退到parameter.default ?? null。推送时还有两层防抖优化值本身为null/undefined时重置内部记录并跳过若上一次派发的引用相同、或参数定义尚未就绪parameterDefinitions.length 0、或转换结果与已应用值isEqual使用 underscore 的深比较则跳过冗余派发。2. 观察链路应用状态 → 宿主回调useObserveAppliedSqlParameters监听内部应用值的变化通过两个 ref 区分事件类型emittedQuestionIdRef记录最近一次已上报回调的问题 ID当问题 ID 变化时判定为initial-state加载事件lastSqlParametersPushRef记录最近一次由宿主推送产生的值观察器通过比对本次已应用值与宿主推送值是否一致来区分auto-change推送被规范化、载荷与推送值不同与manual-change其余一切用户编辑。也就是说auto-change的本质是宿主推送给sqlParameters的值与实际查询应用的值不一致SDK 主动把归一化后的事实回传给宿主纠偏。3. 非受控初始值initialSqlParameters如果宿主不需要全程受控也可以在LoadSdkQuestionParams中使用initialSqlParameters?: SqlParameterValuesquestion.ts#L121-L126提供一次性初始值。该路径同样经过mapExplicitNullToEmpty保证null语义在受控与非受控两种模式下完全一致见 controlled-parameters.ts#L48-L52 的getEffectiveParameterValues受控值优先未设置时回退到初始值。六、类型安全与边界实践多值参数传数组对于string/等支持多选的参数类型直接传入数组即可例如{ source: [affiliate, organic] }。数组元素允许null配合清除语义使用。slug 拼写必须与模板标签一致键是 SQL 模板变量名slug。拼写错误不会得到编译期报错Recordstring, ...键为开放字符串只会导致该 slug 在内部映射时回退到默认值或null需要留意。值规范化是常态Metabase 的 SQL 参数控件可能把标量归一为单元素数组、或把NY规范为查询实际使用的形态因此建议始终用onSqlParametersChange的payload.parameters作为本地状态的唯一事实来源。null与undefined语义不同null 显式清除忽略默认值undefined/缺键 走默认值回退。七、仓库中的验证证据仓库提供了针对该受控机制的端到端组件测试e2e/test-component/scenarios/embedding-sdk/sdk-question-controlled-parameters.cy.spec.tsx。测试基于 Sample Database 构造了带state、city、source三个维度模板标签的原生 SQL 问题并验证受控参数在InteractiveQuestion中推送到查询、以及变更回调事件的正确触发。此外use-sdk-controlled-sql-parameters.unit.spec.tsx 提供了单元级验证覆盖 push/observe 两条链路与三种source的判定逻辑。结语SqlParameterValues虽只是一个类型别名但它定义了 Metabase 嵌入 SDK 与宿主应用之间交换 SQL 参数值的公共契约slug 为键、标量/数组/null/undefined为值的灵活取值空间配合onSqlParametersChange的initial-state、manual-change、auto-change三态事件构成了完整、可预测的受控数据流。理解这一契约你就能在自己的应用中实现可靠的 SQL 参数外部控制——无论是简单的单选筛选还是需要严格区分默认值与清除的复杂查询面板。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Metabase 嵌入 SDK 的 SqlParameterValues 类型：受控 SQL 参数值的完整解析
Metabase 嵌入 SDK 的 SqlParameterValues 类型受控 SQL 参数值的完整解析【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase导读本文围绕 Metabase 嵌入 SDKEmbedding SDK中SqlParameterValues类型展开深入讲解如何在InteractiveQuestion组件中通过受控方式驱动原生 SQL 问题的参数值从类型定义的每个成员、值的语义null清除、数组多选到onSqlParametersChange回调的三种变更来源并结合仓库源码剖析其底层实现机制。读完本文你将能够在自己的 React 宿主应用中安全、类型完备地实现 SQL 参数的外部状态控制并理解 Metabase 如何处理受控值推送与应用值回传之间的双向同步。一、SqlParameterValues类型定义该类型在 SDK 公共 API 中以 TypeScript 类型别名形式公开定义如下type SqlParameterValues Record string, | string | number | boolean | (string | number | boolean | null)[] | null | undefined ;它在仓库中的实际定义位于 frontend/src/embedding-sdk-bundle/types/question.ts#L172-L180同时 SDK 公共入口enterprise/frontend/src/embedding-sdk-package/index.ts会将其随包导出供宿主应用通过import { type SqlParameterValues } from metabase/embedding-sdk-react使用。结构解读SqlParameterValues本质是一个以参数 slugslug为键、以多种合法取值为值的对象映射组成含义键stringSQL 问题的参数名slug即 SQL 模板变量template tag对应的名称如state、product_id值string/number/boolean单值参数如文本筛选、数字 ID、布尔开关值(string \| number \| boolean \| null)[]多值参数例如等于多个值的string/筛选可传入数组值null显式清除该参数——忽略参数默认值与上次使用的值等价于严格清空值undefined键存在但值为undefined与缺失该键的宽松语义类似需要特别注意的是键是 slug 而不是参数的 ID。例如一个 SQL 问题包含模板标签{{state}}则SqlParameterValues的键为state。这与受控参数值在内部参数 ID 键与外部slug 键之间的转换机制有关见下文源码机制一节。二、适用场景SQL 问题的受控参数SqlParameterValues只服务于原生 SQL 问题native/SQL question。SDK 的类型注释明确说明它用于SQL 参数名到参数值的映射例如{ product_id: 42 }。这一点在 frontend/src/embedding-sdk-bundle/types/question.ts#L121-L126 的LoadSdkQuestionParams中同样有印证——initialSqlParameters?: SqlParameterValues字段专门标注为For SQL questions only。在实际组件中SqlParameterValues主要出现在InteractiveQuestion的以下两个属性上受控模式sqlParameters: SqlParameterValues—— 宿主应用控制的 SQL 参数值onSqlParametersChange: (payload: SqlParameterChangePayload) void—— 每次参数值变化时向宿主回调用于反向同步本地状态。仓库给出的受控示例位于 docs/embedding/snippets/parameters/questions/controlled-sql-parameters.tsx是官方推荐的接入方式。三、受控 SQL 参数实战完整示例以下代码展示了如何在宿主应用中接管 SQL 参数的完整状态流源码见 docs/embedding/snippets/parameters/questions/controlled-sql-parameters.tsximport { InteractiveQuestion, type SqlParameterChangePayload, type SqlParameterValues, } from metabase/embedding-sdk-react; import { useState } from react; const questionId 1; const ExampleControlled () { const [sqlParameters, setSqlParameters] useStateSqlParameterValues({ state: NY, }); const handleSqlParametersChange (payload: SqlParameterChangePayload) { // 在每次已应用的变更后同步本地状态。 // payload.source 取值为 // initial-state —— 问题加载完成后的初始快照每个问题每次加载只触发一次 // manual-change —— 用户在参数控件中手动编辑 // auto-change —— 你推送的值被规范化后回传请用 payload.parameters 重新同步 setSqlParameters(payload.parameters); }; return ( InteractiveQuestion questionId{questionId} sqlParameters{sqlParameters} onSqlParametersChange{handleSqlParametersChange} / ); };这一模式的关键是单向数据流 回传闭环宿主持有sqlParameters状态SDK 负责把状态应用到 SQL 查询再通过onSqlParametersChange把真正被应用的值回传给宿主宿主据此更新本地状态。这样即便 SDK 内部对值做了规范化处理例如把NY归一为数组[NY]宿主状态也能与查询实际使用的值保持一致避免状态漂移。用null清除参数受控模式的另一个实用特性是把某个参数设置为null即可清除它且会忽略该参数的默认值。官方示例controlled-sql-parameters.tsx中的ExampleClear演示了这一点// 将 SQL 参数设置为 null 会清除它忽略参数的默认值。 InteractiveQuestion questionId{questionId} sqlParameters{{ state: null }} /这意味着宿主可以在使用默认值与严格无值之间显式区分——undefined/缺省键走默认值回退而null表示彻底清除。四、onSqlParametersChange回调的三种变更来源回调的载荷类型SqlParameterChangePayload定义于 frontend/src/embedding-sdk-bundle/types/question.ts#L195-L204type SqlParameterChangePayload { source: SqlParameterChangeSource; parameters: ParameterValues; // 当前已应用的值按 slug 键 defaultParameters: ParameterValues; // 各参数定义的默认值按 slug 键 };其中source是一个三值联合类型同文件 L190-L193准确描述这次变更的来源source 取值触发时机处理建议initial-state问题加载后第一次应用的状态快照每个问题每次加载只触发一次用它初始化宿主本地状态保证宿主与 SDK 首次渲染一致manual-change用户在嵌入页面的参数控件中手动编辑正常同步到本地状态auto-change宿主推送的值在路由过程中被规范化例如值形态与控件期望不符SDK 把归一化后的值回传务必用payload.parameters覆盖本地状态否则下一次推送会继续使用未经规范化的旧值形成循环偏差payload.parameters与payload.defaultParameters均以 slug 为键构建逻辑位于 frontend/src/embedding-sdk-bundle/lib/controlled-parameters.ts#L61-L96 的buildParametersPayloadparameters来自当前已应用值defaultParameters来自参数定义中的默认值填充结果供宿主做重置为默认之类的 UI 操作。五、源码机制受控值如何从宿主流向查询理解SqlParameterValues的完整生命周期需要看驱动它的 Hook use-sdk-controlled-sql-parameters.ts。它把受控逻辑拆成推与察两条链路1. 推送链路宿主 → 查询状态usePushControlledSqlParameters监听sqlParametersprop 的变化在满足条件时把值转换为内部以参数 ID 为键的ParameterValuesMap并派发调用updateParameterValues。转换由buildControlledParameters完成controlled-parameters.ts#L32-L39核心步骤是先经mapExplicitNullToEmpty把显式null翻译为空字符串见 controlled-parameters.ts#L15-L25——这是为了让 URL 查询串解析器把该值视为严格清除忽略默认值再通过getParameterValuesByIdFromQueryParams依据参数定义把 slug 键映射为参数 ID 键缺失的 slug 回退到parameter.default ?? null。推送时还有两层防抖优化值本身为null/undefined时重置内部记录并跳过若上一次派发的引用相同、或参数定义尚未就绪parameterDefinitions.length 0、或转换结果与已应用值isEqual使用 underscore 的深比较则跳过冗余派发。2. 观察链路应用状态 → 宿主回调useObserveAppliedSqlParameters监听内部应用值的变化通过两个 ref 区分事件类型emittedQuestionIdRef记录最近一次已上报回调的问题 ID当问题 ID 变化时判定为initial-state加载事件lastSqlParametersPushRef记录最近一次由宿主推送产生的值观察器通过比对本次已应用值与宿主推送值是否一致来区分auto-change推送被规范化、载荷与推送值不同与manual-change其余一切用户编辑。也就是说auto-change的本质是宿主推送给sqlParameters的值与实际查询应用的值不一致SDK 主动把归一化后的事实回传给宿主纠偏。3. 非受控初始值initialSqlParameters如果宿主不需要全程受控也可以在LoadSdkQuestionParams中使用initialSqlParameters?: SqlParameterValuesquestion.ts#L121-L126提供一次性初始值。该路径同样经过mapExplicitNullToEmpty保证null语义在受控与非受控两种模式下完全一致见 controlled-parameters.ts#L48-L52 的getEffectiveParameterValues受控值优先未设置时回退到初始值。六、类型安全与边界实践多值参数传数组对于string/等支持多选的参数类型直接传入数组即可例如{ source: [affiliate, organic] }。数组元素允许null配合清除语义使用。slug 拼写必须与模板标签一致键是 SQL 模板变量名slug。拼写错误不会得到编译期报错Recordstring, ...键为开放字符串只会导致该 slug 在内部映射时回退到默认值或null需要留意。值规范化是常态Metabase 的 SQL 参数控件可能把标量归一为单元素数组、或把NY规范为查询实际使用的形态因此建议始终用onSqlParametersChange的payload.parameters作为本地状态的唯一事实来源。null与undefined语义不同null 显式清除忽略默认值undefined/缺键 走默认值回退。七、仓库中的验证证据仓库提供了针对该受控机制的端到端组件测试e2e/test-component/scenarios/embedding-sdk/sdk-question-controlled-parameters.cy.spec.tsx。测试基于 Sample Database 构造了带state、city、source三个维度模板标签的原生 SQL 问题并验证受控参数在InteractiveQuestion中推送到查询、以及变更回调事件的正确触发。此外use-sdk-controlled-sql-parameters.unit.spec.tsx 提供了单元级验证覆盖 push/observe 两条链路与三种source的判定逻辑。结语SqlParameterValues虽只是一个类型别名但它定义了 Metabase 嵌入 SDK 与宿主应用之间交换 SQL 参数值的公共契约slug 为键、标量/数组/null/undefined为值的灵活取值空间配合onSqlParametersChange的initial-state、manual-change、auto-change三态事件构成了完整、可预测的受控数据流。理解这一契约你就能在自己的应用中实现可靠的 SQL 参数外部控制——无论是简单的单选筛选还是需要严格区分默认值与清除的复杂查询面板。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
