Metabase 嵌入式分析 SDK：EntityTypeFilterKeys 类型详解与数据选择器实体过滤实践

Metabase 嵌入式分析 SDK：EntityTypeFilterKeys 类型详解与数据选择器实体过滤实践

发布时间：2026/10/11 11:22:41
Metabase 嵌入式分析 SDK：EntityTypeFilterKeys 类型详解与数据选择器实体过滤实践 数据分析数据可视化后端数据库客户端企业应用【免费下载链接】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 嵌入式分析 SDK 中的EntityTypeFilterKeys类型——一个仅包含table | model两个字面量的联合类型。它是控制嵌入式问题Question数据选择器Data Picker中可选数据源类型的核心开关。读完本文你将掌握EntityTypeFilterKeys的定义、它在 SDK 组件与 iframe 嵌入中的实际应用位置以及如何通过entityTypes属性精确限定最终用户只能从「表」或「模型」中选择数据源从而定制更安全的嵌入式分析体验。EntityTypeFilterKeys是 Metabase 嵌入式分析 SDKEmbedding SDK中暴露给宿主应用Host App的类型别名之一其完整定义如下type EntityTypeFilterKeys table | model;这一类型在仓库中的权威定义位于 frontend/src/embedding-sdk-bundle/types/question.ts#L170并被 docs/embedding/sdk/api/snippets/EntityTypeFilterKeys.md 收录为 SDK API 文档的独立类型条目同时生成了对应的 HTML 文档 docs/embedding/sdk/api/EntityTypeFilterKeys.html。一、类型语义为什么是 table 与 modelEntityTypeFilterKeys是一个字符串字面量联合类型String Literal Union Type可接受的值只有两个取值含义数据源形态table物理表数据库中的原生表数据库表直接来自已连接的数据库model模型基于查询封装的数据集由 Question 或 SQL 查询保存生成的虚拟数据集需要特别注意的是EntityTypeFilterKeys并不包含question。在仓库中存在一个与其形态相近但取值范围更宽的类型 EmbeddingEntityTypetype EmbeddingEntityType model | table | question;两者在 SDK 内部各司其职EmbeddingEntityType是内部通用实体类型出现在数据选择器上下文frontend/src/metabase/redux/store/embedding-data-picker.ts、Redux 状态切片frontend/src/metabase/redux/embedding-data-picker.ts以及 iframe 嵌入的dataPickerEntityTypes等场景EntityTypeFilterKeys是面向宿主应用对外暴露的公共 API 类型专门用于QuestionEmbedOptions与ExplorationEmbedOptions中的entityTypes属性作用是把宿主允许的实体范围从「默认宽集合」收窄到「仅表与模型」。从类型设计的角度看对外 API 刻意排除了question作为EntityTypeFilterKeys的合法值这是为了约束嵌入场景中新建问题的数据源选择范围避免最终用户在嵌入环境里把其他 Question 当作数据源从而保持嵌入数据边界的可预测性。二、EntityTypeFilterKeys 在 SDK 组件属性中的应用EntityTypeFilterKeys最核心的使用位置是 iframe 嵌入类型定义文件 frontend/src/metabase/embedding/embedding-iframe-sdk/types/embed.ts它被用于两处entityTypes属性QuestionEmbedOptions嵌入问题组件embed.ts#L130-L153export type QuestionEmbedOptions StrictUnion { questionId: number | string | null } | { token: EntityToken } { componentName: metabase-question; drills?: boolean; withTitle?: boolean; withDownloads?: boolean; withAlerts?: boolean; targetCollection?: CollectionId; entityTypes?: EntityTypeFilterKeys[]; // ← 限定数据源类型 isSaveEnabled?: boolean; // ... };ExplorationEmbedOptions探索式嵌入embed.ts#L166-L178export interface ExplorationEmbedOptions { componentName: metabase-question; template: exploration; isSaveEnabled?: boolean; targetCollection?: CollectionId; entityTypes?: EntityTypeFilterKeys[]; // ← 同上 // ... }而在模块化嵌入 SDKReact SDK一侧虽然SdkQuestionProps的entityTypes属性在文档类型标注中引用的是更宽的EmbeddingEntityType[]见 docs/embedding/sdk/api/snippets/SdkQuestionProps.md#L11但其语义与EntityTypeFilterKeys完全一致——都是「指定数据选择器中可用的实体类型数组」。三、entityTypes的传递链路与数据选择器行为要真正理解EntityTypeFilterKeys的作用需要追踪entityTypes在 SDK 中的完整传递与消费链路。3.1 iframe 嵌入的透传在 iframe 嵌入路由组件 frontend/src/metabase/embedding/embedding-iframe-sdk/components/SdkIframeEmbedRoute.tsx#L344-L359 中嵌入设置中的settings.entityTypes会被直接透传给SdkQuestion组件SdkQuestion questionId{settings.questionId ?? null} token{settings.token} // ... targetCollection{settings.targetCollection} entityTypes{settings.entityTypes} /在构建嵌入属性embed attributes的工具函数 frontend/src/metabase/embedding/embedding-iframe-sdk-setup/utils/build-embed-attributes.ts#L50-L64 中entityTypes仅在非空数组时才被写入嵌入配置entityTypes: questionSettings.entityTypes?.length ? questionSettings.entityTypes : /* 省略时保持默认 */,3.2 数据选择器中的过滤逻辑entityTypes最终在数据选择器组件 frontend/src/metabase/querying/notebook/components/NotebookDataPicker/EmbeddingDataPicker/EmbeddingDataPicker.tsx 中被消费组件同时读取 React Context 与 Redux 中的实体类型EmbeddingDataPicker.tsx#L57-L67两者取其一后作为最终过滤依据当数据源总数小于 100时使用「简单下拉式选择器」simple data picker其中仅允许model与tableEmbeddingDataPicker.tsx#L82-L97并将过滤后的实体类型传给SimpleDataPicker当数据源总数达到 100 及以上或显式设置dataPicker: staged时切换为分阶段数据选择器staged picker通过canSelectModel{entityTypes.includes(model)}、canSelectTable{entityTypes.includes(table)}三个开关分别控制模型、表与 Question 的可选性EmbeddingDataPicker.tsx#L141-L143。需要特别说明entityTypes: [question]只在 staged picker 中生效见 docs/embedding/sdk/api/snippets/EditableDashboardProps.md#L12 与 docs/embedding/sdk/api/EditableDashboardProps.html 中dataPickerProps的说明。由于EntityTypeFilterKeys本身不含question这意味着使用该类型作为entityTypes时无论哪种 picker 形态最终用户的数据源选择范围都被稳定限定在「表」和「模型」两类实体上。3.3 Redux 状态层的默认值与校验兜底在模块化嵌入中entityTypes由 React Context 直接注入而在全应用嵌入full-app embedding中则依赖 Redux 切片 frontend/src/metabase/redux/embedding-data-picker.tsexport const DEFAULT_EMBEDDING_ENTITY_TYPES: EmbeddingEntityType[] [ model, table, ];该切片提供normalizeEntityTypes函数embedding-data-picker.ts#L60-L78其核心作用包括从传入数组中过滤掉不在白名单[model, table, question]中的非法值当过滤后结果为空如传了[]时回退到默认值[model, table]保证选择器不会因空数组而失效。这印证了table | model作为默认与最小可用集合的设计意图即便宿主完全不传entityTypes嵌入环境默认仍向用户开放「表 模型」两类数据源。四、实战用法在嵌入式问题中限定数据源类型4.1 React SDK模块化嵌入示例在InteractiveQuestion/CreateQuestion等组件中通过entityTypes属性控制数据选择器import { InteractiveQuestion } from metabase/embedding-sdk-react; export default function TablesOnlyQuestion() { return ( InteractiveQuestion questionId{42} entityTypes{[table]} // 仅允许选择物理表 dataPickerstaged // 强制使用分阶段数据选择器 / ); }若只想开放模型InteractiveQuestion questionId{42} entityTypes{[model]} /4.2 可编辑仪表盘中的dataPickerProps在EditableDashboard中新建问题时的数据选择器行为通过dataPickerProps透传。仓库内置的示例 docs/embedding/sdk/snippets/dashboards/editable-dashboard-data-picker.tsx 展示了「仅表」的配置import React from react; import { EditableDashboard } from metabase/embedding-sdk-react; export default function TablesOnlyDashboard() { const dashboardId 1; // This is the dashboard ID you want to embed return ( EditableDashboard dashboardId{dashboardId} dataPickerProps{{ entityTypes: [table] }} / ); }4.3 iframe 嵌入静态 JS SDK示例在 iframe 嵌入场景中entityTypes作为QuestionEmbedOptions的属性传入metabase-question question-id42 entity-types[model, table] is-save-enabledtrue /metabase-question对应地SDK 在初始化时会把该属性写入嵌入设置见 frontend/src/metabase/embedding/embedding-iframe-sdk/constants.ts 中entityTypes被列入可用的嵌入属性键随后经SdkIframeEmbedRoute透传给SdkQuestion组件。五、常见配置组合与注意事项场景entityTypes取值效果开放全部原生数据源[table]用户仅能从物理表开始分析仅开放模型[model]用户只能以受管模型作为数据源适合「先建模型再分发」的治理式嵌入表 模型默认行为[model, table]或省略不传对应DEFAULT_EMBEDDING_ENTITY_TYPES的默认值非法值或空数组如[question]之外的无效字面量、[]被normalizeEntityTypes过滤空结果回退为[model, table]实践建议安全优先若嵌入场景面向外部客户且不希望其接触到原始表结构建议设置entityTypes: [model]配合数据权限Data Permissions实现「只见模型、不见底表」的隔离区分 picker 形态question类型仅在 staged picker 下生效而EntityTypeFilterKeys不含该值因此使用本类型时无需关心这一差异与dataPicker属性配合数据源数量较多≥ 100时 SDK 会自动切换到 staged picker如需统一体验可显式设置dataPickerstaged类型约束由编译期保证EntityTypeFilterKeys是字面量联合类型在 TypeScript 中传入其他字符串会直接产生编译错误这比运行时校验更早地拦截错误配置。六、相关类型与文档索引围绕EntityTypeFilterKeys可在以下仓库路径继续深入类型定义frontend/src/embedding-sdk-bundle/types/question.ts#L170iframe 嵌入选项frontend/src/metabase/embedding/embedding-iframe-sdk/types/embed.ts数据选择器实现frontend/src/metabase/querying/notebook/components/NotebookDataPicker/EmbeddingDataPicker/EmbeddingDataPicker.tsx默认值与校验frontend/src/metabase/redux/embedding-data-picker.tsSDK API 文档入口docs/embedding/sdk/api/index.html相关类型EmbeddingEntityTypedocs/embedding/sdk/api/snippets/EmbeddingEntityType.md、SdkQuestionPropsdocs/embedding/sdk/api/snippets/SdkQuestionProps.md小结EntityTypeFilterKeys虽只有一行定义却是 Metabase 嵌入式分析数据源边界控制的关键类型。通过entityTypes属性宿主应用可以在不修改任何服务端配置的前提下将嵌入环境中的可分析数据源精确限定为「物理表」与「模型」实现从界面层面对数据范围的第一道约束。赞分享数据分析数据可视化后端数据库客户端企业应用【免费下载链接】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点击查看免费下载相关推荐NutUI DatePicker 日期选择器全解析类型模式、格式化、过滤与源码实现NutUI DatePicker 日期选择器全解析类型模式、格式化、过滤与源码实现 本指南以 NutUI 移动端组件库京东风格 Vue 组件库中的 Dat前端UI组件OneUptime API 查询过滤器 LessThan 数据类型详解JSON 格式、值类型与序列化实现OneUptime API 查询过滤器 LessThan 数据类型详解JSON 格式、值类型与序列化实现 OneUptime 是一套完整的开源监控与可观测性平可观测性后端运维前端云原生微服务AI AgentMetabase 嵌入 SDK 全局插件配置MetabaseGlobalPluginsConfig 类型详解与实战Metabase 嵌入 SDK 全局插件配置MetabaseGlobalPluginsConfig 类型详解与实战 导读 MetabaseGlobalPlug数据分析数据可视化后端数据库客户端企业应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考