Skip to content

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

概要 ​

作成したノートブックファイル(*.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 オプションを指定します。SQLの実行が成功した場合、チャートなどのSQLの実行結果に依存する処理を検証し、SQLの実行結果と合わせてステータスとして出力します。

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

WARNING

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

ステータス ​

ステータスには、SQLの実行成否に加えて、SQLの実行結果に依存しているチャートやマークアップページ内の式の検証結果も反映されます。

ステータス意味
成功(SUCCESS)SQLの実行が成功し、検証でも問題が見つからなかった場合
スキップ(SKIPPED)SQLの実行の代わりにブラウザ上のインメモリ処理が行われ、検証でも問題が見つからなかった場合
警告(WARNING)SQLの実行は成功したが、依存するチャートがデータによって描画できない場合(サンキーの循環など)、または依存するマークアップページの式が実行時エラーになった場合
エラー(ERROR)SQLの実行が失敗した場合、依存するチャートの設定が実行結果と合わない場合、または依存するマークアップページにスキーマエラーが見つかった場合
  • ERROR が見つからず WARNING だけが見つかった場合は、exit 0 で終了します
  • 検証の結果は、ノートブックファイルの実行状態(state)には反映されません

エラー・中断時の挙動 ​

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

エラー時 ​

  • 既定では、いずれかのSQLの実行が失敗した時点で exit 1 で終了します
  • --keep-going を指定した場合、SQLがエラーになっても後続の実行を継続し、すべて実行し終えた後にエラーがあれば exit 1 で終了します
  • SQLの実行が成功し、検証結果が ERROR になった場合は、後続の実行を継続し、すべて実行し終えた後に 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ブロック に切り出しておくと、このキャッシュが効きやすくなります

出力の分離 ​

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

進捗表示(stderr) ​

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

TTY 時の出力例 ​

実行中の例です。

Running 4 SQLs from notebooks/sales.cnb.md

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

完了時の例です。チャートの ERROR とマークアップページの WARNING を含みます。

Running 4 SQLs from notebooks/sales.cnb.md

Sales Dashboard (pageId:6ae7f0c5907c12ee1b96057a)
├─ Daily Summary (sqlId:26c0d479d8e0e22f5011579e)
│  │  ✔ SUCCESS  rows=42  duration=0.2s  cache=FULL
│  ├─ Revenue Trend (chartId:9f963a03bd34d263efe05da6)
│  │  ✔ SUCCESS  rows=14  duration=0.2s  cache=FULL
│  ├─ Sales by Category (chartId:7c41733d03f1754111c1a297)
│  │  ○ SKIPPED (in-memory processing)
│  └─ Sales by Region (chartId:666f517df1fc1840f926e2d1)
│     ✘ ERROR
│     errorMessage=Column not found: 'region'
└─ Today's Alerts (sqlId:d5fe61a4accfb072760d778f)
      ✔ SUCCESS  rows=0  duration=0.2s  cache=FULL
Summary (pageId:6cd8983a976b5ed11604a69b)
├─ Daily Summary (itemId:3ec6c7c1713e76d80e5f9b04)
│  ✔ SUCCESS  rows=42  duration=0.2s  cache=FULL
└─ Today's Alerts (itemId:9815bb8ac5eda85bedb6f578)
      ⚠ WARNING  rows=0  duration=0.2s  cache=FULL
      warningMessage=L137:11 Could not evaluate with the current data: The SQL block returned 0 rows, so `row` is not available. Check `size(rows) > 0` first.

Completed: 4 SQLs executed, 7 items: 4 success, 1 skipped, 1 warning, 1 error (total 1.9s)

最終結果(stdout) ​

次の例は、進捗表示の例と同じ実行で出力したものです。

text(既定) ​

ページごとに見出しと表を出力します。SQL とチャートの両方を含みます。ERROR・WARNING の理由は含まないため、進捗表示か json で確認します。

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

Id                                Name               Status   Cache  RowCount  DurationMs
sqlId:26c0d479d8e0e22f5011579e    Daily Summary      SUCCESS  FULL   42        212
chartId:9f963a03bd34d263efe05da6  Revenue Trend      SUCCESS  FULL   14        208
chartId:7c41733d03f1754111c1a297  Sales by Category  SKIPPED
chartId:666f517df1fc1840f926e2d1  Sales by Region    ERROR
sqlId:d5fe61a4accfb072760d778f    Today's Alerts     SUCCESS  FULL   0         215

Summary (pageId:6cd8983a976b5ed11604a69b)

Id                               Name            Status   Cache  RowCount  DurationMs
itemId:3ec6c7c1713e76d80e5f9b04  Daily Summary   SUCCESS  FULL   42        212
itemId:9815bb8ac5eda85bedb6f578  Today's Alerts  WARNING  FULL   0         215
4 SQLs executed, 7 items: 4 success, 1 skipped, 1 warning, 1 error
json ​

results には、SQL ごとに 1 件ずつ出力します。次の例では、チャートの ERROR を含む 1 件と、WARNING の 1 件だけを示します。

json
{
  "summary": {
    "successCount": 4,
    "errorCount": 1,
    "warningCount": 1
  },
  "results": [
    {
      "pageId": "6ae7f0c5907c12ee1b96057a",
      "pageName": "Sales Dashboard",
      "sqlId": "26c0d479d8e0e22f5011579e",
      "sqlName": "Daily Summary",
      "status": "SUCCESS",
      "cache": "FULL",
      "charts": [
        {
          "chartId": "9f963a03bd34d263efe05da6",
          "name": "Revenue Trend",
          "status": "SUCCESS",
          "cache": "FULL",
          "rowCount": 14,
          "durationMs": 208,
          "jobId": "bq/cn=6653ebcc9e305b6b62d31525/jb=l8YcHYnf0DmYixH7DyazmtKH8v3"
        },
        {
          "chartId": "7c41733d03f1754111c1a297",
          "name": "Sales by Category",
          "status": "SKIPPED"
        },
        {
          "chartId": "666f517df1fc1840f926e2d1",
          "name": "Sales by Region",
          "status": "ERROR",
          "errorMessage": "Column not found: 'region'"
        }
      ],
      "stats": [],
      "jobId": "bq/cn=6653ebcc9e305b6b62d31525/jb=vMvZ2fhHA2SwnAjErvFR3Ty067D",
      "rowCount": 42,
      "durationMs": 212
    },
    {
      "pageId": "6cd8983a976b5ed11604a69b",
      "pageName": "Summary",
      "sqlId": "9815bb8ac5eda85bedb6f578",
      "sqlName": "Today's Alerts",
      "status": "WARNING",
      "cache": "FULL",
      "charts": [],
      "stats": [],
      "jobId": "bq/cn=6653ebcc9e305b6b62d31525/jb=UX5FfdNBqAXhLxr7QwW1Avs5t1C",
      "rowCount": 0,
      "durationMs": 215,
      "warningMessages": [
        "L137:11 Could not evaluate with the current data: The SQL block returned 0 rows, so `row` is not available. Check `size(rows) > 0` first."
      ]
    }
  ]
}

ページの 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)
  --tz <timezone>          TIMESTAMP の表示に使う IANA タイムゾーン(例: Asia/Tokyo)
  -w, --width <px>         png 出力時の横幅: 1〜2048(既定: 1024)
  --paper-format <fmt>     pdf 出力時の用紙サイズ: A4 | A3(既定: A4)
  --landscape              pdf 出力時に横向きで出力
  --view <name>=<value>    マークアップページの表示の状態(複数指定可)
  --profile <name>         利用する profile を指定

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

  • <file> には、ノートブックファイル を指定してください
  • --page で対象ページを指定します
    • <pageId> にはページ属性で指定した id を指定してください
    • --page を省略した場合、ノートブック内のすべてのページが対象となります
  • --format で出力形式を指定します(既定: png)
    • --width は png 出力時のみ、--paper-format・--landscape は pdf 出力時のみ有効です。対象の形式で利用しないオプションを指定した場合、エラーを出力して exit 1 で終了します
  • --width には 1〜2048 の整数を指定してください。範囲外の値を指定した場合、エラーを出力して exit 1 で終了します
  • --view で、マークアップページの表示の状態を指定して描画します
    • <name> には、as で付けた名前を指定します。<value> に指定する値は、要素ごとに次のとおりです
      • <Select>・<Tabs>:選択肢の value
      • <Switch>・<Collapse>:true か false
      • <TextInput>:文字
      • <NumberInput>・<Slider>:数値。空の値(--view min=)を指定すると、未入力で描画します
      • <RangeSlider>:下限と上限を , で区切った値(--view price=10,100)。空の値を指定すると、未選択で描画します
    • --page でマークアップページを指定したときだけ利用できます。指定しなかった名前の状態は、既定の状態で描画されます
    • 指定が誤っている場合、エラーを出力して exit 1 で終了します
  • --tz で、チャートなどの TIMESTAMP の値を表示するタイムゾーンを指定します
    • 省略した場合は、コマンド実行環境のローカルタイムゾーンを使います。CI など実行環境のタイムゾーンが利用環境と異なる場合は、--tz を直接指定してください
    • IANA タイムゾーンとして無効な値を指定した場合、エラーを出力して 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 page notebooks/sales.cnb.md \
  --page 6a17a2ba5c8f6652542a0d67 --view tab=detail --view compare=true -o out/

チャートの画像生成 ​

cdm notebook render chart <file>
  -k, --key <key>          対象とするチャート / グリッド要素のキー(必須)
  -o, --output <path>      出力先(ファイルパス または ディレクトリ)
  -w, --width <px>         横幅: 1〜2048(既定: 480)
  -H, --height <px>        高さ: 1〜2048(既定: 320)
  --theme <theme>          テーマ: light | dark(既定: light)
  --locale <locale>        ロケール: en-US | ja-JP(既定: en-US)
  --tz <timezone>          TIMESTAMP の表示に使う IANA タイムゾーン(例: Asia/Tokyo)
  --profile <name>         利用する profile を指定

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

  • <file> には、ノートブックファイル を指定してください
  • --key で対象を指定します(必須)
    • --key の形式は SQL・ページの指定キー を参照してください(チャートは pageId:${pageId}/chartId:${chartId}、グリッド要素は pageId:${pageId}/itemId:${itemId})
    • マークアップページでは、Chart の要素だけを指定できます(pageId:${pageId}/itemId:${要素の id})。ほかの要素を指定した場合、エラーを出力して exit 1 で終了します
    • --key で指定したキーが存在しない場合、エラーを出力して exit 1 で終了します
  • --width・--height には 1〜2048 の整数を指定してください。範囲外の値を指定した場合、エラーを出力して exit 1 で終了します
  • --tz の扱いは render page と同じです
  • チャート内で利用しているコネクションの閲覧権限が必要です

レンダリングの仕組み・必要な権限は 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エージェントのための分析環境