DataHub ClickHouse 元数据接入指南表/视图/血缘/Usage/剖析一站式采集【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubClickHouse 是用于存储和查询分析型、操作型数据的数据库平台DataHub 通过clickhouse与clickhouse-usage两个 ingestion source 将其核心元数据纳入统一元数据体系。本文以 ClickHouse 接入文档 为骨架结合仓库内源码、recipe 示例与集成测试系统讲解如何配置连接、采集数据集/视图/字典、提取表级与列级血缘、收集 Usage 统计与操作历史并启用数据剖析与有状态删除检测帮助你在一份可运行的 recipe 上完成从建连到验证的全流程。概述DataHub 能从 ClickHouse 采集什么DataHub 的 ClickHouse 集成覆盖了核心元数据实体数据集表/视图、Schema 字段与容器database/table 两层结构同时支持表级血缘Table Lineage视图View、物化视图Materialized View、字典Dictionary、分布式表Distributed之间的依赖关系默认开启列级血缘Column-Level Lineage默认开启由 SQL 解析器从视图定义中推导Usage 统计Usage Statistics通过解析system.query_log得到被查询的表与列、Top 查询等可选开启数据剖析Data Profiling字段空值率、最值、均值、直方图等统计可选开启有状态删除检测Stateful Deletion Detection默认开启识别 ClickHouse 中被删除的表操作历史Operation Capture展示数据集近期的 INSERT/UPDATE/DELETE 写入活动可选开启。从源码装饰器可以看出官方对这套能力的状态与开关clickhouse.pyplatform_name(ClickHouse) support_status(SupportStatus.GA) # 官方支持状态GA capability(SourceCapability.DELETION_DETECTION, Enabled by default via stateful ingestion) capability(SourceCapability.DATA_PROFILING, Optionally enabled via configuration) capability(SourceCapability.LINEAGE_COARSE, Enabled by default ... include_view_lineage) capability(SourceCapability.LINEAGE_FINE, Enabled by default via include_view_column_lineage) capability(SourceCapability.USAGE_STATS, Optionally enabled via include_usage_statistics) capability(SourceCapability.OPERATION_CAPTURE, Optionally enabled via include_query_log_operations)即血缘表级 列级与删除检测默认开启Usage 统计、数据剖析、操作捕获需要在配置中显式打开。概念映射ClickHouse 对象如何落入 DataHub 模型原文档给出了 DataHub 的通用概念映射关系这是理解采集结果落在哪个实体、哪个字段的关键源概念Source ConceptDataHub 概念说明Platform/account/project 作用域Platform Instance、Container在平台上下文中组织资产核心技术资产如表/视图/Topic/文件Dataset主要采集的技术资产Schema 字段 / 列SchemaField在支持 Schema 提取时包含所有权与协作主体CorpUser、CorpGroup由支持所有权与身份元数据的模块发出依赖与处理关系Lineage edges在支持并启用血缘提取时可用结合 ClickHouse 的实现ClickHouse 是两级命名空间database.tableClickHouseSource继承自TwoTierSQLAlchemySource见 clickhouse.py即database映射为 Container 层级中的 schema表/视图映射为 Dataset列映射为 SchemaFieldplatform_instance用于区分同一环境下的多套 ClickHouse 集群避免 URN 冲突。快速开始最小可运行 Recipe元数据采集clickhouse source仓库提供了完整的最小示例 clickhouse_recipe.yml基本形式如下source: type: clickhouse config: # 连接坐标默认 localhost:8123 host_port: localhost:9000 # 凭据 username: user password: pass # 平台实例用于区分多集群建议显式设置 platform_instance: DatabaseNameToBeIngested # 是否包含视图/表均默认 True include_views: True include_tables: True sink: # sink 配置例如 file / datahub-rest / datahub-kafka执行采集datahub ingest -c clickhouse_recipe.ymlUsage 统计采集clickhouse-usage sourceUsage 使用独立的clickhouse-usagesource仓库示例 clickhouse-usage_recipe.ymlsource: type: clickhouse-usage config: host_port: db_host:port platform_instance: dev_cluster email_domain: acryl.io # 必填用于将 ClickHouse 用户名拼成用户邮箱 URN username: username password: password sink: # sink 配置其中email_domain是ClickHouseUsageConfig的必填项源码用f{username}{email_domain}构造CorpUserUrn若用户名已包含则直接使用见 clickhouse_usage.py。注意clickhouse-usage仍是独立 source保留clickhouse-usage入口点但其聚合逻辑已统一走SqlParsingAggregator路径见 clickhouse_usage.py与clickhouse源中的 query log 解析共用同一套 SQL 解析与聚合管线。配置详解ClickHouseConfig 核心参数ClickHouseConfigclickhouse.py继承自TwoTierSQLAlchemyConfig、BaseTimeWindowConfig与DatasetLineageProviderConfigBase关键参数如下参数默认值说明host_portlocalhost:8123ClickHouse 地址HTTP 接口默认 8123schemeclickhouse隐藏字段SQLAlchemy 方言可改为clickhousenativeusername/password- / 空连接凭据uri_opts{}连接 URI 的附加参数如secure、protocol、TLS 证书secure/protocolNone已废弃请改用uri_opts两者混用会直接报错include_table_lineageTrue是否采集表级血缘include_materialized_viewsTrue是否采集物化视图include_query_log_lineageFalse是否从query_log提取 INSERT/CREATE 查询产生的血缘是对视图/物化视图定义型血缘的补充include_usage_statisticsFalse是否从query_log提取 Usage 统计追踪被 SELECT 的表与列include_query_log_operationsFalse是否展示数据集近期写入活动INSERT/UPDATE/DELETE 历史query_log_deny_usernames[]从 query log 提取中排除的用户名列表temporary_tables_pattern见源码从血缘中过滤临时表的正则列表top_n_queries10每个表保存的 Top 查询数用于 Usage 统计start_time/end_time/bucket_duration-时间窗口与分桶继承自BaseTimeWindowConfig影响 query log 范围profiling关闭数据剖析配置块stateful_ingestion-有状态删除检测配置几点值得注意的实现细节安全校验query_log_deny_usernames经 Pydantic validator 校验仅允许字母、数字、下划线与连字符防止拼接进system.query_log查询时发生 SQL 注入clickhouse.pyUsage 源的query_log_table同样被限制为合法标识符clickhouse_usage.py。临时表过滤默认正则包括^_.*下划线开头、.*\.tmp_.*、.*\.temp_.*、.*\._inner.*物化视图内部表用于从血缘中剔除噪音clickhouse.py。向后兼容若仅设置了废弃的secure/protocol而未设uri_opts源码会自动将其转换到uri_opts并给出告警两者同时设置则抛出异常clickhouse.py。连接方式HTTP、Native 与 SSL/TLSClickHouse 提供 HTTP 与 Native 两套接口仓库 recipe 中给出了三种典型配置形态。HTTP 接口 HTTPS 协议source: type: clickhouse config: host_port: localhost:8443 uri_opts: protocol: httpsNative 接口 加密传输source: type: clickhouse config: host_port: localhost:9440 scheme: clickhousenative uri_opts: secure: True配置了 SSL-TLS 与双向证书的完整示例推荐 URI 形式source: type: clickhouse config: # URL 形式推荐 sqlalchemy_uri: clickhousenative://user:passlocalhost:9000/db?ca_certsca.crt # 非 URL 形式 username: user password: pass host_port: localhost:9000 uri_opts: secure: True ca_certs: ca.crt certfile: clickhouse.crt keyfile: clickhouse.key实现层注意点clickhouse.py方言为clickhousenative时若 URI 查询串中再带protocol参数会直接抛异常避免 native 与 http 两种 schema 混用配置两种形态sqlalchemy_uri或host_port/username/password都支持血缘与 query log 查询内部会基于同一套get_sql_alchemy_url()重建连接连接 URL 会自动打上datahub客户端标识clickhouse_connection.pyHTTP 驱动注入User-Agent: datahubnative/asynch 驱动注入client_name: datahub便于在system.query_log中归因 DataHub 自身的读取行为若用户已显式提供同名参数则保留用户值。表级与列级血缘从定义到 Query Log 的完整链路定义型血缘默认开启ClickHouseSource通过三类 SQL 从system.tables提取血缘clickhouse.py表级血缘Distributed引擎表解析engine_full中的远端表Dictionary字典解析SOURCE(CLICKHOUSE(...))中的来源表血缘类型标记为COPY视图血缘对View的create_table_query做分词并与现存表集合求交集血缘类型标记为VIEW物化视图血缘对MaterializedView生成两类血缘——SRC → MV源表到物化视图与SRC → TO源表到TO子句指定的目标表后者为直接血缘。血缘提取只保留仍存在于 ClickHouse 中的源表缺失表会告警跳过并受database_pattern/table_pattern过滤clickhouse.py。最终以UpstreamLineageaspect 通过 MCP 输出clickhouse.py。列级血缘默认开启列级血缘由SqlParsingAggregator从视图/物化视图定义中解析。针对 ClickHouse 物化视图的TO子句特性_add_view_to_aggregator会为TO目标表额外注册一次视图定义从而同时生成SRC → MV与SRC → TO的列级血缘clickhouse.py。Query Log 血缘可选设置include_query_log_lineage: True后采集器会查询system.query_log中QueryFinish且is_initial_query 1的Insert/Create/Select查询clickhouse.pyInsert/Create查询用于生成血缘INSERT ... SELECT、CREATE TABLE AS纯INSERT VALUES/INSERT FORMAT会被过滤无血缘价值查询自动排除system.*内部查询与配置的query_log_deny_usernames每条观测查询进入SqlParsingAggregator最终产出血缘/Usage/操作三类 workunitclickhouse.py。Usage 统计与操作捕获使用统计Usage Statistics开启include_usage_statistics: True或使用独立的clickhouse-usagesource后采集器读取system.query_log中的Select查询start_time会被向下取整到bucket_duration分桶边界保证首个不完整桶也能被完整聚合clickhouse_usage.pyquery_log_table可配置为自定义视图默认system.query_log例如对日志做预过滤或脱敏聚合器输出DatasetUsageStatistics分桶、Top 用户/查询top_n_queries控制每个表保留的 Top 查询数时间戳统一按 UTC 处理system.query_log的 DateTime 列本身为 UTC 无时区标记。操作捕获Operation Capture开启include_query_log_operations: True后数据集 Activity 页会展示近期 INSERT/UPDATE/DELETE 写入历史基于同一份 query log 数据生成无需额外表。数据剖析与有状态删除检测数据剖析SourceCapability.DATA_PROFILING可选开启通过profiling配置块启用仓库集成测试给出了完整示例clickhouse_to_file.ymlsource: type: clickhouse config: username: clickhouseuser password: clickhousepass host_port: localhost:${CLICKHOUSE_PORT} platform_instance: clickhousetestserver database_pattern: allow: - ^db1 profile_pattern: allow: - clickhousetestserver.db1.mv_target_table profiling: enabled: true include_field_null_count: true include_field_min_value: true include_field_max_value: true include_field_mean_value: true include_field_median_value: true include_field_stddev_value: true include_field_quantiles: true include_field_distinct_value_frequencies: true include_field_histogram: true include_field_sample_values: true有状态删除检测默认开启通过stateful_ingestion机制识别被删除的表/视图。注意其与 ClickHouse 双层命名配合血缘由system.tables中现存表校验删除检测则基于 stateful 索引比对上次采集状态。Schema 与容器类型映射与自定义属性ClickHouseSource通过 monkey-patch 增强clickhouse_sqlalchemydialect实现批量、高性能的元数据反射clickhouse.py表/视图枚举从system.tables一次性取全部表与视图按engine LIKE %View区分 relkind列信息从system.columns按 schema 整库批量拉取ORDER BY database, table, position避免逐表 DESCRIBE类型映射补充DateTime64(N)、Date32、Bool、Nothing、Int128/256、UInt128/256等原生方言未覆盖类型LowCardinality/Nullable自动解包内层类型Array→ArrayTypeClass、Map→MapTypeClass、Tuple→UnionTypeClass、IPv4→NumberTypeClass、IPv6→StringTypeClassclickhouse.py表属性从system.tables提取engine、partition_key、sorting_key、primary_key、sampling_key、storage_policy、total_rows、total_bytes等写入customProperties并支持表注释视图定义从system.tables.create_table_query取完整 CREATE 语句交给 SQL 解析器抽取 SELECT 部分对无法解析的复杂类型如嵌套Map回退为NullType保证 Schema 发现不中断clickhouse.py。集成测试如何在仓库中验证采集行为仓库通过 Docker 编排了完整的 ClickHouse 集成测试docker-compose.yml镜像clickhouse/clickhouse-server:22.5.2test_clickhouse.py 中两个用例分别验证配置形式与URI 形式两种 recipe启动 ClickHouse 容器后等待 8123 端口就绪将实际端口注入${CLICKHOUSE_PORT}环境变量避免 CI 残留容器端口冲突执行datahub ingest -c clickhouse_to_file.yml或_uri_form变体sink 为本地文件用 golden 文件 clickhouse_mces_golden.json 比对输出仅忽略metadata_modification_time、data_paths、metadata_path等随容器变化的属性冻结测试时间2020-04-14 07:00:00保证 MCE 中时间相关字段可复现。此外仓库还有针对clickhousenative连接的单元测试 test_clickhouse_connection.py、source 与 usage source 的单元测试 test_clickhouse_source.py、test_clickhouse_usage_source.py以及物化视图TO子句、dictGet函数等列级血缘解析的 golden 用例test_clickhouse_materialized_view_to.json 等可作为理解行为边界与排查问题的参考。常见问题与注意事项端口选择clickhouse源默认localhost:8123HTTPNative 接口为 9000TLS 场景下 HTTP 为 8443、Native 为 9440测试容器同时暴露 8123 与 9000。secure/protocol已废弃请统一使用uri_optssecure、protocol、ca_certs、certfile、keyfile等混用会报错。双层命名ClickHouse 只有database.table两级血缘与 query log 解析中default_db故意不填充避免把已限定名过度限定成default.my_db.table这类错误 URN见 clickhouse.py 注释。query log 需要权限血缘/Usage/操作捕获依赖读取system.query_log请确保连接用户具备相应权限对敏感查询可用query_log_deny_usernames排除。临时表噪音血缘结果默认过滤下划线开头、tmp_/temp_前缀及物化视图.inner内部表可通过temporary_tables_pattern自定义。删除检测与剖析删除检测默认开启剖析需profiling.enabled: true并配合profile_pattern控制范围避免大表全量剖析带来性能开销。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考