DataHub LookML 元数据摄取实战指南从 Looker 到 DataHub 的三种接入方式与配置详解【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读本文基于 DataHub 开源仓库中的 LookML 摄取模块lookmlsource文档系统讲解如何将 Looker 的 LookML 模型、视图与字段元数据摄入 DataHub。你将掌握 UI、GitHub Action、CLI 三种摄取方式的选型与配置学会 GitHub Deploy Key、连接映射connection mapping、API 化血缘提取等关键前置条件并了解大视图字段拆分、Liquid 模板与 LookML 常量解析等生产环境高频场景的配置细节。一、LookML 摄取模块概述lookml模块是 DataHub 元数据摄取框架中的一个 source负责把 Looker 中由 LookMLLooker Modeling Language定义的模型model、视图view、字段field以及视图到上游数据仓库表/列的依赖关系摄取为 DataHub 中的 Dataset 实体。从源码结构看该模块位于 metadata-ingestion/src/datahub/ingestion/source/looker/核心入口为 lookml_source.py配置模型定义在 lookml_config.py。它被设计用于生产环境摄取工作流支持状态化摄取stateful ingestion与陈旧实体清理stale entity removal。摄取方式选型你有 3 种控制 LookML 摄取运行位置的方式方式适用场景特点DataHub UI开箱即用的最简体验官方推荐在 Web 界面配置源并手动/定时触发无需本地环境GitHub Action推送式集成官方推荐Looker 的 GitHub 仓库变更即触发摄取保证元数据最新鲜CLI通过 Airflow 等编排器调度可编程、可调度适合纳入现有数据管道下文分别展开这三种方式。二、UI 方式摄取 LookML 元数据要通过 UI 摄取 LookML 元数据必须先用下文「GitHub Deploy Key 配置」一节的方法为你的 Looker GitHub 仓库配置一个 deploy key。配置完成后进入 DataHub 的Ingestion页面按页面指引创建 LookML 类型的源并将 deploy key 的私钥内容填入GitHub Deploy Key字段即可。官方文档同时提供了一段视频演示如何通过 UI 摄取 LookML 元数据以及如何从 Looker 账号中找到相关信息。三、基于 GitHub Action 的推送式摄取如果你希望每次主 Looker GitHub 仓库发生变更时自动推送元数据可以使用 GitHub Action 方式。将下面的示例工作流文件放入 Looker GitHub 仓库的.github/workflows目录并在仓库中配置如下 SecretsDATAHUB_GMS_URLDataHub 服务端地址如http://datahub-gms:8080DATAHUB_GMS_TOKEN为 DataHub 摄取预置的认证 TokenLOOKER_BASE_URLLooker 资产所在的 base URL例如https://acryl.cloud.looker.comLOOKER_CLIENT_ID已申请的 Looker Client IDLOOKER_CLIENT_SECRET已申请的 Looker Client Secret示例工作流文件name: lookml metadata upload on: # 该 Action 只在推送到 main 分支时运行。 # 如果想在 pull request 上也运行建议用 --dry-run 标志执行 datahub ingest。 push: branches: - main release: types: [published, edited] workflow_dispatch: jobs: lookml-metadata-upload: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.10 - name: Run LookML ingestion run: | pip install acryl-datahub[lookml,datahub-rest] cat EOF lookml_ingestion.yml # LookML ingestion configuration. # This is a full ingestion recipe, and supports all config options that the LookML source supports. source: type: lookml config: base_folder: ${{ github.workspace }} parse_table_names_from_sql: true git_info: repo: ${{ github.repository }} branch: ${{ github.ref }} # Options #connection_to_platform_map: # connection-name: # platform: platform-name (e.g. snowflake) # default_db: default-db-name (e.g. DEMO_PIPELINE) api: client_id: ${LOOKER_CLIENT_ID} client_secret: ${LOOKER_CLIENT_SECRET} base_url: ${LOOKER_BASE_URL} # Enable API-based lineage extraction (required for field splitting features) use_api_for_view_lineage: true # Optional: Large view handling configuration # field_threshold_for_splitting: 100 # allow_partial_lineage_results: true # enable_individual_field_fallback: true # max_workers_for_parallel_processing: 10 sink: type: datahub-rest config: server: ${DATAHUB_GMS_URL} token: ${DATAHUB_GMS_TOKEN} EOF datahub ingest -c lookml_ingestion.yml env: DATAHUB_GMS_URL: ${{ secrets.DATAHUB_GMS_URL }} DATAHUB_GMS_TOKEN: ${{ secrets.DATAHUB_GMS_TOKEN }} LOOKER_BASE_URL: ${{ secrets.LOOKER_BASE_URL }} LOOKER_CLIENT_ID: ${{ secrets.LOOKER_CLIENT_ID }} LOOKER_CLIENT_SECRET: ${{ secrets.LOOKER_CLIENT_SECRET }}这份配置是一个完整的 ingestion recipelookml源支持的所有配置项都可以在其中使用。该工作流在以下三种情况下触发推送到main分支、发布 releasepublished/edited、手动触发workflow_dispatch从而保证元数据在仓库变更后保持新鲜。四、前置条件GitHub Deploy Key 与克隆超时无论使用 UI 摄取还是通过 CLI 自动 checkout GitHub 仓库都需要为 Looker 的 GitHub 仓库配置 deploy key。deploy key 的创建遵循 GitHub 官方 deploy key 管理文档核心为三步生成无 passphrase 的 SSH 密钥对生成looker_datahub_deploy_key与looker_datahub_deploy_key.pub两个文件将公钥添加到 Looker git 仓库配置为只读 deploy key保存私钥文件内容供 UI 摄取页面的GitHub Deploy Key字段使用或通过环境变量/Secret 传给 CLI 摄取。克隆超时配置默认情况下DataHub 允许 git clone 最多600 秒。如果仓库较大或网络较慢可以调大该值source: type: lookml config: git_info: repo: https://github.com/your-org/your-lookml-repo branch: main deploy_key: ${DEPLOY_KEY} clone_timeout: 900 # 单位秒设为 null 表示不设超时需要说明的是源码中GitInfo.clone_timeout的默认值为300 秒见 metadata-ingestion/src/datahub/configuration/git.py文档中 600 秒是更宽松的运行环境约定实际以你安装版本为准将其设为null可完全禁用超时。如果 clone 失败网络错误、SSH 配置错误、超时摄取会以清晰的错误条目停止而不是让整个 pipeline 崩溃。GitInfo还支持deploy_key_file指向包含私钥的文件与repo_ssh_locator自定义git clone的地址对 GitHub/GitLab 会自动推断并且deploy_key字段支持多行字符串自动修复换行见 git.py。五、连接映射让血缘精确指向上游数仓连接映射connection mapping通过把 Looker 连接名映射到平台与数据库实现到上游数据仓库的准确血缘。LookML 摄取要求配置中必须提供以下二者之一源码校验见 lookml_config.pyapi凭据Looker API 配置或connection_to_platform_map连接名到平台标识的映射。同时还要求提供project_name或api凭据之一见 lookml_config.py。方式一自动映射推荐提供具备 LookerAdmin权限的 API 凭据即可自动完成映射。创建方式按照 Looker API 认证文档创建一个 Client ID 与 Client Secret并确保该 API key 拥有Admin 权限。DataHub 会通过 Looker 的连接connectionAPI 自动读取连接定义见 looker_connection.py 中的get_connection_def_based_on_connection_string以及 looker_config.py 中对 BigQuery/通用平台的连接定义推导逻辑。方式二手动映射如果没有 admin API 凭据则需要在 recipe 中手动填充connection_to_platform_map与project_name。仓库自带的 starter recipe lookml_recipe.yml 给出了完整示例source: type: lookml config: # GitHub Coordinates: 用于本地 checkout 仓库并在 Dataset 实体页添加 github 链接 git_info: repo: org/repo-name deploy_key_file: ${LOOKER_DEPLOY_KEY_FILE} # 指向 looker git 仓库 deploy key 私钥的文件 # Coordinates # base_folder: /path/to/model/files ## 若无法提供 GitHub deploy key 则为可选 # Options api: # 你的 looker 实例地址 base_url: https://YOUR_INSTANCE.cloud.looker.com # 你的 Looker 连接凭据 client_id: ${LOOKER_CLIENT_ID} client_secret: ${LOOKER_CLIENT_SECRET} # 手动连接映射的替代方案 # project_name: PROJECT_NAME # connection_to_platform_map: # connection_name_1: # platform: snowflake # bigquery, hive, etc # default_db: DEFAULT_DATABASE. # 该连接配置的默认数据库 # default_schema: DEFAULT_SCHEMA # 该连接配置的默认 schema # platform_instance: snow_warehouse # 可选 # platform_env: PROD # 可选手动映射中每个连接可配置的字段包括platform如 snowflake、bigquery、hive 等、default_db、default_schema、可选的platform_instance与platform_env。从源码看platform/default_db/default_schema会被统一转小写处理platform_env仅允许prod/dev等枚举值见 looker_config.py。base_folder是纯文件式摄取的另一种输入方式当你不打算提供 GitHub deploy key 时可以指定一个已被 git clone 到本地的 LookML 仓库根目录存放*.model.lkml与*.view.lkml文件的根目录。注意git_info与base_folder至少要提供其一校验逻辑见 lookml_config.py若只提供git_info而没有 SSH key私有仓库将无法克隆。六、摄取核心能力与进阶配置6.1 API 化血缘提取与可达视图当use_api_for_view_lineage: true时DataHub 使用LookerQueryAPIBasedViewUpstream实现提取血缘。该方案使用 Looker API 的 SQL系统调用 Looker API 生成视图的完整解析后 SQL 语句再解析出列级与表级血缘比基于正则的解析更准确仅适用于可达视图Looker Query API 需要 explore 名称来生成 SQL因此该方法只对从 model 文件中定义的 explore 可达被至少一个 explore 直接或通过 join 引用的视图有效回退行为不可达的视图无法使用 API 方案会自动回退到基于正则的解析若emit_reachable_views_only: true默认不可达视图会被整体跳过。source: type: lookml config: # 启用基于 API 的血缘提取需要可达视图 use_api_for_view_lineage: true # 控制是否处理不可达视图 # 为 true默认时只处理被 explore 引用的视图 # 为 false 时处理所有视图但不可达视图使用正则解析 emit_reachable_views_only: true视图不可达时的行为emit_reachable_views_only: true跳过该视图并记录 warning源码通过report_unreachable_view_dropped上报见 lookml_config.pyemit_reachable_views_only: false视图改用正则解析处理血缘精度可能受限。另外源码中use_api_for_view_lineage: true时若未配置api凭据会直接报错提示见 lookml_config.py并支持通过use_api_cache_for_view_lineage: true启用 Looker API 服务端缓存。6.2 大视图100 字段的字段拆分处理对于字段数量较多的 Looker 视图100 字段DataHub 会自动启用字段拆分field splitting把大字段集拆成多个可管理的块并行处理后再合并结果以保证血缘提取的可靠性。字段拆分的触发条件缺一不可use_api_for_view_lineage: true已提供 Looker API 凭据api配置段视图字段数超过阈值默认 100无 API 配置时字段拆分不可用系统回退到基于正则的解析大视图可能解析失败。可配置项如下source: type: lookml config: base_folder: /path/to/lookml # API 配置字段拆分必需 api: base_url: https://your-instance.cloud.looker.com client_id: ${LOOKER_CLIENT_ID} client_secret: ${LOOKER_CLIENT_SECRET} # 启用基于 API 的血缘提取字段拆分必需 use_api_for_view_lineage: true # 可选启用 API 缓存提升性能 use_api_cache_for_view_lineage: true # 大视图处理配置 field_threshold_for_splitting: 100 # 字段数超过该值则拆分默认 100 allow_partial_lineage_results: true # 部分块失败时仍返回部分血缘默认 true enable_individual_field_fallback: true # 块失败时逐字段处理默认 true max_workers_for_parallel_processing: 10 # 并行处理的工作线程数默认 10上限 100各参数的调优建议field_threshold_for_splitting若 50-100 字段的视图出现 SQL 解析失败可降低阈值如 50若视图普遍 100 字段且想减少 API 调用可提高阈值如 150allow_partial_lineage_results默认true保证即使某些字段块解析失败也能拿到可用字段的血缘调试排障时可设false追求严格校验enable_individual_field_fallback块失败时逐个处理字段最大化血缘覆盖并定位问题字段若已知字段全部有效、想省去回退开销可设falsemax_workers_for_parallel_processing提高如 20-30可加速处理但占用更多系统资源遇到 API 限流则降低如 5设为 1 即串行处理便于调试。源码中该参数低于 1 会直接报错超过 100 会被自动截断为 100 并告警见 lookml_config.py。通过日志验证与排障拆分触发View view_name has X fields, exceeding threshold of Y. Splitting into multiple queries成功率统计Combined results for view view_name: X tables, Y column lineages, success rate: Z%问题字段日志中针对处理失败字段的 warning常见问题字段拆分不生效检查use_api_for_view_lineage: true与 API 凭据是否配置成功率低于 50%考虑降低field_threshold_for_splitting或排查问题字段API 限流降低max_workers_for_parallel_processing减少并发请求内存压力同样降低max_workers_for_parallel_processing。6.3 Liquid 模板与 LookML 常量解析Liquid 模板变量若视图包含 Liquid 模板例如sql_table_name: {{ user_attributes[db] }}.kafka_streaming.events其中dbANALYTICS_PROD需要在liquid_variables配置中指定变量值liquid_variables: user_attributes: db: ANALYTICS_PRODLookML 常量若视图包含 LookML 常量例如sql_table_name: {db}.kafka_streaming.events;摄取会尝试从项目manifest.lkml文件中解析其值manifest.lkml constant: db { value: ANALYTICS_PROD }如果常量解析不到或解析错误可在 recipe 中通过lookml_constants显式指定——recipe 中的常量值优先于 manifest 解析结果lookml_constants: db: ANALYTICS_PROD支持范围限制支持简单变量插值{{ var }}与条件指令{% condition filter_name %} field {% endcondition %}不支持带if/else/endif的条件逻辑以及date_start、date_end、parameter等自定义 Looker 标签。重要提示不支持的模板可能导致部分资产的 lineage 提取失败。虽然 Liquid 变量与 LookML 常量可以出现在 LookML 代码的任何位置但 DataHub 目前只对 LookML 视图解析它们的值——由于 LookML 摄取只处理视图及其上游依赖这一行为已足够。6.4 多项目 LookML高级Looker 项目可以组织为多个 git 仓库并通过 remote include 引用存储在其他仓库中的项目。多项目场景下LookML 文件中会出现类似include: //e_flights/views/users.view.lkml的指令manifest.lkml中也会列出被引用的项目project_name: this_project local_dependency: { project: my-remote-project } remote_dependency: ga_360_block { url: https://github.com/llooker/google_ga360 ref: 0bbbef5d8080e88ade2747230b7ed62418437c21 }要摄取包含其他项目文件的 Looker 仓库需在配置中使用project_dependencies指令。例如主项目引用了托管在 GitHub 仓库my_org/my_remote_project的远程项目my_remote_project且已配置 deploy key 并存于环境变量或 UI Secret${MY_REMOTE_PROJECT_DEPLOY_KEY}则可以这样配置source: type: lookml config: ... other config variables project_dependencies: my_remote_project: repo: my_org/my_remote_project deploy_key: ${MY_REMOTE_PROJECT_DEPLOY_KEY}底层实现上DataHub 会使用提供的 deploy key checkout 你的远程仓库并用它解析主项目 model 文件中的 include。如果你的远程项目已在本地 checkout、不需要 DataHub 代为克隆也可以直接提供本地路径source: type: lookml config: ... other config variables project_dependencies: my_remote_project: /path/to/local_git_clone_of_remote_project:::note 这与把远程项目作为主 Looker 项目摄取不是一回事DataHub 不会处理远程项目中可能存在的 model 文件。如果还想额外摄取远程项目 model 中可访问的视图请再建一个以远程项目为主项目的 recipe。 :::从源码看project_dependencies是「项目名 → 本地目录或 Git 凭据」的映射所有在manifest.lkml中列出的local_dependencies或私有remote_dependencies都应有对应条目若未提供 deploy key会复用主项目的 deploy key见 lookml_config.py。七、排障指南7.1 仓库克隆失败或超时症状摄取的 Errors 中出现Failed to clone LookML repository错误上下文包含GitCommandError、ssh: not found、Connection refused或exit code(128)。解决方案SSH/deploy key 未配置——确保在git_info中通过deploy_key或deploy_key_file提供了公钥已加入仓库的 deploy key或个人 SSH key22 端口被封——若环境屏蔽出站 SSH22 端口无法用gitgithub.com克隆可改用带 personal access token 的 HTTPS通过repo_ssh_locator或换一个允许 SSH 的网络运行摄取大仓库克隆超时——调大clone_timeout默认 600 sgit_info: repo: https://github.com/your-org/your-lookml-repo deploy_key: ${DEPLOY_KEY} clone_timeout: 900手动验证 SSH 连通性——在运行摄取的主机上执行ssh -T gitgithub.com成功响应形如Hi user! Youve successfully authenticated…。7.2 LookML 解析错误排查如果日志出现类似my_file.view.lkml: failed to load view file: Unable to find a matching expression for literal on line 5的消息说明 LookML 文件解析失败。首先确认 Looker IDE 能在开发模式下通过Validate LookML校验该文件。若 IDE 校验正常则可能是 DataHub 使用的解析器基于 joshtemple/lkml 库比 Looker 官方解析器略严格——目前已知的差异仅有一处与块中使用前导冒号leading colons in blocks有关。可以使用lkmlCLI 工具验证 DataHub 能否解析你的 LookML 文件pip install lkml lkml path/to/my_file.view.lkml若该命令抛出异常DataHub 解析该文件时也会失败。八、总结从文档到源码的完整摄取链路回顾整条链路LookML 摄取以git_info/base_folder获取 LookML 代码 → 解析 model/view 文件含process_refinements视图细化、Liquid 模板与常量解析→ 通过connection_to_platform_map或 Looker API 解析连接定义 → 生成视图 Dataset 与列级血缘正则解析或LookerQueryAPIBasedViewUpstreamAPI 化解析→ 经 datahub-rest sink 写入 DataHub。配置校验层面lookml_config.py 内置了五重 pydantic 校验连接映射或 API 必须二选一、项目名或 API 必须二选一、启用 API 血缘必须有 API 凭据、必须有base_folder或git_info、并行 worker 数必须在 1-100 区间。理解这些校验规则可以帮助你在写 recipe 时一步到位避免运行时才暴露配置错误。更多能力说明与故障排查细节可继续阅读同模块的 lookml_post.md 与完整示例 lookml_recipe.yml。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 0:13:18 · 阅读 1.2k DataHub LookML 元数据摄取实战指南：从 Looker 到 DataHub 的三种接入方式与配置详解
DataHub LookML 元数据摄取实战指南从 Looker 到 DataHub 的三种接入方式与配置详解【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读本文基于 DataHub 开源仓库中的 LookML 摄取模块lookmlsource文档系统讲解如何将 Looker 的 LookML 模型、视图与字段元数据摄入 DataHub。你将掌握 UI、GitHub Action、CLI 三种摄取方式的选型与配置学会 GitHub Deploy Key、连接映射connection mapping、API 化血缘提取等关键前置条件并了解大视图字段拆分、Liquid 模板与 LookML 常量解析等生产环境高频场景的配置细节。一、LookML 摄取模块概述lookml模块是 DataHub 元数据摄取框架中的一个 source负责把 Looker 中由 LookMLLooker Modeling Language定义的模型model、视图view、字段field以及视图到上游数据仓库表/列的依赖关系摄取为 DataHub 中的 Dataset 实体。从源码结构看该模块位于 metadata-ingestion/src/datahub/ingestion/source/looker/核心入口为 lookml_source.py配置模型定义在 lookml_config.py。它被设计用于生产环境摄取工作流支持状态化摄取stateful ingestion与陈旧实体清理stale entity removal。摄取方式选型你有 3 种控制 LookML 摄取运行位置的方式方式适用场景特点DataHub UI开箱即用的最简体验官方推荐在 Web 界面配置源并手动/定时触发无需本地环境GitHub Action推送式集成官方推荐Looker 的 GitHub 仓库变更即触发摄取保证元数据最新鲜CLI通过 Airflow 等编排器调度可编程、可调度适合纳入现有数据管道下文分别展开这三种方式。二、UI 方式摄取 LookML 元数据要通过 UI 摄取 LookML 元数据必须先用下文「GitHub Deploy Key 配置」一节的方法为你的 Looker GitHub 仓库配置一个 deploy key。配置完成后进入 DataHub 的Ingestion页面按页面指引创建 LookML 类型的源并将 deploy key 的私钥内容填入GitHub Deploy Key字段即可。官方文档同时提供了一段视频演示如何通过 UI 摄取 LookML 元数据以及如何从 Looker 账号中找到相关信息。三、基于 GitHub Action 的推送式摄取如果你希望每次主 Looker GitHub 仓库发生变更时自动推送元数据可以使用 GitHub Action 方式。将下面的示例工作流文件放入 Looker GitHub 仓库的.github/workflows目录并在仓库中配置如下 SecretsDATAHUB_GMS_URLDataHub 服务端地址如http://datahub-gms:8080DATAHUB_GMS_TOKEN为 DataHub 摄取预置的认证 TokenLOOKER_BASE_URLLooker 资产所在的 base URL例如https://acryl.cloud.looker.comLOOKER_CLIENT_ID已申请的 Looker Client IDLOOKER_CLIENT_SECRET已申请的 Looker Client Secret示例工作流文件name: lookml metadata upload on: # 该 Action 只在推送到 main 分支时运行。 # 如果想在 pull request 上也运行建议用 --dry-run 标志执行 datahub ingest。 push: branches: - main release: types: [published, edited] workflow_dispatch: jobs: lookml-metadata-upload: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.10 - name: Run LookML ingestion run: | pip install acryl-datahub[lookml,datahub-rest] cat EOF lookml_ingestion.yml # LookML ingestion configuration. # This is a full ingestion recipe, and supports all config options that the LookML source supports. source: type: lookml config: base_folder: ${{ github.workspace }} parse_table_names_from_sql: true git_info: repo: ${{ github.repository }} branch: ${{ github.ref }} # Options #connection_to_platform_map: # connection-name: # platform: platform-name (e.g. snowflake) # default_db: default-db-name (e.g. DEMO_PIPELINE) api: client_id: ${LOOKER_CLIENT_ID} client_secret: ${LOOKER_CLIENT_SECRET} base_url: ${LOOKER_BASE_URL} # Enable API-based lineage extraction (required for field splitting features) use_api_for_view_lineage: true # Optional: Large view handling configuration # field_threshold_for_splitting: 100 # allow_partial_lineage_results: true # enable_individual_field_fallback: true # max_workers_for_parallel_processing: 10 sink: type: datahub-rest config: server: ${DATAHUB_GMS_URL} token: ${DATAHUB_GMS_TOKEN} EOF datahub ingest -c lookml_ingestion.yml env: DATAHUB_GMS_URL: ${{ secrets.DATAHUB_GMS_URL }} DATAHUB_GMS_TOKEN: ${{ secrets.DATAHUB_GMS_TOKEN }} LOOKER_BASE_URL: ${{ secrets.LOOKER_BASE_URL }} LOOKER_CLIENT_ID: ${{ secrets.LOOKER_CLIENT_ID }} LOOKER_CLIENT_SECRET: ${{ secrets.LOOKER_CLIENT_SECRET }}这份配置是一个完整的 ingestion recipelookml源支持的所有配置项都可以在其中使用。该工作流在以下三种情况下触发推送到main分支、发布 releasepublished/edited、手动触发workflow_dispatch从而保证元数据在仓库变更后保持新鲜。四、前置条件GitHub Deploy Key 与克隆超时无论使用 UI 摄取还是通过 CLI 自动 checkout GitHub 仓库都需要为 Looker 的 GitHub 仓库配置 deploy key。deploy key 的创建遵循 GitHub 官方 deploy key 管理文档核心为三步生成无 passphrase 的 SSH 密钥对生成looker_datahub_deploy_key与looker_datahub_deploy_key.pub两个文件将公钥添加到 Looker git 仓库配置为只读 deploy key保存私钥文件内容供 UI 摄取页面的GitHub Deploy Key字段使用或通过环境变量/Secret 传给 CLI 摄取。克隆超时配置默认情况下DataHub 允许 git clone 最多600 秒。如果仓库较大或网络较慢可以调大该值source: type: lookml config: git_info: repo: https://github.com/your-org/your-lookml-repo branch: main deploy_key: ${DEPLOY_KEY} clone_timeout: 900 # 单位秒设为 null 表示不设超时需要说明的是源码中GitInfo.clone_timeout的默认值为300 秒见 metadata-ingestion/src/datahub/configuration/git.py文档中 600 秒是更宽松的运行环境约定实际以你安装版本为准将其设为null可完全禁用超时。如果 clone 失败网络错误、SSH 配置错误、超时摄取会以清晰的错误条目停止而不是让整个 pipeline 崩溃。GitInfo还支持deploy_key_file指向包含私钥的文件与repo_ssh_locator自定义git clone的地址对 GitHub/GitLab 会自动推断并且deploy_key字段支持多行字符串自动修复换行见 git.py。五、连接映射让血缘精确指向上游数仓连接映射connection mapping通过把 Looker 连接名映射到平台与数据库实现到上游数据仓库的准确血缘。LookML 摄取要求配置中必须提供以下二者之一源码校验见 lookml_config.pyapi凭据Looker API 配置或connection_to_platform_map连接名到平台标识的映射。同时还要求提供project_name或api凭据之一见 lookml_config.py。方式一自动映射推荐提供具备 LookerAdmin权限的 API 凭据即可自动完成映射。创建方式按照 Looker API 认证文档创建一个 Client ID 与 Client Secret并确保该 API key 拥有Admin 权限。DataHub 会通过 Looker 的连接connectionAPI 自动读取连接定义见 looker_connection.py 中的get_connection_def_based_on_connection_string以及 looker_config.py 中对 BigQuery/通用平台的连接定义推导逻辑。方式二手动映射如果没有 admin API 凭据则需要在 recipe 中手动填充connection_to_platform_map与project_name。仓库自带的 starter recipe lookml_recipe.yml 给出了完整示例source: type: lookml config: # GitHub Coordinates: 用于本地 checkout 仓库并在 Dataset 实体页添加 github 链接 git_info: repo: org/repo-name deploy_key_file: ${LOOKER_DEPLOY_KEY_FILE} # 指向 looker git 仓库 deploy key 私钥的文件 # Coordinates # base_folder: /path/to/model/files ## 若无法提供 GitHub deploy key 则为可选 # Options api: # 你的 looker 实例地址 base_url: https://YOUR_INSTANCE.cloud.looker.com # 你的 Looker 连接凭据 client_id: ${LOOKER_CLIENT_ID} client_secret: ${LOOKER_CLIENT_SECRET} # 手动连接映射的替代方案 # project_name: PROJECT_NAME # connection_to_platform_map: # connection_name_1: # platform: snowflake # bigquery, hive, etc # default_db: DEFAULT_DATABASE. # 该连接配置的默认数据库 # default_schema: DEFAULT_SCHEMA # 该连接配置的默认 schema # platform_instance: snow_warehouse # 可选 # platform_env: PROD # 可选手动映射中每个连接可配置的字段包括platform如 snowflake、bigquery、hive 等、default_db、default_schema、可选的platform_instance与platform_env。从源码看platform/default_db/default_schema会被统一转小写处理platform_env仅允许prod/dev等枚举值见 looker_config.py。base_folder是纯文件式摄取的另一种输入方式当你不打算提供 GitHub deploy key 时可以指定一个已被 git clone 到本地的 LookML 仓库根目录存放*.model.lkml与*.view.lkml文件的根目录。注意git_info与base_folder至少要提供其一校验逻辑见 lookml_config.py若只提供git_info而没有 SSH key私有仓库将无法克隆。六、摄取核心能力与进阶配置6.1 API 化血缘提取与可达视图当use_api_for_view_lineage: true时DataHub 使用LookerQueryAPIBasedViewUpstream实现提取血缘。该方案使用 Looker API 的 SQL系统调用 Looker API 生成视图的完整解析后 SQL 语句再解析出列级与表级血缘比基于正则的解析更准确仅适用于可达视图Looker Query API 需要 explore 名称来生成 SQL因此该方法只对从 model 文件中定义的 explore 可达被至少一个 explore 直接或通过 join 引用的视图有效回退行为不可达的视图无法使用 API 方案会自动回退到基于正则的解析若emit_reachable_views_only: true默认不可达视图会被整体跳过。source: type: lookml config: # 启用基于 API 的血缘提取需要可达视图 use_api_for_view_lineage: true # 控制是否处理不可达视图 # 为 true默认时只处理被 explore 引用的视图 # 为 false 时处理所有视图但不可达视图使用正则解析 emit_reachable_views_only: true视图不可达时的行为emit_reachable_views_only: true跳过该视图并记录 warning源码通过report_unreachable_view_dropped上报见 lookml_config.pyemit_reachable_views_only: false视图改用正则解析处理血缘精度可能受限。另外源码中use_api_for_view_lineage: true时若未配置api凭据会直接报错提示见 lookml_config.py并支持通过use_api_cache_for_view_lineage: true启用 Looker API 服务端缓存。6.2 大视图100 字段的字段拆分处理对于字段数量较多的 Looker 视图100 字段DataHub 会自动启用字段拆分field splitting把大字段集拆成多个可管理的块并行处理后再合并结果以保证血缘提取的可靠性。字段拆分的触发条件缺一不可use_api_for_view_lineage: true已提供 Looker API 凭据api配置段视图字段数超过阈值默认 100无 API 配置时字段拆分不可用系统回退到基于正则的解析大视图可能解析失败。可配置项如下source: type: lookml config: base_folder: /path/to/lookml # API 配置字段拆分必需 api: base_url: https://your-instance.cloud.looker.com client_id: ${LOOKER_CLIENT_ID} client_secret: ${LOOKER_CLIENT_SECRET} # 启用基于 API 的血缘提取字段拆分必需 use_api_for_view_lineage: true # 可选启用 API 缓存提升性能 use_api_cache_for_view_lineage: true # 大视图处理配置 field_threshold_for_splitting: 100 # 字段数超过该值则拆分默认 100 allow_partial_lineage_results: true # 部分块失败时仍返回部分血缘默认 true enable_individual_field_fallback: true # 块失败时逐字段处理默认 true max_workers_for_parallel_processing: 10 # 并行处理的工作线程数默认 10上限 100各参数的调优建议field_threshold_for_splitting若 50-100 字段的视图出现 SQL 解析失败可降低阈值如 50若视图普遍 100 字段且想减少 API 调用可提高阈值如 150allow_partial_lineage_results默认true保证即使某些字段块解析失败也能拿到可用字段的血缘调试排障时可设false追求严格校验enable_individual_field_fallback块失败时逐个处理字段最大化血缘覆盖并定位问题字段若已知字段全部有效、想省去回退开销可设falsemax_workers_for_parallel_processing提高如 20-30可加速处理但占用更多系统资源遇到 API 限流则降低如 5设为 1 即串行处理便于调试。源码中该参数低于 1 会直接报错超过 100 会被自动截断为 100 并告警见 lookml_config.py。通过日志验证与排障拆分触发View view_name has X fields, exceeding threshold of Y. Splitting into multiple queries成功率统计Combined results for view view_name: X tables, Y column lineages, success rate: Z%问题字段日志中针对处理失败字段的 warning常见问题字段拆分不生效检查use_api_for_view_lineage: true与 API 凭据是否配置成功率低于 50%考虑降低field_threshold_for_splitting或排查问题字段API 限流降低max_workers_for_parallel_processing减少并发请求内存压力同样降低max_workers_for_parallel_processing。6.3 Liquid 模板与 LookML 常量解析Liquid 模板变量若视图包含 Liquid 模板例如sql_table_name: {{ user_attributes[db] }}.kafka_streaming.events其中dbANALYTICS_PROD需要在liquid_variables配置中指定变量值liquid_variables: user_attributes: db: ANALYTICS_PRODLookML 常量若视图包含 LookML 常量例如sql_table_name: {db}.kafka_streaming.events;摄取会尝试从项目manifest.lkml文件中解析其值manifest.lkml constant: db { value: ANALYTICS_PROD }如果常量解析不到或解析错误可在 recipe 中通过lookml_constants显式指定——recipe 中的常量值优先于 manifest 解析结果lookml_constants: db: ANALYTICS_PROD支持范围限制支持简单变量插值{{ var }}与条件指令{% condition filter_name %} field {% endcondition %}不支持带if/else/endif的条件逻辑以及date_start、date_end、parameter等自定义 Looker 标签。重要提示不支持的模板可能导致部分资产的 lineage 提取失败。虽然 Liquid 变量与 LookML 常量可以出现在 LookML 代码的任何位置但 DataHub 目前只对 LookML 视图解析它们的值——由于 LookML 摄取只处理视图及其上游依赖这一行为已足够。6.4 多项目 LookML高级Looker 项目可以组织为多个 git 仓库并通过 remote include 引用存储在其他仓库中的项目。多项目场景下LookML 文件中会出现类似include: //e_flights/views/users.view.lkml的指令manifest.lkml中也会列出被引用的项目project_name: this_project local_dependency: { project: my-remote-project } remote_dependency: ga_360_block { url: https://github.com/llooker/google_ga360 ref: 0bbbef5d8080e88ade2747230b7ed62418437c21 }要摄取包含其他项目文件的 Looker 仓库需在配置中使用project_dependencies指令。例如主项目引用了托管在 GitHub 仓库my_org/my_remote_project的远程项目my_remote_project且已配置 deploy key 并存于环境变量或 UI Secret${MY_REMOTE_PROJECT_DEPLOY_KEY}则可以这样配置source: type: lookml config: ... other config variables project_dependencies: my_remote_project: repo: my_org/my_remote_project deploy_key: ${MY_REMOTE_PROJECT_DEPLOY_KEY}底层实现上DataHub 会使用提供的 deploy key checkout 你的远程仓库并用它解析主项目 model 文件中的 include。如果你的远程项目已在本地 checkout、不需要 DataHub 代为克隆也可以直接提供本地路径source: type: lookml config: ... other config variables project_dependencies: my_remote_project: /path/to/local_git_clone_of_remote_project:::note 这与把远程项目作为主 Looker 项目摄取不是一回事DataHub 不会处理远程项目中可能存在的 model 文件。如果还想额外摄取远程项目 model 中可访问的视图请再建一个以远程项目为主项目的 recipe。 :::从源码看project_dependencies是「项目名 → 本地目录或 Git 凭据」的映射所有在manifest.lkml中列出的local_dependencies或私有remote_dependencies都应有对应条目若未提供 deploy key会复用主项目的 deploy key见 lookml_config.py。七、排障指南7.1 仓库克隆失败或超时症状摄取的 Errors 中出现Failed to clone LookML repository错误上下文包含GitCommandError、ssh: not found、Connection refused或exit code(128)。解决方案SSH/deploy key 未配置——确保在git_info中通过deploy_key或deploy_key_file提供了公钥已加入仓库的 deploy key或个人 SSH key22 端口被封——若环境屏蔽出站 SSH22 端口无法用gitgithub.com克隆可改用带 personal access token 的 HTTPS通过repo_ssh_locator或换一个允许 SSH 的网络运行摄取大仓库克隆超时——调大clone_timeout默认 600 sgit_info: repo: https://github.com/your-org/your-lookml-repo deploy_key: ${DEPLOY_KEY} clone_timeout: 900手动验证 SSH 连通性——在运行摄取的主机上执行ssh -T gitgithub.com成功响应形如Hi user! Youve successfully authenticated…。7.2 LookML 解析错误排查如果日志出现类似my_file.view.lkml: failed to load view file: Unable to find a matching expression for literal on line 5的消息说明 LookML 文件解析失败。首先确认 Looker IDE 能在开发模式下通过Validate LookML校验该文件。若 IDE 校验正常则可能是 DataHub 使用的解析器基于 joshtemple/lkml 库比 Looker 官方解析器略严格——目前已知的差异仅有一处与块中使用前导冒号leading colons in blocks有关。可以使用lkmlCLI 工具验证 DataHub 能否解析你的 LookML 文件pip install lkml lkml path/to/my_file.view.lkml若该命令抛出异常DataHub 解析该文件时也会失败。八、总结从文档到源码的完整摄取链路回顾整条链路LookML 摄取以git_info/base_folder获取 LookML 代码 → 解析 model/view 文件含process_refinements视图细化、Liquid 模板与常量解析→ 通过connection_to_platform_map或 Looker API 解析连接定义 → 生成视图 Dataset 与列级血缘正则解析或LookerQueryAPIBasedViewUpstreamAPI 化解析→ 经 datahub-rest sink 写入 DataHub。配置校验层面lookml_config.py 内置了五重 pydantic 校验连接映射或 API 必须二选一、项目名或 API 必须二选一、启用 API 血缘必须有 API 凭据、必须有base_folder或git_info、并行 worker 数必须在 1-100 区间。理解这些校验规则可以帮助你在写 recipe 时一步到位避免运行时才暴露配置错误。更多能力说明与故障排查细节可继续阅读同模块的 lookml_post.md 与完整示例 lookml_recipe.yml。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考