カタログタグ

概要

Codatumのカタログでは、テーブル・カラムに付与するタグをワークスペース単位で管理します
タグはテーブル用（type:table）とカラム用（type:column）の2種類があり、それぞれ名前・色・説明の設定ができます
カタログタグファイル（.ctag.yaml）は、これらのタグ定義をローカルファイルとして管理し、CLIを使ってサーバと同期するために利用されるファイル形式です
- カタログタグファイルの生成や同期については、cdm catalog tag の各コマンドで行います
- ファイルは通常の YAML 形式のファイルで、 git 等でバージョン管理することを想定しています
テーブル・カラムへのタグの付与は、カタログアノテーション（.cann.yaml）で行います
- .ctag.yaml はタグそのものの定義（名前・色・説明）を管理し、.cann.yaml は各テーブル・カラムへのタグの付与を管理します

カタログの構造

タグはワークスペース単位で type と name の組み合わせで一意に管理されています
- 同じ名前でも type（table / column）が異なれば、別のタグとして扱われます
- 例えば、テーブル用の core（type:table）とカラム用の core（type:column）は別のタグです
isSystem が true のタグ（Not null 等）は、システムが管理するタグです
- 削除・名前変更・色や説明の変更ができません
- .ctag.yaml では管理対象外となります（システムタグの扱い）

ファイル定義

カタログタグファイル（.ctag.yaml）は、有効なYAML形式のファイルで、次のオブジェクト型で表現します

type CatalogTagFile = {
  tags: TagDefinition[];
};

tags は、管理するタグ定義の配列です
ローカルでのファイル名・ディレクトリ構造は自由です
- サーバとの同期は、ファイル内の type と name で対象を特定します

タグ定義

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

type TagDefinition = {
  name: string;  // 最大 128 文字
  type: "table" | "column";
  color: TagColor;
  description: string;  // 最大 1024 文字
};

type TagColor =
  | "#71767E" | "#666CFF" | "#BB79E7" | "#FF6767" | "#FF91BE"
  | "#3DC8F7" | "#FDAD6D" | "#F1C519" | "#7ECF4F";

name にはタグ名を指定します
- type と name の組み合わせでタグを一意に識別します
type にはタグの種別（table または column）を指定します
- table はテーブルに付与できるタグ、column はカラムに付与できるタグです
- 同じ name でも type が異なれば別のタグとして扱われます
color にはタグの表示色を、TagColor 型のいずれかで指定します
- TagColor の型にない値を指定した場合はエラーになります
description にはタグの説明を指定します
- 説明が不要な場合は空文字（""）を指定できます
color と description はいずれも必須です

記述例

yaml

tags:
  - name: core
    type: table
    color: "#666CFF"
    description: 分析の中核となるテーブル
  - name: daily_batch
    type: table
    color: "#7ECF4F"
    description: 日次バッチで更新されるテーブル
  - name: pii
    type: column
    color: "#FF6767"
    description: 個人情報を含むカラム

システムタグの扱い

isSystem が true のタグ（Not null 等）は、システムが管理するタグで、.ctag.yaml では管理できません
- cdm catalog tag dump / cdm catalog tag pull では書き出されません
- cdm catalog tag push でシステムタグと同名・同 type のタグを反映しようとした場合はエラーになります
- cdm catalog tag prune の削除対象にもなりません
システムタグを含む登録済のタグは cdm catalog tag list で確認できます

更新時の挙動

サーバとの同期は、最新化が cdm catalog tag pull、作成・更新が cdm catalog tag push、削除が cdm catalog tag prune で行います。pull / push はいずれもファイルに記載された (type, name) を対象としますが、prune は対象の決め方が異なります。

作成・更新（push）

cdm catalog tag push は、ファイルに記載された (type, name) を対象に、次のように動作します
- (type, name) がサーバ上に存在しない場合は、タグを新規作成します
- (type, name) がサーバ上に存在する場合は、その color / description を更新します
- push は記載されたタグの作成・更新のみを行うため、タグ定義を複数の .ctag.yaml ファイルに分割して管理することもできます
ファイルに記載のない (type, name) には影響しません
- push はファイルの記載を「削除の宣言」とはみなしません。ファイルからタグの記載を削除しても、サーバ上のタグは削除されません
- ファイル上で name を変更した場合、リネームではなく別タグの新規作成として扱われます（元のタグはサーバ上に残ります）

削除（prune）

タグの削除は、cdm catalog tag prune で行います
- prune は、サーバ上のカタログでどのテーブル・カラムにも付与されていない（参照されていない）タグを削除します
- 判定には、利用中の PAT が閲覧権限を持たないコネクションのカタログからの付与も含みます。自分に見えていないコネクションで使われているタグを誤って削除しないためです
リネームには対応していません
- タグ名を変えたい場合は、新しい名前のタグを push で作成し、付与先を付け替えたうえで、参照されなくなった旧タグを prune で削除する、という流れになります

カタログタグ ​

概要 ​

カタログの構造 ​

ファイル定義 ​

タグ定義 ​

記述例 ​

システムタグの扱い ​

更新時の挙動 ​

最新化（pull） ​

作成・更新（push） ​

削除（prune） ​

カタログタグ

概要

カタログの構造

ファイル定義

タグ定義

記述例

システムタグの扱い

更新時の挙動

最新化（pull）

作成・更新（push）

削除（prune）