タグの管理

cdm catalog tag サブコマンドは、カタログタグファイル（.ctag.yaml）を介して、タグの定義（名前・色・説明）をサーバと同期します。

cdm catalog tag <subcommand> [options]

サブコマンド	機能概要
`tag dump`	サーバの状態から `.ctag.yaml` を生成
`tag pull`	ローカルファイルをサーバの最新状態に更新
`tag diff`	サーバへ反映した場合の差分を確認
`tag push`	ローカルの変更をサーバに反映
`tag prune`	参照されていないタグをサーバから削除
`tag format`	ファイルのフォーマット
`tag validate`	ファイルの検証

タグの一覧取得（tag list）はカタログの検索を参照してください。

タグファイルの生成

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

ワークスペースに登録されたタグから .ctag.yaml を生成します。

システムタグ（isSystem が true のタグ）は書き出しません（システムタグの扱い）
登録されているタグが1件もない場合でも tags: [] でファイルを生成します
閲覧権限を持つコネクションが1つ以上必要です

出力先

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

利用例

bash

# カレントディレクトリに自動命名で生成
cdm catalog tag dump

# 出力先ファイルを指定
cdm catalog tag dump -o tags/tags.ctag.yaml

# 標準出力
cdm catalog tag dump --stdout > tags/tags.ctag.yaml

タグの最新化

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

サーバ上のタグ定義から最新の状態を取得して、ローカルの .ctag.yaml を更新します。

<file|directory> には、カタログタグファイル（.ctag.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .ctag.yaml を再帰的に対象とします
更新対象はファイルに記載された (type, name) のみです（更新時の挙動）
- サーバ上で color / description が変わっていれば、その内容で上書きします
- サーバ上に存在しなくなったタグは、ファイルからも削除されます
- サーバ上に新規追加されたタグは、ファイルへ自動追記しません
  - タグ定義を複数ファイルに分割して管理できるため、どのファイルへ追記すべきかを決められないためです
  - サーバ上のタグをまとめて取り込みたい場合は、dump でファイルを再生成してください
システムタグ（isSystem が true のタグ）は書き出しません（システムタグの扱い）
書き出し時に内部で format を実行するため、インデントやキーの並び順は整形され、既存のコメント・空行は保持されません
変更がある場合、書き込み前に確認プロンプトが表示されます
- --yes を指定することで、確認をスキップできます
閲覧権限を持つコネクションが1つ以上必要です

出力例

tags/tags.ctag.yaml   changed (2 updated, 1 removed)
tags/column.ctag.yaml unchanged

2 files processed: 1 changed, 1 unchanged

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

利用例

bash

# 確認しつつ最新化
cdm catalog tag pull tags/

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

サーバとの差分確認

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

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

<file|directory> には、カタログタグファイル（.ctag.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .ctag.yaml を再帰的に対象とします
差分の計算前に、内部で次の検査を行います
- validate 相当の書式検査
- システムタグの変更が含まれていないか（システムタグの扱い）
- ファイルをまたいで (type, name) が重複していないか
- いずれかでエラーが見つかった場合は、エラー詳細を表示して exit 1 で終了します
変更のあるタグのみを出力します
--exit-code を指定した場合、差分がある場合は exit 2 で終了します
閲覧権限を持つコネクションが1つ以上必要です

出力例（text）

Summary: +1 created, 1 updated

Changes:
Name         Type    Field        Before        After
daily_batch  table   (new)        -             -
daily_batch  table   color        (not set)     #666CFF
daily_batch  table   description  (not set)     日次バッチ
core         table   description  中核テーブル  分析の中核となるテーブル
pii          column  color        #71767E       #FF6767

出力例（json）

json

{
  "summary": { "create": 1, "update": 1, "hasChange": true },
  "entries": [
    {
      "kind": "create",
      "name": "daily_batch",
      "type": "table",
      "color": "#666CFF",
      "description": "日次バッチ"
    },
    {
      "kind": "update",
      "name": "core",
      "type": "table",
      "description": { "before": "中核テーブル", "after": "分析の中核となるテーブル" }
    }
  ]
}

利用例

bash

# 差分確認
cdm catalog tag diff tags/tags.ctag.yaml

# 機械可読な差分
cdm catalog tag diff tags/ -f json

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

タグの反映

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

指定した .ctag.yaml の内容を元にサーバ上のタグの作成・更新を行います。

<file|directory> には、カタログタグファイル（.ctag.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .ctag.yaml を再帰的に対象とします
ファイルに記載された (type, name) を対象に、更新時の挙動に従って作成・更新します
- サーバ上に存在しない (type, name) は新規作成、存在する場合は color / description を更新します
- ファイルに記載のない (type, name) には影響しません（削除・リネームは行いません。タグの削除は prune を利用してください）
反映前に、内部で validate 相当の検査を行います
- エラーが見つかった場合は exit 1 で終了します
- 複数のファイルを対象とする場合、すべてのファイルを検査し終えてから、エラーをまとめて報告します
この処理によりサーバのタグが更新される場合、更新前に確認プロンプトが表示されます
- --yes を指定することで、確認をスキップできます
- 反映される差分を事前に確認したい場合は、別途 diff を実行してください
閲覧権限を持つコネクションが1つ以上と、カタログ用のタグ（table / column）の編集権限が必要です

出力例

tags/tags.ctag.yaml   changed (+1 created, 2 updated)

1 file processed: 1 changed

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

利用例

bash

# 確認しつつ反映
cdm catalog tag push tags/tags.ctag.yaml

# 事前に差分を確認してから反映
cdm catalog tag diff tags/tags.ctag.yaml
cdm catalog tag push tags/tags.ctag.yaml

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

タグの削除

cdm catalog tag prune [file|directory]
  --tag-id <id>             削除対象を特定のタグに限定（複数指定可）
  --type <table|column>     削除対象を種別で絞り込み
  --dry-run                 削除は行わず、削除対象の一覧のみを表示
  -f, --format <fmt>        出力形式: text | json（既定: text）。json は --dry-run 必須
  -y, --yes                 確認プロンプトをスキップして削除
  --profile <name>          利用する profile を指定

サーバ上のカタログで、どのテーブル・カラムにも付与されていない（参照されていない）タグを削除します。

push がファイルの記載を対象に作成・更新するのに対し、prune はサーバ上のカタログの付与状況を基準に削除対象を決めます（更新時の挙動）
- 参照の有無は、閲覧権限を持たないコネクションのカタログからの付与も含めて判定します
判定基準（未参照であること）は共通で、以下の指定は削除対象の母集団を絞り込むフィルタとして働きます
- 引数なし: サーバ上のすべてのタグを対象とします（システムタグを除く）
- <file|directory>: 指定した .ctag.yaml（ディレクトリ指定時は配下の .ctag.yaml）に定義されたタグに限定します
- --tag-id: 特定のタグに限定します。複数指定でき、cdm catalog tag list や prune の出力に表示される Id を指定します。未参照の一覧を確認した上で、特定のタグだけを削除したい場合に利用します
- --type: 種別（table / column）で絞り込みます。特定種別の削除権限のみを持つ場合などに利用します
システムタグ（isSystem が true のタグ）は削除対象になりません（システムタグの扱い）
削除対象がある場合、削除前に対象の一覧を表示して確認プロンプトを表示します（--yes でスキップ）。削除対象がない場合はその旨を表示して exit 0 で終了します
--dry-run を指定すると、削除を行わず削除対象の一覧のみを表示して exit 0 で終了します（--yes とは排他）。削除前の確認や、CI で対象を取得する用途に利用できます
--format json は --dry-run 併用が必須です。--yes とも排他です
閲覧権限を持つコネクションが1つ以上と、削除対象のタグ（table / column）の削除権限が必要です

WARNING

prune は取り消しできない破壊的な操作です。今この時点で参照されていないタグを削除するため、将来利用する予定で用意したタグや、一時的にすべての付与を外しているタグも削除対象になります。実行前に、表示される削除対象の一覧を必ず確認してください。

出力例（text）

Id                        Name          Type    Color      Description
69a1f0c2b34e5d6f7a8b9c01  old_campaign  table   #FDAD6D    2024 キャンペーン用
69a1f0c2b34e5d6f7a8b9c02  tmp_flag      column  #71767E    ""

2 tags will be deleted.

? Delete these tags from the server? (y/N)

Description 列は切り捨てず折り返します。本文中の改行は \n と表示します。空の description は "" と表示します
特定のタグだけを削除したい場合は、--dry-run で未参照タグの Id を確認し、その Id を --tag-id に渡してください

出力例（json）

bash

cdm catalog tag prune --dry-run -f json

json

{
  "tags": [
    {
      "id": "69a1f0c2b34e5d6f7a8b9c01",
      "name": "old_campaign",
      "type": "table",
      "color": "#FDAD6D",
      "description": "2024 キャンペーン用"
    }
  ]
}

利用例

bash

# サーバ上の未参照タグをすべて掃除（確認あり）
cdm catalog tag prune

# 削除対象の確認のみ
cdm catalog tag prune --dry-run

# 削除対象の確認のみ（JSON形式）
cdm catalog tag prune --dry-run -f json

# 自分が管理するファイルのタグに限定して掃除
cdm catalog tag prune tags/

# 未参照の一覧を確認した上で、特定のタグだけ削除
cdm catalog tag prune --tag-id 69a1f0c2b34e5d6f7a8b9c01

# カラム用タグのみを対象に掃除（column の削除権限のみを持つ場合など）
cdm catalog tag prune --type column

# CI 等で確認なしに削除
cdm catalog tag prune tags/ --yes

ファイルのフォーマット

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

.ctag.yaml をローカルで整形します。

<file|directory> には、カタログタグファイル（.ctag.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .ctag.yaml を再帰的に対象とします
次の処理を行います
- validate 相当の書式検査を行います
- tags を type・name の順でソートします
- インデントやキーの並び順などを整えます
- コメント・空行は保持されません（削除されます）
--check を指定した場合、整形が必要かどうかのみを判定し、ファイルは変更しません。整形が必要な場合は exit 1 で終了するため、CI での検査に利用できます

利用例

bash

# 整形
cdm catalog tag format tags/

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

ファイルの検証

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

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

<file|directory> には、カタログタグファイル（.ctag.yaml）またはディレクトリを指定してください
- ディレクトリを指定した場合は、配下の .ctag.yaml を再帰的に対象とします
次の観点を検査します
- 有効な YAML 形式か
- 必須フィールド（name / type / color / description）が欠落していないか
- type が table / column のいずれかか
- color が TagColor 型のいずれかの値か
- (type, name) に重複がないか（複数ファイル・ディレクトリを対象とした場合はファイルをまたいで検査します）
検証エラーがある場合は exit 1 で終了します

利用例

bash

# 書式を検証
cdm catalog tag validate tags/

タグの管理 ​

タグファイルの生成 ​

出力先 ​

利用例 ​

タグの最新化 ​

出力例 ​

利用例 ​

サーバとの差分確認 ​

出力例（text） ​

出力例（json） ​

利用例 ​

タグの反映 ​

出力例 ​

利用例 ​

タグの削除 ​

出力例（text） ​

出力例（json） ​

利用例 ​

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

利用例 ​

ファイルの検証 ​

利用例 ​

タグの管理

タグファイルの生成

出力先

利用例

タグの最新化

出力例

利用例

サーバとの差分確認

出力例（text）

出力例（json）

利用例

タグの反映

出力例

利用例

タグの削除

出力例（text）

出力例（json）

利用例

ファイルのフォーマット

利用例

ファイルの検証

利用例