Codatum CLI

Appearance

ノートブックファイルの編集 ​

概要 ​

ローカルのノートブックファイル（*.cnb.md）を編集する際に、繰り返し使うサブコマンド群です。検証・整形・SQL ビルド・依存関係分析といった操作に加え、ブラウザと双方向同期しながら対話的に編集する preview を含みます。引数の共通定義（ファイル / ディレクトリ / SQL・ページの指定キー）は 使い方 を参照してください。

サブコマンド機能概要
notebook validateスキーマ・構文を検証（書き換えなし）
notebook format自動修復・検証・整形
notebook param listパラメータ値の一覧
notebook param resetパラメータ値のリセット
notebook build-sql参照を解決した実行可能なSQLにビルド
notebook depsSQLの依存関係・影響範囲を分析
notebook lintダイアグラム・数式の文法をチェック
notebook previewブラウザと双方向同期しながらプレビュー・編集

ノートブックファイルの本文は CLI では編集できないため、エディタやファイルシステム経由で直接編集します。*.cnb.md は通常のマークダウンとフォーマットが異なるため、手動での整形は避け、編集後は必ず CLI で検証・整形してください。

ノートブックの検証 ​

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

対象のノートブックファイルのスキーマ・構文を検証します。ファイルは書き換えません。

  • <file|directory> には、ノートブックファイル または ディレクトリ を指定してください
  • 検証エラーが見つかった場合、exit 1 で終了します
    • 複数のファイルを対象とする場合、すべてのファイルを検証し終えてから、エラーをまとめて報告します
    • 自動修復可能なエラーも検証エラーとして扱われるため、formatを実行することでエラーを解消できる場合があります
  • ダイアグラム（Mermaid）・数式（KaTeX）の文法はチェックの対象外です。これらは notebook lint で確認します

ノートブックのフォーマット ​

cdm notebook format <file|directory>
  --check             ファイルを書き換えず、フォーマットが必要なファイルを表示して終了
                      （差分あり → exit 1、CI用）
  --profile <name>    利用する profile を指定

対象の *.cnb.md ファイルをフォーマットします。

  • <file|directory> には、ノートブックファイル または ディレクトリ を指定してください
  • 処理内でファイルの検証も同時に行い、自動修復可能なエラーは自動修復し、自動修復不可能なエラーが見つかった場合、exit 1 で終了します。

自動修復について ​

  • 検証エラーのうち以下は cdm notebook format により自動的に修復されます。
    • ドキュメントページのページ属性（```yaml {.page}）の指定漏れ
    • ページ属性の id の指定漏れ
    • SQL ブロック属性（:::sql-block の ```yaml {.attrs}）の id の指定漏れ
    • SQL ブロック内チャート（```yaml {.chart}）の id の指定漏れ
    • SQL ブロック内 stats（```yaml {.stats}）の id の指定漏れ
    • ドキュメントページのチャートブロック（```yaml {.chart}）の id の指定漏れ
    • グリッドレイアウト（```yaml {.grid-layout}）の列幅合計不一致（均等幅に再分配）
  • 以下は cdm notebook format では自動付与されません。手動で記述する必要がある場合は cdm util gen-id を利用してください。
    • チャート設定内の view_id
    • インラインチャートの id

パラメータ値の一覧 ​

cdm notebook param list <file>
  --page <pageId>        対象ページを限定する場合に指定
  --param <paramId>      対象パラメータを限定する場合に指定
  -f, --format <fmt>     出力形式: text | json（既定: text）
  --with-refs            被参照数（Ref）も出力する
  --tz <timezone>        相対日付の解決に使う IANA タイムゾーン（例: Asia/Tokyo）
  --profile <name>       利用する profile を指定

対象のノートブックファイルに定義されたパラメータの一覧を出力します。

  • <file> には、ノートブックファイル を指定してください
  • パラメータの値はページごとに保持されるため、ページ単位で出力します
  • 各行は次の情報を示します
    • Value: ノートブックの実行時に展開される実効値。値の実体（*_widget_values）が未設定の場合はゼロ値が表示されます（詳細は値の解決を参照）
    • Default: cdm notebook param reset を実行した場合に書き込まれる値
      • defaultValue が未定義の場合はゼロ値が表示されます
      • 相対日付（defaultValue で RELATIVE_DATE / RELATIVE_DATE_RANGE を指定）の場合は、コマンド実行時点の日付を基準に相対日付を計算した値が表示されます
      • 相対日付の解決は、デフォルトではコマンド実行環境のローカルタイムゾーンを使います。CI など実行環境のタイムゾーンが利用環境と異なる場合、日付が 1 日ずれることがあるため、--tz を直接指定してください
  • --with-refs を指定した場合、各行に Ref（被参照数）も出力します。0 の場合はどこからも参照されていません
    • SQLを生成して参照の確認を行うため、--with-refs を指定する場合はノートブック内で利用しているコネクションの閲覧権限が必要です
  • --page で特定ページに、--param で特定パラメータに絞り込めます（併用可能）
    • 指定の条件でパラメータが見つからない場合、エラーを出力して exit 1 で終了します
  • 処理内でファイルの検証も同時に行い、エラーが見つかった場合、exit 1 で終了します

出力形式 ​

text（既定） ​

ページごとに見出しと表を出力します。--with-refs 未指定時は Ref 列は出力されません。

$ cdm notebook param list notebooks/sales.cnb.md --with-refs

# Value: effective value used by "cdm notebook run"
# Default: default value used by "cdm notebook param reset"
# Ref: reference count (--with-refs)

Sales Dashboard (pageId:6a17a2ba5c8f6652542a0d67)

Scope     ParamId                       Label       Type          Ref  Value                            Default
notebook  69f402b7cfdb63ad974352c2      term        DATE_RANGE    3    ["1970-01-01","1970-01-01"]      ["2025-06-01","2026-06-30"]
page      69f402c7de82fc3714e5ed1c      min_amount  NUMBER_INPUT  0    0                                1000

Monthly Report (pageId:6a17dead68eb7847e092cb75)

Scope     ParamId                       Label       Type          Ref  Value                            Default
notebook  69f402b7cfdb63ad974352c2      term        DATE_RANGE    1    ["2025-01-01","2025-12-31"]      ["2025-06-01","2026-06-30"]

2 param(s)

json ​

text と同じく、ページを単位にした配列で出力します。--with-refs 未指定時は referencedBy フィールドは含まれません。

json
$ cdm notebook param list notebooks/sales.cnb.md -f json --with-refs

{
  "pages": [
    {
      "pageId": "6a17a2ba5c8f6652542a0d67",
      "pageName": "Sales Dashboard",
      "params": [
        {
          "scope": "notebook",
          "id": "69f402b7cfdb63ad974352c2",
          "label": "term",
          "type": "DATE_RANGE",
          "referencedBy": 3,
          "value": ["1970-01-01", "1970-01-01"],
          "default": ["2025-06-01", "2026-06-30"]
        },
        {
          "scope": "page",
          "id": "69f402c7de82fc3714e5ed1c",
          "label": "min_amount",
          "type": "NUMBER_INPUT",
          "referencedBy": 0,
          "value": 0,
          "default": 1000
        }
      ]
    },
    {
      "pageId": "6a17dead68eb7847e092cb75",
      "pageName": "Monthly Report",
      "params": [
        {
          "scope": "notebook",
          "id": "69f402b7cfdb63ad974352c2",
          "label": "term",
          "type": "DATE_RANGE",
          "referencedBy": 1,
          "value": ["2025-01-01", "2025-12-31"],
          "default": ["2025-06-01", "2026-06-30"]
        }
      ]
    }
  ]
}

利用例 ​

bash
# 全パラメータの状態をページ別に一覧
cdm notebook param list notebooks/sales.cnb.md

# 特定ページの特定パラメータのみ
cdm notebook param list notebooks/sales.cnb.md --page 6a17a2ba5c8f6652542a0d67 --param 69f402b7cfdb63ad974352c2

# 被参照数も含めて JSON 出力
cdm notebook param list notebooks/sales.cnb.md -f json --with-refs

# CI などでタイムゾーンを明示して相対日付を解決
cdm notebook param list notebooks/sales.cnb.md --tz Asia/Tokyo

パラメータ値のリセット ​

cdm notebook param reset <file>
  --page <pageId>        対象ページを限定する場合に指定
  --param <paramId>      対象パラメータを限定する場合に指定
  --tz <timezone>        相対日付の解決に使う IANA タイムゾーン（例: Asia/Tokyo）
  --profile <name>       利用する profile を指定

パラメータの値（*_widget_values）を、defaultValue で定義された値にリセットして、ノートブックファイルを書き換えます。詳細は値の解決を参照してください。

  • <file> には、ノートブックファイル を指定してください
  • リセット前後の値は cdm notebook param list の Value / Default で確認できます
  • 相対日付の解決には、未指定時はコマンド実行環境のローカルタイムゾーンを使います。CI などで環境が異なる場合は param list と同じ --tz を指定してください
  • --page で特定ページに、--param で特定パラメータに絞り込めます（併用可能）
    • 指定の条件でパラメータが見つからない場合、エラーを出力して exit 1 で終了します
  • ファイルの書き換えに伴い、フォーマットも適用されます。フォーマット時にエラーが見つかった場合、exit 1 で終了します

利用例 ​

bash
# clone 後にデフォルトを実体化してから実行
cdm notebook clone <notebook> -o notebooks/
cdm notebook param reset notebooks/sales.cnb.md
cdm notebook run notebooks/sales.cnb.md

# 特定ページの特定パラメータのみリセット
cdm notebook param reset notebooks/sales.cnb.md \
  --page 6a17a2ba5c8f6652542a0d67 --param 69f402b7cfdb63ad974352c2

# CI などでタイムゾーンを明示して相対日付を解決
cdm notebook param reset notebooks/sales.cnb.md --tz Asia/Tokyo

SQLのビルド ​

cdm notebook build-sql <file>
  -k, --key <key>       出力対象の SQL を限定する場合は指定
  --page <pageId>       出力対象のページを限定する場合は指定
  -f, --format <fmt>    出力形式: text | json（既定: text）
  --profile <name>      利用する profile を指定

対象のノートブックファイル内に含まれる SQLを、バインド値などを解決した実行可能な形にビルドして出力します。ファイルは書き換えません。

  • <file> には、ノートブックファイル を指定してください
  • ワークスペースのコネクション一覧を参照して SQL をビルドします
  • 既定では、ファイル内のすべてのSQLブロックとグリッド要素が対象となります
    • チャートの実行するSQLは、データソースの実行結果に依存して動的に生成されるため、このコマンドでは出力しません
  • --key / --page による対象の限定方法は SQL・ページの指定キー を参照してください
    • --key で指定したキーが存在しない場合、エラーを出力して exit 1 で終了します
  • 処理内でファイルの検証も同時に行い、エラーが見つかった場合、exit 1 で終了します。
  • ノートブック内で利用しているコネクションの閲覧権限が必要です（SQLの生成に必要なコネクション情報を取得する必要があるため）

出力形式 ​

text（既定） ​

SQL をそのまま出力します。

  • --key を指定した場合、該当の SQL 文のみを出力します。
  • --key を省略した場合、各 SQL の直前に -- @cnb-sql <key> 形式のコメント行を区切りとして挿入し、SQL 間を空行で区切って連結します。
    • SQL 末尾にセミコロンは付与しません。
    • 個別の SQL に分割する場合は、-- @cnb-sql をマーカーとして split してください。

出力例（全件出力時）:

sql
-- @cnb-sql pageId:xxx/sqlId:yyy
SELECT * FROM users WHERE created_at > '2025-01-01'

-- @cnb-sql pageId:xxx/sqlId:zzz
SELECT COUNT(*) FROM orders WHERE status = 'completed'

-- @cnb-sql pageId:aaa/itemId:bbb
SELECT * FROM users WHERE status = 'active'

json ​

出力例:

json
{
  "sqls": [
    { "key": "pageId:xxx/sqlId:yyy", "sql": "SELECT * FROM users WHERE created_at > '2025-01-01'" },
    { "key": "pageId:xxx/sqlId:zzz", "sql": "SELECT COUNT(*) FROM orders WHERE status = 'completed'" },
    { "key": "pageId:aaa/itemId:bbb", "sql": "SELECT * FROM users WHERE status = 'active'" }
  ]
}

SQL の実行 ​

ビルドした SQL をその場で実行・検証したい場合は、cdm sql サブコマンドと組み合わせます。SQL の渡し方は SQL の渡し方 を参照してください。

bash
# 特定の SQL をビルドして実行
cdm notebook build-sql my.cnb.md -k pageId:p1/sqlId:q1 | cdm sql run -c <connection-id>

# dry-run でスキーマ・処理量を確認
cdm notebook build-sql my.cnb.md -k pageId:p1/sqlId:q1 | cdm sql dry-run -c <connection-id>

SQLの依存関係分析 ​

cdm notebook deps <file>
  --invert <key>        指定したノードを起点に、影響範囲（被参照）を逆向きに辿って表示
  -k, --key <key>       表示の起点とするノードを限定する場合に指定
  --page <pageId>       表示対象のページを限定する場合に指定
  --profile <name>      利用する profile を指定

対象のノートブックファイルを解析し、内部のSQLの依存関係をツリー形式で出力します。

  • <file> には、ノートブックファイル を指定してください
  • SQLブロック・グリッド要素からのSQLブロック・パラメータ・テーブル・保存済クエリへの参照関係を出力します
  • 処理内でファイルの検証も同時に行い、エラーが見つかった場合、exit 1 で終了します
  • ノートブック内で利用しているコネクションの閲覧権限が必要です（SQLの生成に必要なコネクション情報を取得する必要があるため）

表示の向き ​

  • 既定（--invert なし）では、消費側を起点に依存を辿ります
    • ドキュメントページでは SQLブロック を、グリッドページでは グリッド要素を起点として、参照先の SQL ブロック、さらに参照する SQL ブロックやパラメータ・テーブルへと降りていきます
  • --invert <key> を指定すると、指定したノードを起点に被参照（影響範囲）を逆向きに辿ります
    • SQLブロックを書き換えた場合に、どのSQLブロック・グリッド要素が影響を受けるかを把握する用途を想定しています
    • <key> には起点とするノードのキーを指定します（形式は SQL・ページの指定キー を参照）

起点・対象の限定 ​

  • --key <key> を指定した場合、表示の起点を該当ノードに限定します
    • --key / --page による対象の限定方法は SQL・ページの指定キー を参照してください
    • --key で指定したキーが存在しない場合、エラーを出力して exit 1 で終了します

出力 ​

依存関係をツリー形式で出力します。各参照には、参照の種類（SQL_BLOCK_REF / PARAM_REF / TABLE_REF / QUERY_REF 等）が併記されます。

  • 参照元と異なるページの SQLブロック を指す場合、参照先の表示に pageId も併記されます（同一ページ内の参照では sqlId のみ）
  • 末尾には、表示対象ページのルート数を出力します（DOC_PAGE では SQL ブロック数、GRID_PAGE ではグリッド要素数）
  • --invert 指定時は、末尾に影響を受けるノード数を出力します

消費側起点（既定）の出力例:

$ cdm notebook deps notebooks/sales.cnb.md
notebooks/sales.cnb.md  (Sales Analysis)

Sales Detail (pageId:69cafa30) [DOC_PAGE]
├─ Daily Summary (sqlId:69cafa6c)
│  ├─ SQL_BLOCK_REF → Base Filter (sqlId:69cafa50)
│  │  └─ TABLE_REF → `bigquery-public-data.thelook_ecommerce.orders`
│  └─ PARAM_REF → Year (paramId:671ef14b, NUMBER)
├─ Region Breakdown (sqlId:69cafa7a)
│  ├─ SQL_BLOCK_REF → Base Filter (sqlId:69cafa50)
│  │  └─ TABLE_REF → `bigquery-public-data.thelook_ecommerce.orders`
│  └─ PARAM_REF → Start Station (paramId:671ef14c, STRING)

Sales Dashboard (pageId:6a17a2ba) [GRID_PAGE]
├─ Revenue Trend (itemId:6a18d401)
│  └─ SQL_BLOCK → Daily Summary (pageId:69cafa30, sqlId:69cafa6c)
│     ├─ SQL_BLOCK_REF → Base Filter (sqlId:69cafa50)
│     │  └─ TABLE_REF → bq/…/tb=orders
│     └─ PARAM_REF → Year (paramId:671ef14b, NUMBER)
├─ Region Table (itemId:6a18d405)
│  └─ SQL_BLOCK_RESULT → Region Breakdown (pageId:69cafa30, sqlId:69cafa7a)
│     ├─ SQL_BLOCK_REF → Base Filter (sqlId:69cafa50)
│     │  └─ TABLE_REF → bq/…/tb=orders
│     └─ PARAM_REF → Start Station (paramId:671ef14c, STRING)
└─ Composition Donut (itemId:6a18d409)
   └─ SQL_BLOCK → Category Totals (pageId:69cafa30, sqlId:69cafa673)
      └─ QUERY_REF → Saved: Monthly Base (queryId:71aa02)

2 SQL blocks, 3 grid items

影響範囲（--invert）の出力例:

$ cdm notebook deps notebooks/sales.cnb.md --invert pageId:69cafa30/sqlId:69cafa50
notebooks/sales.cnb.md  (Sales Analysis)

⊙ Base Filter (sqlId:69cafa50) [DOC_PAGE Sales Detail]
└─ used by
   ├─ Daily Summary (sqlId:69cafa6c)  SQL_BLOCK_REF
   │  └─ used by
   │     └─ Revenue Trend (itemId:6a18d401)  SQL_BLOCK
   │        └─ on page → Sales Dashboard (pageId:6a17a2ba) [GRID_PAGE]
   └─ Region Breakdown (sqlId:69cafa7a)  SQL_BLOCK_REF
      └─ used by
         └─ Region Table (itemId:6a18d405)  SQL_BLOCK_RESULT
            └─ on page → Sales Dashboard (pageId:6a17a2ba) [GRID_PAGE]

5 dependents

利用例 ​

bash
# 全体の依存ツリーを表示（消費側起点）
cdm notebook deps notebooks/sales.cnb.md

# SQLブロックを書き換える前に影響範囲を確認
cdm notebook deps notebooks/sales.cnb.md --invert pageId:6a17a2ba/sqlId:69cafa50

# 特定ページの依存のみ表示
cdm notebook deps notebooks/sales.cnb.md --page 6a17a2ba

ノートブックの記述チェック ​

cdm notebook lint <file|directory>
  --rule <name>       適用するルールを限定する場合に指定（複数指定可、未指定で全ルール）
  --profile <name>    利用する profile を指定

対象のノートブックファイルの記述を下記ルールに従いチェックします。ファイルは書き換えません。サーバへの反映を止めるエラーを検知する validate とは異なり、 lint では警告を検知します。

ルール対象チェック事項
mermaid-syntaxダイアグラムブロック（```mermaid）Mermaid の文法
math-syntax数式ブロック・インライン数式（```math, :math[...]）KaTeX の文法
  • <file|directory> には、ノートブックファイル または ディレクトリ を指定してください
    • ディレクトリを指定した場合は、配下の *.cnb.md を再帰的に対象とします
  • --rule を指定した場合、指定したルールのみを適用します（複数指定可）
  • 警告が1件以上ある場合、exit 1 で終了します
  • 処理内でファイルの検証も同時に行い、検証エラーが見つかった場合も exit 1 で終了します
    • 検証エラーは lint の警告より優先して報告します

利用例 ​

bash
# ダイアグラム・数式の文法をチェック
cdm notebook lint notebooks/sales.cnb.md

# ディレクトリ配下をまとめてチェック
cdm notebook lint notebooks/

# 数式のみをチェック
cdm notebook lint notebooks/sales.cnb.md --rule math-syntax

ノートブックのプレビュー ​

cdm notebook preview <file>
  -p, --port <n>      ファイル同期用の WebSocket ポート番号（既定: 8743）
  -d, --debug         同期・書き込みの詳細ログを出力
  --profile <name>    利用する profile を指定

ローカルのノートブックファイルとブラウザを双方向に同期しながら、ブラウザ上でノートブックをプレビュー・編集できるようにします。エディタでの編集と並行して使うことを想定しています。終了するまで起動し続けます（Ctrl+C で終了）。

  • <file> には、ノートブックファイル を指定してください
  • 既定ポート（8743）または --port で指定したポートが使用中の場合、そこから順に空きポートを探索して利用します
  • 起動後、既定のブラウザで対象ノートブックのプレビュー画面が開きます
  • プレビュー中は、対象ファイルとブラウザの間で双方向の同期が自動的に行われます。
    • ファイル → ブラウザ: ファイルの更新をポーリングにより監視し、変更を検知するとプレビューを自動的に更新します。あわせて format によるフォーマット処理が適用され、自動修復可能なエラーは自動的に修復されます
    • ブラウザ → ファイル: プレビュー内でユーザの行った操作（クエリの実行、チャートの追加・編集など）が自動的にファイルへ反映されます
  • プレビュー中はブラウザ側から SQL の一括実行（run 相当）やサーバへの反映（push 相当）も行えます
  • プレビューはCodatumのWebサービス上で行うため、CodatumのWebサービス側の権限に準じます（PATの権限は利用しません）

WARNING

ノートブックのプレビューは、技術的な制約により Safari では利用できません。Chrome / Firefox 等のブラウザをご利用ください。

出力例 ​

$ cdm notebook preview notebooks/sales.cnb.md
Codatum Preview
  Workspace: 6653ebab5a1acaa5bd5422a5
  Notebook : 671ef14b0d08cf6c657df7da
  File     : notebooks/sales.cnb.md
  Session  : 6a1a7aae6f4c4e6348c26356
  Server   : ws://localhost:8743

  Browser: https://app.codatum.com/workspace/6653ebab5a1acaa5bd5422a5/...

  Polling active file on disk... (Ctrl+C to stop)

利用例 ​

bash
# 基本
cdm notebook preview notebooks/sales.cnb.md

# ポートを指定して起動
cdm notebook preview notebooks/sales.cnb.md -p 9000

# profile を指定して起動
cdm notebook preview notebooks/sales.cnb.md --profile staging

注意事項 ​

  • エディタからの保存時に書き込みの競合が頻発する場合、以下の設定をご確認ください
    • エディタの保存時の自動フォーマット機能が有効な場合、プレビューからの変更と競合するため、必ず無効にしてください
    • 同じエディタプロセス内で大量のファイルを監視している場合、ファイル監視イベントの遅延によりエディタに更新が反映されず、競合が発生しやすくなります
      • 大量のファイルを監視するエディタプロセスを終了してからファイルを編集すると、競合が発生しにくくなります

Codatum CLI AIエージェントのための分析環境

© Codatum Inc.