借助 Knowledge Catalog，您可以存储和管理元数据。 默认情况下，Knowledge Catalog 中会提供 Dataform 代码库，无需进行任何其他配置。 Knowledge Catalog 会自动从 Dataform 代码库中检索以下元数据：
数据资产名称
数据素材资源父级
数据资产位置
数据素材资源类型
对应的 Google Cloud 项目
第三方代码库来源
服务账号
准备工作
-
在 Google Cloud 控制台的项目选择器页面上，选择或创建 Google Cloud 项目。
选择或创建项目所需的角色
- 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
-
创建项目：如需创建项目，您需要拥有 Project Creator 角色 (
roles/resourcemanager.projectCreator)，该角色包含resourcemanager.projects.create权限。了解如何授予角色。
-
启用 Dataplex API 和 Data Lineage API（如果尚未启用）。
启用 API 所需的角色
如需启用 API，您需要拥有
serviceusage.services.enable权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
所需的角色
如需在 Knowledge Catalog 中管理 Dataform 代码库和查看数据沿袭，您需要具有可让您访问 Dataform 资源的预定义 Dataform 角色，以及所需的 Knowledge Catalog 角色。
下表列出了每个主账号记录和查看 Dataform 数据沿袭所需的角色：
| 任务 | 主体 | 所需角色 | 在哪里授予角色 |
|---|---|---|---|
| 记录工作流调用中的沿袭 | 代码库、发布配置或工作流配置的自定义服务账号。如果未设置自定义服务账号，则使用 Dataform 服务代理 (service-PROJECT_NUMBER@gcp-sa-dataform.)。 |
Data Lineage Events Producer (roles/datalineage.producer) |
包含代码库的项目 |
| 通过 Dataform CLI 记录沿袭 | CLI 使用的应用默认凭证 | Data Lineage Events Producer (roles/datalineage.producer) |
每个输出表的项目 |
| 查看沿袭图 | 查看沿袭的用户 | Data Lineage Viewer (roles/datalineage.viewer) |
记录沿袭的项目和查看沿袭的项目 |
| 从沿袭图打开 Dataform | 查看沿袭的用户 | Dataform Viewer (roles/dataform.viewer)，或 dataform.repositories.get 和 dataform.workflowInvocations.get 权限 |
包含代码库的项目 |
| 查看 BigQuery 表详情 | 查看沿袭的用户 | BigQuery Data Viewer (roles/bigquery.dataViewer) 或 bigquery.tables.get 权限 |
存储表的项目 |
| 查看 BigQuery 作业详情 | 查看沿袭的用户 | BigQuery Resource Viewer (roles/bigquery.resourceViewer) 或 bigquery.jobs.get 权限 |
运行作业的项目 |
Data Lineage Events Producer 角色包含 datalineage.locations.processOpenLineageMessage 权限，这是记录沿袭所必需的。
在 Knowledge Catalog 中管理元数据
Knowledge Catalog 会将 Dataform 代码库作为条目记录在日志中，并包含以下条目值：
- 系统条目组
- Dataform 代码库的系统条目组为
@dataform。如需在 Knowledge Catalog 中查看代码库条目的详细信息，您需要查看dataform系统条目组。如需了解如何查看条目组中所有条目的列表，请参阅 Knowledge Catalog 文档中的查看条目组的详细信息。 - 系统条目类型
- Dataform 代码库的系统条目类型为
dataform-repository。如需查看 Dataform 代码库的详细信息，您需要查看dataform-repository系统条目类型。如需了解如何查看所选条目类型的详细信息，请参阅 Knowledge Catalog 文档中的查看条目类型的详细信息。 如需了解如何查看所选条目的详细信息，请参阅 Knowledge Catalog 文档中的查看条目的详细信息。
搜索资产
如需了解如何在 Knowledge Catalog 中搜索数据资产，请参阅 Knowledge Catalog 文档中的在 Knowledge Catalog 中搜索数据资产。
为代码库添加注解
如需为 Knowledge Catalog 中的 Dataform 代码库提供更多上下文，您可以使用切面为 Dataform 条目添加注解。
Dataform 代码库的系统切面类型为 dataform-repository。
如需了解如何使用切面为条目添加注解，请参阅 Knowledge Catalog 文档中的管理切面并丰富元数据。
在 Knowledge Catalog 中跟踪数据沿袭
Dataform 会针对其在 Dataform 工作流和 BigQuery 流水线中运行的操作向 Knowledge Catalog 报告数据沿袭。对于每个执行的操作，Knowledge Catalog 和 BigQuery 中的沿袭图都会显示该操作读取的表与写入的表之间的 Dataform 进程。您无需更改 SQLX 文件即可报告沿袭。
您可以使用 Dataform 数据沿袭执行以下任务：
影响分析：在更改表之前，请确定每个下游操作和表。
根本原因分析：将不正确的数据追溯到写入该数据的操作和工作流调用。
治理：显示数据如何在项目之间流动，以及哪个流水线移动了数据。
端到端沿袭：在一个图表中查看 Dataform 沿袭以及来自 BigQuery、Managed Service for Apache Airflow、Managed Service for Apache Spark 和 Dataflow 的沿袭。
数据沿袭的运作方式
当操作开始时，Dataform 会向 Data Lineage API 发送 OpenLineage START 事件。操作结束时，Dataform 会发送 COMPLETE、FAIL 或 ABORT 事件。每个 Dataform 操作在 Knowledge Catalog 中都显示为来源类型为 BIGQUERY_PIPELINES 的进程，并且该操作的每次执行都显示为该进程的一次运行。
下表介绍了哪些 Dataform 操作类型会报告沿袭：
| 操作类型 | 报告沿袭 |
|---|---|
表、视图、增量表、具体化视图、断言、属性图、数据准备和操作，带有 hasOutput: true |
可以。报告进程、运行和表到表沿袭链接。 |
不使用 hasOutput: true 的操作 |
仅限处理和运行。输入和输出为空，因此不会创建表到表的沿袭链接。 |
| 声明 | 不会。声明仅作为其他操作的输入。 |
| Notebook、SQL 单元测试 | 否 |
报告沿袭绝不会导致工作流调用失败。如果 Data Lineage API 已停用、缺少权限或超出配额，Dataform 会跳过沿袭报告，并且工作流调用会继续进行，而不会发生任何更改。
Dataform 会将沿袭写入每个操作的 BigQuery 处理位置的区域端点。如果区域端点不可用，Dataform 会将沿袭写入全球端点。
Dataform 工作流如何映射到数据沿袭
下表介绍了 Dataform 执行实体如何映射到 Knowledge Catalog 数据沿袭信息模型：
| 数据沿袭对象 | Dataform 等效项 |
|---|---|
| 流程 | Dataform 操作 |
| 运行 | 工作流调用中操作的一次执行 |
| 沿袭事件 | 从输入表到该运行的输出表的链接 |
设置数据沿袭
如需设置 Dataform 以报告数据沿袭，请按以下步骤操作：
在包含 Dataform 代码库的项目以及用户查看沿袭的项目中启用 Data Lineage API (
datalineage.googleapis.com)。在包含代码库的项目中，向运行工作流的身份授予 Data Lineage Events Producer 角色 (
roles/datalineage.producer)：如果代码库、发布配置或工作流配置使用自定义服务账号，请向该自定义服务账号授予此角色。
如果未设置自定义服务账号，请向 Dataform 服务代理 (
service-PROJECT_NUMBER@gcp-sa-dataform.) 授予该角色。
使用 Google 账号的用户凭据运行的工作流调用不会报告沿袭。
启用或停用数据沿袭
在初始发布期间，数据沿袭报告功能需要选择启用。
如需控制代码库或 BigQuery 流水线的数据沿袭报告，请在 workflow_settings.yaml 文件中设置 lineage.enabled 属性：
在 Google Cloud 控制台中，前往 Dataform 页面。
选择一个代码库，然后选择一个开发工作区。
在文件窗格中，打开
workflow_settings.yaml文件。如需开启数据沿袭报告，请添加以下
lineage代码块：lineage: enabled: true如需在默认启用沿袭后让代码库停用数据沿袭报告，请将
enabled设置为false：lineage: enabled: false提交更改并将更改推送到代码库。
如需停止整个项目的数据沿袭报告，请在项目中停用 Data Lineage API。停用该 API 还会停止项目中其他服务的数据沿袭报告。
查看数据沿袭
如需查看 Dataform 操作生成的表的数据沿袭，请按照以下步骤操作：
在 Google Cloud 控制台中，前往 BigQuery 页面。
在探索器窗格中，展开您的项目和数据集，然后选择 Dataform 操作生成的表。
点击沿袭标签页。
如需查看操作、代码库和运行，请选择 Dataform 进程节点。
如需在 Dataform 中打开代码库，请点击在 Dataform 中打开。
如需详细了解如何浏览沿袭图，请参阅在 Knowledge Catalog 中查看数据沿袭。
通过 Dataform CLI 报告数据沿袭
如需从 Dataform CLI 的本地或 CI 运行报告数据沿袭，请在 workflow_settings.yaml 中设置 lineage.enabled: true，或运行以下命令：
dataform run --emit-lineage
--emit-lineage 和 --no-emit-lineage 标志会替换单次运行的 lineage.enabled 设置。
Dataform CLI 使用应用默认凭证，并在每个输出表的项目中记录沿袭。在每个项目中，启用 Data Lineage API 并向凭证授予 Data Lineage Events Producer 角色 (roles/datalineage.producer)。CLI 会将具有 [lineage] 前缀的沿袭消息写入 stderr。
如需详细了解如何通过 CLI 报告沿袭，请参阅 GitHub 上的 Dataform CLI 参考文档。
排查数据沿袭问题
下表介绍了常见的数据沿袭问题以及解决方法：
| 症状 | 可能的原因 | 修复 |
|---|---|---|
| 沿袭标签页不显示 Dataform 节点。 | Data Lineage API 已停用。 | 在包含代码库的项目和您查看沿袭的项目中启用该 API。 |
| 代码库不会报告沿袭。 | 运行工作流的身份不具有 Data Lineage Events Producer 角色。 | 向自定义服务账号或 Dataform 服务代理授予 roles/datalineage.producer。 |
| 使用用户凭证运行的工作流调用不会报告沿袭。 | 沿袭报告不支持用户凭据。 | 使用自定义服务账号运行工作流。 |
| 即使已授予角色，代码库也不会报告沿袭。 | Dataform 无法充当自定义服务账号。 | 向 Dataform 服务代理授予自定义服务账号的 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。 |
| 一个代码库不报告沿袭。 | 该代码库已选择不参与。 | 从 workflow_settings.yaml 中移除 lineage.enabled: false。 |
| 某些运行缺少沿袭。 | 已超出 Data Lineage API 配额。 | 分散工作流运行或申请更高的配额。 |
| CLI 运行不会报告某些表的沿袭。 | 输出表所在的项目中未启用该 API 或未授予该角色。 | 在该项目中启用 API 并授予角色。 |
| 点击在 Dataform 中打开会返回权限错误。 | 用户无权访问 Dataform。 | 向用户授予 Dataform Viewer 角色 (roles/dataform.viewer)。 |
在工作流调用中出现第一个权限或 API 错误后，Dataform 会停止报告该工作流调用的其余部分的沿袭。下一次工作流调用会尝试再次报告沿袭。
如果您就数据沿袭问题与支持团队联系，请提供工作流调用 ID、项目 ID 和区域。
查看工作流调用的沿袭日志
在 Cloud Logging 中，Dataform 会将沿袭日志条目写入 dataform.googleapis.com/lineage_emission 日志。每个条目都包含 workflowInvocationId、actionTarget 和 eventType 字段。
如需查看工作流调用的沿袭日志，请按以下步骤操作：
在 Google Cloud 控制台中，打开工作流调用的详情页面。
点击查看日志。
Logging 随即打开，其中显示了按
jsonPayload.workflowInvocationId过滤的工作流调用日志。
每个沿袭日志条目中的 outcome 字段都具有以下值之一：
SUCCEEDED：Data Lineage API 接受了事件。这些条目的严重级别为DEBUG，eventType为START、COMPLETE、FAIL或ABORT。SKIPPED：Dataform 跳过了沿袭报告。这些条目的严重级别为INFO，并且在工作流调用中每个原因都会记录一次。skipReason字段为API_DISABLED、PERMISSION_DENIED、EUC_UNSUPPORTED或AUTHORITY_UNAVAILABLE，errorMessage字段包含修复步骤。FAILED：重试后沿袭报告失败。这些条目的严重级别为WARNING，并包含errorCode和errorMessage字段。
如需在 Logs Explorer 中过滤跳过或失败的沿袭报告，请运行以下查询：
log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")
来自 Dataform CLI 的数据沿袭消息
Dataform CLI 会将以下沿袭消息写入 stderr：
skip_reason=workflow_opt_out：lineage.enabled设置为false。skip_reason=invocation_override：使用--no-emit-lineage或--emit-lineage=false为此运行关闭了沿袭报告。skip_reason=dry_run：试运行不会报告沿袭。skip_reason=api_disabled：未启用 Data Lineage API。CLI 在此运行中不会发送更多沿袭请求。skip_reason=permission_denied：凭证不具有 Data Lineage Events Producer 角色 (roles/datalineage.producer)。CLI 在此运行中不会发送更多沿袭请求。Failed to emit lineage for action ...：一项操作的沿袭报告失败。其他操作的沿袭报告会继续。
限制
在 Knowledge Catalog 中管理 Dataform 代码库和跟踪数据沿袭存在以下限制：
Knowledge Catalog 中仅提供代码库级和工作流级条目。Dataform 中的单个文件级代码资产（例如 SQLX 定义文件）不会作为单独的条目编目。
Dataform 仅报告表级沿袭。不会报告列级沿袭。
声明、笔记本和 SQL 单元测试不会报告沿袭。声明仅作为其他操作的输入出现。没有
hasOutput: true的操作仅报告进程和运行，不报告表到表的沿袭链接。使用 Google 账号的用户凭据运行的工作流调用不会报告沿袭。如需报告沿袭，请使用自定义服务账号。
数据沿袭报告受每个项目、身份和区域的写入操作的 Data Lineage API 配额约束。在标准层级，配额约为每分钟 1,000 次操作。
位置
您可以使用 Knowledge Catalog 管理所有 Dataform 位置中的 Dataform 代码库。
配额
在 Knowledge Catalog 中管理 Dataform 代码库需遵循 Knowledge Catalog 配额和限制。
价格
在 Knowledge Catalog 中管理 Dataform 代码库需遵循 Knowledge Catalog 价格。
数据沿袭提取按 Knowledge Catalog Premium Processing SKU 计费，并且仅对写入表到表沿袭链接的事件计费。数据沿袭存储空间按元数据存储空间 SKU 计费。如需控制数据沿袭费用，请在 workflow_settings.yaml 中选择停用工作流，或停用 Data Lineage API。
后续步骤
- 如需详细了解 Knowledge Catalog，请参阅 Knowledge Catalog 文档中的 Knowledge Catalog 概览。