kSQL Dashboard は、kintone のレコード一覧画面に kSQL（read-only な SQL ライク構文）で取得したデータを、表・グラフのダッシュボードとして表示するプラグインです。集計クエリを書くだけで、一覧の上部に「今の数字」を並べられます。
📌 本記事の位置づけ
kSQL 本体（アプリを SQL ライクに操作するプラグイン）については別記事を参照してください。本記事はその エンジンを使った可視化プラグイン の紹介です。
🔥 主な特徴
- 📊 SQL を書くだけで即可視化: 1〜4 分割のレイアウトに対応し、表や棒グラフ（縦・横）を描画
- 🔒 外部依存なし＆CSP 安全: チャートライブラリ不使用・完全自前描画で安心
- 👁️ 実データで即座にプレビュー: アプリ更新を待たずに設定画面上で見た目とデータを確認可能
- ⚙️ 柔軟な出し分け: 「共通設定」と「一覧ごとの個別設定」に対応
概要
- レコード一覧画面のヘッダースペースに、1〜4 分割のダッシュボードを表示します。
- 各ペインに SQL 文と表示方法（表 / 棒グラフ） を設定します。
- 一覧（ビュー）ごとに別々のダッシュボードを出し分けできます（共通／個別）。
- データ取得は kSQL エンジン（read-only） を同梱。外部 CDN 不要（CSP 安全）で、グラフも依存なしの自前描画です。
- 値はすべて文字列で返るため、数値は3桁区切り＋右詰めで見やすく整形します。
GitHub: https://github.com/rex0220/ksql-dashboard
（kSQL エンジン本体: https://github.com/rex0220/kintone-sql-tools ）
ライセンス: MIT
インストール
配布 zip から導入（かんたん）
ビルド済みの zip をリポジトリの dist/ に同梱しています（例: dist/ksql-dashboard-v1.0.0.zip）。この zip を使えば、ビルドなしで導入できます。
-
リポジトリの
dist/からksql-dashboard-v<version>.zipをダウンロード。 - kintone の システム設定 → その他 → プラグイン → 読み込む から zip をアップロード。
- 対象アプリの設定 → プラグイン でこのプラグインを追加。
- 「アプリを更新」 して反映。
ソースからビルド（開発者向け）
kintone 標準 CLI（cli-kintone）でパッケージ化・アップロードもできます。
npm run package # dist/ksql-dashboard-v<version>.zip を生成（version は manifest から）
npm run package:upload # 生成＋kintone へアップロード（.env の認証情報を使用）
npm run upload # 生成済みの zip をアップロードのみ（再ビルドしない）
npm run uploadはソースを再パッケージ化しません。変更したソースを反映するときはnpm run package:uploadを使います。
署名の秘密鍵は
keys/ksql-dashboard.ppkに保管します（同じ鍵を使い続けるため plugin ID は固定。鍵はリポジトリ外へバックアップ推奨）。
注意（plugin ID）: 秘密鍵
keys/*.ppkはリポジトリに含めていません（コミット禁止）。そのため手元でソースからビルドすると、新しい鍵が生成され、配布 zip とは別の plugin ID になります。配布版とは別プラグイン扱いになり、配布版の「更新」にはなりません（自分用の検証には問題ありません）。配布版と同じ ID で更新したい場合は、配布元の.ppkを入手してkeys/ksql-dashboard.ppkに置いてからnpm run packageしてください。
JS/CSS を変更したのに反映されないときは、まず 「アプリを更新」漏れを疑ってください。ブラウザは Ctrl+F5 で再読込します。
プラグイン設定
設定画面の上部（固定表示）で、対象の一覧と全体の操作を行います。
- 対象の一覧（ビュー）: ダッシュボードを設定する一覧を選びます。「すべての一覧（共通）」と、各カスタマイズ一覧・標準の「(すべて)」一覧が選べます。
- この一覧でダッシュボードを表示する: その一覧で表示するかどうか（既定はオフ）。
- 表示するダッシュボード: 「共通」か「個別（この一覧専用）」を選びます。
- 保存 / キャンセル / 運用環境に反映: 「運用環境に反映」をオンにして保存すると、保存後にアプリ更新まで自動実行されます。
- 未保存ガード: 編集すると保存ボタンの横に 「未保存の変更があります」 バッジが表示されます。未保存のままキャンセルすると破棄確認のダイアログが出るので、うっかり編集内容を失う心配がありません。
共通ダッシュボードと個別ダッシュボード
- 共通（すべての一覧）: 個別設定の無い一覧に共通で表示されます。まずここに主要な集計を置くのがおすすめです。
- 個別: 特定の一覧だけ別のダッシュボードを出したいときに使います。
- オフ: その一覧では何も表示しません（共通にも継承しません）。
- 共通の継承範囲は「設定を保存した時点で存在した一覧」です。設定後に追加した一覧には自動では表示されません（表示したくなったら設定を開いて保存し直します）。
画面分割とペイン
画面分割数でレイアウトを選びます。
| 分割 | レイアウト |
|---|---|
| 1 | 単一 |
| 2 | 横2 |
| 3（上2・下1） | 上段2枚・下段1枚 |
| 3（上1・下2） | 上段1枚・下段2枚 |
| 4 | 2×2 |
- 自動更新（分）: 一覧画面で一定間隔ごとにダッシュボードを再取得します（最短10分・10分単位。0で無効）。掲示・モニタ用途に便利です。
分割数に応じてペイン一覧が並びます。ペインはタブで切り替えて 1 つずつ編集します（タブには番号＋タイトルを表示）。各ペインの編集エリアは左に SQL、右に表示設定の 2 カラムです。
各ペインで次を設定します。
- ペイン名（タブに表示されます）
- SQL（下記参照）と 検証 ボタン。SQL 欄は 8 行・縦横リサイズ可（横は列内まで）
- 表示方法: 表 / グラフ（棒）
- グラフの向き（表示方法の横）: グラフ選択時のみ表示。縦棒 / 横棒を選択
- グラフ時: ラベル列、値列
-
取得件数: そのペインの結果取得数の上限（未指定なら 500・10単位）。増やすほど取得量と API 負荷が増えるため、必要な場合だけ調整します。kintone 側の検索打ち切り（
SEARCH_ABORTED）はこの値を増やしても解消しません。
SQL の書き方（ペインの SQL）
kSQL の read-only な SQL（SELECT / WITH / UNION / SHOW APPS / DESCRIBE）が使えます。ダッシュボードでは集計クエリが中心です。単文だけでなく、; 区切りの複数文（バッチ） も1ペインに書けます。
- 対象アプリは
APPxxx（xxx はアプリ ID）で指定します。 - 値はすべて文字列で返ります。数値の列は自動で3桁区切り・右詰め表示になります。
-
複数文（バッチ）:
CREATE TEMP TABLE/SET/DECLAREなどを組み合わせて、一時テーブルの構築 → 集計 → 表示までを1ペインで完結できます。表示されるのは最後に行を返す文（＝最終SELECT）の結果です。
-- 例: 全体比（構成比）をバッチで計算して表示
CREATE TEMP TABLE #g AS SELECT 担当, SUM(売上) AS 売上 FROM APP100 GROUP BY 担当;
SET @total = (SELECT SUM(売上) FROM #g);
SELECT 担当, 売上, ROUND(売上 * 100 / @total, 1) AS 構成比 FROM #g ORDER BY 売上 DESC
検証ボタンで、保存前に構文チェックできます（SELECT/WITH/UNION・複数文は EXPLAIN、SHOW/DESCRIBE は軽い実行で確認）。
使える関数（
SUBSTR/COUNT/SUMなど）や標準 SQL との違い・制限事項は、kSQL 本体のリポジトリを参照してください。kintone の日時は ISO8601 形式の文字列で返るため、SUBSTR(更新日時, 1, 7)のような切り出しで年月キーを作れます。
コピペ用クエリ集
いずれも APP100 を対象アプリの ID に置き換えてください。
担当ごとの件数（棒グラフ向き）
SELECT 担当, COUNT(*) AS 件数
FROM APP100
GROUP BY 担当
ORDER BY 件数 DESC
- 表示方法=グラフ（棒）、ラベル列=
担当、値列=件数
区分ごとの金額合計
SELECT 区分, SUM(金額) AS 合計金額
FROM APP100
GROUP BY 区分
月次の件数（更新日時ベース）
SELECT SUBSTR(更新日時, 1, 7) AS 年月, COUNT(*) AS 件数
FROM APP100
GROUP BY 年月
ORDER BY 年月
ステータス別の一覧（表向き）
SELECT ステータス, 顧客名, 金額
FROM APP100
WHERE ステータス IN ('対応中', '確認待ち')
ORDER BY 金額 DESC
グラフ（縦棒・横棒）
表示方法を「グラフ（棒）」にすると、向き（縦棒 / 横棒） を選べます。ラベル列・値列を指定するだけで、依存ライブラリなしの棒グラフを描画します（CSP 安全）。
値列には 0 以上の数値を返す列を指定してください。数値と解釈できない値は 0 として扱われ、負数の描画には対応していません。
プレビュー機能
設定画面の上部にある 「プレビュー」 ボタン（目のアイコン）から、編集中のダッシュボードを実際のアプリのデータで表示して確認できます。保存やアプリ更新をしなくても、その場で見た目とデータをチェックできるので、SQL やレイアウトの試行錯誤がとても速くなります。
使い方
- ペインの SQL・表示方法・分割数を編集します（保存しなくて OK）。
- 上部の 「プレビュー」 をクリックします。
- 画面いっぱいのモーダルに、実データのダッシュボードが表示されます。
ポイント
- 実データで実行します。設定画面でもエンジンが動くため、実際の一覧画面と同じ描画・同じ集計結果を確認できます。
- 画面いっぱいの横幅で表示するので、一覧画面での見え方に近い比率でレイアウト（2列・上2下1・上1下2・2×2）を確認できます。
-
SQL エラーは各ペインに表示されます（
[PARSE_ERROR]等）。どのペインの SQL が悪いか一目で分かります。 - 「再実行」 でデータを取り直せます。SQL を直したらもう一度実行して確認できます。
- 表示されるのは編集中のダッシュボード全体（分割数に応じた全ペイン）です。まだ保存していない変更もそのまま反映されます。
ツール機能
上部の 「ツール」 ボタン（歯車アイコン）を押すと、複写・入れ替え・バックアップをまとめたダイアログが開きます。ふだんの設定画面からは操作ボタンを隠しているので、誤操作を防ぎつつ必要なときだけまとめて使えます。上書きを伴う操作はボタンを注意色にしています。
ペインの複写・入れ替え
同じダッシュボード内で、ペインの設定（タイトル・SQL・表示方法・グラフ設定）をまるごと動かせます。似たペインを作るときに便利です。
- 複写（元→対象）: 「元ペイン」の設定を「対象ペイン」へ上書きコピーします。
- 入れ替え: 「元ペイン」と「対象ペイン」の設定を交換します。
ペインが1つ（1分割）のときは対象が無いため使えません。
一覧の設定を複写・入れ替え
今編集している一覧のダッシュボード設定を、別の一覧へまるごとコピーしたり、2つの一覧の設定を相互に交換したりできます。「A 一覧で作った構成を B 一覧にも」というときに、作り直さずに済みます。
- 元になる一覧を選んで内容を整えます。
- ツールを開き、「対象の一覧」 を選んで 「複写」 または 「入れ替え」 を押します。
- 複写: 対象の一覧は「個別（この一覧専用）」として設定されます（対象の既存設定は上書きされます）。
- 入れ替え: 今の一覧と対象の一覧の設定を交換します。実行後の内容がそのままエディタに表示されるので、続けて確認・調整できます。共通（すべての一覧）との入れ替えも可能です。
設定のダウンロード / アップロード
ダッシュボード設定全体を JSON ファイルとして書き出し／読み込みできます。バックアップや、別アプリ・別環境への移植に使えます。
-
ダウンロード: 現在の設定を
ksql-dashboard-app<アプリID>-<日時>.jsonとして保存します。日時・プラグイン名・アプリ ID などのメタ情報付きです。 - アップロード（読込）: 選んだ JSON で現在の設定を置き換えます。読み込んだだけでは保存されないので、内容を確認してから「保存」 してください。
アップロードは現在の設定を上書きします。必要なら先にダウンロードでバックアップを取っておくと安心です。
その他の表示上の工夫
- 数値の整形: 値はすべて文字列で返りますが、数値の形式に一致するセルは3桁区切り＋右詰めで表示します（文字列のまま整形するため、大きな ID でも桁あふれしません）。フィールド型ではなくセル単位の判定のため、数字だけの文字列コードも整形対象になります。
- ゼブラ表示: 表は行ごとに背景色を変え、ホバーで強調して見やすくしています。
実行の仕組みと権限
- ダッシュボードは一覧表示イベント（
app.record.index.show）でヘッダースペースに描画されます。SQL は同梱の kSQL エンジンの read-only クライアントで実行され、更新系 SQL は構文段階で拒否されます（クライアント側でも更新 API は使えません）。 - データ取得にはログインユーザーの kintone 権限が適用されます。
APPxxxで別アプリを参照する場合は、そのアプリ・レコード・フィールドへの閲覧権限が必要です（権限の無いユーザーにはそのデータは表示されません）。
よくあるエラーと対処
| 症状 | 原因・対処 |
|---|---|
[PARSE_ERROR] |
SQL の構文エラー。検証ボタンで場所を確認します。 |
[READ_ONLY_VIOLATION] |
INSERT/UPDATE/VALIDATE など read-only 外の文。参照系（SELECT 等）に直します。 |
[SEARCH_ABORTED] |
kintone 側で検索が打ち切られました。WHERE で対象を絞るか、クエリを見直します（部分表示はしません。取得件数を増やしても解消しません）。 |
[FETCH_LIMIT_EXCEEDED] |
結果がペインの取得件数の上限を超えました。結果を絞るか、必要に応じて取得件数を増やします。 |
APPxxx が違う |
対象アプリ ID を確認します（SHOW APPS で一覧を確認可）。 |
| ダッシュボードが出ない | プラグインの有効化と 「アプリを更新」、対象一覧の表示設定を確認。設定画面のプレビューや、ブラウザ開発者ツールのコンソールでも切り分けできます。 |
| 設定変更が反映されない | パッケージ→アップロード→アプリを更新→ハードリロードの順で反映します。 |
使い始めのコツ
- まず 共通（すべての一覧） に、代表的な集計（件数・金額）を1〜2ペイン置く。
- プレビューで見た目とデータを確認する。
- 特定の一覧だけ変えたくなったら、その一覧を選んで個別に切り替える。
- 出したくない一覧はオフにする。
- 問題なければ 「運用環境に反映」 をオンにして保存。
まとめ
kSQL Dashboard を使うと、集計 SQL を書くだけでレコード一覧の上に「今の数字」を並べられます。一覧ごとの出し分け（共通／個別／オフ）、縦横グラフ、ペイン単位の取得件数、自動更新、プレビュー、設定のバックアップまで揃っているので、運用のダッシュボードづくりがぐっと楽になります。
まずは共通ダッシュボードに1ペイン置いて、プレビューで確認するところから始めてみてください。