分析コンテキストの整備

概要

分析コンテキストの設計 で「どんな情報を・どこに・どう書くか」を決めたら、それを実際にカタログへ反映していきます。テーブル・カラムの説明（description）やタグ（tags）を整備することで、cdm catalog search-tables の検索性が向上し、AIエージェントの精度も上がります。

カタログアノテーションファイル（.cann.yaml）やカタログタグファイル（.ctag.yaml）を活用することで、カタログの整備や管理をAIエージェントや git 経由で行うことができます。このページでは、設計した内容を整備・反映する一連の操作フローと、整備を回すうえでの運用上の注意を説明します。

何を書くべきか・どこに書くべきかという設計の考え方は 分析コンテキストの設計 を参照してください。

整備を回す際の考え方

進め方

• カタログの整備とノートブックによる分析は、それぞれが独立した工程ではなく、相互にフィードバックを行いながら、改善していくことを推奨します
  • ノートブックによるデータ分析の結果やその過程から得られた知見を、カタログに還流していくことで、分析の精度とカタログの精度の両方を改善していきます
  • AIエージェントを使うことで、大量のノートブック資産から、カタログの改善に必要な情報を効率よく抽出し、カタログの改善につなげることができます
  • カタログアノテーションファイル（.cann.yaml）やカタログタグファイル（.ctag.yaml）は、テキストファイルなので、git でバージョン管理すれば、いつでも過去の状態に戻すことができます
• カタログアノテーションファイルは、1つのスキーマ内のテーブルを1ファイルで管理することも、複数の .cann.yaml ファイルに分けて管理することもできます（管理のパターン）
  • より厳密にカタログを整備したい場合は、dbt などのデータパイプライン用のコードと一緒に管理することもできます

運用上の注意

説明（description）やタグ（tags）に「何を書くか」は 分析コンテキストの設計 で扱いますが、整備を継続的に回すうえでは、次のような運用面の注意があります。

説明（description）

• テーブルやカラムの説明は、cdm catalog search-tables の検索対象（テーブル名・カラム名・タグ名とあわせた部分一致）になります。検索でヒットさせたいキーワードを詰め込むと、ヒット数が増えすぎて逆に目的のテーブルが見つけにくくなるため、横断的な分類はタグで表現します
• 長文の記述は避けてください（上限1024文字）。テーブルのリレーションやサンプルSQLなどはノートブックに記述し、そのノートブックへのリンク（URL、ファイルパス）を説明内に記載することを推奨します

タグ（tags）

• タグは --tag / --tag-id による完全一致での絞り込みに対応しています。分析に利用したいテーブルにタグを付けておけば、似たテーブルが混在していても、そのタグの付いたテーブル群を確実に絞り込めます
• タグはワークスペース全体で共有されるリソースで、表記ゆれ（daily_batch と daily-batch など）も別タグ扱いになります
  • 無計画に増やすと分類が機能しなくなるため、必要になったタイミングで都度作成するのではなく、ワークスペース全体で作成・管理のルールを事前に定めておくことを推奨します（どのようなタグを設計するかは タグを先に設計する を参照）
  • 使われなくなったタグは cdm catalog tag prune で掃除できます。ただしタグはワークスペース全体で共有されるため、複数のワークフローで同じタグを扱う場合は、どのワークフローがどのタグを管理・削除するかを事前に取り決めておくと、意図しない削除を避けられます
  • タグの編集権限・削除権限はPAT単位で制限できるため、必要な場合のみ権限を付与する運用を推奨します。特に削除は破壊的な操作のため、CI 等で作成・更新のみを行う場合は削除権限を付与しないことを推奨します

カタログ整備の流れ

あるスキーマのテーブルにアノテーションを付けて反映するまでの流れを説明します。インストールと認証は はじめに と共通です。

1. 対象スキーマを確認する

整備したいスキーマの schemaUri を cdm catalog list-schemas で確認します（コネクションIDは cdm connection list で確認できます）。

cdm connection list                                    # コネクションIDを確認
cdm catalog list-schemas -c 671ef14b0d08cf6c657df7da   # スキーマ一覧を確認

2. 対象ファイルを用意する

どのパターンで管理するかに応じて、起点となる .cann.yaml を dump で生成します。既にアノテーションを整備したファイルがある場合は、生成ではなく pull で最新化してから編集してください（push はファイルの内容を正として反映するため、古いファイルのまま反映するとサーバ側の変更を意図せず上書きすることがあります）。

スキーマ全体を管理する

dump を --table を付けずに実行して、manages: all-tables のファイルを生成します。続いて、サーバ上のカタログに存在するがアノテーションがないテーブルを untracked で確認します。

cdm catalog annotation dump bq:my-project/analytics -o annotations/
cdm catalog annotation untracked annotations/analytics.cann.yaml   # 未整備テーブルの確認

特定のテーブルだけを管理する

dump を --table で対象を絞り込んで実行して、manages: listed-tables のファイルを生成します。

cdm catalog annotation dump bq:my-project/analytics --table orders --table order_items -o annotations/analytics.mart.cann.yaml

なお、1つのスキーマを複数ファイルに分割して全体を管理したい場合は、分割して管理するを参照してください。

3. アノテーションの雛形を追記する

整備したいテーブルのカラムを cdm catalog annotation scaffold でファイルに追記します。サーバにアノテーションがあれば取り込み、無ければテーブル名・カラム名だけの空の候補行が追記されます。

cdm catalog annotation scaffold annotations/analytics.cann.yaml orders

4. 説明とタグを埋める

ファイルをエディタで開いて、追記された候補行に説明（description）やタグ（tags）を記述します。何をどう書くかの考え方と記述例は 分析コンテキストの設計 を参照してください。

タグを利用する場合は、まず cdm catalog tag list で既存のタグを確認し、なるべく再利用してください。新しくタグを定義する場合は、.ctag.yaml（カタログタグ）で管理します。既にタグ定義ファイルがある場合は、annotation と同様に cdm catalog tag pull で最新化してから編集してください。

cdm catalog tag list   # 既存のタグを確認

5. 検証とフォーマット

編集後、cdm catalog annotation format で整形します。値を埋めていない空の候補行は format で削除されるため、埋め忘れの確認も兼ねられます。

cdm catalog annotation format annotations/

6. 差分の確認とサーバへの反映

反映内容を cdm catalog annotation diff で確認し、問題なければ cdm catalog annotation push で反映します。

記載のないカラムのアノテーション（manages: all-tables の場合は記載のないテーブルも）は削除されるため（詳しくはサーバとの同期を参照）、意図しない削除が含まれていないか diff で確認してください。

cdm catalog annotation diff annotations/   # 反映される差分を確認
cdm catalog annotation push annotations/   # サーバへ反映

タグはアノテーションから参照されるため、アノテーションが新しいタグを参照する場合は、先にタグを反映しておきます。タグ定義（.ctag.yaml）の反映も、同様に cdm catalog tag diff で差分を確認してから cdm catalog tag push で反映します。

cdm catalog tag diff tags/   # 反映される差分を確認
cdm catalog tag push tags/   # サーバへ反映

7. 使われなくなったタグの掃除（任意）

整備を重ねると、付与先がなくなって参照されないタグが残ることがあります。必要に応じて cdm catalog tag prune で、どのテーブル・カラムにも付与されていないタグを削除できます。

cdm catalog tag prune tags/   # tags/ 配下に定義したタグのうち、未参照のものを掃除

関連ドキュメント

• 分析コンテキストの設計 — 何を・どこに書くかの設計の考え方
• カタログアノテーション — .cann.yaml の形式と正規化・管理のパターン
• カタログタグ — .ctag.yaml の形式とタグ定義
• アノテーションの管理 — アノテーション同期コマンドの一覧
• タグの管理 — タグ同期コマンドの一覧
• カタログの検索 — テーブル・スキーマ・タグの検索