分析コンテキストの設計

概要

AIエージェントにデータ分析を任せると、ハルシネーション・間違ったテーブルの参照・古いロジックでの集計・文脈を無視した解釈といった問題にぶつかります。これらの多くは、モデルの賢さの問題ではなく、エージェントに渡すべき情報（コンテキスト）が整理されていないことに起因します。

このページは「どんな情報を・どこに・どう書くか」という設計の考え方を扱います。あくまで考え方の一例であり、すべての環境に当てはまる唯一の正解ではありません。データの規模や組織の運用に応じて、必要な部分を取り入れてください。

ここで設計した内容を実際に整備・反映する操作の流れは分析コンテキストの整備を、ファイル形式の詳細はカタログアノテーション / カタログタグを参照してください。実際にこの題材でダッシュボードを作る流れは対話でダッシュボードを作成を参照してください。

分析に必要な情報の分類

エージェントが正しく分析するために必要な情報は、性質の異なる3つのレイヤーとして捉えると整理しやすくなります。

Metadata Layer（スキーマ・構造）

データの物理的な構造に関する情報です。多くは DWH から機械的に取得できます。

スキーマ・カラムの型
リネージ（どのテーブルから派生したか）
統計情報（行数、NULL 率、値の分布）

エージェントは、まずここを見て「どんなカラムがあり、どんな型か」を知ります。ただしこのレイヤーだけでは「そのカラムが何を意味するか」までは分かりません。

Semantic Layer（意味・定義）

データが何を意味するかの情報です。名前だけでは分からない、ビジネス上の意味がここに入ります。

メトリクスの定義（売上とは何の列を、どう集計したものか）
ビジネス用語（「確定注文」「実売価」などが何を指すか）
エンティティ解決（複数テーブルにまたがる同一概念の対応づけ）

このレイヤーにより、エージェントは「テーブル構造から指標を推測する」作業から解放され、一貫した定義で集計できます。同じ問いに毎回同じ数字が返る土台になります。

Context Layer（文脈・判断）

データをどう扱うべきか・なぜそうするかの情報です。組織固有の知識や、過去の判断の蓄積がここに入ります。3つのレイヤーの中で最も暗黙知になりやすい情報です。

暗黙知（tribal knowledge）: 「この期間のデータには旧仕様の値が混じる」「この異常値は仕様であってデータ不良ではない」といった、経験がないと気づけない注意点
判断のプレイブック: 「売上を聞かれたら、まずチャネルと期間を確認する」「金額はレポート時に税抜換算する」といった、分析を進める際の型
意思決定ログ: 「正式な売上値はどの集計方法を使うと決めたか」「なぜそう決めたか」の記録
ガバナンス: 機微情報（PII）の扱い、コスト（全件スキャンの回避）、アクセス制御、鮮度・非推奨（deprecation）といった、使ってよいかの判断材料

3つのレイヤーは入れ子の関係にあります。Metadata が土台にあり、その上に意味づけ（Semantic）が乗り、さらにその外側を組織固有の文脈（Context）が包む、という構造です。

どの情報を、どこに書くか

3つのレイヤーの情報を、Codatum のどこに書くかを整理します。すべてをカタログに詰め込むのではなく、カタログが得意なものだけをカタログに書き、それ以外はノートブックに書きます。

判断の基準

カタログのアノテーションは、(テーブル, カラム) に紐づく短い説明を書く場所です。ここに向くのは、次の3条件をすべて満たすものです。

テーブル・カラムに一意に紐づく（どのカラムの説明かが決まる）
短く収まる（description は簡潔な説明を書くもので、文字数上限がある）
文脈非依存で変わらない（どの用途・場面でも同じことが言える）

逆に、次のいずれかに当てはまるものは、カタログよりノートブックに書く方が適しています。

複数テーブルにまたがる: 「このテーブルとあのテーブルはこう結合する」「この3つを組み合わせて初めて意味を持つ」といった関係は、特定の1カラムに紐付けられないため、無理にカタログに書くと内容が重複してしまいます。
分量が多い: まとまったサンプルSQL、複数ステップの分析手順、長い背景説明。
用途によって答えが変わる: 「売上の定義」が経営レポートとマーケ分析で違う、のように文脈次第で変わるものは、カラムに1つの正解を固定できないため、用途ごとのノートブック（と用途タグ）で表現する方が適しています。

カタログ（アノテーション・タグ）に書くもの

上の3条件を満たす、テーブル・カラムに固定できる短い事実を書きます。カタログアノテーション（.cann.yaml）の description と tags に書きます。

Metadata の補足: 型だけでは分からない値の意味・単位・NULL の扱い
Semantic: そのカラムの意味、標準的な集計方法、対になるカラムとの関係
Context のうちカラムに固定できるもの: 「この列は税込」「Complete 以外は返品・キャンセル」といった、用途によらず変わらない注意
用途・ガバナンスの目印: tags による分類（board-report / certified / pii など）

カタログは、エージェントが分析の起点で cdm catalog search-tables を通じて参照する場所です。テーブル・カラム単位で「これは何で、どう扱うか」が引ける状態にしておきます。

ノートブックに書くもの

上の3条件のいずれかを外れるもの（複数テーブルにまたがる関係、まとまった分量、用途で変わる判断）はノートブックに書きます。Context Layer の情報のうち、暗黙知の詳しい背景・分析のプレイブック・意思決定ログといった「説明を要するもの」も、多くはこちらに向きます。

例えばサンプルSQL（完全なクエリに限らず、WHERE 句の書き方や結合パターンなど）は、コードブロックや考察と一体で扱えるノートブックに置くのが適しており、カタログの description からはそのノートブックのURLを参照する形にします。

ノートブック自体が、分析の知見が蓄積・共有される Context の源です。分析を重ねるほどノートブックに知見が溜まり、そのうちカラムに固定できる短い事実だけをカタログに還流させる——この役割分担と往復が、カタログとノートブックの両方を育てます（詳しくは分析コンテキストの整備）。

整理

情報	書く場所
値の意味・単位・NULL の扱い（カラムに固定）	カタログ（`description`）
カラムの意味・標準的な集計方法・対になるカラムとの関係	カタログ（`description`）
用途によらず変わらない短い注意	カタログ（`description`）
用途・信頼性・扱いの目印	カタログ（`tags`）
複数テーブルにまたがる関係・結合パターン	ノートブック
サンプルSQL・分析手順・考察・チャート	ノートブック
用途によって変わる定義・判断のプレイブック・意思決定ログ	ノートブック

タグを先に設計する

具体的な記載に入る前に、タグを先に設計します。タグは分類とガバナンスの骨格であり、その場の思いつきで増やすと機能しなくなるためです（タグはワークスペース全体で共有され、表記揺れも別タグ扱いになります。運用ルールの詳細は分析コンテキストの整備を参照）。

タグは、テーブル・カラムを横断する「分類」や「目印」を担います。ここで価値があるのは、スキーマを見れば分かることではなく、見ても分からない、組織が決めた用途や約束事です。分析でよく使う軸を、あらかじめ洗い出しておきます。

用途の分類: どの場面で使うことを想定したデータか（例: board-report = 経営レポートに使う正式な数値の源 / marketing-analysis = マーケ分析用のデータ群）
信頼性・状態: 正式に使ってよいか（例: certified = 検証済み / experimental = 検証中で正式な数値には使わない / deprecated = 非推奨）
扱いの注意: 出力やコストで気をつける点（例: pii = 個人情報を含む / high-cost = 全件スキャンでコスト大、絞り込み必須）

なかでも用途の分類が、タグの価値を最もよく表します。テーブルが多いと、そもそもどれを分析に使うべきかが分かりません。さらに、同じ「売上」を出すにも、経営会議に出す確定値とマーケの速報分析で使う数値では、参照すべきテーブルが違うことがあります。こうした違いは構造を見ても分からず、組織が「経営レポートの売上はこのテーブル群を使う」と決めた約束事です。これを board-report タグにしておくと、エージェントは「経営会議用の売上を出して」に対し --tag board-report で公式の源だけに絞り込め、用途を取り違えた集計を防げます。

これらは Context Layer の「用途・ガバナンス」を、機械的に絞り込める形にしたものです。説明（description）が部分一致で「探す」のに向くのに対し、タグは --tag の完全一致で分析対象を「確定する」のに向きます。

定義はカタログタグ（.ctag.yaml）に記述します。

yaml

tags:
  - name: board-report
    type: table
    color: "#666CFF"
    description: 経営・取締役会レポートに使う正式な数値の源となるテーブル
  - name: certified
    type: table
    color: "#7ECF4F"
    description: 検証済みで、正式な分析に使ってよいテーブル
  - name: experimental
    type: table
    color: "#FDAD6D"
    description: 検証中のテーブル。正式な数値には使わない
  - name: pii
    type: column
    color: "#FF91BE"
    description: 個人を特定しうる情報を含むカラム。出力時は集約・匿名化に注意

カタログに記載する

タグ設計ができたら、テーブル・カラムのアノテーションを書きます。ここでは BigQuery 公開データセット bigquery-public-data.thelook_ecommerce（架空ECの売上データ）を題材に、3つのレイヤーを意識した description の書き分けを示します。

description は自由記述なので、Metadata の補足・Semantic の意味づけ・Context の注意を、1つの説明の中にまとめて書けます。以下の例では、どの記述がどのレイヤーにあたるかを後述の解説で示します。

yaml

schemaUri: bq:bigquery-public-data/thelook_ecommerce
manages: listed-tables
tables:
  - tableId: order_items
    description: |
      注文明細（1行＝1注文中の1商品）。売上・数量分析の基点。
      売上をどの注文状態で集計するかは用途で変わる。集計の指針と代表的な集計例はノートブックにまとめている:
      https://app.codatum.com/workspace/xxx/notebook/yyy/zzz
    tags: [board-report, certified]
    columns:
      - name: status
        description: |
          注文状態: Complete / Shipped / Processing / Cancelled / Returned。
          売上集計でどの状態を対象にするかは用途で変わる（ノートブックを参照）
      - name: sale_price
        description: |
          明細1行あたりの実売価（税込）。売上 = この列の SUM。
          定価は products.retail_price。値引き後の実売価はこちらを使う
      - name: created_at
        description: 注文作成日時。売上を日次・月次で見るときの基準日はこの列を使う
  - tableId: users
    description: 会員マスタ。顧客の属性を持つ
    columns:
      - name: email
        description: メールアドレス。個別値は出力せず、集計・件数のみに使う
        tags: [pii]

各記述が、どのレイヤーの情報かを見ていきます。

status の値の一覧（Complete / Shipped / …）→ Metadata。型からは読めない、取りうる値を示しています。
「どの状態を対象にするかは用途で変わる」→ Context。売上の集計対象は用途によって変わるため、カラムに1つの正解を固定せず、集計の指針はノートブックに委ね、カタログからはそこへ誘導します。名前からは要否が読めないので、この誘導自体をカタログに置いて絞り込み忘れを防ぎます。
sale_price は実売価、retail_price は定価→ Semantic。名前の似た2つの価格カラムの違いを相互参照で書き、どちらを見ても正しい方を参照できるようにしています。
created_at を基準日にする→ Semantic / Context。複数ある日時カラムのうち、分析の基準日に何を使うかの取り決めです。
email の「個別値は出力せず集計のみ」＋ pii タグ→ Context（ガバナンス）。扱い方の注意で、カラムに固定できる短いものなのでカタログに書けます。
テーブル説明のノートブックURL→ 用途で変わる集計方法やサンプルSQLは Context ですが、用途で変わるうえ分量も多いためノートブックに置き、カタログからは URL で参照します。

タグの付与も、Context の情報です。

board-report → 用途の分類です。「経営レポートの正式な売上はこのテーブルを使う」という約束事で、--tag board-report で公式の源だけに絞り込めます。
certified → 信頼性の状態です。検証済みで正式な分析に使ってよい、という目印になります。
pii → 扱いの注意です。個人情報を含むカラムの目印で、--tag pii で機微なカラムを横断的に洗い出せます。

ノートブックに記載する

カタログに収まらないもの（複数テーブルにまたがる関係、まとまった分量、用途で変わる判断）は、ノートブックに書きます。例えば「売上分析ガイド」のようなノートブックを1つ用意し、カタログの description からそこへリンクします。このノートブックには、例えば次のような内容をセクションとして書きます。以下の各項目は、その1つのノートブックを構成する要素の例です。

用途で変わる定義を書く

「売上」に含める注文状態が用途で違う、というカラムに1つの正解を固定できない判断は、用途ごとに何を対象にするかを書き分けます。

用途	集計対象の status	備考
経営レポート	`Complete` のみ	確定した売上のみ。返品・キャンセルは除外
出荷ベースの速報	`Complete`, `Shipped`	出荷済みを見込みで含める
需要分析	`Cancelled` 以外すべて	注文の意思があったものを需要とみなす

用途別の絞り込みを、WHERE 句の断片で示す

上の用途に対応する絞り込み条件を、そのまま参照できる形で示します。

sql

-- 経営レポート向け（確定売上のみ）
WHERE status = 'Complete'

-- 需要分析向け（キャンセル以外）
WHERE status != 'Cancelled'

複数テーブルにまたがる関係を示す

テーブルをまたぐ関係はカタログに収まりにくいため、ノートブックにまとめます。ノートブックではダイアグラムブロックが利用できるため、全体像を掴めるように主要テーブルのER図をまとめます。

そのうえで、具体的な取り出し方は結合パターンごとに示します。例えば原価を使った粗利の算出は、order_items → inventory_items の結合が必要で、特定の1カラムには固定できない関係です。

sql

-- 粗利 = 実売価 - 原価。原価は inventory_items 経由で引く
SELECT
  oi.order_id,
  oi.sale_price - ii.cost AS gross_profit
FROM order_items AS oi
JOIN inventory_items AS ii
  ON oi.inventory_item_id = ii.id
WHERE oi.status = 'Complete'

ER図に限らず、ノートブックではダイアグラムブロックで Mermaid 記法（フローチャート・状態遷移図など）が使えます。関係や流れが文章より図で伝わりやすい場面では、うまく活用してください。

分析の進め方や暗黙知を、文章で残す

分析を進める際の型や、経験がないと気づけない注意点は、文章で書き残します。

売上を問われたら、まずチャネル（EC / 店舗）と対象期間を確認する。金額はデータ上すべて税込なので、社外向けレポートでは税抜換算する。なお、初期の一部データには旧仕様の状態コードが混じるため、古い期間を対象にするときは値の分布を確認してから集計する。

こうしたノートブックを整えておけば、カタログの短い説明ではカバーしきれない「用途で変わる判断」「結合を伴う分析」「説明を要する知見」を、カタログからのリンクをたどってエージェントが参照できます。

次のステップ

ここで設計した分析コンテキストを、実際に整備・反映する手順は分析コンテキストの整備を参照してください。フォーマット・差分確認・反映といった一連の操作フローを説明しています。

整備は一度で完成するものではありません。分析を進める中で見つかった新しい意味・注意点をカタログに書き足し、整備されたカタログが次の分析の精度を上げる——この往復で、分析とコンテキストの両方を育てていきます。エージェントに整備を任せる場合の進め方は AIエージェントのセットアップと AIエージェント向けガイドを参照してください。

分析コンテキストの設計 ​

概要 ​

分析に必要な情報の分類 ​

Metadata Layer（スキーマ・構造） ​

Semantic Layer（意味・定義） ​

Context Layer（文脈・判断） ​

どの情報を、どこに書くか ​

判断の基準 ​

カタログ（アノテーション・タグ）に書くもの ​

ノートブックに書くもの ​

整理 ​

タグを先に設計する ​

カタログに記載する ​

ノートブックに記載する ​

用途で変わる定義を書く ​

用途別の絞り込みを、WHERE 句の断片で示す ​

複数テーブルにまたがる関係を示す ​

分析の進め方や暗黙知を、文章で残す ​

次のステップ ​

関連ドキュメント ​