自 2026 年 4 月 10 日起，Dataplex Universal Catalog 更名为 Knowledge Catalog。API、客户端库、CLI 和 IAM 名称保持不变。如需了解详情，请参阅 Google Cloud Knowledge Catalog 简介。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

从 dbt Core 导入元数据

对于数据工程师、分析工程师和数据管家而言，集中管理元数据对于企业数据发现和治理至关重要。当团队使用 dbt 进行数据转换时，会生成有价值的运营、语义和谱系元数据，但这些元数据通常仍孤立于 dbt 生态系统内。

如需将这些信息集成到集中式目录中，您可以将 dbt Core、dbt Cloud 和 MetricFlow 中的元数据导入 Knowledge Catalog（以前称为 Dataplex Universal Catalog）。

由于 dbt Core 充当转换引擎，而不是像 Oracle 或 PostgreSQL 这样的存储系统，因此导入其元数据可实现不同的使用情形。您可以导入 Oracle 或 PostgreSQL 元数据来回答“我们有哪些原始数据？”这个问题，还可以导入 dbt Core 元数据来回答“我们的数据是如何转换的？是否可靠？对业务有何意义？”这个问题。

本文档介绍了如何使用 Google Cloud CLI 命令和 dbt 制品文件导入元数据。

运行 dbt 集成时，您会捕获以下元数据：

技术元数据：通过探索关键资源（来源、种子、模型）及其技术属性（列名称、数据类型、行数）来发现企业数据。
业务和语义元数据：通过探索由 dbt MetricFlow 提供支持的业务定义和逻辑（例如语义模型、指标和已保存的查询），为 BI 工具和 AI 智能体提供上下文。
运营和数据质量元数据：通过探索执行元数据（例如时间、成功或失败状态、数据新鲜度和测试结果）来监控流水线健康状况并排查数据问题。
沿袭和关系元数据：通过探索转换图 (DAG) 和 dbt 资源之间的依赖关系、跟踪和关联物理转换块的物理沿袭、联接键和动态联接以及父子关系，实现下游影响分析和根本原因追溯。
使用情况元数据：通过探索曝光中的元数据（这些元数据可映射 dbt 外部的数据使用方式），排查下游应用使用转换后数据时出现的问题。

限制

支持 dbt Core v1（已针对版本 1.11 和 1.12 进行验证）、dbt Core v2 和 dbt Fusion。
gcloud CLI 586.0.0 版及更高版本支持 dbt 和 BigQuery 集成。如需安装或更新该 CLI，请参阅安装 Google Cloud CLI。
没有直接连接到 dbt Cloud。如需从 dbt Cloud 作业导入元数据，请先获取该作业的制品。请参阅从 dbt Cloud 运行中导入元数据。
过大或嵌套过深的架构会被截断：单个方面不能超过每个方面的尺寸上限，因此嵌套过深的架构可能会丢失尾随字段。
--aspects-only 可以添加和刷新元数据，但无法移除元数据。删除 dbt 资源需要完整运行。
此集成仅支持 Data Lineage API 和图表中 BigQuery 资源上的 dbt 血缘事件。外部第三方来源的 dbt 条目（来源、种子、模型）不会捕获在数据血缘中。
- 如需在 Data Lineage API 中注入所有 dbt 沿袭事件，请使用 OpenLineage dbt 集成。然后，将 OpenLineage 与 Knowledge Catalog 集成，以从 dbt 导入和可视化数据沿袭。

准备工作

在从 dbt Core 和 MetricFlow 导入元数据之前，请完成以下任务：

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

IAM 角色和权限

如需创建和管理知识目录连接器作业，您需要 Identity and Access Management (IAM) 角色，该角色可授予知识目录和 Cloud Storage 的权限。

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

如需创建和管理条目组及条目链接，您需要拥有项目的 Dataplex Catalog Admin (roles/dataplex.catalogAdmin)、Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) 角色。
如需执行 dbt gcloud 命令并创建元数据导入作业，请遵循最小权限原则并授予以下角色：
- 针对项目的 Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) 角色。
- 针对目标条目组或项目的 Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter)。如果您还导入条目链接，请改为授予项目的 Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) 角色。此外，还要向每个包含 dbt 模型写入到的 BigQuery 表的项目授予 Dataplex Entry Owner (roles/dataplex.entryOwner) 角色。对于自定义角色，入口链接权限为 dataplex.entryGroups.useReferenceEntryLink、dataplex.entryGroups.useSchemaJoinEntryLink 和 dataplex.entryLinks.reference。
或者，您可以授予项目的 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色和 Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) 角色。
如需将转换后的元数据上传到输出暂存存储桶 (--storage-uri)，请在暂存存储桶上授予以下权限：Storage Object Creator (roles/storage.objectCreator) 或 Storage Object Admin (roles/storage.objectAdmin)。
如需从输入 Cloud Storage 存储桶（如果使用 Cloud Storage，则为 --artifacts-path）读取 dbt 制品，请对输入制品存储桶授予 Storage Object Viewer (roles/storage.objectViewer) 或 Storage Object Admin (roles/storage.objectAdmin) 角色。如果您拥有 Storage Object Admin 角色，则不需要 Storage Object Viewer 角色。
如需查看 dbt 元数据，请为项目授予 Dataplex Catalog Viewer (roles/dataplex.catalogViewer) 角色。
如需在 Cloud Logging 中查看日志，请确保您拥有项目的 Logs Viewer (roles/logging.viewer) 角色。

如果您拥有在项目中管理 IAM 访问权限所需的权限，则可以运行以下 gcloud 命令，向自己的用户账号授予这些角色：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

如果您使用服务账号（例如在自动化 CI/CD 流水线中）运行导入，则可以通过运行以下 gcloud 命令向服务账号授予这些角色：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

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

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
USER_EMAIL：您的用户账号电子邮件地址。
SERVICE_ACCOUNT_EMAIL：您的服务账号电子邮件地址。
STAGING_BUCKET：输出暂存 Cloud Storage 存储桶的名称 (--storage-uri)。
PROJECT_NUMBER：您的 Google Cloud 项目编号。

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

启用 API

启用 Knowledge Catalog API。

启用 API

dbt 前提条件

为了导入完整的 dbt 元数据，我们建议生成所有四个 dbt JSON 制品文件。仅 manifest.json 是必需的；其他参数可丰富导入功能，即使没有这些参数，转换功能也能正常运行：

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

在安装了 dbt 的本地终端、Cloud Shell 或自动化 CI/CD 环境中，前往 dbt 项目根目录，然后针对单个配置文件和目标按顺序执行以下 dbt 命令，以生成完整的 dbt 元数据制品 JSON 文件集：

对于 dbt Core 2.x 和 dbt Fusion：
1. dbt source freshness
2. dbt build
3. dbt parse --write-catalog
  
  警告：请勿在 dbt Core 2.x 或 dbt Fusion 上使用 dbt docs generate。它不会写入 catalog.json，并且会覆盖 run_results.json，但没有任何测试结果。dbt build --write-catalog 也不写入目录，因此请使用单独的 dbt parse --write-catalog 步骤。
对于 dbt Core 1.x（其中 dbt parse 不写入目录）：
1. dbt source freshness
2. dbt build
3. dbt docs generate --no-compile
  
  警告：如果没有 --no-compile，dbt docs generate 会将每个节点的 run_results.json 覆盖为 success 状态。dbt build中的测试结果会丢失，并且目录会将所有数据质量测试报告为通过。

了解 Cloud Storage 角色

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

输入（dbt 源制品）：生成 dbt JSON 文件所在的位置。此路径可以是您机器或 CI Runner（例如 ./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）才能上传文件，而知识目录服务代理需要拥有读取权限 (roles/storage.objectViewer) 才能导入文件。

从 dbt Cloud 运行中导入元数据

Knowledge Catalog 不会直接连接到 dbt Cloud。由于 dbt Cloud 作业生成的制品文件与 dbt Core 相同，因此您可以通过将这些制品文件检索到本地目录或输入 Cloud Storage 存储桶并运行 gcloud 命令，从 dbt Cloud 导入元数据。

在检索制品之前，请配置 dbt Cloud 作业以生成完整的制品集。然后，您可以使用以下方法之一从 dbt Cloud 作业运行中检索制品文件：

从 dbt Cloud 控制台下载制品：从 dbt Cloud 界面中的作业运行详情页面手动下载制品文件，以进行一次性导入或初始测试。
使用 dbt 平台 CLI 下载制品：在本地终端上对 dbt Cloud 执行 dbt 命令，以在开发期间自动将生成的制品保存到本地项目目录。
使用 dbt Administrative API 下载制品：通过 HTTP 以编程方式从已完成的运行中检索制品，以用于自动化、已调度的流水线。

设置 dbt Cloud 作业

在 dbt Google Cloud 控制台中，配置作业设置以生成完整的元数据制品集：

在执行设置部分，选择运行来源新鲜度。dbt Cloud 会在作业命令之前运行 dbt source freshness 以生成 sources.json。
在命令部分中，添加 dbt build。
添加一个命令，以根据发布轨道生成 catalog.json：
- 对于 dbt Core 2.x 和 dbt Fusion 发布轨道：添加 dbt parse --write-catalog 作为作业命令。
- 对于 dbt Core 1.x 发布轨道：添加 dbt docs generate --no-compile 作为作业命令，而不是选择在运行中生成文档选项。勾选在运行时生成文档复选框会运行 dbt docs generate 而不运行 --no-compile，这会覆盖 dbt build 中的测试结果，如 dbt 前提条件中所述。请注意，如果命令步骤失败，作业也会失败，而复选框步骤不会导致作业失败。

如果 dbt build 失败（例如，由于测试失败），dbt Cloud 会跳过其后的命令，并且运行不会有 catalog.json。如需始终生成一个，请在 dbt build 之前添加目录命令。然后，目录会描述 build 之前的表。

如需了解详情，请参阅 dbt 文档中的作业命令和发布轨道。

从 dbt Google Cloud 控制台下载制品

如需在 dbtGoogle Cloud 控制台中手动下载已完成运行的制品，请执行以下操作：

在 dbt Google Cloud 控制台中，打开已完成的作业运行。
前往制品标签页，查看生成的制品文件。
将 manifest.json、catalog.json、run_results.json 和 sources.json 下载到本地目录。
在本地终端或 Cloud Shell 中，运行配置 dbt 连接中所述的 gcloud 导入命令，并将 --artifacts-path 设置为包含已下载文件的目录。

如需了解详情，请参阅 dbt 文档中的运行可见性。

使用 dbt 平台 CLI 下载制品

dbt 平台 CLI（以前称为 dbt Cloud CLI）可在本地终端中执行 dbt Cloud 平台上的 dbt 命令，并自动将生成的制品下载到本地 dbt 项目的 target/ 目录中。

在本地终端中，前往您的 dbt 项目根目录，然后运行 dbt 前提条件中列出的三个命令。
运行配置 dbt 连接中所述的 gcloud 导入命令，并将 --artifacts-path 设置为项目根目录或 target/ 目录。

该 CLI 在您的开发环境中运行，使用您的个人数据仓库凭据，因此生成的元数据反映的是您的开发架构，而不是由预定作业构建的生产表。使用 CLI 进行测试或开发工作流，并使用部署作业进行预定的生产导入。

如需了解详情，请参阅 dbt 文档中的安装 dbt 平台 CLI。

使用 dbt Administrative API 下载制品

您可以使用 dbt 管理 API 以编程方式从任何已完成的作业运行中检索制品。List Run Artifacts 端点会返回运行生成的文件路径，而 Retrieve Run Artifact 端点会从以下网址下载特定的制品文件：

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

ACCESS_URL取决于托管 dbt Cloud 账号的区域。使用 dbt Cloud 服务令牌对请求进行身份验证。如需了解详情，请参阅 dbt 文档中的以下页面：

从本地终端、Cloud Shell 或自动化工作流环境中，将 manifest.json、catalog.json、run_results.json 和 sources.json 下载到本地目录或 Cloud Storage 存储桶，然后针对该路径运行配置 dbt 连接中所述的 gcloud 命令。

默认情况下，除非您指定 step 查询参数，否则制品端点会返回运行的最后一步中的制品。当您按照设置 dbt Cloud 作业中所述配置作业时，最后一步是 dbt parse --write-catalog 或 dbt docs generate --no-compile，这只会写入 catalog.json，而其他三个制品在默认步骤中保持不变。

检索运行 ID

如需下载特定运行的制品，您需要该运行的运行 ID。您可以从 dbt Google Cloud 控制台中的运行网址复制运行 ID，也可以从终端或工作流脚本中查询 API，以获取作业最近一次成功运行的运行 ID：

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

在查询参数中，status=10 用于过滤状态为 Success 的已完成跑步。您可以按计划轮询此端点，以确定最近一次成功运行，下载其制品，并执行 gcloud 导入命令。

使用网络钩子触发导入

您可以配置 dbt Cloud Webhook，以便在作业运行完成后触发自动元数据导入，而无需轮询 API。Webhook 会将载荷发送到您提供的 HTTP 端点：

在 dbt Google Cloud 控制台中，依次前往账号设置 > Webhook，然后点击创建 webhook（或创建新 webhook）。配置 webhook 订阅：
- 事件：选择运行完成 (job.run.completed)，此选项仅在运行完成且其制品可供下载时触发。
- 作业：选择要监控的 dbt Cloud 部署作业。
- 端点：输入您运行的服务的 HTTPS 网址（例如 Cloud Run 服务或 Cloud Run 函数）。
保存 dbt Cloud 显示的 Webhook Secret 令牌。您的服务使用此密钥验证 Authorization 标头，该标头包含请求正文的 HMAC-SHA256 签名。
在您的服务中，从 JSON 载荷中读取 data.runId，使用管理 API 下载运行的制品（如前所述），然后运行 gcloud alpha dataplex dbt metadata-jobs create 命令。

实现 Webhook 处理程序时，请考虑以下事项：

dbt Cloud 最多等待 10 秒来获取响应。由于元数据导入需要几分钟时间，因此请先返回 HTTP 响应，然后在后台运行导入（例如，作为 Cloud Run 作业或使用 --async 标志）。
job.run.completed 也会针对失败的运行触发，因此系统仍会导入包含失败测试的运行。请勿订阅 job.run.errored，因为该事件可能会在运行的制品可用之前触发。

如需详细了解 Webhook 载荷和签名验证，请参阅 dbt 文档中的作业的 Webhook。

配置 dbt 连接

如需建立 dbt 连接，您必须先运行相应的 dbt 命令来生成元数据制品。JSON 文件存储完毕并可供访问后，导入流程会执行以下操作：

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

控制台

在 Google Cloud 控制台中，前往 Knowledge Catalog 连接器页面。

前往“连接器”
点击添加连接。
在连接器列表中，选择 dbt Core 和 MetricFlow 卡片。

注意：由于 dbt Core 元数据提取需要在提取之前将客户端 dbt 制品 JSON 文件（manifest.json、catalog.json、run_results.json、sources.json）转换为 Knowledge Catalog 导入格式，因此选择此卡片会将您定向到 CLI 或 API 说明。
如需查看导入的 dbt 资产，请前往搜索页面或查看目标条目组页面。

gcloud

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

确保 dbt 元数据工件文件存储在本地或输入 Cloud Storage 存储桶中。
确保您已配置输出暂存 Cloud Storage 存储桶，并为调用方和 Knowledge Catalog 服务代理授予适当的权限。
在 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 制品的方面会保留之前运行赋予的值。此方法适用于常规的重复提取。请参阅重新运行提取。
- --include-entry-links：为 dbt 关系发出条目链接。此选项默认处于启用状态。如需停用，请使用 --no-include-entry-links。该命令会发出以下入口链接类型：
  - reference：一个资源依赖于、描述或使用另一个资源。这包括节点之间的 dbt 依赖关系、测试及其测试的资源、语义模型或指标及其构建所依据的资源、节点及其调用的项目宏，以及节点及其具体化的 BigQuery 表。
  - schema-join：由 dbt relationships 测试声明的可联接列。
- --skip-bigquery-link：跳过 reference 链接（dbt 节点 → 实际 BigQuery 表）。默认情况下，系统会为每个具体化的 dbt 节点（模型、种子、快照）发出一个 reference 链接，这些节点的 BigQuery 数据集位于导入位置 (--location)。dbt 源不会收到指向其 BigQuery 表的 reference 链接。入口链接只能引用同一区域中的 @bigquery 条目，因此系统会自动跳过其他区域中的数据集。为了确定每个数据集的区域，该命令会调用 BigQuery API，因此调用者需要对这些数据集拥有 bigquery.datasets.get 权限；否则，该命令无法跳过其他区域中的数据集，并且指向这些数据集的链接也无法解析。如果 BigQuery 表未在 Knowledge Catalog 中编入目录，请使用 --skip-bigquery-link。
- --validate-only：构建并上传 JSON，验证元数据作业，但不实际注入数据。
确认您收到了 Created 状态。

REST

如需使用 REST API 导入 dbt 元数据，请执行以下操作：

生成 dbt 制品，并将其转换为 Knowledge Catalog JSON 导入文件 (dbt_metadata.jsonl)。
将转换后的文件上传到您的 Cloud Storage 临时存储桶 (gs://BUCKET_NAME/PATH/)。

调用 projects.locations.metadataJobs.create 方法

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

替换以下内容：

PROJECT_ID：您的条目组所在的 Google Cloud 项目 ID。
LOCATION：入口组的区域（例如 us-central1）。
JOB_ID：元数据作业的唯一标识符。
BUCKET_NAME/PATH：上传 dbt_metadata.jsonl 的 Cloud Storage URI 前缀。
ENTRY_GROUP：目标条目组的简短 ID。

如需跟踪导入作业的状态，请使用 projects.locations.metadataJobs.get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

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

重新运行注入

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

当条目集发生变化时，运行完整注入（省略 --aspects-only）：

首次将数据提取到条目组中。
添加、重命名或删除了 dbt 资源。
条目的显示名称、说明或标签发生变化。
条目层次结构发生变化。
dbt 依赖项发生更改，例如添加或移除了 ref()、source()、测试或宏调用。--aspects-only运行不会创建或更新条目链接。
您更改 --include-entry-links 或 --skip-bigquery-link。

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

运行 --aspects-only 以进行常规刷新：

在流水线运行的任何 dbt 命令（dbt build、dbt test、dbt source freshness 或 --select 缩窄的重建）之后。
添加、移除、更改类型或重新描述了列。
模型 SQL 已更改，运行也写入了 catalog.json。
新的测试结果或来源新鲜度。

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

搜索和查看 dbt 元数据

控制台

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

转到搜索
在过滤条件面板中，按 dbt 资源进行过滤：
- 在系统部分中，选择导入的上下文。
- 在随即显示的受管理的连接器子部分中，选择 dbt。
在搜索字段中，使用关键字或自然语言搜索输入查询内容。例如，如需使用关键字搜索查看所有 dbt 资产，请输入 system=DBT 或 system=DBT AND type=dbt-model。
在搜索结果中，点击任意 dbt 资产以打开其条目详情页面，查看其架构、沿袭和技术方面的信息。

gcloud

如需在整个项目中搜索 dbt 条目，请使用 gcloud dataplex entries search 命令：
```
gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID
```
如需按特定 dbt 条目类型（例如模型或来源）进行过滤，请执行以下操作：
```
gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID
```
如需查看特定 dbt 条目的完整详细信息和各个方面，请使用 gcloud dataplex entries lookup 命令：
```
gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL
```
替换以下内容：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- LOCATION：条目组的位置（例如 us-central1）。
- ENTRY_GROUP：目标条目组的简短 ID（例如 dbt-metadata-ingestion）。
- ENTRY_ID：dbt 条目的简短 ID 或相对资源名称。

REST

如需搜索 dbt 条目，请调用 projects.locations:searchEntries 方法：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

如需按特定 dbt 资源类型进行过滤，请执行以下操作：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

如需检索特定条目的完整元数据详细信息和方面，请调用 projects.locations.entryGroups.entries.get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

如需检索特定 dbt 资源的 LLM 上下文，请使用 projects.locations:lookupContext API：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：条目组的位置（例如 us-central1）。
ENTRY_GROUP：目标条目组的简短 ID（例如 dbt-metadata-ingestion）。
ENTRY_ID：dbt 条目的简短 ID 或相对资源名称。

如需列出 dbt 条目的条目链接，请调用 projects.locations:lookupEntryLinks 方法。例如，如需检索 dbt 模型实体化的 BigQuery 表，请执行以下操作：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

ENTRY_NAME 是 dbt 条目的完整资源名称。结果进行了分页，每页最多显示 10 个链接。

如需详细了解如何搜索资源，请参阅在 Knowledge Catalog 中搜索资源。如需详细了解查询表达式和过滤条件，请参阅 Knowledge Catalog 的搜索语法。

后续步骤

了解如何管理连接器作业。

从 dbt Core 导入元数据 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

限制

准备工作

IAM 角色和权限

启用 API

dbt 前提条件

了解 Cloud Storage 角色

从 dbt Cloud 运行中导入元数据

设置 dbt Cloud 作业

从 dbt Google Cloud 控制台下载制品

使用 dbt 平台 CLI 下载制品

使用 dbt Administrative API 下载制品

检索运行 ID

使用网络钩子触发导入

配置 dbt 连接

控制台

gcloud

必需的标志

可选标志

REST

重新运行注入

搜索和查看 dbt 元数据

控制台

gcloud

REST

后续步骤

从 dbt Core 导入元数据