Appearance
cdm notebook の使い方
cdm notebook サブコマンドで、ノートブックファイル（*.cnb.md）の取得・反映・検証・実行・レンダリングなどの一通りの操作を行うことができます。
cdm notebook <subcommand> [arguments] [options]このページでは、編集から反映までの操作の流れと、サブコマンドで共通利用する引数の指定方法について説明します。個別サブコマンドの詳細は、各リンク先を参照してください。
操作の流れ
cdm notebook のサブコマンドの説明は、利用する場面ごとに3つのページに分かれています。おおまかには「取得と反映で取り出す → 編集で作り込む → 実行と出力で動作確認 → 取得と反映で書き戻す」という流れで進めます。
取得と反映
サーバ上のノートブックをローカルに取り出したり、編集後の変更を書き戻したりするサブコマンドです。詳細は 取得と反映 を参照してください。
| サブコマンド | 機能概要 |
|---|---|
notebook clone | サーバ上のノートブックを新規取得 |
notebook create | サーバ上に新規ノートブックを作成して取得 |
notebook pull | ローカルファイルをサーバの最新状態に更新 |
notebook diff | サーバへ反映した場合の差分を確認 |
notebook push | ローカルの変更をサーバに反映 |
notebook delete | サーバ上のノートブックを削除 |
notebook move | サーバ上のノートブックを別フォルダに移動 |
notebook copy | サーバ上のノートブックを複製 |
notebook info | ノートブックのメタ情報を取得 |
notebook list | フォルダ直下のノートブックを一覧 |
notebook search | キーワードでノートブックを横断検索 |
notebook folder list | フォルダ直下のサブフォルダを一覧 |
notebook folder info | フォルダのメタ情報を取得 |
編集を始める前に、まず対象のノートブックをローカルに取り出します。
- 編集対象が決まっている場合は、ノートブックのURLやIDを指定して
notebook cloneで取得します。新規に作る場合はnotebook createでサーバ側に作成しつつローカルに取得します。 - 既に手元にあるファイルを編集する場合は、作業前に
notebook pullでサーバの最新状態に揃えておくと、後の書き戻し時に差分が生じにくくなります。 - 新しいノートブックを作る際に、既存のノートブックを参考にしたいこともあります。その場合は
notebook search（キーワードで横断検索）やnotebook list/notebook folder listで参考になりそうなノートブックを見つけ、notebook cloneで手元に取得しておくと、編集時の参考にできます。
編集が済んだら、サーバへ書き戻します。
- 反映前に
notebook diffで「サーバへ反映した場合に何が変わるか」を確認できます（単純な文字列差分ではなく、サーバ側の統合処理を反映した差分が確認できます）。 - 問題がなければ
notebook pushで反映します。
編集
ローカルの *.cnb.md を作り込む際に、繰り返し使うサブコマンドです。詳細は 編集 を参照してください。
| サブコマンド | 機能概要 |
|---|---|
notebook validate | スキーマ・構文を検証（書き換えなし） |
notebook format | 自動修復・検証・整形 |
notebook param list | パラメータ値の一覧 |
notebook param reset | パラメータ値のリセット |
notebook build-sql | 参照を解決した実行可能なSQLにビルド |
notebook deps | SQLの依存関係・影響範囲を分析 |
notebook lint | ダイアグラム・数式の文法をチェック |
notebook preview | ブラウザと双方向同期しながらプレビュー・編集 |
ノートブックファイルの本文は CLI では編集できないため、エディタやファイルシステム経由で直接編集します。*.cnb.md は通常のマークダウンとフォーマットが異なるため、手動での整形は避け、編集後は必ず CLI で検証・整形します。
- 編集のたびに
notebook formatを実行すると、自動修復可能なエラー（idの指定漏れなど）が修正され、あわせて検証・整形が行われます。検証だけ行いたい場合はnotebook validateを使います。 - SQLブロックの参照やバインドが意図通りに展開されるかは、
notebook build-sqlで実際にビルドされるSQLを出力して確認できます。出力をcdm sqlにパイプすれば、その場で実行・検証もできます。 - パラメータの値の確認やリセット（相対日付の解決、デフォルト値へのロールバック）は、
notebook param list/notebook param resetで行えます。 - SQLブロックを書き換える前に、
notebook depsで依存関係や影響範囲（--invert）を確認しておくと、変更が他のブロック・チャートに与える影響を把握できます。 - クエリ実行結果やチャートを確認しながら作り込む場合は、
notebook previewでブラウザと双方向同期するライブセッションを開きます。プレビュー中はファイルとブラウザの変更が相互に反映され、整形や実行・反映もブラウザ側から行えます。
実行と出力
ある程度形になったノートブックを実行し、結果の反映や成果物の出力、書き戻しの準備を行うサブコマンドです。詳細は 実行と出力 を参照してください。
| サブコマンド | 機能概要 |
|---|---|
notebook run | ノートブック内のSQLを一括実行し結果を反映 |
notebook render page | ページを PNG・PDF として出力 |
notebook render chart | チャートを画像として出力 |
notebook strip | ジョブ実行情報を削除 |
SQLが書けたら実行してファイルに結果を反映し、最終的な確認や成果物の出力を行います。
notebook runでノートブック内のSQLを一括実行し、実行状態・結果をファイルに反映します。キャッシュを参照するため変更があったSQLだけが実行され、最新データで実行したい場合は--refreshを指定します。- 仕上がったページやチャートを共有・保存用に出力する場合は、
notebook render page/notebook render chartで PNG・PDF を生成します。レンダリングはファイルに記録済みの実行結果を参照するため、最新データで出力したい場合は事前にnotebook runを実行してください。 - サーバへの書き戻しや Git 等での管理時に、実行結果に由来する差分を残したくない場合は、
notebook stripでジョブ実行情報を取り除けます。
引数の共通定義
サブコマンドが扱う対象には、サーバ上のノートブック・フォルダと、ローカルのファイル・ディレクトリがあります。サーバのフォルダ階層とローカルのディレクトリ構造は独立しており、例えばサーバ上で別々のフォルダに配置されたノートブックを、ローカルでは同じディレクトリで管理することもできます。
サーバ上の対象の指定方法
ノートブック
サーバ上のノートブックを引数として指定する場合は、以下のいずれかの形式で指定します。
- notebookId （24文字の16進数）: 例
671ef14b0d08cf6c657df7da - URL: Codatum のノートブックページのURL
- 形式:
https://app.codatum.com/workspace/<wsId>/notebook/<notebookId>/<pageId> - URL 内の
<wsId>は、利用中の profile のワークスペースと一致する必要があります
- 形式:
フォルダ
サーバ上のフォルダを引数として指定する場合は、以下のいずれかの形式で指定します。
- フォルダID （24文字の16進数）: 例
67955fa3c1834fdc34705bf8 - URL: Codatum のフォルダページのURL
- 形式:
https://app.codatum.com/workspace/<wsId>/notebook/?folder=<folderId> - URL 内の
<wsId>は、利用中の profile のワークスペースと一致する必要があります
- 形式:
WORKSPACE: ワークスペースのルートフォルダTEAMSPACE:<teamspaceId>: チームスペース単位のルートフォルダPRIVATE: 利用中の profile のアカウントのプライベートのルートフォルダ- 利用中のプランや権限によっては、利用できない場合があります
ローカルの対象の指定方法
ノートブックファイル
*.cnb.md ファイルへのファイルパスを指定します。 拡張子を省略した場合は .cnb.md を自動的に付与します（例: ./notebooks/sales → ./notebooks/sales.cnb.md）
ディレクトリ
*.cnb.md ファイルを含むディレクトリパスを指定します。 指定されたディレクトリ配下のすべての *.cnb.md ファイルが対象となります。
サーバ上の対象との紐づけ
ファイルやディレクトリを指定した場合、サーバ上の対象との紐づけは、ノートブックファイルのフロントマターで指定されたノートブックID（id）を用いて行われます。
フロントマター内の workspace_id と、利用中の profile のワークスペースIDが一致しない場合、ワークスペースの不一致エラーとして、コマンドは exit 1 で終了します。ディレクトリを指定した場合、配下のすべてのノートブックファイルに対して検証が行われます。
SQL・ページの指定キー
build-sql / deps / run / render chart では、--key で対象の SQL・チャート・グリッド要素を限定できます。--key の形式はページの種類によって異なります。
- ドキュメントページの SQLブロック:
pageId:${pageId}/sqlId:${sqlId} - ドキュメントページのチャート（
render chart）:pageId:${pageId}/chartId:${chartId} - グリッドページの グリッド要素:
pageId:${pageId}/itemId:${itemId}
また、--page で対象を特定ページに限定できます。<pageId> にはページ属性で指定した id を指定してください。--page と --key を同時に指定した場合、エラーを出力して exit 1 で終了します。