アノテーションの管理

cdm catalog annotation サブコマンドは、カタログアノテーションファイル（.cann.yaml）を介して、テーブル・カラムのアノテーション（description / tags）をサーバ上のカタログと同期します。ファイルの生成からサーバへの反映までの流れは分析コンテキストの整備を、テーブル・カラムに何を書くかの設計の考え方は分析コンテキストの設計を参照してください。

cdm catalog annotation <subcommand> [options]

サブコマンド	機能概要
`annotation dump`	サーバの状態から `.cann.yaml` を新規生成
`annotation pull`	ローカルファイルをサーバの最新状態に更新
`annotation diff`	サーバへ反映した場合の差分を確認
`annotation push`	ローカルの変更をサーバに反映
`annotation verify`	ローカルファイルとサーバの整合性を検査
`annotation untracked`	未記載テーブルの検出
`annotation scaffold`	指定テーブルのカラムをファイルに追記
`annotation format`	ファイルのフォーマット
`annotation validate`	ファイルの検証

タグの管理はタグの管理を、カタログの検索・一覧はカタログの検索を参照してください。

アノテーションファイルの生成

cdm catalog annotation dump <schema-uri>
  -t, --table <table-id>        管理対象を指定（複数指定可）
  -o, --output <path>           出力先（ファイルパス または ディレクトリ）
  --stdout                      標準出力に出力（--output と排他）
  -y, --yes                     既存ファイルがある場合の確認プロンプトをスキップ
  --profile <name>              利用する profile を指定

サーバ上のカタログから、指定したスキーマのテーブル・カラムに付与されたアノテーションを元に .cann.yaml を新規生成します。

対象は <schema-uri> で指定します（必須）
- <schema-uri> には、cdm catalog list-schemas で出力される schemaUri を指定します
- スキーマ名のみを表す schemaId とは異なる点に注意してください
生成されるファイルの manages は、--table の指定の有無で決まります
- --table の指定がない場合は manages: all-tables（スキーマ全体を1ファイルで管理）になります
- --table で対象テーブルを絞り込んだ場合は manages: listed-tables（指定したテーブルのみを管理）になります
  - --table は繰り返し指定できます（例: --table orders --table users）
  - 指定したテーブルが対象スキーマのカタログに存在しない場合は exit 1 で終了します
サーバ上でアノテーション（description / tags）が付与されているテーブル・カラムのみを書き出します（正規化）
- アノテーションのないテーブル・カラムは書き出しません（--table で指定したテーブルでも、アノテーションがなければ書き出しません）
- 新しくアノテーションを付与する場合は、untracked で未記載テーブルを探し、scaffold でファイルに追記します
- アノテーションのあるテーブル・カラムが1件も見つからない場合でも tables: [] でファイルを生成します
コネクションの閲覧権限が必要です

出力先

--output で出力先を指定できます
- ファイルパス（拡張子 .cann.yaml）を指定した場合、そのパスに書き込みます
- ディレクトリを指定した場合、ディレクトリ内に .cann.yaml を生成します（ファイル名は schemaUri から自動生成されます）
- 書き込み先に既存のファイルがある場合、確認プロンプトが表示されます
  - --yes を指定することで、確認をスキップできます
--stdout を指定した場合、生成結果を標準出力に出力します
--output, --stdout のいずれも指定のない場合は、--output ./ として処理します

利用例

bash

# カレントディレクトリに自動命名で生成
cdm catalog annotation dump bq:my-project/analytics

# 出力先ディレクトリを指定
cdm catalog annotation dump bq:my-project/analytics -o annotations/

# ファイル名まで明示
cdm catalog annotation dump bq:my-project/analytics -o annotations/analytics.cann.yaml

# 対象テーブルを絞り込んで生成（manages: listed-tables になる）
cdm catalog annotation dump bq:my-project/analytics --table orders --table order_items -o annotations/analytics.mart.cann.yaml

# 標準出力
cdm catalog annotation dump bq:my-project/analytics --stdout > annotations/analytics.cann.yaml

アノテーションの最新化

cdm catalog annotation pull <file|directory>
  -y, --yes             確認プロンプトをスキップして反映
  --profile <name>      利用する profile を指定

サーバ上のカタログから最新のアノテーションを取得して、ローカルの .cann.yaml を更新します。

<file|directory> には、カタログアノテーションファイル（.cann.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .cann.yaml を再帰的に対象とします
更新対象のテーブルは manages によって決まります
- manages: listed-tables では、ファイルに記載されたテーブルのみを対象に最新化します
- manages: all-tables では、スキーマ内の全テーブルを対象に最新化します
  - サーバ上で新規にアノテーションが追加されたテーブルについては、自動でファイルに追記します（サーバとの同期）
サーバ上でアノテーションが付与されたテーブル・カラムのみを取り込みます（正規化）
- サーバ上でアノテーションが削除されたテーブル・カラムはファイルからも削除されます
- manages: listed-tables で delete: true を指定したテーブルは、push によりサーバ上のアノテーションが削除された状態になるため、pull するとファイルから削除されます
書き出し時に内部で format を実行するため、インデントやキーの並び順は整形され、既存のコメント・空行は保持されません
- scaffold で追記した未記入の候補行も削除されます。候補行を埋めている途中で pull を実行しないでください
変更がある場合、書き込み前に確認プロンプトが表示されます
- --yes を指定することで、確認をスキップできます
コネクションの閲覧権限が必要です
複数のファイルを対象とする場合、どのファイルで失敗したかをまとめて報告し、ファイルを更新せずに exit 1 で終了します

出力例

annotations/analytics.cann.yaml   changed (+2 tables, 1 updated)
annotations/raw.cann.yaml         unchanged

2 files processed: 1 changed, 1 unchanged

? Pull these changes from the server? (y/N)

利用例

bash

# 確認しつつ最新化
cdm catalog annotation pull annotations/

# CI 等で確認なしに最新化
cdm catalog annotation pull annotations/ --yes

サーバとの差分確認

cdm catalog annotation diff <file|directory>
  -f, --format <fmt>        出力形式: text | json（既定: text）
  --exit-code               差分がある場合に exit 2 を返す
  --profile <name>          利用する profile を指定

指定した .cann.yaml をサーバへ push した場合に発生する差分を出力します。

<file|directory> には、カタログアノテーションファイル（.cann.yaml）またはディレクトリを指定してください
削除される差分も表示されます。反映前に削除内容を確認する用途で利用してください
- 管理対象テーブルの未記載カラム
- manages: listed-tables で delete: true を指定したテーブル
- manages: all-tables でファイルから記載を削除したテーブル
差分の計算前に、内部で verifyを実行します
変更のある path のみを出力します
--exit-code を指定した場合、差分がある場合は exit 2 で終了します
コネクションの閲覧権限が必要です
複数のファイルを対象とする場合、どのファイルで失敗したかをまとめて報告し、--exit-code の指定にかかわらず exit 1 で終了します（成功した分の差分は出力します）

出力例（text）

Schema: bq:my-project/analytics

Summary: 2 tables updated, 1 table deleted, 2 columns deleted

Changes:
Path                         Annotation   Before              After
orders                       description  注文                注文トランザクション
orders                       tags         [core]              [core, daily_batch]
orders.user_id               description  (not set)           購入ユーザー
orders.legacy_flag           description  廃止フラグ          (not set)
orders.legacy_flag           tags         [deprecated]        (not set)
legacy_orders (delete: true) description  旧注文テーブル      (not set)

出力例（json）

json

{
  "summary": {
    "tableUpdate": 1,
    "tableDelete": 1,
    "columnUpdate": 1,
    "columnDelete": 1,
    "hasChange": true
  },
  "results": [
    {
      "schemaUri": "bq:my-project/analytics",
      "entries": [
        {
          "kind": "update",
          "path": "orders",
          "description": { "before": "注文", "after": "注文トランザクション" },
          "tags": { "before": ["core"], "after": ["core", "daily_batch"] }
        },
        {
          "kind": "delete",
          "path": "legacy_orders",
          "reason": "delete-true",
          "description": { "before": "旧注文テーブル", "after": null }
        }
      ]
    }
  ]
}

利用例

bash

# 差分確認
cdm catalog annotation diff annotations/analytics.cann.yaml

# スクリプト用に JSON 出力
cdm catalog annotation diff annotations/ -f json

# CI で変更検知（変更があれば exit 2）
cdm catalog annotation diff annotations/ --exit-code

アノテーションの反映

cdm catalog annotation push <file|directory>
  -y, --yes             確認プロンプトをスキップして反映
  --profile <name>      利用する profile を指定

指定した .cann.yaml の内容を元にサーバ上のアノテーションを更新します。

<file|directory> には、カタログアノテーションファイル（.cann.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .cann.yaml を再帰的に対象とします
更新・削除の対象は manages によって異なります（サーバとの同期）
- manages: all-tables: ファイルの記載をスキーマ全体のあるべき状態とみなします。ファイルに記載のあるテーブルはファイルの内容で更新し、ファイルに記載のないテーブルのアノテーションは削除します
- manages: listed-tables: ファイルに記載されたテーブルのみを更新対象とし、ファイルに記載のないテーブルは更新・削除をしません。テーブルのアノテーションを削除するには delete: true を指定します
反映前に、内部で verifyを実行します
- scaffold で追記した未記入の候補行が残っている場合は検証エラーになります。候補行を埋めるか、format で削除してから実行してください
- 複数のファイルを対象とする場合、すべてのファイルを検査し終えてから、エラーをまとめて報告します
この処理によりサーバのアノテーションが更新される場合、更新前に確認プロンプトが表示されます
- アノテーションが削除される場合は、削除されるテーブル数・カラム数・テーブルの項目数を表示します（manages: all-tables の未記載テーブル削除、manages: listed-tables の delete: true を含む）
- --yes を指定することで、確認をスキップできます
- 反映される差分を事前に確認したい場合は、別途 diff を実行してください
コネクションの閲覧権限とアノテーション編集権限が必要です
複数のファイルを対象とする場合、どのファイルで失敗したかをまとめて報告し、exit 1 で終了します
- 反映中に失敗した場合、その時点までに反映済みの内容は取り消されません

WARNING

manages: all-tables のファイルでは、ファイルに記載のないテーブルのアノテーションは削除されます。また、記載のあるテーブルについても、ファイルの記載内容を「あるべき状態」とみなして、記載のないカラム等のアノテーションは削除されます。編集前に pull でサーバの最新状態を取り込み、反映前に diff で意図せずサーバ上の変更を上書き・削除していないか確認してください。

出力例

annotations/analytics.cann.yaml   changed (2 updated, 1 table deleted, 3 columns deleted)
annotations/raw.cann.yaml         unchanged

2 files processed: 1 changed, 1 unchanged

Deleting: 1 table annotation, 3 column annotations

? Push these changes to the server? (y/N)

利用例

bash

# 確認しつつ反映
cdm catalog annotation push annotations/

# 事前に差分を確認してから反映
cdm catalog annotation diff annotations/analytics.cann.yaml
cdm catalog annotation push annotations/

# CI 等で確認なしに反映
cdm catalog annotation push annotations/ --yes

サーバとの整合性検査

cdm catalog annotation verify <file|directory>
  --profile <name>      利用する profile を指定

指定した .cann.yaml が有効かをサーバに問い合わせて検査します。

<file|directory> には、カタログアノテーションファイル（.cann.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .cann.yaml を再帰的に対象とします
はじめに内部で validateを実行し、続いてサーバと照合して次の観点で検査します
- schemaUri がサーバに存在する有効なスキーマか
- 記載されたテーブル・カラムがサーバのカタログに存在するか（テーブルやカラムが削除されていないか）
- 記載されたタグ名に該当するタグがサーバ上に存在するか（テーブルにはテーブル用、カラムにはカラム用のタグが解決できるか）
問題が見つかった場合は exit 1 で終了します
コネクションの閲覧権限が必要です
複数のファイルを対象とする場合、どのファイルで失敗したかをまとめて報告します

出力例

Schema: bq:my-project/analytics   OK

Tables:
  OK    orders
  OK    users
  ERROR legacy_orders   (not found in catalog)

Tags:
  OK    table:core, column:pii
  ERROR dailly          (no matching tag)

利用例

bash

# 整合性を検査
cdm catalog annotation verify annotations/

# CI で整合性を検査（問題があれば exit 1）
cdm catalog annotation verify annotations/

未取り込みテーブルの検出

cdm catalog annotation untracked <file|directory>...
  -f, --format <fmt>    出力形式: text | json（既定: text）
  --profile <name>      利用する profile を指定

サーバのカタログに存在するが、ローカルのアノテーションファイルに記載のないテーブルを検出します。新しく整備するテーブルを見つけ、scaffold で追記する、という流れで利用します。

<file|directory>... には、カタログアノテーションファイル（.cann.yaml）またはディレクトリを1つ以上指定してください
- ディレクトリ指定時は配下の .cann.yaml を再帰的に対象とし、ワイルドカードでも指定できます（例: annotations/analytics.*.cann.yaml）
- 対象のファイルにはすべて同一の schemaUri を指定してください
- manages: listed-tables で分割管理している場合は、同一 schemaUri を管理する全ファイルを対象に含めてください。未記載かどうかを対象ファイル全体で判定するため、一部のファイルだけを指定すると、他のファイルに記載済みのテーブルも未記載として検出されます
各テーブルについて、サーバ上でアノテーション（description / tags）が付与されているかどうかも表示します
コネクションの閲覧権限が必要です

出力形式

`text`（既定）

$ cdm catalog annotation untracked annotations/analytics.cann.yaml
Schema: bq:my-project/analytics

Untracked tables:
TableId         Annotated
orders          yes
temp_scratch    no

`json`

json

{
  "schemaUri": "bq:my-project/analytics",
  "untrackedTables": [
    { "tableId": "orders", "annotated": true },
    { "tableId": "temp_scratch", "annotated": false }
  ]
}

利用例

bash

# 未記載テーブルを検出
cdm catalog annotation untracked annotations/analytics.cann.yaml

# 分割ファイルをまとめて対象に
cdm catalog annotation untracked annotations/analytics.*.cann.yaml

# スクリプト用に JSON 出力
cdm catalog annotation untracked annotations/analytics.cann.yaml -f json

アノテーション候補の追記

cdm catalog annotation scaffold <file> <table-id>
  -y, --yes             確認プロンプトをスキップして追記
  --profile <name>      利用する profile を指定

<table-id> のカラムのうち、<file> にまだ記載のないものを <file> に追記します。サーバ上にアノテーションがあればその内容も含めて取り込み、なければ名前だけの空の候補行を追記します。テーブル・カラム名を書き写す必要なく、description / tags を埋めるだけでアノテーションを整備できます。

dump や pull はサーバでアノテーション済みのものしか取り込まないため、scaffold はまだアノテーションのないテーブル・カラムを新しく整備する入口になります。untracked で未記載テーブルを探し、scaffold で追記し、エディタで description / tags を埋めて push する、という流れで利用します。

<file> には追記先のカタログアノテーションファイル（.cann.yaml）を、<table-id> には整備対象のテーブルを指定します
- <table-id> がサーバ上のカタログに存在しない場合は exit 1 で終了します
- テーブル行が <file> にない場合は、テーブル行もあわせて作成します
- manages: listed-tables で分割管理している場合は、そのテーブルを管理するファイルを <file> に指定してください
追記は <file> に記載済みの行には影響しません。ただし、書き込みはファイル全体の再書き出しとなるため、既存のコメント・空行は保持されません
追記対象がない場合（すべて記載済みの場合）は、その旨を表示して exit 0 で終了します
コネクションの閲覧権限が必要です

未記入の候補行の削除

空の候補行は「有効なアノテーションを持たない行」で、ファイルをサーバの状態に正規化する操作（format や、内部で format を実行する pull）を通すと削除されます。アノテーションを埋めた候補行は残るため、追記 → 値を埋める → format で仕上げる、という流れになります。

追記例

記載済みの id はそのまま残り、未記載のカラムが追記されます。last_login_at はサーバ上のアノテーションを含む行、plan_type 以下は値を埋めるべき空の候補行です。

yaml

  - tableId: users
    columns:
      - name: id
        description: ユーザーID
      - name: last_login_at
        description: 最終ログイン日時
        tags: [pii]
      - name: plan_type
      - name: is_active
      - name: deleted_at

利用例

bash

# 未記載テーブルを探してから、整備するテーブルのカラムを追記
cdm catalog annotation untracked annotations/analytics.cann.yaml
cdm catalog annotation scaffold annotations/analytics.cann.yaml orders

# 分割管理している場合: そのテーブルを管理するファイルに追記
cdm catalog annotation scaffold annotations/analytics.mart.cann.yaml orders

# 確認プロンプトをスキップして追記
cdm catalog annotation scaffold annotations/analytics.cann.yaml users --yes

ファイルのフォーマット

cdm catalog annotation format <file|directory>
  --check               整形が必要かの確認のみ行い、ファイルは変更しない
  --profile <name>      利用する profile を指定

.cann.yaml をローカルで整形・正規化します。

<file|directory> には、カタログアノテーションファイル（.cann.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .cann.yaml を再帰的に対象とします
次の処理を行います
- validate 相当の書式検査を実施します
  - ただし、有効なアノテーションを持たないテーブル・カラムを見つけた場合は、エラーとせずに自動で削除します
  - scaffold で追記した未記入の候補行もこの削除の対象です。候補行を残したい場合は、format の前に値を埋めてください
- manages: all-tables のファイルでは、delete: true を持つテーブルの記載を削除します
- tables を tableId の順でソートします
- インデントやキーの並び順などを整えます
- コメント・空行は保持されません（削除されます）
--check を指定した場合、整形（正規化を含む）が必要かどうかのみを判定し、ファイルは変更しません。整形が必要な場合は exit 1 で終了するため、CI での検査に利用できます

利用例

bash

# 整形（有効なアノテーションを持たない項目の削除を含む）
cdm catalog annotation format annotations/

# CI で整形済みか確認（未整形なら exit 1）
cdm catalog annotation format annotations/ --check

ファイルの検証

cdm catalog annotation validate <file|directory>
  --profile <name>      利用する profile を指定

.cann.yaml の書式をローカルで検証します。

<file|directory> には、カタログアノテーションファイル（.cann.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .cann.yaml を再帰的に対象とします
次の観点を検査します
- 有効な YAML 形式か
- 必須フィールドの欠落や不正な値がないか（ファイル定義の型に適合するか）
- 各テーブル・カラムが有効なアノテーションを持つか（正規化）
  - scaffold で追記した未記入の候補行は検証エラーになります。候補行を埋めている途中の検証エラーは正常な状態で、埋め終えるか format で候補行を削除することで解消します
- 配列内のテーブル・カラムに重複がないか
- manages の指定が整合しているか（複数ファイル・ディレクトリを対象とした場合。同一 schemaUri を対象とするファイル間でテーブルが重複していないか。詳細は分割管理）
検証エラーがある場合は exit 1 で終了します

利用例

bash

# 書式を検証
cdm catalog annotation validate annotations/

アノテーションの管理 ​

アノテーションファイルの生成 ​

出力先 ​

利用例 ​

アノテーションの最新化 ​

出力例 ​

利用例 ​

サーバとの差分確認 ​

出力例（text） ​

出力例（json） ​

利用例 ​

アノテーションの反映 ​

出力例 ​

利用例 ​

サーバとの整合性検査 ​

出力例 ​

利用例 ​

未取り込みテーブルの検出 ​

出力形式 ​

text（既定） ​

json ​

利用例 ​

アノテーション候補の追記 ​

追記例 ​

利用例 ​

ファイルのフォーマット ​

利用例 ​

ファイルの検証 ​

利用例 ​

アノテーションの管理

アノテーションファイルの生成

出力先

利用例

アノテーションの最新化

出力例

利用例

サーバとの差分確認

出力例（text）

出力例（json）

利用例

アノテーションの反映

出力例

利用例

サーバとの整合性検査

出力例

利用例

未取り込みテーブルの検出

出力形式

`text`（既定）

`json`

利用例

アノテーション候補の追記

追記例

利用例

ファイルのフォーマット

利用例

ファイルの検証

利用例