从 dbt Core 导入元数据

本文档介绍了如何使用 gcloud 命令将元数据从 dbt Core 和 MetricFlow 导入 Knowledge Catalog（以前称为 Dataplex Universal Catalog）。

dbt 集成捕获的元数据如下：

  • 技术元数据：包括关键资源（来源、种子、 模型）及其技术属性（列名称、数据类型、行 数）。
  • 业务和语义元数据：由 dbt MetricFlow 提供支持，这 包括业务定义和逻辑，例如语义模型、指标 和已保存的查询。
  • 运营和数据质量元数据：包括执行 元数据，例如时间、成功或失败状态、数据新鲜度、测试 和测试结果。
  • 沿袭和关系元数据：包括转换 图 (DAG) 和 dbt 资源之间的依赖关系、跟踪和链接物理转换块的物理沿袭 、联接键和 动态联接以及父子关系。
  • 使用情况元数据：包括在映射 dbt 外部数据使用方式的曝光中捕获的元数据。

如需从 dbt Core 和 MetricFlow 导入元数据，请先完成以下任务：

  1. 授予所需的 角色和权限。
  2. 启用 Knowledge Catalog API。
  3. 满足 dbt 前提条件。
  4. 创建目标条目组 （如果尚不存在）。
  5. 了解 Cloud Storage 角色。

IAM 角色和权限

如需创建和管理 Knowledge Catalog 连接器作业，您需要 Identity and Access Management (IAM) 角色，这些角色可授予 Knowledge Catalog 和 Cloud Storage 的权限。

如需获得配置 dbt 连接器所需的权限，请让您的管理员为您授予以下 IAM 角色：

此外，您必须针对输出暂存 Cloud Storage 存储桶 (--storage-uri) 向 Knowledge Catalog 服务代理 (service-PROJECT_NUMBER@gcp-sa-dataplex.) 授予 Storage Object Viewer (roles/storage.objectViewer) 角色，以便导入作业可以读取暂存的元数据文件。

如需详细了解如何授予角色，请参阅管理 访问权限。

启用 API

启用 Knowledge Catalog API。

启用 API

dbt 前提条件

如需导入完整的 dbt 元数据集，我们建议生成所有四个 dbt JSON 制品文件。只需要 manifest.json；其他文件可以丰富导入内容，并且在没有这些文件的情况下，转换会正常降级：

  • manifest.json （必需）：核心项目结构和执行图。还包含 MetricFlow 语义模型、指标和已保存的查询。
  • catalog.json：列名称和数据类型。如果没有 catalog.json，则会导入具有无类型列的架构切面。
  • run_results.json：测试结果和执行元数据。
  • sources.json：来源新鲜度。

如需生成完整的 dbt 元数据制品 JSON 文件集，您可以按以下顺序执行 dbt 命令：

  1. dbt source freshness
  2. dbt build

  3. dbt docs generate --no-compile

了解 Cloud Storage 角色

导入 dbt 元数据涉及两个不同的 Cloud Storage 位置，它们具有不同的用途，不应混淆：

  • 输入（dbt 来源制品）：生成 dbt JSON 文件 所在的位置。这可以是机器或 CI 运行器上的本地目录路径 （例如 ./target/ 或 .），也可以是输入 Cloud Storage 存储桶 URI 前缀 （例如 gs://my-dbt-artifacts-bucket/target/）。您可以使用 --artifacts-path 标志提供此路径。gcloud 命令会在作业准备期间读取这些输入文件。如果使用 Cloud Storage，执行 gcloud 命令的调用方需要读取权限（roles/storage.objectViewer 或 roles/storage.objectAdmin）。Knowledge Catalog 服务代理不需要访问输入制品存储桶。
  • 输出（Knowledge Catalog 导入暂存存储桶）：Cloud Storage 存储桶 URI 前缀（例如 gs://my-staging-bucket/dbt-imports/），gcloud 命令会将转换后的元数据导入文件 (dbt_metadata.jsonl) 上传到该位置， Knowledge Catalog 导入作业会在提取期间从该位置读取文件。您可以使用 --storage-uri 标志提供此 URI。执行 gcloud 命令的调用方需要写入权限（roles/storage.objectCreator 或 roles/storage.objectAdmin）才能上传文件，Knowledge Catalog 服务代理需要读取权限 (roles/storage.objectViewer) 才能导入文件。

配置 dbt 连接

如需建立 dbt 连接，您必须先运行相应的 dbt 命令来生成元数据制品。JSON 文件存储并可访问后，您可以使用 gcloud alpha dataplex dbt metadata-jobs create 命令执行以下操作：

  1. 读取输入制品：从输入位置（本地目录或 --artifacts-path 中指定的 Cloud Storage URI）读取 dbt Core 和 MetricFlow 生成的 JSON 制品。
  2. 转换元数据：将内容转换为 Knowledge Catalog 元数据导入格式 (dbt_metadata.jsonl)。
  3. 上传到暂存区：将转换后的元数据导入文件上传到 输出暂存 Cloud Storage 位置，该位置在 --storage-uri 中指定。
  4. 触发导入作业：触发 Knowledge Catalog 元数据导入作业，该作业 指示 Knowledge Catalog 服务代理读取暂存的 元数据并将其注入到 Knowledge Catalog 资源中。--storage-uri

如需创建 dbt 元数据作业，请完成以下步骤：

  1. 确保 dbt 元数据制品文件存储在本地或输入 Cloud Storage 存储桶中。
  2. 确保您已配置输出暂存 Cloud Storage 存储桶，并为调用方和 Knowledge Catalog 服务代理配置了适当的权限。

  3. 从 Cloud Shell、本地终端或自动化工作流工具执行 gcloud 命令：

    gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/

    必需标志

    • --storage-uri=STORAGE_URI：（输出/暂存） Cloud Storage URI 前缀 (gs://bucket/path/)，转换后的 JSONL 会上传到该位置，导入作业会在提取期间从该位置读取文件。调用方必须具有写入权限（roles/storage.objectCreator 或 roles/storage.objectAdmin），Knowledge Catalog 服务代理必须具有读取权限 (roles/storage.objectViewer)。

    可选标志

    • --artifacts-path=ARTIFACTS_PATH：（输入） 来源 dbt 制品的路径。这可以是本地目录路径（例如 . 或 ./target），也可以是 Cloud Storage URI 前缀（例如 gs://my-bucket/dbt-artifacts/）。可以指向 dbt 项目根目录 （系统会自动检测 target/ 子目录），也可以直接指向 包含 manifest.json 的目录。默认值为 .。如果提供了 Cloud Storage URI，调用方必须具有对输入存储桶的读取权限（roles/storage.objectViewer 或 roles/storage.objectAdmin）。
    • --async：立即返回结果，而无需等待正在进行的操作完成。
    • --entry-group=ENTRY_GROUP：接收 dbt 条目的条目组的简短 ID。必须已存在于项目和位置中（默认值为 dbt-metadata-ingestion）。
    • --aspects-only：仅更新此 dbt 运行观察到的元数据，并保持条目组的其余部分不变。不会创建、删除或重新父级化任何条目，并且在此运行中缺少 dbt 制品的切面会保留之前运行赋予的值。将此用于例行重复提取。请参阅 重新运行提取。
    • --validate-only：构建并上传 JSON，验证元数据作业，但实际上不注入。

  4. 确认您收到了 Created 状态。

  5. 创建作业后，Knowledge Catalog 会根据您的配置安排首次运行，您也可以手动启动。

重新运行提取

首次导入后，大多数运行只需要刷新已存在资源的元数据。对于这些运行，请使用 --aspects-only。它只会更新 dbt 运行观察到的内容，并保持条目组中的所有其他内容不变，因此可以安全地按任何时间表重复运行，并且可以从多个作业运行。

当条目集发生更改时，运行完整提取 （省略 --aspects-only）：

  • 首次提取到条目组中。
  • 添加、重命名或删除 dbt 资源。
  • 条目的显示名称、说明或标签发生更改。
  • 条目层次结构发生更改。

完整运行会从磁盘上的制品重写每个条目的必需切面，因此请从流水线可以生成的最完整的制品集高效运转。

运行 --aspects-only 以进行例行刷新：

  • 在流水线运行的任何 dbt 命令之后：dbt build、dbt test、dbt source freshness 或 --select 缩小的重新构建。
  • 添加、移除、重新键入或重新描述列。
  • 模型 SQL 发生更改，并且运行还写入了 catalog.json。
  • 新的测试结果或来源新鲜度。

--aspects-only 可以添加和刷新元数据，但无法移除元数据。

搜索和查看 dbt 元数据

  1. 在 Google Cloud 控制台中，前往 Knowledge Catalog 搜索 页面。

    转到搜索

  2. 在过滤条件 面板中，您可以使用 项目、系统和类型别名部分来过滤 dbt 资产。在系统 部分中，选择导入的上下文 。选择此过滤条件会打开受管理的连接器 子部分。选择 dbt 以过滤所有 dbt 元数据。

  3. 您可以使用搜索字段执行搜索查询。您可以执行关键字搜索或自然语言搜索。例如，如需通过关键字搜索查看所有 dbt 资产，请输入 system=DBT。

    如需详细了解如何搜索资源，请参阅在 Knowledge Catalog中搜索资源。如需详细了解可在搜索字段中使用的 表达式，请参阅 Knowledge Catalog 的 搜索语法。

  4. 您还可以使用 LookupContext API 为特定 dbt 资源检索 LLM 上下文。

限制

  • 支持最新的 dbt Core v1 版本（已针对版本 1.11 和 1.12 进行验证）。不支持 dbt Core v2 和 dbt Fusion。
  • 不支持使用 模型版本控制 的 dbt 模型。
  • 不支持 dbt Cloud。
  • 非常大或深度嵌套的架构会被截断：单个切面不能超过每个切面的大小上限，因此深度嵌套的架构可能会丢失尾随字段。
  • --aspects-only 可以添加和刷新元数据，但无法移除元数据。 删除 dbt 资源需要完整运行。
  • 不支持条目链接。
  • 此集成仅支持 Data Lineage API 和图表中的 BigQuery 资源的 dbt 沿袭事件。外部第三方来源的 dbt 条目（来源、种子、模型）不会在数据沿袭中捕获。

后续步骤