DataWorks:Data Agent のセマンティック分析

概要

Data Agent が NLQ や SQL 生成などのタスクを実行する際、ビジネスデータの構造とセマンティクスを理解する必要があります。セマンティック分析機能は、MaxCompute のデータソーステーブルを自動的にスキャンし、テーブル間のリレーションシップ、フィールド定義、メトリクス計算ロジックを抽出し、YAML 形式で構造化されたセマンティックモデルを生成します。このモデルは、視覚的なグラフとソースコードのデュアルパネルビューを通じて分析結果を提示し、データ資産間のリレーションシップを直感的に理解するのに役立ちます。

セマンティック分析により、次のことが可能になります。

• データ資産のリレーションシップを自動的に整理：手動の作業なしで、システムがテーブル構造、フィールドセマンティクス、テーブル間のリレーションシップを自動的に識別します。

• 視覚的なセマンティックグラフを生成：データセットとメトリクス間のリレーションシップをグラフ形式で表示し、グラフと YAML ソースコード間のデュアルパネルナビゲーションを提供します。

• AI クエリの精度を向上：セマンティックモデルを Data Agent のセッションコンテキストにロードする (/dataworks-semantic コマンドを使用) ことで、AI はビジネスセマンティクスに基づいてより正確な SQL を生成できます。

• 手動での修正とイテレーションをサポート：分析結果はオンラインで編集および保存できます。変更はタスクを再実行することなく即座に有効になります。

MaxCompute データソースから正確なデータクエリまで、セマンティック分析は 5 つの主要な段階をカバーします。

前提条件

• Data Agent をアクティベート済みであること。アクティベートしていない場合は、「アクティベーションプロセス」を参照してアクティベーションを完了してください。

• 利用可能な MaxCompute データソースがワークスペースに設定されていること。

• 利用可能なリソースグループが準備されていること。少なくとも 4 CU の仕様を推奨します。

ステップ 1：セマンティック分析タスクの作成

1. Data Agent の設定 に移動します。左側メニューで、[セマンティック分析] をクリックします。

2. セマンティック分析のリストページで、[タスクの作成] をクリックします。

3. [タスクの作成] ダイアログボックスで、次のパラメーターを設定します。

   パラメーター	説明
   名前	必須。形式は、使用制限に記載されている要件に準拠する必要があります。
   データソースタイプ	必須。現在、MaxCompute のみがサポートされています。
   ビジネスドメインとフォーカス	必須。分析の対象としたいビジネスドメインとテーブル階層を自然言語で記述します。例：「E コマースのライブストリーミングドメイン、アンカーの売上と商品の売上ディメンションをカバー、DWD から ADS 階層まで。」 このパラメーターは 2 つの目的を果たします。 分析の方向性をガイド：AI にどのビジネスディメンションを優先すべきかを伝え、関連するメトリクスとリレーションシップを抽出するように誘導します。 コードスキャン範囲の絞り込み：AI はビジネスドメインの記述を使用して、ワークスペース内の DataWorks フォルダー構造を通じて関連するコードとスケジューリングタスクを特定します。たとえば、「E コマースライブストリーミングドメイン」と記述した場合、AI はワークスペース全体をスキャンするのではなく、「e-commerce」および「livestream」フォルダー配下のノードの分析に集中します。 より詳細な記述は、より正確なテーブル分析と、より的を絞ったコードスキャンにつながります。
   ワークスペース	必須。ドロップダウンリストから DataWorks ワークスペースを選択します。 このワークスペースは単なる実行環境ではなく、AI の ビジネスナレッジソース でもあります。AI はこのワークスペースから SQL スクリプト、スケジューリングタスク、コードフォルダー構造を読み取り、実際のメトリクス計算ロジックを解釈します。たとえば、SQL コードから SUM(CASE WHEN order_status='paid' THEN pay_amount END) のような式を抽出し、メトリクスが実際にどのように計算されるかを理解します。 重要 必ずデータ処理コードが含まれるワークスペースを選択してください。間違ったワークスペースを選択すると、AI は実際の処理コードを読み取ることができず、フィールドのコメントからメトリクスの意味を推測するしかなくなり、モデルと実際の計算との間に不整合が生じます。
   リソースグループ	必須。タスクの実行に使用するリソースグループを選択します。
   ピン留めされたテーブル	必須。カスケードセレクターで、左側のパネルで MaxCompute プロジェクトを展開し、右側のパネルで特定のテーブルを選択します。プロジェクトをまたいでテーブルを選択でき、合計で最大 30 テーブルまで選択できます。モデルは、これらのテーブルの構造とリレーションシップの分析に焦点を当てます。
   参照ファイル	任意。ファイルをアップロードするか、ファイル URL を入力して、外部の参照資料を提供できます。

4. 設定が完了したら、ダイアログボックスの下部にある [OK] ボタンをクリックします。「Task created」というメッセージが表示されると、リストが自動的に更新されます。

ステップ 2：セマンティック分析タスクの実行

タスクが作成された後、次のように実行できます。

1. セマンティック分析リストページで、対象のタスクを見つけ、[操作] 列の [実行] をクリックします。

2. システムに「Run submitted」というメッセージが表示され、自動的にタスク詳細ダイアログボックスが開きます。

タスクが送信されると、システムはバックグラウンドでセマンティック分析を実行します。実行時間は分析対象のテーブルの数と量に依存し、通常は数分かかります。AI エンジンは、2 つのディメンションから同時に分析を実行します。

• ディメンション 1： ワークスペースから SQL スクリプトとスケジューリングタスクを読み取る。ビジネスドメインの記述に基づき、AI は DataWorks のフォルダー構造を通じて関連するコードを特定し、SQL から実際のメトリクス計算ロジックとテーブル間の処理リレーションシップを解釈します。

• ディメンション 2： ピン留めされたテーブルのメタデータをスキャンする。AI は各フィールドのビジネスセマンティクス、シノニム、テーブル間の階層関係、ビジネスメトリクス定義、派生メトリクス式、および Q&A の例を抽出します。

両ディメンションの分析結果は相互に検証され、単一の包括的なセマンティックモデルにマージされます。

ステップ 3：タスク詳細と実行ステータスの表示

タスクリストでタスク名をクリックすると、タスク詳細ダイアログボックスが開きます。タスク詳細には次のタブが含まれています。

ステップ 4：セマンティックモデルの表示と編集

[実行履歴] タブに移動し、「Success」ステータスの実行記録の [結果の表示] をクリックして、セマンティックモデル結果ビューアーを開きます。

結果ビューアーは、グラフとソースコードのデュアルパネルビューを提供します。

• セマンティックモデルグラフ：データセット間のリレーションシップを視覚的な形式で表示します。グラフ内のノードはデータセットまたはメトリクスを表し、エッジはそれらの間のリレーションシップを表します。グラフ内のノードまたはエッジをクリックすると、右側のソースコードエディターが自動的に対応する行までスクロールし、ハイライト表示します。

• YAML ソースコードエディター：セマンティックモデルの YAML ソースコードを表示します。トップレベルの構造には、データセット定義、フィールド記述、ai_context、およびその他の情報が含まれます。ソースコードを閲覧すると、左側のグラフが自動的に対応するノードまたはエッジをハイライトし、中央に表示します。

結果ビューアーは、次の機能もサポートしています。

• フルスクリーン表示：[フルスクリーン] ボタンをクリックすると、グラフまたはソースコードをフルスクリーンモードで表示できます。

• 編集と保存：[編集] をクリックして編集モードに入ります。YAML の内容を変更した後、[保存] をクリックして変更をバックエンドに書き込みます。変更はタスクを再実行することなく、保存後すぐに有効になります。変更を破棄するには、[リセット] をクリックして最後に保存されたバージョンを復元します。[変更の比較] を使用して差分を表示することもできます。

セマンティックモデルの YAML 構造

AI エンジンによって生成されるセマンティックモデルは、トップレベルに 4 つのコアモジュールを持つ YAML 形式を使用します。

以下は、簡略化された YAML ソースコードの例です。

semantic_model:
  - ai_context:
      instructions: |
        E コマースのライブストリーミングデータ分析ドメイン。アンカーの売上
        と商品の売上ディメンションをカバーしています。
        データ階層： ODS → DWD → DWS → ADS
        パーティションフィールド： dt。通貨： CNY。
      few_shots:
        - question: 昨日の GMV トップ 10 のアンカーは誰ですか？
          sql: |
            SELECT anchor_name, gmv
            FROM ads_ctlive_anchor_stats
            WHERE stat_period = '1d'
            ORDER BY gmv DESC LIMIT 10;

    metrics:
      - name: GMV
        description: 総取引額 (CNY)
        ai_context:
          synonyms: [売上高、取引量、収益]
        expression:
          dialects:
            - dialect: MaxCompute
              expression: SUM(gmv)

    metric_formulas:
      - name: 平均注文額
        description: 注文あたりの平均取引額 (CNY)
        formula: GMV / 注文数

    datasets:
      - source: ads_ctlive_anchor_stats
        description: ADS - アンカー取引統計
        fields:
          - name: anchor_name
            type: string
            description: アンカーのニックネーム
            synonyms: [アンカー、ストリーマー、ホスト]
          - name: gmv
            type: double
            description: 総取引額 (CNY)
            metric: true
            synonyms: [売上高、GMV、収益]

ステップ 5：Data Agent でセマンティックモデルをロードして使用する

前述の手順で YAML セマンティックモデルを生成した後、モデルはサーバー側に保存されます。Data Agent のチャットセッションからこのモデルへ自動的にアクセスすることはありません。AI が質問に答える際にモデル内のビジネスナレッジを参照できるように、エージェントセッションでセマンティックモデルを明示的にロードする必要があります。

手順：

1. Data Agent を開き、チャットウィンドウに入ります。

2. チャット入力ボックスに /dataworks-semantic と入力して送信します。

3. エージェントは自動的に実行します： 環境チェック → 利用可能なタスクのリスト → YAML 出力のダウンロード → 現在のセッションの AI コンテキストへのインジェクション。

4. ロードが成功したことを確認した後、セマンティックモデルに基づいてクエリと SQL の生成を開始できます。

結果ファイルを手動でダウンロードするには、コンソールの [実行履歴] タブに移動し、成功した実行記録の [結果のダウンロード] をクリックして YAML 出力ファイルを取得します。

セマンティックモデルをロードした後、次のシナリオで品質が大幅に向上します。

シナリオ例：E コマースライブストリーミングのエンドツーエンドウォークスルー

以下では、E コマースライブストリーミングシナリオを使用して、タスクの作成から正確なクエリまでの完全なワークフローをウォークスルーします。

1. タスクの作成 (ステップ 1)

セマンティック分析ページで [タスクの作成] をクリックし、次の設定を入力します。

2. タスクの実行 (ステップ 2)

[実行] をクリックします。AI セマンティックエンジンは自動的に次の分析を実行します：「E コマースライブストリーミングドメイン」に一致するワークスペースフォルダーを特定し、SQL スクリプトを読み取る → コードから実際のメトリクス計算ロジックを抽出する (例：gmv = SUM(CASE WHEN order_status='paid' THEN pay_amount END) であることを特定) → 4 つのテーブルにわたるメタデータとフィールドリレーションシップをスキャンする → ADS/DWS 階層を特定する → メトリクス定義、派生式、および SQL の例を含む構造化 YAML モデルを生成する。

3. モデルの表示と編集 (ステップ 3 および 4)

タスクが完了したら、タスク詳細ページの [セマンティックモデル] タブを開きます。グラフビューを使用してテーブルのリレーションシップを確認し、YAML エディターでメトリクス定義を微調整したり、ビジネスコンテキストを追加したりします。満足したら変更を保存します。

4. Data Agent へのロード (ステップ 5)

Data Agent セッションで、/dataworks-semantic download <job-name> に続けて /dataworks-semantic index <job-name> を実行して、モデルをローカルにダウンロードし、インデックスを構築します。そのセッションでの後続のすべてのクエリは、セマンティックモデルを活用して正確な回答を生成します。

5. 結果の検証

ロード後、ロード前後の同じ質問に対するエージェントの応答品質を比較します。

ユーザーの質問：「昨日の GMV トップ 10 のアンカーは誰ですか？」

-- AI がテーブル名とフィールド名を推測
SELECT host_name, total_amount
FROM live_stream_sales
WHERE date = '2026-07-27'
ORDER BY total_amount DESC
LIMIT 10;

-- セマンティックモデルに基づいて生成
SELECT anchor_name, gmv
FROM ads_ctlive_anchor_stats
WHERE stat_period = '1d'
ORDER BY gmv DESC
LIMIT 10;

ユーザーの質問：「過去 30 日間のカテゴリ別平均注文額はいくらですか？」

-- AI が「平均注文額」を誤解
SELECT category, AVG(price) AS avg_price
FROM products
GROUP BY category;

-- モデルは知っている：平均注文額 = GMV / 注文数
SELECT cate_level1_name,
  SUM(gmv) / SUM(order_cnt) AS avg_order_value
FROM ads_ctlive_item_stats
WHERE stat_period = '30d'
GROUP BY cate_level1_name
ORDER BY avg_order_value DESC;

セマンティックモデルをロードすると、AI は自動的に ai_context (ビジネスドメインの記述)、metrics (定義とシノニム)、metric_formulas (派生式)、および datasets (テーブルとフィールドのマッピング) を参照し、「推測」から「知識に基づく正確な生成」へと変貌します。

よくある質問

Q： タスクが失敗する可能性のある原因は何ですか？

A： タスクの失敗は、通常、次の理由によって引き起こされます。

• リソースグループの仕様が不十分：リソースグループの仕様が 4 CU 未満の場合、リソース不足によりタスクが失敗することがあります。少なくとも 4 CU の仕様のリソースグループを選択することを推奨します。

• MaxCompute プロジェクトの権限が不十分：セマンティック分析タスクを実行するワークスペースには、対象の MaxCompute プロジェクトに対する読み取り権限が必要です。ワークスペースと MaxCompute プロジェクト間のバインディング関係と権限設定を確認してください。

• データ量が過大：1 回の分析でテーブルが多すぎる、またはデータ量が多すぎると、タイムアウトが発生する可能性があります。ピン留めされたテーブルの数を減らして、再度試すことを推奨します。

Q： YAML を編集した後にタスクを再実行する必要がありますか？

A： いいえ。結果ビューアーで YAML を編集して保存すると、変更はすぐに有効になります。次回 /dataworks-semantic を介してダウンロードすると、最新バージョンが自動的に取得されます。

Q： Data Agent でセマンティックモデルを使用すると、トークンの有効期限切れエラーが発生します。

A： /dataworks-semantic check を実行して環境を確認してください。認証関連のエラーが表示された場合は、認証情報を更新して再試行してください。

Q： ダウンロード時に「local edits detected」と表示されます。どうすればよいですか？

A： これは、前回のダウンロード後に YAML ファイルが変更されたことを意味します (ハッシュの不一致)。ローカルの変更を上書きするには、--force フラグを追加して強制的にダウンロードします。最初にローカルの編集をバックアップすることを推奨します。

関連ドキュメント

• Data Agent の課金

• Data Agent