DataHub CLI 批量元数据摄取CLI Ingestion实战指南从 Recipe 配置到定时调度【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读DataHub 的批量元数据摄取Batch Ingestion是指从源系统一次性、成规模地抽取元数据并写入 DataHub 的过程通常按照预定义的计划周期执行依赖 DataHub 的 Metadata Ingestion 框架。被抽取的元数据包括数据集dataset、图表chart、看板dashboard、管道pipeline、用户user、用户组group、使用情况usage与任务task等实体的时间点快照。本文以仓库内的 CLI Ingestion 官方文档 为骨架结合 DataHub CLI 参考、Recipe 配置指南、DataHub Sink 文档 与 CLI 源码ingest_cli.py系统讲解如何通过datahub命令行完成从安装、插件选择、Recipe 编写、身份认证到执行与调度的完整链路。读完本文你将掌握用一条命令把 MySQL、Snowflake 等任意受支持数据源的元数据批量灌入 DataHubOSS 自托管或 DataHub Cloud并学会用 Airflow、CRON、Kubernetes 等方式将其固化到生产调度体系。一、安装 DataHub CLIDataHub 提供名为datahub的命令行工具可完成元数据摄取、实体管理、本地快速启动等常见操作。它有两种最常用的安装方式。1.1 通过 Homebrew 安装macOS / Linux在 macOS 或 Linux 上最简单的方式是使用 Homebrewbrew install datahub-project/tap/datahub datahub versionHomebrew 会为datahub维护一个隔离的 Python 环境无需手动激活 venv也不会与系统 Python 产生 PATH 冲突后续升级执行brew upgrade datahub即可。注意Homebrew 公式默认只安装核心 CLI。若要使用 Snowflake、BigQuery、Looker 等连接器需要安装到 brew 管理的环境中$(brew --prefix datahub)/libexec/bin/pip install acryl-datahub[snowflake,bigquery]1.2 通过 pip 安装全平台在任何平台上都可通过 pip 安装但要求 Python 3.10 及以上版本。官方建议先创建并激活虚拟环境避免污染系统环境python3 -m venv venv # 创建虚拟环境 source venv/bin/activate # 激活虚拟环境 # Requires Python 3.10 python3 -m pip install --upgrade pip wheel setuptools python3 -m pip install --upgrade acryl-datahub python3 -m datahub version命令成功执行后命令行会打印出对应的 DataHub CLI 版本号。如果出现command not found改用python3 -m datahub version即可。注意如果在虚拟环境中安装每次新开 shell 会话时都需要重新source venv/bin/activate。遇到安装问题可参考common setup issues。更多安装选项源码安装、容器内运行 CLI 等参见 CLI Installation Guide 与 alternate installation options。安装完成后建议先执行datahub init配置 CLI 连接的 DataHub 实例地址为后续摄取做好准备。二、安装连接器插件Connector PluginsDataHub CLI 采用插件架构核心包只提供框架能力针对不同数据源的连接器需要按需单独安装。所有受支持的数据源列表见 open source docs。找到你需要的连接器后直接用 pip 安装对应 extra 即可。例如安装mysql连接器pip install --upgrade acryl-datahub[mysql]常用的连接器安装模式还包括# Snowflake pip install acryl-datahub[snowflake] # BigQuery pip install acryl-datahub[bigquery] # 同时安装多个 pip install acryl-datahub[mysql,snowflake,bigquery] # REST sinkdatahub-rest插件 pip install acryl-datahub[datahub-rest]提示如果需要尚未提供的连接器仓库内的 datahub-skills 是一个 Claude Code 插件可从规划、脚手架搭建到标准审查与社区测试加速自定义连接器开发。三、配置 Recipe摄取配置文件的解剖Recipe 是元数据摄取的主配置文件它告诉摄取脚本从哪里拉数据source、把数据放到哪里sink。一个 Recipe 文件只能包含 1 个 source 和 1 个 sink需要多个数据源时需要准备多个 Recipe 文件。3.1 最小可运行示例以 MySQL 为例创建example-recipe.ymlOSS / 自托管部署未启用认证时无需 token# example-recipe.yml # MySQL source configuration source: type: mysql config: username: root password: password host_port: localhost:3306 # Recipe sink configuration. sink: type: datahub-rest config: server: http://localhost:8080DataHub Cloud 部署需要 token# example-recipe.yml # MySQL source configuration source: type: mysql config: username: root password: password host_port: localhost:3306 # Recipe sink configuration. sink: type: datahub-rest config: server: https://your-instance.acryl.io/gms token: your-token仓库中同类型的完整示例见 mysql_to_datahub.dhub.yamlexamples/recipes目录下还提供了 dbt、Snowflake、BigQuery、Tableau、Kafka 等数十种源与 sink 组合的现成 Recipe如 example_to_datahub_rest.dhub.yaml、example_to_datahub_kafka.dhub.yaml。3.2 理解 source 与 sinksource 配置块定义从哪里抽取元数据。它可以是 OLTP 数据库、数据仓库甚至是本地文件。每个 source 因访问元数据所需的条件不同有各自专属的配置项详见 Sources 文档。sink 配置块定义把元数据推送到哪里。每种 sink 类型同样需要特定的配置详见 Sinks 文档。server字段应指向 DataHub 实例的 GMS API 地址本地 OSS 部署为http://localhost:8080DataHub Cloud 为https://your-instance.acryl.io/gms。关于 Docker / Kubernetes 环境下的 server 地址DataHub sink reference 给出了明确指引摄取进程与 GMS 都跑在 Docker 中时使用 GMS 容器的内部 Docker 主机名例如http://datahub-gms:8080GMS 通过 Helm Charts 部署在 Kubernetes 中、且摄取进程也在集群内时使用 GMS 的 Kubernetes Service 名称例如http://datahub-datahub-gms.datahub.svc.cluster.local:8080使用 UI 摄取时则取决于 GMS 实际部署位置来决定主机名。3.3 datahub-rest sink 配置参数详解datahub-rest是默认且最常用的 sink通过 GMS REST API 推送元数据其优势在于错误可以立即被报告。完整配置参数如下YAML 中用.表示嵌套字段字段必填默认值说明server✅—DataHub GMS 端点 URLtoken——用于认证的 Bearer tokentimeout_sec—30单次 HTTP 请求超时时间retry_max_times—1HTTP 请求失败的最大重试次数重试间隔呈指数退避retry_status_codes—[429, 502, 503, 504]命中这些状态码时也触发重试extra_headers——附加到请求上的额外请求头max_threads—15REST API 调用的最大并行度mode—ASYNC_BATCH[高级] 运行模式SYNC、ASYNC或ASYNC_BATCHca_certificate_path——校验 HTTPS 通信时使用的服务端 CA 证书路径client_certificate_path——HTTPS 通信使用的客户端 CA 证书路径disable_ssl_verification—false是否关闭 SSL 证书校验respect_mcp_sync_marker—false[高级] 当任一 MCP 携带emitModeMarkersync系统元数据标记时将批量升级为同步写入其中respect_mcp_sync_marker是一个较新的高级特性开启后若某批次中的 MCP 携带了emitModeMarkersync标记则该批次会被升级为同步asyncfalse否则沿用配置的mode它只会增强同步性而不会削弱。该标记由生产方写入例如通过自定义 aspect mutator/validatorsink 只读取不产生。该特性仅在 DataHub Cloud 的特定配置下受支持。3.4 使用带认证的 Recipe在 DataHub Cloud 部署中仅支持datahub-restsink——元数据会被推送到你的 DataHub 实例暴露的 REST 端点。该 sink 必填两个配置server你的 DataHub 实例所暴露 REST API 的地址token用于对该实例 REST API 请求进行认证的唯一 API Key。任何拥有Generate Personal Access Tokens平台权限的用户都可以创建 token进入Settings → Access Tokens点击Generate Personal Access Token并选择期望的过期时间即可。安全提醒请务必妥善保管 API Key避免泄露与共享。如果你在 DataHub Cloud 上且密钥因任何原因泄露请及时联系 DataHub 团队。3.5 高级配置环境变量注入、文件指令与转换器环境变量注入Recipe 配置会自动展开环境变量如${MSSQL_PASSWORD}语义类似 GNU bash 或 docker-compose 的变量替换详见 Secret Resolution。注意变量名不能包含空格或除下划线外的特殊字符。借助环境变量敏感信息无需写入 Recipe 文件——只要能够安全地把环境变量传给摄取进程即可source: type: mssql config: username: sa password: ${MSSQL_PASSWORD} database: DemoData sink: type: datahub-rest config: server: http://localhost:8080文件型敏感数据__DATAHUB_TO_FILE_指令部分 source如 kafka、bigquery、mysql需要本地文件系统上的文件路径这在 UI 摄取场景下不可行Recipe 必须完全自足。DataHub 提供__DATAHUB_TO_FILE_指令语法为__DATAHUB_TO_FILE_property: value执行时会转换为property: path to file containing valuevalue 可以是内联值或环境变量/密钥source: type: mysql config: host_port: localhost:3306 database: dbname username: root password: example # If you need to use SSL with MySQL: options: connect_args: __DATAHUB_TO_FILE_ssl_key: ${secret} # 将转换为 ssl_key: /tmp/path/to/fileTransformers转换器若希望在元数据到达 sink 之前进行修改例如给所有数据集追加 owner 或 tag可以编写自定义 transformer 模块并通过 Recipe 中的transformers段落声明按顺序依次执行。例如对 MSSQL 摄取的所有表应用默认 important tag# A recipe to ingest metadata from MSSQL and apply default tags to all tables source: type: mssql config: username: sa password: ${MSSQL_PASSWORD} database: DemoData transformers: # an array of transformers applied sequentially - type: simple_add_dataset_tags config: tag_urns: - urn:li:tag:Important # default sink, no config needed更灵活的流水线处理请参考 transformers guide。编辑器自动补全与语法校验将 Recipe 命名为.dhub.yaml后缀如myrecipe.dhub.yaml配合 VSCodeRed Hat YAML 插件或 IntelliJ官方 YAML 插件即可获得自动补全与语法校验能力。四、执行摄取datahub ingest配置好 Recipe 后最后一步是调用 DataHub CLI 执行摄取datahub ingest -c path/to/recipe.yml其中-c / --config指向 Recipe 文件支持.toml或.yaml格式传-可从 stdin 读取。4.1 常用命令选项从 CLI 源码ingest_cli.py与 CLI 文档 可以确认datahub ingest的run子命令支持以下核心选项选项说明-c, --config配置文件.toml 或 .yaml必填-n, --dry-run干跑执行全部摄取步骤但不写 sink用于验证 Recipe 是否产生预期元数据事件--preview只处理 source 产生的前 10 个 workunit 并送到 sink用于快速端到端冒烟测试--preview-workunits指定 preview 产生的 workunit 数量默认 10--strict-warnings启用后带有 warning 的摄取运行返回非零退出码--test-source-connection仅测试 Recipe 中的 source 连接信息不执行摄取--report-to运行结构化报告的发送目的地默认datahub发送到 DataHub 服务端--no-default-report关闭默认的摄取结果上报默认会向 DataHub 上报便于在 UI 中查看 CLI 摄取结果--no-spinner/--no-progress关闭 spinner / 中间进度报告--record等Beta 特性录制摄取运行HTTP 请求与数据库查询为加密归档可离线重放调试需pip install acryl-datahub[debug-recording]典型用法组合# 干跑不写 sink datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml --dry-run # 短形式 datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml -n # 预览前 10 个 workunit datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml --preview # 干跑 预览 20 个 workunit datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml -n --preview --preview-workunits20 # 关闭上报 datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml --no-default-report # 只测试 source 连接 datahub ingest -c ./recipe.yml --test-source-connection4.2 关闭 Recipe 上报默认情况下 CLI 会把摄取报告含所用 Recipe发送给 DataHub可在 UI 中查看。若不想上报 Recipe 内容可在 Recipe 中增加reporting段并配合failure_log记录失败 JSONsource: # source configs sink: # sink configs # Add configuration for the datahub reporter reporting: - type: datahub config: report_recipe: false # Optional log to put failed JSONs into a file # Helpful in case you are trying to debug some issue with specific ingestion failing failure_log: enabled: false log_config: filename: ./path/to/failure.json4.3 运行状态查询与回滚datahub ingest list-source-runs列出历次运行展示 run ID、source 名、开始时间、状态与 URN支持--urn与--source过滤部分/完全匹配。datahub ingest list-runs列出近期摄取运行。datahub ingest show --run-id id查看某次运行的详情可用-a展示 aspect。datahub ingest rollback --run-id id回滚某次摄取删除该次运行创建的实体并回退被更新的 aspect支持-n干跑、--safe/--nuke模式与--report-dir报告目录。4.4 摄取流水线的底层原理从源码看datahub ingest的run命令ingest_cli.py的核心流程是通过load_config_file加载 Recipe支持 stdin、远程 URL、环境变量解析与__DATAHUB_TO_FILE_指令处理调用Pipeline.create(...)依据配置构建流水线——Pipeline类pipeline.py持有config、ctx、source、extractor、sink、transformers等核心组件调用pipeline.run()执行source 抽取元数据 → extractor 提取 → transformers 依次转换 → sink 写入最终通过pipeline.pretty_print_summary(...)输出运行总结--strict-warnings会把含 warning 的运行转为非零退出码。4.5 通过datahub ingest deploy将 Recipe 部署到 DataHub除了本地运行CLI 还支持datahub ingest deploy把 Recipe 上传到 DataHub 由 UI Ingestion 执行可同时配置调度或更新已有摄取源上传目标是 CLI 所连接的实例而非 Recipe 的 sink。核心选项--nameRecipe 名、--urn更新指定 URN 的摄取源、--scheduleCron 表达式、--time-zone时区默认 UTC、--executor-id路由到自定义远程执行器、--cli-version、--extra-pip、--extra-env。# 部署并设置每天 5 点伦敦时区执行 datahub ingest deploy --name Snowflake Integration --schedule 0 5 * * * --time-zone Europe/London -c recipe.yaml # 部署到指定远程执行器 datahub ingest deploy --name Remote Snowflake Integration --executor-id remote-executor-pool-1 --schedule 0 5 * * * -c recipe.yaml # 更新已有 Recipe注意这是全量更新未指定的选项会被移除 datahub ingest deploy --urn urn:li:dataHubIngestionSource:deploy-12345678 --schedule 0 6 * * * -c updated_recipe.yaml这些部署参数也可写在 Recipe 的deployment段中CLI 选项优先级更高deployment: name: Snowflake Integration schedule: 0 5 * * * time_zone: Europe/London executor_id: remote-executor-pool-1 # Optional cli_version: 0.15.0.1 # Optional extra_pip: [polars1.35.2] extra_env: VAR1value1,VAR2value2 source: ...批量部署场景下可通过 shell 组合对目录下所有 Recipe 逐一执行ls recipe_directory/*.yml | xargs -n 1 -I {} datahub ingest deploy -c {}五、调度摄取让元数据保持新鲜摄取既可以由管理员临时ad-hoc手动执行也可以安排周期重复执行——最常见的节奏是每天一次。由于源系统不断变化需要定期重新运行 Recipe 才能让这些变化反映到 DataHub 中。调度方式的选择取决于部署复杂度5.1 Apache Airflow推荐对于复杂部署官方推荐使用 Apache Airflow 之类的任务调度器将datahub ingest -c recipe.yml包装为 DAG 任务可获得失败重试、依赖编排、日志与监控等能力。5.2 CRON在更简单的部署中在一台常开机器上用 CRON 定时执行同样可行# 每天早上 8 点执行 MySQL 摄取 0 8 * * * cd /home/ubuntu/datahub_ingest datahub ingest -c mysql_to_datahub.yml5.3 Kubernetes CronJob若 DataHub 部署在 Kubernetes 中也可以使用 CronJob 容器化执行摄取详见 Kubernetes 调度文档。注意每个源系统需要单独的 Recipe 文件。这样既可以把不同源的摄取独立调度也可以组合到同一次调度中。更多调度方式Airflow、cron、Kubernetes、DataHub 内建调度的完整示例参见 Scheduling Ingestion Guide 及其下的 airflow.md、cron.md、datahub.md、kubernetes.md 分册。六、版本兼容性与升级注意版本号体系DataHub 服务端使用 3 位版本号CLI 使用 4 位版本号。例如服务端为 1.5.0 时应使用 CLI 1.5.0.7最后一位是补丁号。这是因为 CLI 的发布频率远高于服务端——CLI 补丁大约每周发布一次服务端大约每几个月发布一次。向后兼容窗口对于摄取源任何破坏性变更都会在 release notes 中标注。当字段被弃用或变更时官方会尽量维持两个服务端版本的向后兼容约 4-6 周CLI 在使用被弃用选项时也会打印警告。七、进阶参考CLI 摄取的进阶指引可继续阅读以下仓库内文档Reference fordatahub ingestcommand全部子命令与选项的权威参考UI Ingestion Guide在 UI 中配置并执行 Recipe 的图形化方式RecipesRecipe 的完整配置语法与高级主题环境变量、转换器、.dhub.yaml编辑器支持DataHub Sink referencedatahub-rest、datahub-kafka、datahub-lite三种 sink 的配置细节与失败行为Sources各数据源 source 的专属配置Sinks各 sink 类型概览示例 Recipe 集合覆盖 MySQL、MSSQL、Snowflake、BigQuery、Kafka、Tableau 等数十种现成配置【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DataHub CLI 批量元数据摄取CLI Ingestion实战指南从 Recipe 配置到定时调度【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读DataHub 的批量元数据摄取Batch Ingestion是指从源系统一次性、成规模地抽取元数据并写入 DataHub 的过程通常按照预定义的计划周期执行依赖 DataHub 的 Metadata Ingestion 框架。被抽取的元数据包括数据集dataset、图表chart、看板dashboard、管道pipeline、用户user、用户组group、使用情况usage与任务task等实体的时间点快照。本文以仓库内的 CLI Ingestion 官方文档 为骨架结合 DataHub CLI 参考、Recipe 配置指南、DataHub Sink 文档 与 CLI 源码ingest_cli.py系统讲解如何通过datahub命令行完成从安装、插件选择、Recipe 编写、身份认证到执行与调度的完整链路。读完本文你将掌握用一条命令把 MySQL、Snowflake 等任意受支持数据源的元数据批量灌入 DataHubOSS 自托管或 DataHub Cloud并学会用 Airflow、CRON、Kubernetes 等方式将其固化到生产调度体系。一、安装 DataHub CLIDataHub 提供名为datahub的命令行工具可完成元数据摄取、实体管理、本地快速启动等常见操作。它有两种最常用的安装方式。1.1 通过 Homebrew 安装macOS / Linux在 macOS 或 Linux 上最简单的方式是使用 Homebrewbrew install datahub-project/tap/datahub datahub versionHomebrew 会为datahub维护一个隔离的 Python 环境无需手动激活 venv也不会与系统 Python 产生 PATH 冲突后续升级执行brew upgrade datahub即可。注意Homebrew 公式默认只安装核心 CLI。若要使用 Snowflake、BigQuery、Looker 等连接器需要安装到 brew 管理的环境中$(brew --prefix datahub)/libexec/bin/pip install acryl-datahub[snowflake,bigquery]1.2 通过 pip 安装全平台在任何平台上都可通过 pip 安装但要求 Python 3.10 及以上版本。官方建议先创建并激活虚拟环境避免污染系统环境python3 -m venv venv # 创建虚拟环境 source venv/bin/activate # 激活虚拟环境 # Requires Python 3.10 python3 -m pip install --upgrade pip wheel setuptools python3 -m pip install --upgrade acryl-datahub python3 -m datahub version命令成功执行后命令行会打印出对应的 DataHub CLI 版本号。如果出现command not found改用python3 -m datahub version即可。注意如果在虚拟环境中安装每次新开 shell 会话时都需要重新source venv/bin/activate。遇到安装问题可参考common setup issues。更多安装选项源码安装、容器内运行 CLI 等参见 CLI Installation Guide 与 alternate installation options。安装完成后建议先执行datahub init配置 CLI 连接的 DataHub 实例地址为后续摄取做好准备。二、安装连接器插件Connector PluginsDataHub CLI 采用插件架构核心包只提供框架能力针对不同数据源的连接器需要按需单独安装。所有受支持的数据源列表见 open source docs。找到你需要的连接器后直接用 pip 安装对应 extra 即可。例如安装mysql连接器pip install --upgrade acryl-datahub[mysql]常用的连接器安装模式还包括# Snowflake pip install acryl-datahub[snowflake] # BigQuery pip install acryl-datahub[bigquery] # 同时安装多个 pip install acryl-datahub[mysql,snowflake,bigquery] # REST sinkdatahub-rest插件 pip install acryl-datahub[datahub-rest]提示如果需要尚未提供的连接器仓库内的 datahub-skills 是一个 Claude Code 插件可从规划、脚手架搭建到标准审查与社区测试加速自定义连接器开发。三、配置 Recipe摄取配置文件的解剖Recipe 是元数据摄取的主配置文件它告诉摄取脚本从哪里拉数据source、把数据放到哪里sink。一个 Recipe 文件只能包含 1 个 source 和 1 个 sink需要多个数据源时需要准备多个 Recipe 文件。3.1 最小可运行示例以 MySQL 为例创建example-recipe.ymlOSS / 自托管部署未启用认证时无需 token# example-recipe.yml # MySQL source configuration source: type: mysql config: username: root password: password host_port: localhost:3306 # Recipe sink configuration. sink: type: datahub-rest config: server: http://localhost:8080DataHub Cloud 部署需要 token# example-recipe.yml # MySQL source configuration source: type: mysql config: username: root password: password host_port: localhost:3306 # Recipe sink configuration. sink: type: datahub-rest config: server: https://your-instance.acryl.io/gms token: your-token仓库中同类型的完整示例见 mysql_to_datahub.dhub.yamlexamples/recipes目录下还提供了 dbt、Snowflake、BigQuery、Tableau、Kafka 等数十种源与 sink 组合的现成 Recipe如 example_to_datahub_rest.dhub.yaml、example_to_datahub_kafka.dhub.yaml。3.2 理解 source 与 sinksource 配置块定义从哪里抽取元数据。它可以是 OLTP 数据库、数据仓库甚至是本地文件。每个 source 因访问元数据所需的条件不同有各自专属的配置项详见 Sources 文档。sink 配置块定义把元数据推送到哪里。每种 sink 类型同样需要特定的配置详见 Sinks 文档。server字段应指向 DataHub 实例的 GMS API 地址本地 OSS 部署为http://localhost:8080DataHub Cloud 为https://your-instance.acryl.io/gms。关于 Docker / Kubernetes 环境下的 server 地址DataHub sink reference 给出了明确指引摄取进程与 GMS 都跑在 Docker 中时使用 GMS 容器的内部 Docker 主机名例如http://datahub-gms:8080GMS 通过 Helm Charts 部署在 Kubernetes 中、且摄取进程也在集群内时使用 GMS 的 Kubernetes Service 名称例如http://datahub-datahub-gms.datahub.svc.cluster.local:8080使用 UI 摄取时则取决于 GMS 实际部署位置来决定主机名。3.3 datahub-rest sink 配置参数详解datahub-rest是默认且最常用的 sink通过 GMS REST API 推送元数据其优势在于错误可以立即被报告。完整配置参数如下YAML 中用.表示嵌套字段字段必填默认值说明server✅—DataHub GMS 端点 URLtoken——用于认证的 Bearer tokentimeout_sec—30单次 HTTP 请求超时时间retry_max_times—1HTTP 请求失败的最大重试次数重试间隔呈指数退避retry_status_codes—[429, 502, 503, 504]命中这些状态码时也触发重试extra_headers——附加到请求上的额外请求头max_threads—15REST API 调用的最大并行度mode—ASYNC_BATCH[高级] 运行模式SYNC、ASYNC或ASYNC_BATCHca_certificate_path——校验 HTTPS 通信时使用的服务端 CA 证书路径client_certificate_path——HTTPS 通信使用的客户端 CA 证书路径disable_ssl_verification—false是否关闭 SSL 证书校验respect_mcp_sync_marker—false[高级] 当任一 MCP 携带emitModeMarkersync系统元数据标记时将批量升级为同步写入其中respect_mcp_sync_marker是一个较新的高级特性开启后若某批次中的 MCP 携带了emitModeMarkersync标记则该批次会被升级为同步asyncfalse否则沿用配置的mode它只会增强同步性而不会削弱。该标记由生产方写入例如通过自定义 aspect mutator/validatorsink 只读取不产生。该特性仅在 DataHub Cloud 的特定配置下受支持。3.4 使用带认证的 Recipe在 DataHub Cloud 部署中仅支持datahub-restsink——元数据会被推送到你的 DataHub 实例暴露的 REST 端点。该 sink 必填两个配置server你的 DataHub 实例所暴露 REST API 的地址token用于对该实例 REST API 请求进行认证的唯一 API Key。任何拥有Generate Personal Access Tokens平台权限的用户都可以创建 token进入Settings → Access Tokens点击Generate Personal Access Token并选择期望的过期时间即可。安全提醒请务必妥善保管 API Key避免泄露与共享。如果你在 DataHub Cloud 上且密钥因任何原因泄露请及时联系 DataHub 团队。3.5 高级配置环境变量注入、文件指令与转换器环境变量注入Recipe 配置会自动展开环境变量如${MSSQL_PASSWORD}语义类似 GNU bash 或 docker-compose 的变量替换详见 Secret Resolution。注意变量名不能包含空格或除下划线外的特殊字符。借助环境变量敏感信息无需写入 Recipe 文件——只要能够安全地把环境变量传给摄取进程即可source: type: mssql config: username: sa password: ${MSSQL_PASSWORD} database: DemoData sink: type: datahub-rest config: server: http://localhost:8080文件型敏感数据__DATAHUB_TO_FILE_指令部分 source如 kafka、bigquery、mysql需要本地文件系统上的文件路径这在 UI 摄取场景下不可行Recipe 必须完全自足。DataHub 提供__DATAHUB_TO_FILE_指令语法为__DATAHUB_TO_FILE_property: value执行时会转换为property: path to file containing valuevalue 可以是内联值或环境变量/密钥source: type: mysql config: host_port: localhost:3306 database: dbname username: root password: example # If you need to use SSL with MySQL: options: connect_args: __DATAHUB_TO_FILE_ssl_key: ${secret} # 将转换为 ssl_key: /tmp/path/to/fileTransformers转换器若希望在元数据到达 sink 之前进行修改例如给所有数据集追加 owner 或 tag可以编写自定义 transformer 模块并通过 Recipe 中的transformers段落声明按顺序依次执行。例如对 MSSQL 摄取的所有表应用默认 important tag# A recipe to ingest metadata from MSSQL and apply default tags to all tables source: type: mssql config: username: sa password: ${MSSQL_PASSWORD} database: DemoData transformers: # an array of transformers applied sequentially - type: simple_add_dataset_tags config: tag_urns: - urn:li:tag:Important # default sink, no config needed更灵活的流水线处理请参考 transformers guide。编辑器自动补全与语法校验将 Recipe 命名为.dhub.yaml后缀如myrecipe.dhub.yaml配合 VSCodeRed Hat YAML 插件或 IntelliJ官方 YAML 插件即可获得自动补全与语法校验能力。四、执行摄取datahub ingest配置好 Recipe 后最后一步是调用 DataHub CLI 执行摄取datahub ingest -c path/to/recipe.yml其中-c / --config指向 Recipe 文件支持.toml或.yaml格式传-可从 stdin 读取。4.1 常用命令选项从 CLI 源码ingest_cli.py与 CLI 文档 可以确认datahub ingest的run子命令支持以下核心选项选项说明-c, --config配置文件.toml 或 .yaml必填-n, --dry-run干跑执行全部摄取步骤但不写 sink用于验证 Recipe 是否产生预期元数据事件--preview只处理 source 产生的前 10 个 workunit 并送到 sink用于快速端到端冒烟测试--preview-workunits指定 preview 产生的 workunit 数量默认 10--strict-warnings启用后带有 warning 的摄取运行返回非零退出码--test-source-connection仅测试 Recipe 中的 source 连接信息不执行摄取--report-to运行结构化报告的发送目的地默认datahub发送到 DataHub 服务端--no-default-report关闭默认的摄取结果上报默认会向 DataHub 上报便于在 UI 中查看 CLI 摄取结果--no-spinner/--no-progress关闭 spinner / 中间进度报告--record等Beta 特性录制摄取运行HTTP 请求与数据库查询为加密归档可离线重放调试需pip install acryl-datahub[debug-recording]典型用法组合# 干跑不写 sink datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml --dry-run # 短形式 datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml -n # 预览前 10 个 workunit datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml --preview # 干跑 预览 20 个 workunit datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml -n --preview --preview-workunits20 # 关闭上报 datahub ingest -c ./examples/recipes/example_to_datahub_rest.dhub.yaml --no-default-report # 只测试 source 连接 datahub ingest -c ./recipe.yml --test-source-connection4.2 关闭 Recipe 上报默认情况下 CLI 会把摄取报告含所用 Recipe发送给 DataHub可在 UI 中查看。若不想上报 Recipe 内容可在 Recipe 中增加reporting段并配合failure_log记录失败 JSONsource: # source configs sink: # sink configs # Add configuration for the datahub reporter reporting: - type: datahub config: report_recipe: false # Optional log to put failed JSONs into a file # Helpful in case you are trying to debug some issue with specific ingestion failing failure_log: enabled: false log_config: filename: ./path/to/failure.json4.3 运行状态查询与回滚datahub ingest list-source-runs列出历次运行展示 run ID、source 名、开始时间、状态与 URN支持--urn与--source过滤部分/完全匹配。datahub ingest list-runs列出近期摄取运行。datahub ingest show --run-id id查看某次运行的详情可用-a展示 aspect。datahub ingest rollback --run-id id回滚某次摄取删除该次运行创建的实体并回退被更新的 aspect支持-n干跑、--safe/--nuke模式与--report-dir报告目录。4.4 摄取流水线的底层原理从源码看datahub ingest的run命令ingest_cli.py的核心流程是通过load_config_file加载 Recipe支持 stdin、远程 URL、环境变量解析与__DATAHUB_TO_FILE_指令处理调用Pipeline.create(...)依据配置构建流水线——Pipeline类pipeline.py持有config、ctx、source、extractor、sink、transformers等核心组件调用pipeline.run()执行source 抽取元数据 → extractor 提取 → transformers 依次转换 → sink 写入最终通过pipeline.pretty_print_summary(...)输出运行总结--strict-warnings会把含 warning 的运行转为非零退出码。4.5 通过datahub ingest deploy将 Recipe 部署到 DataHub除了本地运行CLI 还支持datahub ingest deploy把 Recipe 上传到 DataHub 由 UI Ingestion 执行可同时配置调度或更新已有摄取源上传目标是 CLI 所连接的实例而非 Recipe 的 sink。核心选项--nameRecipe 名、--urn更新指定 URN 的摄取源、--scheduleCron 表达式、--time-zone时区默认 UTC、--executor-id路由到自定义远程执行器、--cli-version、--extra-pip、--extra-env。# 部署并设置每天 5 点伦敦时区执行 datahub ingest deploy --name Snowflake Integration --schedule 0 5 * * * --time-zone Europe/London -c recipe.yaml # 部署到指定远程执行器 datahub ingest deploy --name Remote Snowflake Integration --executor-id remote-executor-pool-1 --schedule 0 5 * * * -c recipe.yaml # 更新已有 Recipe注意这是全量更新未指定的选项会被移除 datahub ingest deploy --urn urn:li:dataHubIngestionSource:deploy-12345678 --schedule 0 6 * * * -c updated_recipe.yaml这些部署参数也可写在 Recipe 的deployment段中CLI 选项优先级更高deployment: name: Snowflake Integration schedule: 0 5 * * * time_zone: Europe/London executor_id: remote-executor-pool-1 # Optional cli_version: 0.15.0.1 # Optional extra_pip: [polars1.35.2] extra_env: VAR1value1,VAR2value2 source: ...批量部署场景下可通过 shell 组合对目录下所有 Recipe 逐一执行ls recipe_directory/*.yml | xargs -n 1 -I {} datahub ingest deploy -c {}五、调度摄取让元数据保持新鲜摄取既可以由管理员临时ad-hoc手动执行也可以安排周期重复执行——最常见的节奏是每天一次。由于源系统不断变化需要定期重新运行 Recipe 才能让这些变化反映到 DataHub 中。调度方式的选择取决于部署复杂度5.1 Apache Airflow推荐对于复杂部署官方推荐使用 Apache Airflow 之类的任务调度器将datahub ingest -c recipe.yml包装为 DAG 任务可获得失败重试、依赖编排、日志与监控等能力。5.2 CRON在更简单的部署中在一台常开机器上用 CRON 定时执行同样可行# 每天早上 8 点执行 MySQL 摄取 0 8 * * * cd /home/ubuntu/datahub_ingest datahub ingest -c mysql_to_datahub.yml5.3 Kubernetes CronJob若 DataHub 部署在 Kubernetes 中也可以使用 CronJob 容器化执行摄取详见 Kubernetes 调度文档。注意每个源系统需要单独的 Recipe 文件。这样既可以把不同源的摄取独立调度也可以组合到同一次调度中。更多调度方式Airflow、cron、Kubernetes、DataHub 内建调度的完整示例参见 Scheduling Ingestion Guide 及其下的 airflow.md、cron.md、datahub.md、kubernetes.md 分册。六、版本兼容性与升级注意版本号体系DataHub 服务端使用 3 位版本号CLI 使用 4 位版本号。例如服务端为 1.5.0 时应使用 CLI 1.5.0.7最后一位是补丁号。这是因为 CLI 的发布频率远高于服务端——CLI 补丁大约每周发布一次服务端大约每几个月发布一次。向后兼容窗口对于摄取源任何破坏性变更都会在 release notes 中标注。当字段被弃用或变更时官方会尽量维持两个服务端版本的向后兼容约 4-6 周CLI 在使用被弃用选项时也会打印警告。七、进阶参考CLI 摄取的进阶指引可继续阅读以下仓库内文档Reference fordatahub ingestcommand全部子命令与选项的权威参考UI Ingestion Guide在 UI 中配置并执行 Recipe 的图形化方式RecipesRecipe 的完整配置语法与高级主题环境变量、转换器、.dhub.yaml编辑器支持DataHub Sink referencedatahub-rest、datahub-kafka、datahub-lite三种 sink 的配置细节与失败行为Sources各数据源 source 的专属配置Sinks各 sink 类型概览示例 Recipe 集合覆盖 MySQL、MSSQL、Snowflake、BigQuery、Kafka、Tableau 等数十种现成配置【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
