カタログアノテーション

概要

Codatumでは、コネクション設定で同期対象として指定されたテーブルのメタデータ（カラム定義等）を定期的に取得して、カタログを構築します
カタログ機能では、コネクションから自動的に取得できる情報に加えて、ユーザが手動で付与するアノテーション情報（説明・タグ）も管理できます
カタログアノテーションファイル（.cann.yaml）は、これらのアノテーション情報をローカルファイルとして管理し、CLIを使ってサーバと同期するために利用されるファイル形式です
- カタログアノテーションファイルの生成や同期については、cdm catalog annotation の各コマンドで行います
  - 各コマンドの利用方法は分析コンテキストの整備を、テーブル・カラムに何を書くかの設計の考え方は分析コンテキストの設計を参照してください
- ファイルは通常の YAML 形式のファイルで、 git 等でバージョン管理することを想定しています
- テーブル単位・カラム単位の説明(description)とタグ(tags)をアノテーション情報として管理できます
アノテーションが未設定のテーブル・カラムでは、DWH から取得された説明・タグ（DWH由来の値）がカタログ上に表示されます。アノテーションはこれらを上書きするものとして機能します

カタログの構造

カタログ内のテーブル情報は、ワークスペース毎に schemaUri と tableId の組み合わせで管理されています
- コネクション単位ではなく、DWH 上のスキーマ・テーブルの実体単位で管理されます
- 例えば BigQuery なら project / dataset / table 、Snowflake なら account / database / schema / table が一致すれば、同一の実体として扱われます
schemaUri は、DWH 上のスキーマを一意に識別するための識別子です
- スキーマ名のみを表す schemaId と異なり、project / account 等を含めてスキーマを一意に特定します（例: bq:my-project/analytics）
- 値は cdm catalog list-schemas で確認できます
tableId は、テーブル名で、スキーマ内でテーブルを一意に識別する ID として利用されます

ファイル定義

カタログアノテーションファイル（.cann.yaml）は、有効なYAML形式のファイルで、次のオブジェクト型で表現します

type CatalogAnnotationFile = {
  schemaUri: string;  // 例 bq:bigquery-public-data/thelook_ecommerce
  manages: 'listed-tables' | 'all-tables';
  tables: TableAnnotation[];
};

schemaUri は、このファイルが対象とするスキーマの識別子です
- 1ファイルで管理できる schemaUri は1つのみで、schemaUri ごとにファイルを生成します
manages は、このファイルが schemaUri の全テーブルを管理（all-tables）するか、一部のテーブルのみを管理（listed-tables）するかを宣言します
- 詳細についてはサーバとの同期と管理のパターンを参照してください
tables は、アノテーションを付与するテーブルの配列です
ローカルでのファイル名・ディレクトリ構造は自由です
- サーバとの同期は、ファイル内の schemaUri と tableId で対象を特定します

テーブルアノテーション

tables 配列の各要素は、次のオブジェクト型で表現します

type TableAnnotation =
  | {
      tableId: string;
      description?: string;  // 最大 1024 文字
      tags?: string[];  // 最大 16 タグ
      columns?: ColumnAnnotation[];
    }
  | {
      tableId: string;
      delete: true;  // アノテーションの削除を宣言（manages: listed-tables のみ）
    };

tableId はテーブル名で、スキーマ内でテーブルを一意に識別する ID として利用されます
description にはアノテーションとして付与するテーブルの説明を指定します
tags にはアノテーションとして付与するテーブルのタグ名の配列を指定します
- タグはIDではなくタグ名で記述します。指定可能なタグ名は cdm catalog tag list で確認できます
- テーブルに付与できるのはテーブル用（type:table）のタグのみです
description と tags の反映のされ方はサーバとの同期を参照してください
columns はカラム単位のアノテーションの配列です
delete: true は、このテーブルのアノテーションをすべて削除することを宣言します
- manages: all-tables では、テーブルの記載を削除することでアノテーションを削除するため、manages: listed-tables のファイルでのみ利用できます（サーバとの同期 / 正規化）
delete: true を指定しない各テーブルは、description / tags / columns のいずれかのフィールドを持つ必要があります（正規化）
- columns のみの場合は、空配列は許容されず、有効なアノテーションを持つカラムを含む必要があります

カラムアノテーション

columns 配列の各要素は、次のオブジェクト型で表現します

type ColumnAnnotation = {
  name: string;
  description?: string;  // 最大 1024 文字
  tags?: string[];  // 最大 16 タグ
};

name にはカラム名を指定します
- items.item_id のようにドットを含むカラム名も指定できます
description にはアノテーションとして付与するカラムの説明を指定します
tags にはアノテーションとして付与するカラムのタグ名の配列を指定します
- タグはIDではなくタグ名で記述します。指定可能なタグ名は cdm catalog tag list で確認できます
- カラムに付与できるのはカラム用（type:column）のタグのみです
description と tags の反映のされ方はサーバとの同期を参照してください
各カラムは、description または tags のいずれかのフィールドを持つ必要があります（正規化）

記述例

yaml

schemaUri: bq:my-project/analytics
manages: listed-tables
tables:
  - tableId: orders
    description: 注文トランザクション
    tags: [core, daily_batch]
    columns:
      - name: items.item_id
        description: 商品ID
        tags: [foreign_key]
      - name: amount
        description: 税込金額
        tags: []
  - tableId: users
    description: ユーザーマスタ
    tags: [core]
  - tableId: legacy_orders
    delete: true

正規化

ファイルには、有効なアノテーションを持つテーブル・カラムのみを記載します
- 「有効なアノテーションを持つ」とは、description または tags のいずれかのフィールドが定義されていることを指します
- テーブルの場合は、columns に有効なアノテーションを持つカラムがあれば、有効なアノテーションを持つとみなします
- フィールドの値が "" や [] であっても、それは「明示的に空を指定した」アノテーションの定義とみなします
- manages: listed-tables では delete: true を持つテーブルは、有効な削除宣言を持つ行として扱います
  - manages: all-tables で宣言された場合は、validate でエラーに、format で自動的に削除されます
管理対象のテーブルがない、もしくは、アノテーションを持つテーブルが1つもない状態の、tables: [] も有効なファイルとして扱われます
有効なアノテーションも delete: true も持たないテーブル・カラムは、
- cdm catalog annotation validate でエラーになります
- cdm catalog annotation format で自動的に削除されます
新しくアノテーションを付与するテーブルの発見には cdm catalog annotation untracked を、そのカラムの追記には cdm catalog annotation scaffold を利用します

DWH由来の値との関係

カタログには、アノテーションとは別に、DWH から自動的に取得される DWH由来の値 が存在します
- description は DWH 上のテーブル・カラムのコメント（COMMENT ON 等）を、tags は DWH 上のスキーマ情報（カラムの NOT NULL 制約など）を、それぞれソースとします
- 取得できる値の種類は DWH の種別によって異なり、今後拡張される可能性があります
カタログ上の表示は、description / tags のフィールド単位で決定されます
- アノテーションが設定されている場合: アノテーションの値を表示
- アノテーションが未設定の場合: DWH由来の値を表示（なければ空）
- 明示的な空（description: "" / tags: []）は未設定とは区別され、DWH由来の値にフォールバックせず空を表示します。DWH由来の値を隠したい場合に利用します
アノテーションを未設定のままにすると、DWH側の値の変更に自動追従します。そのため DWH由来の値は .cann.yaml に取り込まれず、pull でもファイルに書き込まれません

サーバとの同期

カタログアノテーションファイルは、pull と push でサーバ上のカタログと同期します。同期の挙動は pull / push とテーブル / カラムで異なるため、以下に分けて説明します。

pull（サーバ → ファイル）

pull は、サーバ上のカタログの最新のアノテーションをファイルに取り込みます。各テーブルがどう扱われるかは、 manages の設定により異なります。

	`all-tables`	`listed-tables`
ファイルに記載のあるテーブル	サーバの内容で更新	サーバの内容で更新
ファイルに記載のないテーブル	ファイルに追記	取得しない

サーバ上でアノテーションが削除されている場合は、 manages の設定とは関係なくファイルからも削除されます
- manages: listed-tables で delete: true を push したテーブルは、push 後はサーバ上でアノテーション未設定になるため、その後の pull でファイルから削除されます
テーブル内のカラムは、 manages の設定とは関係なく、サーバ上にアノテーションがあればファイルに反映し、サーバ上から削除されていればファイルからも削除します

push（ファイル → サーバ）

push は、ファイルの内容をサーバ上のカタログに反映します。ファイルに記載のないものをどう扱うかが、manages とテーブル / カラムで異なります。

テーブル

manages によって、ファイルに未記載のテーブルの扱いが異なります。

manages: all-tables: ファイルの記載をスキーマ全体のあるべき状態とみなします。ファイルに未記載のテーブルのアノテーションがサーバ上に存在する場合、そのアノテーションは削除されます。テーブルのアノテーションを削除するには、ファイルからそのテーブルの記載を削除します。
manages: listed-tables: ファイルに記載されたテーブルのみを対象とし、ファイルに未記載のテーブルは管理対象外として更新も削除もしません。テーブルのアノテーションを削除するには、記載を残したまま delete: true を指定します（記載を削除しても、そのテーブルは管理対象外になるだけで、サーバ上のアノテーションは削除されません）。

	`all-tables`	`listed-tables`
ファイルに記載のあるテーブル	ファイルの内容で更新	ファイルの内容で更新
ファイルに記載のあるテーブル（`delete: true`）	（利用不可）	削除
ファイルに記載のないテーブル	削除	更新しない

カラム

ファイルに記載されたテーブルについては、ファイルの内容を「あるべき状態」としてサーバに反映します。サーバ側の既存のアノテーションは、ファイルの記載内容で全面的に上書きされます。ファイルに書いていない説明・タグやカラムのアノテーションは削除されます。

一部だけを更新する（サーバ上の値を残したまま一部を変える）ことはできません。既存の状態を保ったまま編集するには、必ず編集前に pull でサーバの最新状態をファイルに取り込んでください。

	サーバにアノテーションあり	サーバにアノテーションなし
ファイルに記載のあるカラム	ファイルの内容で上書き	ファイルの内容で新規作成
ファイルに記載のないカラム	削除	変化なし

管理のパターン

スキーマ内のテーブルをどのように管理するかは、ユースケースに応じて以下のようなパターンがあります。

1ファイルで管理する

manages: all-tables を指定して、スキーマ内の全テーブルのアノテーションを1つのファイルで管理します。dump で --table を指定せずにファイルを生成すると、このパターンになります。

pull を実行すると新規にアノテーションされたテーブルも自動でファイルに追記されるため、1ファイルでスキーマ内の全テーブルのアノテーションを管理する運用ができます。テーブルのアノテーションを削除する場合は、そのテーブルの記載をファイルから削除します（push で削除が反映されます）。

分割して管理する

テーブル数が多く1ファイルでの管理が困難な場合や、ライフサイクルの異なるテーブルのアノテーションを別々に管理したい場合などは、manages: listed-tables のファイルを複数用意して管理することもできます。

その場合、テーブルの重複や漏れを防ぐために、次のような手順で運用します。

dump で --table を指定せずにファイルを生成します
生成したファイルを manages: listed-tables に変更して、分割数に合わせてコピーします
テーブルの記載が重複しないように、コピーしたファイルから不要なテーブルを削除します
- validate を利用してファイル間でのテーブルの重複がないかを検査できます
分割後に追加されたテーブルの検出には untracked を利用します。その際は分割された全ファイルを同時に指定します（一部のファイルだけを指定すると、他のファイルに記載済みのテーブルも未記載として検出されます）
テーブルのアノテーションを削除する場合は、記載を残したまま delete: true を指定します（記載自体を削除すると管理対象外になるだけで、サーバ上のアノテーションは残ります）

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

スキーマの一部のテーブルだけを管理し、それ以外のテーブルは管理しない場合は、dump の --table で対象テーブルを絞り込んでファイル生成します。（生成されるファイルは manages: listed-tables になります）

カタログアノテーション ​

概要 ​

カタログの構造 ​

ファイル定義 ​

テーブルアノテーション ​

カラムアノテーション ​

記述例 ​

正規化 ​

DWH由来の値との関係 ​

サーバとの同期 ​

pull（サーバ → ファイル） ​

push（ファイル → サーバ） ​

テーブル ​

カラム ​

管理のパターン ​

1ファイルで管理する ​

分割して管理する ​

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