Appearance
対話でダッシュボードを作成
概要
ダッシュボードは、一度の指示で完成するものではありません。チャートを表示し、結果を確認し、見せ方を調整する —— この繰り返しの中で形になっていきます。
このユースケースでは、ローカルで Claude Code と対話しながら、新しいノートブック（.cnb.md）をゼロから作成する流れを説明します。テーブルの調査、SQLの記述、チャートの組み立て、仕上がりの確認は Claude Code が担い、利用者はブラウザのプレビューを確認しながら修正を指示します。
- 主役: ローカルで指示を出す個人と、手を動かす Claude Code
- 題材: BigQuery 公開データセット
bigquery-public-data.thelook_ecommerce（架空ECの売上データ） - 成果物: ノートブックファイル（
.cnb.md）
完成形のサンプルは codatum-cli-examples リポジトリ（use-cases/01-build-dashboard/）で公開しています。
準備
作業に入る前に、Codatum 側で次の3つを用意しておきます。ここだけは手作業ですが、一度やれば以降の作り込みはすべて Claude Code に任せられます。
1. 作業用フォルダを作る
Codatum 上に、作業用フォルダを1つ作成します。作成したら、フォルダの URL を控えておいてください。あとで Claude Code に「ここに作って」と渡すために使います。
2. PAT を発行する
このユースケースで Claude Code が行うのは、作業用フォルダへのノートブックの作成・編集と、SQLの実行です。そのため PAT には次の権限だけを与えれば十分です。
- 作業用フォルダの閲覧・編集権限
- 利用するコネクションの閲覧・実行権限
PAT の発行と登録は、cdm auth login のブラウザでの承認から行えます。承認画面で「トークンの権限を制限する」を有効にし、上記の作業用フォルダと利用コネクションだけに絞っておくと、他のノートブックやデータには触れられない安全な状態で作業できます。権限の仕組みの詳細は PATと権限 を参照してください。
3. Claude Code から cdm を使えるようにする
Claude Code が .cnb.md を扱えるよう、AIエージェントのセットアップを済ませておきます。
全体の流れ
準備が済んだら、会話を通じて作業を進めます。
- 作業用フォルダの URL を渡して、ノートブックを作ってもらう
- ノートブックを実行して、チャートにデータを反映してもらう
- プレビューを見て、「こう直して」と指示を重ねていく
- チャートを追加して、ダッシュボードの素材を揃える
- パラメータやグリッドページを足して、ダッシュボードとして仕上げる
- サーバに反映する
cdm notebook preview は単なるビューアではなく、ローカルの .cnb.md とブラウザを双方向に同期するライブセッションです。起動している間は、ファイルの編集がブラウザに即座に反映され、ブラウザ上の操作もファイルに書き戻されます。Claude Code がファイルを編集すれば、その結果がそのままブラウザのプレビューに現れます。
なお、ノートブックの作成・実行・サーバへの反映といった操作の前には、Claude Code が実行してよいか確認を求めます。内容を確かめて進めてください。
使い方
ノートブックを作成する
最初に、控えておいた作業用フォルダの URL を渡して、作りたいものを伝えます。
You: BigQuery のパブリックデータセットの theLook（
bigquery-public-data.thelook_ecommerce）の売上ダッシュボードを新しく作りたい。次のURLのフォルダに新しくノートブックを作成して、今いるディレクトリで作業をしたい。まず、カテゴリ別の売上合計を棒グラフにする1ページを用意して。できたらプレビューを開いて。https://app.codatum.com/workspace/.../?folder=...
Claude Code は .cnb.md を編集する前に CLI と認証を確認し、AIエージェント向けガイド を読み込みます。そのうえで、渡されたフォルダに cdm notebook create でノートブックを作成し、使えるコネクションとテーブルを cdm connection list や cdm catalog search-tables で調べてSQLを書き、チャートを組み立て、プレビューのためにブラウザを開きます。
Claude: フォルダにノートブックを作成しました。
order_itemsとproductsを結合してカテゴリ別売上を集計し、棒グラフを設定しています。プレビューを開いたので、ブラウザで確認してみてください。
ノートブックを実行する
明示的な指示をしていない場合、作成した直後のノートブックはまだSQLが実行されていません。プレビューにはチャートの枠は表示されますが、データは反映されていません。ノートブックを実行して、チャートにデータを反映します。
You: ノートブックを実行して。
Claude: 実行しました。カテゴリ別売上が集計され、プレビューのチャートにデータが反映されています。
Claude Code は cdm notebook run でノートブック内のSQLをまとめて実行し、結果をファイルに反映します。実行結果はプレビューにも自動的に反映されます。
確認して修正する
ここからは、プレビューを確認しながら修正を指示します。仕上がりの確認も Claude Code が行います。チャートを画像に書き出し、内容を確認したうえで修正します。
You: カテゴリのラベルが読みにくい。画像に書き出して確認したうえで改善してみて。
Claude: チャートを画像に書き出して確認しました。縦棒だとカテゴリ名が重なって読めなかったので、横棒に変えて全カテゴリを1行ずつ表示し、各棒に売上の値ラベルも付けました。プレビューに反映しています。
このように、Claude Code は cdm notebook render でチャートやページを画像に書き出し、仕上がりを確認しながら修正します。テーブル名やカラム名、SQLの記述に迷った場合も、cdm catalog や cdm doc で都度確認しながら進めるため、利用者は「どう見せたいか」を伝えることに専念できます。
チャートを追加する
1つのチャートで流れを掴んだら、ダッシュボードの素材となるチャートを増やしていきます。複数のチャートをまとめて依頼することもできます。
You: ダッシュボードの素材になるチャートを追加して。売上の月次推移の折れ線、主要KPI（総売上・注文数・平均注文単価）のビッグナンバー、国別売上の上位ランキング、曜日×時間帯の注文件数のヒートマップ。それぞれ画像で確認しながら整えて。
Claude: 4つのチャートを追加しました。それぞれ画像に書き出して確認しています。ヒートマップは曜日の並び順が崩れないよう、ラベルに曜日番号を付けて整列させました。KPIは桁を圧縮して読みやすくしています。プレビューに反映済みです。
チャートの種類ごとに必要なSQLの加工やチャート設定は異なりますが、Claude Code が cdm doc で仕様を確認しながら組み立てます。追加したチャートは、その都度 cdm notebook run で実行され、プレビューに反映されます。
この間、cdm notebook preview は起動したままです。Claude Code がSQLを実行したりチャートを修正したりするたびに、その結果がブラウザのプレビューへ自動的に反映されます。利用者は、Claude Code に指示を出しながら、同じプレビューを自分の目で確認できます。
パラメータとグリッドページで仕上げる
チャートが揃ったら、ダッシュボードとして仕上げます。期間で絞り込むパラメータの追加や、チャートを並べたグリッドページの作成も、まとめて対話で依頼できます。
You: 期間で絞り込めるように日付範囲のパラメータを追加して、各チャートに効かせて。そのうえで、これまでのチャートをグリッドページにダッシュボードとしてレイアウトして。
Claude: 日付範囲のパラメータ（初期値は直近12ヶ月）を追加し、各SQLに期間フィルタを適用しました。グリッドページでは、上部にKPI、その下に売上推移、さらにカテゴリ別・国別・ヒートマップを配置しています。プレビューで確認してみてください。
パラメータ は、ダッシュボード上部に入力フォームを表示し、SQLブロックから参照することで動的な絞り込みを実現します。グリッドページ は、ドキュメントページで定義したチャートをダッシュボードとしてレイアウトするためのページです。いずれも仕様は細かいですが、Claude Code が cdm doc で仕様を確認しながら組み立てるため、利用者はレイアウトの方針を伝えるだけで構いません。
サーバに反映する
仕上がったら、サーバに反映します。反映が完了すれば、作成したダッシュボードを Codatum 上でチームに共有できます。
You: サーバに反映して。
Claude: サーバへの反映が完了しました。Codatum 上でダッシュボードを確認できます。
Claude Code は cdm notebook push でローカルの変更をサーバに反映します。反映は取り消しできない操作のため、実行前に確認を求めます。
次のステップ
- 繰り返しの作業をテンプレート化して効率化する → 定型作業をテンプレート化
- ノートブックファイルをGithubで管理して履歴を残したい → GitHubで管理
サンプル一式は codatum-cli-examples リポジトリ を参照してください。