数据工程智能体概览

借助数据工程代理，您可以使用自然语言提示在 BigQuery 中构建、修改和排查数据流水线。数据工程代理提供以下功能，可简化您的数据工程工作流，以便将数据注入 BigQuery：

  • Dataform 集成：该代理直接在 Dataform 代码库和工作区中生成和整理数据流水线 代码
  • 计划生成：该代理可以总结其思路并生成 计划，让您在继续操作之前查看和验证代理的计划
  • 代码验证：该代理会自动验证并修复任何生成的代码的编译 错误，以确保数据流水线正常运行
  • 自动数据整理：该代理执行数据整理并将 原始数据转换为结构化表，无需手动干预。
  • 自定义指令：该代理支持自定义代理指令， 让您可以使用自然语言定义特定规则和可重复使用的准则
  • 外部上下文：该代理与 Knowledge Catalog 集成，可提供更多上下文信息
  • 流水线控制：您可以在执行任何操作之前查看和自定义生成的代理计划 。
  • 优化：该代理可以优化数据流水线的性能
  • 问题排查和修复：该代理可以排查流水线故障 并修复其代码。
  • 互动式建议：该代理在会话开始时和整个会话期间提供互动式、 情境感知型建议。

数据工程代理的适用范围

您可以通过以下方法使用数据工程代理：

数据工程代理如何使用您的数据

为了生成质量更高的代理响应，数据工程代理可以从 BigQuery 和 Knowledge Catalog 检索其他数据和元数据，包括 BigQuery 表中的示例行以及在 Knowledge Catalog 中生成的数据扫描配置文件。该代理不会使用这些数据进行训练；它仅在代理对话期间将这些数据用作额外的上下文信息，以指导其响应。

数据工程代理在哪里处理您的数据

如需详细了解数据工程代理 处理您的数据的位置，请参阅 Gemini in BigQuery 处理您的数据。

限制

数据工程代理具有以下限制：

代理功能和自定义

以下部分介绍了其他代理功能以及自定义数据工程代理的其他方法。

代理指令

代理指令是数据工程代理的自然语言指令，可让您存储持久性指令，以便代理遵循一组自定义的预定义规则。如果您希望代理的结果在整个组织中保持一致（例如，使用命名惯例或强制执行样式指南），请使用代理指令。

如需为数据工程代理创建代理指令，请创建 GEMINI.MD上下文 文件 作为代理指令文件。

使用代理指令文件的最佳实践

使用代理指令时，我们建议您执行以下操作：

  • Dataform 中的所有文件路径都相对于代码库的根目录。对任何 @file.md 语法使用相对路径，以便将指令正确导入到 GEMINI.md。
  • 在 GEMINI.md 中导入的文件本身可以包含导入，这会创建嵌套结构。为防止无限递归，GEMINI.md 的最大导入深度为 5 级。
  • 如需在数据流水线之间共享指令，请将指令存储在中央 Dataform 代码库中，并将其链接到工作 Dataform 代码库。您可以使用本地指令替换流水线特定行为的中央规则。
  • 为确保项目中的一致性，您可以链接到命名惯例文件或样式指南，并指示代理在处理数据流水线时遵循这些指南。
  • 您可以在指令文件中建议数据层，以便将不同类型的数据分组在一起。
  • 在代理指令文件中使用标题和列表有助于整理和阐明数据工程代理的指令。
  • 提供有意义的文件名，并将类似指令分组到一个文件中。 使用 Markdown 标题按类别、功能或功能以逻辑方式整理规则。
  • 为避免指令冲突，请明确定义每条指令适用的具体条件。
  • 迭代并优化提示和工作流。随着代理的推出和模型的升级，代理的行为会随时间变化，因此我们建议您使用不同的提示迭代规则，以找出可能需要改进的地方。 使规则文件与数据流水线的任何更改保持同步。

以下示例展示了一个名为 GEMINI.md 的代理指令文件，该文件利用了我们有效使用数据工程代理的最佳实践：

  ### Naming Conventions

  * Datasets: [business_domain]_[use_case] (e.g., ecommerce_sales)

  * Tables:
      - Raw/External: raw_[source_name]
      - Staging: stg_[business_entity]
      - Dimension: dim_[dimension_name]
      - Fact: fct_[fact_name]

  * Dataform Folders:
      - sources
      - staging
      - marts
      - dataProducts

  * Views: vw_[view_name]

  * Columns: snake_case (e.g., order_id, customer_name)

  ## Cloud Storage data load
  * When ingesting data from Cloud Storage, create external tables.

  ## Null handling
  * Filter out null id values

  ## String normalization
  * Standardize string columns by converting to lower case

  ## Data Cleaning Guidelines
  @./generic_cleaning.md

将其他本地文件作为代理指令导入

您还可以使用 @file.md 语法将数据工程代理的其他指令文件导入到 GEMINI.md 文件中。如需了解详情，请参阅内存导入处理器。

自动数据整理

您可以使用数据工程代理将原始的未处理数据转换为适合数据分析的结构化表。如果收到请求，该代理首先会从每个标准表或外部表中抽样最多 100 万条记录。然后，该代理通过对此样本运行分析查询来执行深度数据分析。生成数据转换后，该代理会重复此抽样和分析过程，以评估转换的质量。这些数据整理转换可能包括修复数据不一致、离群值或类型不匹配。 然后，数据工程代理会创建一个计划，其中概述了建议的整理步骤，供您在执行任何操作之前查看和优化。

每当您添加原始表（例如基于 CSV 的外部表）时，数据工程代理也会启动数据整理分析。您可以使用对话命令查看和调整数据整理计划。

数据抽样和分析会使用 BigQuery 资源，并受 BigQuery 价格的约束。

数据工程代理支持以下数据整理转换：

  • 数据清理。该代理可以分析原始数据并提供清理建议，例如移除离群值、填充缺失值或不一致的值（数据插补）、修复重复数据或标准化数据格式（例如手机号码或地址）
  • 结构转换。如果提供了目标架构，该代理可以从 JSON、ARRAY 或 STRUCT 类型中取消嵌套或提取值；将多个列合并为一个列；或将一个列拆分为多个列
  • 数据类型检测和转换。该代理可以分析数据以确定适当的字段类型。然后，该代理可以执行安全类型转换，以解决日期、时间、日期时间或时间戳字段中的任何格式不一致问题。
  • 单位换算。该代理可以自动将字段中的各种单位转换为一个一致的单位，以标准化您的数据。

为确保准确性，该代理会使用具有代表性的数据样本来检测问题并验证其转换逻辑。

生成和查看代理计划

数据工程代理可以生成代理计划，其中提供了完成请求的目标和步骤的摘要和概览。当您向代理发出需要进行许多更改的复杂请求时，我们建议您要求代理向您提供代理计划，以便您在代理执行任何操作之前查看代理的意图。数据工程代理计划通常包含以下内容：

  • 代理针对特定请求的目标
  • 代理计划采取的步骤的概览
  • 代理做出的任何假设
  • 代理计划修改的文件
  • 代理计划执行的任何优化或清理步骤
  • 分阶段执行计划

在提示中，您可以添加查看和批准计划的需求，以便代理在没有您的明确批准的情况下不会采取任何行动。例如：

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. I want to review the plan and
approve it before you create the pipeline.

代理也可能会自动生成代理计划并请求您的批准。如果提示过于模糊，或者代理需要更清晰的信息才能满足您的请求，则可能会出现此结果。

如需了解有关使用代理计划的最佳实践，请参阅最佳实践。

从 Knowledge Catalog 添加上下文

数据工程代理通过将术语表术语附加到 BigQuery 表和列并生成数据配置文件扫描来使用 Knowledge Catalog。术语表术语可以标记需要额外上下文的列，例如包含需要特殊处理说明的个人身份信息 (PII) 的列，或者标识跨表具有不同命名的匹配列。

Knowledge Catalog 还利用 数据 分析，让代理 更好地了解表列中的数据分布，并帮助 代理创建更具体的数据质量断言。

代理还可以使用 Knowledge Catalog 发现和查询 Apache Iceberg 表。如需了解详情，请参阅通过 Apache Iceberg 表创建流水线。

向现有表添加数据质量检查

当您提示代理添加质量检查时，代理会根据架构和样本推断出合理的表检查。您还可以将主观断言作为提示的一部分添加。例如：

  Add data quality checks for bigquery-public-data.thelook_ecommerce.users.

优化数据流水线

您可以提示代理优化数据流水线。为新表生成 DDL 时，数据工程代理会根据分析的数据使用模式推荐分区和聚类。此外，该代理还可以自动应用其他流水线优化。可能的优化示例包括：

  • 列剪枝，以减少从存储空间读取的数据，作为主要的成本和性能驱动因素。
  • 谓词下推，以便在执行计划中尽早过滤数据，从而显著减少后续操作处理的数据量。
  • 消除常见子表达式，通过仅识别和计算一次共享转换逻辑来提高效率，防止多次扫描和联接大型表等低效做法。
  • 增量模型，以便仅处理自上次运行以来新增或更改的数据，而不是在每次运行时重建整个表。

通过 Apache Iceberg 表创建流水线

数据工程代理支持生成和编译通过 Lakehouse 运行时目录（以前称为 BigLake metastore）管理的 Apache Iceberg 表的 Dataform 流水线。借助此功能，您可以直接查询和联接区域性开源格式表（存储在 Cloud Storage 中）以及 BigQuery 表。如需了解详情，请参阅 Apache Iceberg REST Catalog 端点概念。

例如，您可以提示代理查询 Lakehouse 运行时目录中的 Apache Iceberg 表：

Include the stackoverflow_post_history_iceberg table in this pipeline.

在提示中，您无需指定完全限定的四部分路径，例如 project.catalog.dataset.table。您可以使用标准自然语言名称或逻辑标识符引用 Apache Iceberg 表，例如 the StackOverflow post history table 或 post_history。该代理会自动使用 Knowledge Catalog 调用语义目录搜索，以解析正确的 Apache Iceberg 表并将其绑定到您的流水线工作区。

如需使用此功能，您的 Dataform 代码库必须使用 Dataform Core 3.0.33 或更高版本。

互动式建议

数据工程代理会分析您的工作区编译状态、执行历史记录和活跃对话状态，以便直接在聊天界面中提供切实可行的建议。当您打开工作区时，这些建议会自动显示，并在整个会话期间提供设置、问题排查和优化建议，以指导您的工作流。

如需使用建议，请点击 AI 建议 下的其中一个建议，系统会将提示加载到聊天输入栏中，您可以在发送给代理之前对其进行修改或自定义。您还可以将鼠标悬停在建议上以查看确切的提示。

最佳实践

为了在使用数据工程代理和 Dataform 时获得更好的结果，我们建议您执行以下操作：

针对常见请求使用代理指令。如果您经常应用某些技术，或者经常对代理进行相同的更正，请使用代理指令作为集中存储常见指令和请求的位置。

利用代理计划。 代理计划有助于分解复杂的流水线任务。代理计划还可以向您展示代理的假设和意图，因此我们建议您查看这些计划，以确保为代理提供正确的上下文。

查看计划后，您可以通过向数据工程代理提供反馈和更改来修改计划。例如：

In the plan, ensure that all of the intermediate tables are views.

在某些情况下，要求代理生成无需您明确批准的计划可能会很有帮助。制定代理计划的行为会迫使数据工程代理分解其操作，这通常会带来更好的结果。您可以强制代理生成计划并自动执行该计划。例如：

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. You have my explicit pre-approval
to go ahead and execute this plan.

清晰地撰写。清楚地说明您的请求，避免含糊不清。在可能的情况下，请在提示时提供来源和目标数据源，如以下示例所示：

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

提供直接且有范围的请求。一次只问一个问题，并保持提示简洁。对于包含多个问题的提示，请将问题的每个不同部分列出来，以提高清晰度，如以下示例所示：

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

提供明确的指令并强调关键术语。您可以在提示中强调关键术语或概念，并将某些要求标记为重要，如以下示例所示：

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

指定操作顺序。对于有序任务，请在列表中构建提示，其中列出的项分为小而集中的步骤，如以下示例所示：

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id.
  3. Load the final result into the reporting.customer_orders table.

优化和迭代。不断尝试不同的短语和方法，看看哪种方法能产生最佳结果。如果代理生成无效的 SQL 或其他错误，请使用示例或公开文档指导代理。

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).