DataHub Mode 数据源接入指南从 BI 报告到表级血缘的元数据采集实战【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubMode 是面向数据分析团队的商业智能BI与分析平台。在 DataHub 生态中mode数据源连接器负责将 Mode 中的报告Report、图表Chart、数据集Dataset等 BI 资产连同所有者信息、表级与列级血缘以及基于状态的有状态删除检测统一采集进 DataHub 目录。阅读本文后你将掌握 Mode 连接器的概念映射、前置权限准备、完整配置项语义、典型 Recipe 写法以及其底层基于 Mode REST API 与 SQL 解析引擎的实现原理能够独立完成一套可复用的 Mode → DataHub 元数据同步方案。OverviewDataHub 的 Mode 集成能做什么Mode 是一个商业智能与分析平台其官方能力可参考 Mode 官方文档。DataHub 对 Mode 的集成主要覆盖以下 BI 实体与元数据类型Dashboards仪表盘对应 Mode 中的 Report包含标题、描述、图表关联、浏览路径、使用统计与可选的嵌入地址embed URLCharts图表对应 Mode 中挂在 Query 下的可视化包含图表类型、标题、自定义属性X/Y 轴、度量、筛选条件等Datasets数据集既包括 Mode 中独立的 Dataset也包括 Report 内的 Query二者在 DataHub 中以 Dataset 实体承载所有权上下文将报告/图表的创建者Creator映射为 DataHub 的 CorpUser 所有者表级与列级血缘解析 Query 的 SQL提取上游表与字段依赖生成粗粒度table-level与细粒度column-level血缘有状态删除检测基于 DataHub 有状态摄入框架自动识别 Mode 侧已删除的实体并清理。从连接器注册表connector_registry/datahub.json可以看到mode连接器的类名为datahub.ingestion.source.mode.ModeSource支持状态为GA正式发布默认启用容器CONTAINERS、描述DESCRIPTIONS、平台实例PLATFORM_INSTANCE、所有权OWNERSHIP能力并默认支持粗粒度与细粒度血缘。概念映射Concept Mapping原文档指出Mode 具体的概念映射细节仍有待完善但 DataHub 有通用的概念映射关系可作参考。下表即这一通用映射源概念Source ConceptDataHub 概念说明Platform / account / project scopePlatform Instance, Container在平台上下文中组织资产。Mode 集成中对应 Workspace 与 SpaceCollection。Core technical asset例如 table / view / topic / fileDataset主要摄入的技术资产。Mode 集成中对应 Query 与 Mode Dataset。Schema fields / columnsSchemaField在支持 schema 提取时纳入。Mode 集成通过 SQL 输出列推断生成。Ownership and collaboration principalsCorpUser, CorpGroup由支持所有权与身份元数据的模块发出。Dependencies and processing relationshipsLineage edges在支持血缘提取并启用时可用。结合源码可以给出更具体的映射落地方式实现见 mode.pyWorkspace作为浏览路径的根/mode/{workspace}/...并在_browse_path_space中生成首级 BrowsePathEntrySpaceCollection映射为 DataHub 容器Container。源码中的SpaceKey容器键携带space_token通过construct_space_container生成容器并打上MODE_COLLECTION子类型BIContainerSubTypes.MODE_COLLECTIONReport映射为 Dashboard子类型MODE_REPORTQuery / Mode Dataset均映射为 Dataset子类型分别为MODE_QUERY与MODE_DATASETChart映射为 Chart子类型MODE_CHART创作者映射为urn:li:corpuser:{username}默认取 username而非 email。前置条件认证与权限认证AuthenticationMode 连接器使用Basic Auth进行认证需要一组工作区 API Keytoken创建 Workspace API Key 时的Key IDpassword创建 Workspace API Key 时的Secret。从源码看认证通过requests.Session的HTTPBasicAuth(self.config.token, self.config.password.get_secret_value())完成同时请求头固定为Content-Type: application/json与Accept: application/haljsonMode API 返回 HALJSON 格式。初始化时连接器会先请求{connect_uri}/api/verify验证连通性与凭据失败则直接终止并上报Failed to Connect错误。需要特别注意Mode 仅支持用户账户认证不支持服务账户。官方建议为 DataHub 摄入专门创建一个专用用户避免影响其他成员的日常使用。权限PermissionsMode 集成要求摄入用户具备以下最小权限详见 mode_pre.md至少拥有Member角色对每个Connection至少拥有View访问权可在 Workspace Settings → Manage Connections 中检查点击连接 → Permissions若默认工作区访问是 View 或 Query 即可若为 Restricted需要单独给摄入用户授予 View 权限对每个SpaceCollection至少拥有View访问权以管理员身份进入 My Collections 页面对 Workspace Access 为 Restricted 的集合需在 Manage Access 对话框中手动授予摄入用户 Viewer 权限All Members can View/Edit 的集合无需手动授权。注意若摄入用户拥有Admin权限则会自动获得所有连接与集合的 View 权限。如果摄入失败请优先按上述顺序排查凭据、权限、连通性与范围过滤配置再结合日志中的 source 级错误信息调整。配置项详解ModeConfig 全参数参考Mode 连接器的配置模型为ModeConfig见 mode.py继承自有状态摄入配置与数据源血缘公共配置。下表整理了完整参数、默认值与语义参数类型默认值说明connect_uristrhttps://app.mode.comMode 主机地址结尾多余斜杠会被自动去除。tokenstr必填Workspace API Key 的 Key ID用于 Basic Auth。passwordSecretStr必填Workspace API Key 的 Secret。workspacestr必填Mode 工作区用户名URL 中https://app.mode.com/organizations/workspace-username部分与显示名不同必须全小写。exclude_restrictedboolFalse是否排除 restricted受限的集合。源码同时检查restricted字段与default_access_level restricted因 Mode 侧restricted字段存在已知 bug。exclude_personal_collectionsboolTrue是否通过 Mode 服务端过滤器?filtercustom排除个人集合。为True时仅拉取共享/自定义集合为False时拉取全部集合space_pattern仍会做客户端过滤。space_patternAllowDenyPatterndeny: [^Personal$]按空间/集合名称做正则过滤默认排除名为 Personal 的集合。例如只想摄入名为 analytics 的空间可用allow: [analytics]。report_patternAllowDenyPattern全部允许按报告名称过滤例如deny: [slow_report]可排除名为 slow_report 的报告。owner_username_instead_of_emailboolTrue生成所有者 URN 时使用 username 而非 email。ingest_embed_urlboolTrue是否为报告生成嵌入地址embed URLaspect。tag_measures_and_dimensionsboolTrue是否为 schema 中的度量measures与维度dimensions字段打标签。exclude_archivedboolFalse是否排除已归档archived的报告。max_threadsint1并行 API 请求的最大线程数1–50。增大可加速大工作区的摄入但设置过高可能触发 Mode API 限流429。api_options.retry_backoff_multiplierint/float2指数退避重试的乘数。api_options.max_retry_intervalint/float60重试等待的最大间隔秒。api_options.max_attemptsint10失败前最大重试次数。api_options.timeoutint40单次请求等待 Mode REST API 返回数据的超时时间秒。api_options.requests_per_minuteint180所有线程合计的每分钟最大 API 请求数。Mode API 限制约 240 req/min4 req/s默认 180 留出余量避免 429。items_per_pageint30分页请求的每页条数1–1000属隐藏配置项。stateful_ingestionStatefulStaleMetadataRemovalConfigNone有状态摄入与陈旧实体清理配置。注意原文档配套示例中出现的default_schema参数已被移除pydantic_removed_field标注2025 年 1 月后不再生效新配置中无需再填写。API 选项的底层实现api_options的实现要点源码 mode.py 与_get_request_json请求通过tenacity.Retrying包装对HTTP 429、HTTP 504 与连接错误按wait_exponential(multiplier, max)指数退避、最多max_attempts次重试429 时会读取响应头retry-after并休眠等待504 时短睡 0.1 秒后重试所有请求经过RateLimiter每 60 秒窗口最多requests_per_minute次限流会话级HTTPAdapter还配置了 3 次重试与 10 倍退避因子连接池大小随max_threads扩容。快速开始Recipe 配置示例官方示例配置见 mode_recipe.yml完整形态如下可在其基础上补充sink与可选参数source: type: mode config: # 坐标 connect_uri: https://app.mode.com # 凭据Workspace API Key token: token password: pass # 选项 workspace: datahub owner_username_instead_of_email: false api_options: retry_backoff_multiplier: 2 max_retry_interval: 10 max_attempts: 5 sink: # sink 配置例如 file 或 datahub-rest type: file config: filename: mode_mces.json一个更贴近生产、包含过滤与并行加速的示例source: type: mode config: connect_uri: https://app.mode.com token: ${MODE_API_TOKEN} password: ${MODE_API_SECRET} workspace: datahub exclude_personal_collections: true space_pattern: allow: - analytics - marketing deny: - ^Personal$ report_pattern: deny: - slow_report exclude_archived: true ingest_embed_url: true tag_measures_and_dimensions: true max_threads: 8 api_options: retry_backoff_multiplier: 2 max_retry_interval: 60 max_attempts: 10 timeout: 40 requests_per_minute: 180 stateful_ingestion: enabled: true remove_stale_metadata: true仓库中还提供了mode连接器的 DHUB 示例examples/recipes/mode_to_datahub.dhub.yaml可对照参考。使用datahub ingest子命令加载该 Recipe 即可运行摄入datahub ingest -c mode_recipe.yml摄入完成后可通过datahubCLI 或 DataHub UI 校验生成的 MCE/MCP 结果。工作原理从 REST API 到 DataHub 实体Mode 连接器基于Mode API v3实现类注释见 mode.py核心工作流分三个阶段先拉取空间并生成容器再处理报告Report及其查询与图表最后处理独立数据集。涉及的 Mode API 端点用途端点连接验证{connect_uri}/api/verify空间/集合列表{workspace_uri}/spaces?filtercustom\|all报告列表分页{workspace_uri}/spaces/{space_token}/reports?filterallper_pageNpageN数据集列表分页{workspace_uri}/spaces/{space_token}/datasets?filterallper_pageNpageN报告查询列表{workspace_uri}/reports/{report_token}/queries查询图表列表{workspace_uri}/reports/{report_token}/queries/{query_token}/charts数据源Connection列表{workspace_uri}/data_sources定义Definitions列表{workspace_uri}/definitions其中{workspace_uri}即{connect_uri}/api/{workspace}。源码注释指出查询与图表两个端点不支持分页直接整体拉取空间、报告、数据集则通过_get_paged_request_json按items_per_page分页遍历。实体构建流程容器construct_space_container为每个 Space 生成MODE_COLLECTION容器并写入以工作区为根的 BrowsePathsV2报告 → Dashboardconstruct_dashboard使用报告的名称、描述、创建/修改时间戳created_at/last_saved_at后者为空时回退edited_at、图表 URN 列表与引用数据集构建DashboardInfoClass同时生成浏览路径、MODE_REPORT子类型、所有权DATAOWNER、使用统计view_count与可选的 embed 链接查询/数据集 → Datasetconstruct_query_or_dataset生成DatasetPropertiesClass外部 URL、自定义属性如id、created_at、data_source_id、chart_count等、ViewPropertiesClass原始 SQL 视图逻辑、SubTypesClass与 BrowsePathsV2并解析 SQL 产出 Schema 元数据与血缘图表 → Chartconstruct_chart_from_api_data根据 Mode 图表的chartType/selectedChart映射 DataHub 图表类型见_get_chart_type映射表并抽取encoding中的 X/Y/度量/筛选公式写入自定义属性同时生成ChartQueryClass原始 SQL、InputFields字段级输入关系与所有权。图表类型映射表_get_chart_type值得一提Mode 的table/pivotTable/vegasPivotTable→ DataHubTABLEbar/stackedBar/stackedBar100/hStackedBar/hStackedBar100/hBar→BARline→LINEarea/totalArea→AREApie/donut→PIEscatter→SCATTERbigNumber/bigValue→TEXThistogram→HISTOGRAM未识别的类型置为None并在报告中记录 warning。SQL 血缘提取三层预处理表级与列级血缘是 Mode 集成的核心能力其提取链路在construct_query_or_dataset与get_upstream_lineage_for_parsed_sql中实现包含三层 SQL 预处理定义展开DefinitionsMode 查询中常使用{{ definition as alias }}语法引用公共定义。_replace_definitions会从/definitions端点拉取定义源递归替换最大深度 10检测循环引用还原成完整 SQL表单模板渲染LiquidMode 查询支持{% form %}...{% endform %}块与 Liquid 模板变量。normalize_mode_query解析表单参数的默认值并渲染模板若渲染失败则退回去掉表单块后的 SQL保证后续解析不因模板语法报错SQL 解析sqlglot使用sqlglot_lineage对多语句 SQL 取最后一个有效语句进行解析结合从 DataHub Graph 缓存构建的 schema resolver产出SqlParsingResult。随后infer_output_schema推断查询输出列生成SchemaMetadataClass并生成粗粒度UpstreamLineageClass类型TRANSFORMED与细粒度FineGrainedLineageClassFIELD → FIELD_SET血缘。此外还有两处平台相关的特殊处理JDBC 适配器映射_get_datahub_friendly_platform将 Mode 数据源Connection的 JDBC 前缀映射为 DataHub 平台名例如jdbc:athena → athena、jdbc:bigquery → bigquery、jdbc:postgresql → postgres、jdbc:snowflake → snowflake、jdbc:redshift → redshift等未识别的前缀使用原始名称并记录 warningSnowflake Warehouse 识别当上游平台为 Snowflake 时通过正则从 SQL 中提取use warehouse name;语句将其作为默认数据库名参与血缘解析。度量/维度标签启发式启用tag_measures_and_dimensions后set_field_tags会为 schema 字段打上Dimension或Measure标签。其启发式规则为字段类型为数值NumberType且字段名不以_number结尾、也不是 id 类字段匹配(^id[_\d]?)|([_\d?]id$)时标记为Measure度量否则标记为Dimension维度。源码注释明确说明该启发式可能不准确因为 Mode 侧目前无法明确区分度量与维度。有状态摄入与删除检测ModeSource继承StatefulIngestionSourceBase配置stateful_ingestion.remove_stale_metadata: true后启用陈旧实体清理可自动检测并移除 Mode 侧已删除的报告、查询、图表等实体对应 README 中提到的 stateful deletion detection。该能力在连接器注册表中也标记为 Enabled by default via stateful ingestion。性能与并发设计针对大型工作区连接器提供了以下性能机制均有源码与测试佐证全局线程池max_threads 1时报告与数据集处理分别通过ThreadedIteratorExecutor在跨空间的全局线程池中并行执行见get_workunits_internal限流与重试RateLimiter保证全局每分钟请求数不超阈值429/504/连接错误自动指数退避重试缓存数据源列表、定义列表、创建者信息serialized_lru_cachemaxsize 5000均有缓存且只缓存成功结果避免瞬时失败被永久缓存报告级容错单个报告处理失败或超时仅记录 warning/failure不会中断整个摄入管道报告级错误处理本身还有二次异常保护防止错误上报自身抛错导致线程池整体中止跳过空图表 API 调用当查询的chart_count 0时直接跳过图表接口调用减少无效请求内存观测摄入结束后在报告中记录进程 RSS 内存占用process_memory_used_mb便于监控大工作区摄入的资源消耗。并发执行的安全细节也有专门处理报告对象ModeSourceReport内部使用threading.Lock保护结构化日志与计数器PerfTimer被明确标注为非线程安全、只能在主线程使用。能力边界与限制根据 mode_post.md 与源码实现Mode 连接器的能力与限制总结如下能力说明报告Report通过 Mode 报告 API 获取标题、描述、所有权与图表关联。图表Chart通过reports/{report}/queries/{query}/charts获取含图表类型、标题与构建 DataHub Chart 实体所需的元数据。表信息Table报告查询的表结果元数据用于识别上游数据集上下文与查询关系。透视表信息Pivot Table可用时提取透视结果元数据改善透视分析的图表/数据集关系覆盖。需要说明的限制与注意事项连接器仅实测过 PostgreSQL 数据源其他数据库理论上可用但未经验证源码类注释明确说明血缘解析依赖 SQL 可解析性定义循环引用、模板渲染失败、数据源连接被删除data_source_id找不到等场景都会导致血缘被跳过并在报告中记录告警透视表/图表字段关联基于公式中[...]引用的列名进行大小写不敏感匹配匹配不到真实 schema 字段时会跳过图表类型与度量/维度标签均存在未知类型置空与启发式判定的降级策略摄入行为受 Mode API、权限与平台暴露的元数据约束mode_post.md建议以能力表为权威依据。验证与测试仓库为 Mode 连接器提供了完整的集成测试可作为理解与验证行为的参考tests/integration/mode/test_mode.py通过 Mock 响应模拟 Mode API/api/verify、spaces、reports、queries、charts、data_sources、definitions 等端点验证完整摄入管线的 MCE 输出tests/integration/mode/test_mode_threading.py验证max_threads并发处理场景tests/integration/mode/mode_mces_golden.json摄入结果的 golden 期望文件展示了报告、图表、数据集实体的最终 MCE 形态。测试中的JSON_RESPONSE_MAP清晰地还原了连接器实际调用的 API 路径序列如https://app.mode.com/api/acryl/spaces/157933cc1168/reports、.../reports/9d2da37fa91e/queries、.../queries/6e26a9f3d4e2/charts等与上文端点表一一对应。结语Mode 连接器是 DataHub BI 生态中较完整的开源实现它既覆盖了报告、图表、数据集等 BI 资产的基础元数据也通过定义展开、Liquid 模板渲染与 sqlglot 解析实现了可用的表级与列级血缘并辅以所有权、容器、使用统计与有状态删除检测等增强能力。部署时建议遵循专用摄入用户 最小权限 空间/报告过滤 限流参数的最佳实践组合即可稳定地将 Mode 中的分析资产接入 DataHub 统一目录。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考