Codatum CLI

Appearance

ノートブックファイルの実行と出力 ​

概要 ​

作成したノートブックファイル（*.cnb.md）を実行し、実行結果の確認や成果物の出力、書き戻しの準備を行うサブコマンド群です。引数の共通定義（ファイル / SQL・ページの指定キー）は 使い方 を参照してください。

サブコマンド機能概要
notebook runノートブック内のSQLを一括実行し結果を反映
notebook render pageページを PNG・PDF として出力
notebook render chartチャートを画像として出力
notebook stripジョブ実行情報を削除

SQLの一括実行 ​

cdm notebook run <file>
  -k, --key <key>         実行対象の SQL を限定する場合は指定
  --page <pageId>         実行対象のページを限定する場合は指定
  --refresh               最新のデータで実行
  --keep-going            SQLがエラーになっても後続の実行を継続する
  --sql-timeout <sec>     1SQLあたりのタイムアウト秒数（既定: 300）
  --total-timeout <sec>   ノートブック実行全体のタイムアウト秒数（既定: 無制限）
  -f, --format <fmt>      最終結果の出力形式: text | json（既定: text）
  --profile <name>        利用する profile を指定

対象のノートブックファイル内のSQLを順次実行してノートブックファイルを更新します。SQLを実行する際は既存のキャッシュを参照し、SQLに変更があったものだけが実行されます。最新のデータで実行したい場合は --refresh オプションを指定します。

  • <file> には、ノートブックファイル を指定してください
  • 既定では、ファイル内のすべてのSQLが実行対象となります
  • --key / --page による対象の限定方法は SQL・ページの指定キー を参照してください
    • ドキュメントページの SQL ブロックを --key で指定した場合、該当するSQLブロックをデータソースとするチャートも実行対象となります
    • グリッド要素を --key で指定した場合、該当するグリッド要素の更新に必要なSQLブロックやチャートが実行対象となります
    • --key で指定したキーが存在しない場合、エラーを出力して exit 1 で終了します
  • --refresh を指定した場合、実行開始時点より前に作成されたクエリ実行結果のキャッシュは利用されません（同一実行内で生成されたキャッシュは引き続き利用します）
  • SQLの実行状態や実行結果は適宜ノートブックファイルに反映されます
  • 実行前にformat, build-sqlを実行し、エラーが見つかった場合、exit 1 で終了します
  • ノートブック内で利用しているコネクションの閲覧・実行権限が必要です

WARNING

実行対象のSQLブロックやチャートが多い場合、SQLの純粋な実行時間以外にキャッシュの確認処理にも時間がかかり、全体として実行に時間がかかる場合があります。 必要に応じて実行対象を絞り込むようにしてください。

エラー・中断時の挙動 ​

実行中にエラーやタイムアウト、Ctrl+C による中断が発生した場合の挙動は以下の通りです。

エラー時 ​

  • 既定では、いずれかのSQLの実行が失敗した時点で exit 1 で終了します
  • --keep-going を指定した場合、SQLがエラーになっても後続の実行を継続し、すべて実行し終えた後にエラーがあれば exit 1 で終了します

タイムアウト ​

  • --sql-timeout の超過時はそのSQLの実行失敗として扱い、--keep-going 指定時は後続の実行を継続し、未指定時は exit 1 で終了します
  • --total-timeout の超過時は、--keep-going の指定有無に関わらず終了します

中断時のジョブの扱い ​

  • Ctrl+C（SIGINT）受信時、およびタイムアウト超過時は、実行中のSQLジョブのキャンセルを試みた上で、後続のSQLを実行せずに終了します
  • 各SQLのジョブIDはノートブックファイルに記録されるため、中断後も sql get-job-metadata で状態確認、sql cancel-job でキャンセルが可能です

出力形式 ​

キャッシュの利用結果 ​

  • cache: "FULL" の場合、キャッシュを利用し、SQLは実行されていません
  • cache: "PARTIAL" の場合、SQL内のサブクエリの一部が過去のクエリ実行結果の一時テーブルを参照するクエリに置き換えられて実行されています
    • 共通のサブクエリを独立した SQLブロック に切り出しておくと、このキャッシュが効きやすくなります

ステータスについて ​

  • チャートの status が SKIPPED の場合、SQLによるデータ加工が行われず、ブラウザ上のインメモリ処理で描画されることを意味します
    • データソースのクエリ実行結果が1000件以下で、カスタムSQLの指定がない場合などに適用されます

出力の分離 ​

TTY 接続時は stderr に進捗情報を出力します。実行完了後の最終結果は stdout に出力します（非 TTY では進捗は出力しません）。

進捗表示（stderr） ​

ページごとに階層化された進捗ログを出力します。

TTY 時の出力例 ​

実行中:

Running 4 SQLs from notebooks/sales.cnb.md

Sales Dashboard (pageId:6a17a2ba5c8f6652542a0d67)
├─ Daily Summary (sqlId:6a17a4b325c9a308e87bfa0d)
│  │  ⠋ [1/7] RUNNING (3s)

完了時:

Running 4 SQLs from notebooks/sales.cnb.md

Sales Dashboard (pageId:6a17a2ba5c8f6652542a0d67)
├─ Daily Summary (sqlId:6a17a4b325c9a308e87bfa0d)
│  │  ✔ SUCCESS  rows=42   duration=0.3s  cache=FULL
│  └─ Revenue Trend (chartId:6a18d512593a1ad7c7e80e40)
│     ✔ SUCCESS  duration=0.2s  cache=FULL
├─ Sales Detail (sqlId:6a17a2bca32a0af4fab08a13)
│  │  ✔ SUCCESS  rows=500  duration=1.4s  cache=FULL
│  ├─ Sales by Category (chartId:6a18d405e4f3710aa9166c14)
│  │  ✔ SUCCESS  duration=0.2s  cache=FULL
│  └─ Regional Heatmap (chartId:6a18de1436ddce437aa30b18)
│     ○ SKIPPED (in-memory processing)
└─ Prior Month Compare (sqlId:6a17a2c322ef1f8ba3323fbe)
      ✔ SUCCESS  rows=12   duration=0.4s  cache=NONE
Monthly Report (pageId:6a17dead68eb7847e092cb75)
└─ Category Totals (sqlId:6a18d673a150722d8bab87a9)
   │  ✔ SUCCESS  rows=8    duration=0.3s  cache=FULL
   └─ Composition Donut (chartId:6a18d605d49c2c9c004ff5aa)
      ✔ SUCCESS  duration=0.2s  cache=FULL

Completed: 7 success, 0 error (total 2.8s)

最終結果（stdout） ​

text（既定） ​

ページごとに見出しと表を出力します。SQL とチャートの両方を含みます。

$ cdm notebook run notebooks/sales.cnb.md
Sales Dashboard (pageId:6a17a2ba5c8f6652542a0d67)

Id                                      Name                 Status   Cache  RowCount  DurationMs
sqlId:6a17a4b325c9a308e87bfa0d           Daily Summary        SUCCESS  FULL   42        300
chartId:6a18d512593a1ad7c7e80e40         Revenue Trend        SUCCESS  FULL             200
sqlId:6a17a2bca32a0af4fab08a13           Sales Detail         SUCCESS  FULL   500       1400
chartId:6a18d405e4f3710aa9166c14          Sales by Category    SUCCESS  FULL             200
chartId:6a18de1436ddce437aa30b18         Regional Heatmap     SKIPPED
sqlId:6a17a2c322ef1f8ba3323fbe           Prior Month Compare  SUCCESS  NONE   12        400

Monthly Report (pageId:6a17dead68eb7847e092cb75)

Id                                      Name                 Status   Cache  RowCount  DurationMs
sqlId:6a18d673a150722d8bab87a9           Category Totals      SUCCESS  FULL   8         300
chartId:6a18d605d49c2c9c004ff5aa         Composition Donut    SUCCESS  FULL             200

4 SQLs executed: 7 success
json ​
json
{
  "summary": {
    "successCount": 7,
    "errorCount": 0
  },
  "results": [
    {
      "pageId": "6a17a2ba5c8f6652542a0d67",
      "pageName": "Sales Dashboard",
      "sqlId": "6a17a4b325c9a308e87bfa0d",
      "sqlName": "Daily Summary",
      "status": "SUCCESS",
      "cache": "FULL",
      "rowCount": 42,
      "durationMs": 300,
      "jobId": "bq/cn=6653ebcc9e305b6b62d31525/jb=dcE3yFJHKg9kdbyb9jQy7N387zH",
      "charts": [
        {
          "chartId": "6a18d512593a1ad7c7e80e40",
          "name": "Revenue Trend",
          "status": "SUCCESS",
          "cache": "FULL",
          "rowCount": 12,
          "durationMs": 200,
          "jobId": "bq/cn=6653ebcc9e305b6b62d31525/jb=chartJob1"
        }
      ]
    },
    {
      "pageId": "6a17a2ba5c8f6652542a0d67",
      "pageName": "Sales Dashboard",
      "sqlId": "6a17a2bca32a0af4fab08a13",
      "sqlName": "Sales Detail",
      "status": "SUCCESS",
      "cache": "FULL",
      "rowCount": 500,
      "durationMs": 1400,
      "jobId": "bq/cn=6653ebcc9e305b6b62d31525/jb=sqlJob2",
      "charts": [
        {
          "chartId": "6a18d405e4f3710aa9166c14",
          "name": "Sales by Category",
          "status": "SUCCESS",
          "cache": "FULL",
          "durationMs": 200,
          "jobId": "bq/cn=6653ebcc9e305b6b62d31525/jb=chartJob2"
        },
        {
          "chartId": "6a18de1436ddce437aa30b18",
          "name": "Regional Heatmap",
          "status": "SKIPPED"
        }
      ]
    },
    {
      "pageId": "6a17a2ba5c8f6652542a0d67",
      "pageName": "Sales Dashboard",
      "sqlId": "6a17a2c322ef1f8ba3323fbe",
      "sqlName": "Prior Month Compare",
      "status": "SUCCESS",
      "cache": "NONE",
      "rowCount": 12,
      "durationMs": 400,
      "jobId": "bq/cn=6653ebcc9e305b6b62d31525/jb=sqlJob3",
      "charts": []
    },
    {
      "pageId": "6a17dead68eb7847e092cb75",
      "pageName": "Monthly Report",
      "sqlId": "6a18d673a150722d8bab87a9",
      "sqlName": "Category Totals",
      "status": "SUCCESS",
      "cache": "FULL",
      "rowCount": 8,
      "durationMs": 300,
      "jobId": "bq/cn=665411a7c4a832df6fc01b69/jb=1dIXGcgo1JmJc3lX7VCN12s5Bq0",
      "charts": [
        {
          "chartId": "6a18d605d49c2c9c004ff5aa",
          "name": "Composition Donut",
          "status": "SUCCESS",
          "cache": "FULL",
          "durationMs": 200,
          "jobId": "bq/cn=665411a7c4a832df6fc01b69/jb=chartJob3"
        }
      ]
    }
  ]
}

ページの PNG・PDF 生成 ​

cdm notebook render page <file>
  --page <pageId>          対象ページ（未指定時はノートブック内の全ページ）
  -o, --output <path>      出力先（ファイルパス または ディレクトリ）
  -f, --format <fmt>       出力形式: png | pdf（既定: png）
  --theme <theme>          テーマ: light | dark（既定: light）
  --locale <locale>        ロケール: en-US | ja-JP（既定: en-US）
  -w, --width <px>         png 出力時の横幅（既定: 1024）
  --paper-format <fmt>     pdf 出力時の用紙サイズ: A4 | A3（既定: A4）
  --landscape              pdf 出力時に横向きで出力
  --profile <name>         利用する profile を指定

ノートブックのページをレンダリング（スクリーンショット）して、PNG 画像または PDF として出力します。スクリーンショットは、ノートブックファイルに記録されたジョブ実行情報を参照して、対応する実行結果を元に描画します。

  • <file> には、ノートブックファイル を指定してください
  • --page で対象ページを指定します
    • <pageId> にはページ属性で指定した id を指定してください
    • --page を省略した場合、ノートブック内のすべてのページが対象となります
  • --format で出力形式を指定します（既定: png）
    • --width は png 出力時のみ、--paper-format・--landscape は pdf 出力時のみ有効です。対象の形式で利用しないオプションを指定した場合、エラーを出力して exit 1 で終了します
  • ノートブック内で利用しているコネクションの閲覧権限が必要です

WARNING

ページ内のSQLブロックやチャートが多い場合、レンダリングの処理に非常に時間がかかる場合があります。 チャート単体の描画確認が目的の場合は notebook render chart を利用し、レイアウトを含めたページの描画確認の場合も必要なページのみに絞って利用してください。

全ページ出力時の挙動 ​

--page を省略して全ページを対象とした場合、出力形式によって生成されるファイルが異なります。

出力形式既定の挙動
pdfすべてのページをまとめた 1つの PDF ファイル を生成します
pngページごとに個別の PNG ファイルを生成します

出力先 ​

  • --output で出力先を指定できます
    • ノートブックファイルのようなファイルパスを指定した場合、そのパスに書き込みます
      • 拡張子と --format が不整合な場合はエラーとなります
      • 全ページ png 出力（複数ファイル）でファイルパスを指定した場合は、拡張子の直前に連番サフィックスを付与して複数ファイルに書き出します（後述）
    • ディレクトリを指定した場合、ディレクトリ内にファイルを生成します
      • ファイル名はノートブック名・ページ名から自動生成されます（例: Sales-Analysis__Dashboard.png）
      • 同名のファイルが存在する場合は連番を付与します
    • 中間ディレクトリは必要に応じて自動作成します
  • --output の指定がない場合は、 --output ./ として処理します

全ページ png 出力時のファイル名 ​

--page 省略 + png の場合、出力はページ数分の複数ファイルになります。出力先の指定によって命名規則が変わります。

  • ファイルパスを指定した場合: 指定したパスの拡張子の直前に、ゼロ埋め2桁の連番サフィックス（_01, _02, …）を付与します。1ページ目を含めすべて連番を付与するため、glob 等で漏れなく拾えます
    • 例: -o out/dashboard.png → out/dashboard_01.png, out/dashboard_02.png, out/dashboard_03.png
  • ディレクトリを指定（または未指定）の場合: ノートブック名・ページ名から自動命名します
    • 例: Sales-Analysis__Sales-Dashboard.png, Sales-Analysis__Monthly-Report.png

レンダリングの仕組み ​

レンダリングではSQLの実行は行わず、ノートブックファイルに記録されたジョブ実行情報を参照して、対応する実行結果からレンダリングします。

  • 最新のデータで描画したい場合は、事前に cdm notebook run を実行してからレンダリングしてください
  • この仕組みは render chart でも共通です

利用例 ​

bash
# 単一ページを PNG で出力（カレントディレクトリに自動命名）
cdm notebook render page notebooks/sales.cnb.md --page 6a17a2ba5c8f6652542a0d67

# 全ページを PNG で出力（ページごとに複数ファイル・自動命名）
cdm notebook render page notebooks/sales.cnb.md -o out/

# 全ページを PNG で出力（パス指定 → out/dashboard_01.png, _02.png, ...）
cdm notebook render page notebooks/sales.cnb.md -o out/dashboard.png

# 横幅を指定して単一ページを PNG で出力
cdm notebook render page notebooks/sales.cnb.md \
  --page 6a17a2ba5c8f6652542a0d67 -w 1280 -o out/dashboard.png

# 全ページを綴じた1つの PDF で出力
cdm notebook render page notebooks/sales.cnb.md -f pdf -o out/sales.pdf

# 単一ページを PDF で出力
cdm notebook render page notebooks/sales.cnb.md \
  --page 6a17a2ba5c8f6652542a0d67 -f pdf -o out/

# A3・横向きの PDF で全ページ出力
cdm notebook render page notebooks/sales.cnb.md \
  -f pdf --paper-format A3 --landscape -o out/

# 日本語ロケール・ダークテーマで出力
cdm notebook render page notebooks/sales.cnb.md \
  --page 6a17a2ba5c8f6652542a0d67 --theme dark --locale ja-JP -o out/

チャートの画像生成 ​

cdm notebook render chart <file>
  -k, --key <key>          対象とするチャート / グリッド要素のキー（必須）
  -o, --output <path>      出力先（ファイルパス または ディレクトリ）
  -w, --width <px>         横幅（既定: 480）
  -H, --height <px>        高さ（既定: 320）
  --theme <theme>          テーマ: light | dark（既定: light）
  --locale <locale>        ロケール: en-US | ja-JP（既定: en-US）
  --profile <name>         利用する profile を指定

ノートブック内の単一のチャート（またはグリッド要素）を、指定したサイズの PNG 画像として出力します。

  • <file> には、ノートブックファイル を指定してください
  • --key で対象を指定します（必須）
    • --key の形式は SQL・ページの指定キー を参照してください（チャートは pageId:${pageId}/chartId:${chartId}、グリッド要素は pageId:${pageId}/itemId:${itemId}）
    • --key で指定したキーが存在しない場合、エラーを出力して exit 1 で終了します
  • チャート内で利用しているコネクションの閲覧権限が必要です

レンダリングの仕組み・必要な権限は render page と共通です。

出力先 ​

  • --output の挙動は render page の出力先 と同様です（出力形式は PNG 固定）
    • ファイルパスを指定した場合の拡張子は .png です
    • ディレクトリを指定した場合のファイル名は、ノートブック名・チャート名から自動生成されます（例: Sales-Analysis__Revenue-Trend.png）

利用例 ​

bash
# チャートを 800x600 の PNG で出力（カレントディレクトリに自動命名）
cdm notebook render chart notebooks/sales.cnb.md \
  -k pageId:6a17a2ba5c8f6652542a0d67/chartId:6a18d512593a1ad7c7e80e40

# サイズとファイル名を指定
cdm notebook render chart notebooks/sales.cnb.md \
  -k pageId:6a17a2ba/chartId:6a18d512 -w 1200 -H 800 -o out/revenue.png

# グリッド要素を対象に出力
cdm notebook render chart notebooks/sales.cnb.md \
  -k pageId:6a17a2ba/itemId:6a18d401 -o out/

# 日本語ロケール・ダークテーマで出力
cdm notebook render chart notebooks/sales.cnb.md \
  -k pageId:6a17a2ba/chartId:6a18d512 --theme dark --locale ja-JP -o out/

ジョブ実行情報の削除 ​

cdm notebook strip <file|directory>
  --check             削除は行わず、ジョブ実行情報が残っているかの確認のみ実施
  --profile <name>    利用する profile を指定

対象のノートブックファイルから、ノートブック実行に紐づくジョブ実行情報（ジョブID、エラー、実行結果ID等）を削除します。サーバへの書き戻しや Git 等での管理時に、実行結果に由来する差分を残したくない場合に利用します。

  • <file|directory> には、ノートブックファイル または ディレクトリ を指定してください
  • 処理内でファイルの検証も同時に行い、エラーが見つかった場合、exit 1 で終了します。
    • 自動修復可能なエラーも検証エラーとして扱われるため、対象と同じパスを指定して cdm notebook format を実行することで解消できる場合があります。
  • サーバへの書き戻し時にジョブ実行情報を無視するだけでよい場合は、 strip ではなく、diff / push する際に --ignore-job-metadata オプションを指定してください

削除を伴わない確認 ​

--check を指定した場合、ファイルの書き換えは行わず、ジョブ実行情報が残っているかどうかの確認のみを行います。strip 済であることを CI で担保する用途を想定しています。

  • 結果は終了コードでも表現されます
    • すべてのファイルが strip 済（削除対象なし）: exit 0
    • strip されていないファイルがある、またはエラー: exit 1
  • strip されていないファイルがある場合、対象ファイルを stderr に出力します
  • --check 指定時も検証は同時に行われ、検証エラーがある場合は exit 1 で終了します
    • 検証エラーと未 strip が混在する場合は、format --check と同様に検証エラーを優先して報告します
$ cdm notebook strip notebooks/ --check
notebooks/sales.cnb.md: not stripped
notebooks/orders.cnb.md: not stripped

2 file(s) are not stripped. Run `cdm notebook strip notebooks/` to strip them.

利用例 ​

bash
# ジョブ実行情報を削除
cdm notebook strip notebooks/

# 単一ファイルを対象に削除
cdm notebook strip notebooks/sales.cnb.md

# CI 用: strip 漏れがないかを確認（書き換えはしない）
cdm notebook strip notebooks/ --check

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

© Codatum Inc.