データ エンジニアリング エージェントの概要

Data Engineering Agent を使用すると、自然言語プロンプトを使用して BigQuery でデータ パイプラインを構築、変更、トラブルシューティングできます。Data Engineering Agent には、データ エンジニアリング ワークフローを効率化して BigQuery にデータを取り込むための次の機能が用意されています。

  • Dataform の統合: エージェントは、Dataform リポジトリとワークスペース内でデータ パイプライン コードを直接生成して整理します。
  • プランの生成: エージェントは思考を要約し、プランを生成できます。これにより、続行する前にエージェントのプランを確認して検証できます。
  • コード検証: エージェントは、生成されたコードのコンパイル エラーを自動的に検証して修正し、データ パイプラインが機能していることを確認します。
  • 自動データ ラングリング: エージェントがデータ ラングリングを実行し、手動で介入することなく、未加工データを構造化テーブルに変換します。
  • カスタム手順: エージェントは、自然言語で特定ルールと再利用可能なガイドラインを定義できるカスタム エージェント手順をサポートしています。
  • 外部コンテキスト: エージェントは Knowledge Catalog と統合され、追加のコンテキストを取得します。
  • パイプライン制御: アクションが実行される前に、生成されたエージェント プランを確認してカスタマイズできます。
  • 最適化: エージェントはデータ パイプラインのパフォーマンスを最適化できます
  • トラブルシューティングと修復: エージェントは、パイプラインの障害のトラブルシューティングを行い、コードを修正できます。

Data Engineering Agent を使用できる場所

Data Engineering Agent は、次の方法で使用できます。

Data Engineering Agent によるデータの使用方法

Data Engineering Agent は、より高品質なエージェント レスポンスを生成するために、BigQuery テーブルのサンプル行や Knowledge Catalog で生成されたデータ スキャン プロファイルなど、BigQuery と Knowledge Catalog から追加のデータとメタデータを取得できます。エージェントはこのデータをトレーニングに使用しません。エージェントの会話中に、回答を通知するための追加のコンテキストとしてのみ使用します。

Data Engineering Agent がデータを処理する場所

Data Engineering エージェントがデータを処理するロケーションの詳細については、Gemini in BigQuery がデータを処理する場所をご覧ください。

制限事項

Data Engineering Agent には次の制限があります。

  • Data Engineering Agent は、次のファイル形式の自然言語コマンドをサポートしていません。
    • ノートブック
    • データの準備
  • Data Engineering Agent はパイプラインを実行できません。パイプラインを確認して実行またはスケジュールする必要があります。
  • Data Engineering Agent は、手順や直接プロンプトで提供されたウェブリンクや URL を検索できません。
  • エージェント指示ファイルでファイルをインポートする場合、@ インポート構文は、./、/、または文字で始まるパスのみをサポートします。
  • データ プレビュー機能は、hasOutput フラグが true に設定されているテーブル、宣言、クエリでのみサポートされます。
  • Data Engineering Agent には、AI 技術の一般的な制限事項が適用されます。

エージェントの機能とカスタマイズ

以降のセクションでは、Data Engineering エージェントをカスタマイズするための追加のエージェント機能とその他の方法について説明します。

エージェントへの指示

エージェントへの指示は、Data Engineering Agent に対する自然言語の指示です。この指示を使用すると、永続的な指示を保存して、エージェントがカスタムの事前定義された一連のルールに従うようにできます。組織全体でエージェントの結果を統一したい場合（命名規則やスタイルガイドの適用など）は、エージェントへの指示を使用します。

Data Engineering Agent のエージェント指示を作成するには、エージェント指示ファイルとして GEMINI.MD コンテキスト ファイルを作成します。

エージェント指示ファイルに関するベスト プラクティス

エージェントへの指示を使用する場合は、次のことをおすすめします。

  • Dataform のすべてのファイルパスは、リポジトリのルートからの相対パスです。@file.md 構文には相対パスを使用して、GEMINI.md に指示を正しくインポートします。
  • GEMINI.md でインポートされたファイル自体にインポートを含めることができ、ネストされた構造を作成できます。無限再帰を防ぐため、GEMINI.md の最大インポート深度は 5 レベルになっています。
  • データ パイプライン間で指示を共有するには、指示を一元的な Dataform リポジトリに保存し、作業用の Dataform リポジトリにリンクします。ローカル指示を使用すると、パイプライン固有の動作に対して中央のルールをオーバーライドできます。
  • プロジェクトの一貫性を確保するために、命名規則ファイルまたはスタイルガイドにリンクして、データ パイプラインを操作するときにこれらのガイドラインに従うようにエージェントに指示できます。
  • 指示ファイルでデータレイヤを提案して、さまざまな種類のデータをグループ化できます。
  • エージェントの指示ファイルで見出しとリストを使用すると、Data Engineering Agent に対して指示を整理し、明確にすることができます。
  • わかりやすいファイル名を付け、類似した手順を 1 つのファイルにまとめます。Markdown の見出しを使用して、カテゴリや機能ごとにルールを論理的に整理します。
  • 指示の競合を避けるため、各指示が適用される特定の条件を明確に定義します。
  • プロンプトとワークフローを繰り返し調整します。エージェントの動作は、エージェントのロールアウトとモデルのアップグレードによって時間の経過とともに変化するため、さまざまなプロンプトを使用してルールを繰り返しテストし、改善が必要な領域を特定することをおすすめします。ルールファイルは、データ パイプラインの変更と同期させてください。

次の例は、Data Engineering Agent を効果的に使用するためのベスト プラクティスを活用する、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 構文を使用して、Data Engineering Agent の他の指示ファイルを GEMINI.md ファイルにインポートすることもできます。詳細については、メモリ インポート プロセッサをご覧ください。

自動データ ラングリング

Data Engineering エージェントを使用すると、未加工の未処理データをデータ分析に適した構造化テーブルに変換できます。リクエストされると、エージェントはまず、各標準テーブルまたは外部テーブルから最大 1,000,000 件のレコードをサンプリングします。エージェントは、このサンプルに対してプロファイリング クエリを実行して、詳細なデータ分析を行います。データ変換を生成した後、エージェントはこのサンプリングとプロファイリングのプロセスを繰り返して、変換の品質を評価します。これらのデータ ラングリング変換には、データの不整合、外れ値、型の不一致の修正が含まれる場合があります。Data Engineering Agent は、提案されたデータ変換の手順を概説するプランを作成します。このプランを確認して調整してから、アクションを実行します。

また、Data Engineering エージェントは、CSV ベースの外部テーブルなどの未加工テーブルを追加するたびに、データ ラングリング分析を開始します。データ ラングリング プランを確認し、会話型コマンドで調整できます。

データ サンプリングとプロファイリングでは BigQuery リソースが使用され、BigQuery の料金が適用されます。

Data Engineering Agent は、次のデータ ラングリング変換をサポートしています。

  • データ クリーニング。エージェントは、元データを分析して、外れ値の削除、欠損値や不整合な値の入力（データ補完）、重複データの修正、データ形式（電話番号や住所など）の標準化などのクリーンアップの機会を提案できます。
  • 構造変換。ターゲット スキーマが指定されている場合、エージェントは JSON、ARRAY、STRUCT 型の値をネスト解除または抽出したり、複数の列を 1 つに統合したり、1 つの列を複数の列に分割したりできます。
  • データ型の検出と変換。エージェントはデータを分析して、適切なフィールド タイプを特定できます。エージェントは、安全な型キャストを実行して、日付、時刻、日時、タイムスタンプの各フィールド内の形式の不整合を解決できます。
  • 単位の変換。エージェントは、フィールド内のさまざまな単位を 1 つの単位に自動的に変換して、データを標準化できます。

精度を確保するため、エージェントはデータの代表的なサンプルを使用して問題を検出し、変換ロジックを検証します。

エージェント プランを生成して確認する

データ エンジニアリング エージェントは、リクエストを完了するための目標と手順の概要と概要を提供するエージェント プランを生成できます。多くの変更を必要とする複雑なリクエストでエージェントにプロンプトを表示する場合は、エージェントにエージェント プランの提供を依頼して、エージェントがアクションを実行する前にエージェントの意図を確認することをおすすめします。Data Engineering Agent プランは通常、次の要素で構成されます。

  • 特定のリクエストに対するエージェントの目標
  • エージェントが計画している手順の概要
  • エージェントが立てた前提条件
  • エージェントが変更を計画しているファイル
  • 実行する予定の最適化またはクリーンアップの手順
  • 段階的な実行プラン

プロンプトに、プランの確認と承認が必要であることを含めることで、エージェントが明示的な承認なしにアクションを実行しないようにすることができます。次に例を示します。

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 からコンテキストを追加する

Data Engineering Agent は、用語集の用語を BigQuery のテーブルと列に関連付け、データ プロファイル スキャンを生成することで、Knowledge Catalog を使用します。用語集の用語は、特別な取り扱いが必要な個人情報（PII）を含む列など、追加のコンテキストが必要な列にタグを付ける場合や、テーブル間で名前が異なる一致する列を特定する場合に使用できます。

Knowledge Catalog は、データ プロファイリングも利用します。これにより、エージェントはテーブルの列内のデータ分布をより深く理解し、より具体的なデータ品質アサーションを作成できます。

既存のテーブルにデータ品質チェックを追加する

エージェントに品質チェックの追加を求めるプロンプトを入力すると、エージェントはスキーマとサンプルに基づいて、テーブルの妥当なチェックを推測します。プロンプトの一部として、意見の分かれるアサーションを追加することもできます。次に例を示します。

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

データ パイプラインの最適化

エージェントにデータ パイプラインの最適化を求めることができます。新しいテーブルの DDL を生成するときに、Data Engineering エージェントは、分析されたデータ使用パターンに基づいてパーティショニングとクラスタリングを推奨します。また、エージェントは他のパイプラインの最適化を自動的に適用できます。最適化の例を次に示します。

  • ストレージから読み取られるデータを削減する列プルーニング。費用とパフォーマンスの主な要因として機能します。
  • 述語プッシュダウンを使用して、実行プランの早い段階でデータをフィルタし、後続のオペレーションで処理される量を大幅に削減します。
  • 共通のサブ式を削除して、共有変換ロジックを 1 回だけ特定して計算することで効率を向上させ、大規模なテーブルの複数回のスキャンや結合などの非効率的な処理を防ぎます。
  • 増分モデル。実行ごとにテーブル全体を再構築するのではなく、前回の実行以降に新規作成または変更されたデータのみを処理します。

ベスト プラクティス

Data Engineering Agent と Dataform を使用する際のパフォーマンスを改善するには、次のことをおすすめします。

一般的なリクエストにはエージェントへの指示を活用する。よく使用する手法がある場合や、エージェントに同じ修正を頻繁に加える場合は、エージェントへの指示を共通の手順やリクエストを保存する一元的な場所として使用します。

エージェント プランを活用します。エージェント プランは、複雑なパイプライン タスクを分解するのに役立ちます。エージェントのプランには、エージェントの想定と意図も表示されます。エージェントに正しいコンテキストが提供されていることを確認するため、これらのプランを確認することをおすすめします。

プランを確認した後、フィードバックと変更を Data Engineering Agent にプロンプトで送信して、プランを編集できます。次に例を示します。

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

場合によっては、明示的な承認を必要としないプランをエージェントに作成してもらうと便利です。エージェントに計画を立てさせることで、Data Engineering エージェントはアクションを分解する必要があり、多くの場合、より良い結果が得られます。エージェントにプランの生成と自動実行を強制できます。次に例を示します。

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 つにして、プロンプトを簡潔にします。複数の質問を含むプロンプトの場合は、次の例に示すように、質問の各部分を個別に列挙して、明確さを高めます。

  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).