rex0220 kSQL アクションプラグイン - 事例: ステータスごとの件数を集計する

「rex0220 kSQL アクションプラグイン」の事例です。やりたいことから探せる事例集の 1 件です。

この記事は、ひとつの業務を、画面・設定・SQL・AI への頼み方まで通して見せます。設定の要点・SQL の全文・AI への頼み方は畳んであります（開くと読めます）。機能ごとの説明は、末尾の「関連記事」にある概要と ①〜⑫ の記事にまとめてあります。

やりたいこと

受注のステータス（未処理・処理中・完了）ごとに、件数と金額の合計を別のアプリ（ステータス別集計）に出しておきたい。ステータスを変えたら、自動で数え直したい。

受注アプリのグラフでも数えられますが、別のアプリに数字として持っておくと、ほかのアプリやダッシュボードから参照したり、計算式で使ったりできます。

アクションは 2 つ使います。

アクション	起動	すること
ステータス別に集計	ステータスを変えたとき（自動）	変更前と変更後の 2 つのステータスだけを数え直す
ステータス別に全部数え直す	一覧のボタン	全部のステータスを数え直す（始めるときと、ずれたとき）

ふだんは 1 つ目が動き、変わったところだけを数え直します。ステータスを変える以外の操作（レコードの追加・削除など）では 1 つ目は動かないので、2 つ目のボタンで合わせます。

画面と結果

始めるときは、一覧のパネルの［ステータス別に全部数え直す］を 1 回押します。確認（書き込み先はステータス別集計、3 件）のあと、完了のメッセージが出ます。

この例では、集計アプリに「完了」の行が無かったので追加され、「未処理」「処理中」は書き直されました（追加 1 / 更新 2）。

ふだんは、レコードのステータスを進めるだけです。［完了する］を押すと次のステータスが出るので、［実行］を押します。

画面のステータスの名前がひらがな（しょりちゅう・かんりょう）なのは、試したアプリで、ステータスに日本語の「言語ごとの表示名」を付けているためです（⑪ 多言語編）。集計アプリには、表示名ではなく既定の名称（未処理・処理中・完了）で入ります。

ステータスが変わると、確認も完了のメッセージも出さずに、集計アプリの 2 行だけが書き直されます。金額 1,000 円の受注を 処理中 → 完了 にしたときの集計アプリです。

状態	全部数え直した後	処理中 → 完了 にした後
未処理	223 件 / 37,536,000 円	223 件 / 37,536,000 円（書き直さない）
処理中	1 件 / 1,000 円	0 件 / 0 円
完了	1 件 / 80,000 円	2 件 / 81,000 円

• 集計日時が変わるのは、変更前（処理中）と変更後（完了）の 2 行だけです。未処理は、全部数え直したときの時刻のままです。
• 0 件になった「処理中」も、行を消さずに 0 件で書き直します。
• 試したあと、［戻す］で 処理中 に戻すと、処理中 1 件 / 1,000 円、完了 1 件 / 80,000 円に戻りました。

自分のアプリで使うとき

SQL の中では、アプリを番号ではなく名前で書いています（LAPP_受注 のような名前。設定の「論理アプリ」で、名前とアプリ番号を結び付けます）。そのため、アプリ番号は論理アプリの表を直すだけで差し替えられます。

ただし、項目は合わせる必要があります。下の「使うアプリと項目」の表にある項目コード・種類・「値の重複を禁止する」の設定が違うと、そのままでは動きません。違うところは、表の下の「変えるところ」を見て SQL を直してください。

使うアプリと項目

受注（ボタンを置くアプリ。論理アプリ「受注」）

項目名	項目コード	種類	メモ
ステータス	ステータス	プロセス管理のステータス	未処理 → 処理中 → 完了（完了 → 処理中 に戻せる）
金額	金額	数値

ステータス別集計（論理アプリ「ステータス別集計」）

項目名	項目コード	種類	メモ
状態	状態	文字列（1行）	値の重複を禁止する（書き込むときの目印）
件数	件数	数値
金額合計	金額合計	数値
集計日時	集計日時	日時	書き直した時刻を入れる

「状態」をドロップダウンではなく文字列にしているのは、書き込むときの目印（UPSERT のキー）にドロップダウンは使えないためです。文字列なら、ステータスの名前（既定の名称）がそのまま入ります。

変えるところ

• 論理アプリの表（「受注」「ステータス別集計」）を、自分のアプリに向ける
• 金額の項目が違えば、SQL の「金額」を直す（件数だけでよければ、金額の列を外す）
• 書き込みの上限（どちらも 10 件）は、ステータスの数より多めにする
• 変更前の値を受け取れるのは、ステータス変更の起動だけです。ドロップダウンなど、ステータス以外の項目で数えるときは、この形（2 つだけ数え直す）は使えません。全部数え直す形を使います

気をつけること

• ステータスを変えたときしか、自動では数え直しません。 次のときは集計がずれるので、［ステータス別に全部数え直す］を押してください。
  • レコードを追加したとき（最初のステータスで入るだけで、ステータスの変更ではないため）
  • レコードを削除したとき
  • ステータスを変えずに、金額だけを直したとき
  • ファイルから読み込んだとき、API やほかのプラグインから書いたとき（画面の操作でないと動きません）
• 始めるときも、まず 1 回押します。 押すまでは、一度も変わっていないステータスの行がありません（この例の「完了」がそうでした）。
• ステータスを変えたときは、確認を出さずに書きます。 そのぶん書き込みの上限（10 件）を入れています。書くのは、変更前と変更後の 2 行だけです。
• 読むのは、変更前と変更後のステータスのレコードだけです（全件は読みません）。ただし、どちらかがレコードの多いステータスだと、そのぶん読みます（未処理 → 処理中 なら、未処理の 223 件も読みます）。
• 「完了」のように年々増え続けるステータスには限りがあります。 完了にするたびに完了の全件を読むので、何年も使うと読み取りの上限（既定 10,000 件）に当たります。［ステータス別に全部数え直す］も受注を全件読みます。件数が増えるアプリでは、年で分けて数える（集計キーを「年-状態」にする）など、1 回に読む件数を抑える形を考えてください（考え方は事例: 年別・顧客別に集計すると同じです）。
• 失敗しても、ステータスの変更は取り消されません。 集計だけが前のままになり、失敗は変更後の画面で知らせます。失敗はログアプリにも残ります（この起動の記録を「失敗だけ」にしているため）。原因を取り除いたら、［ステータス別に全部数え直す］で合わせます。
• 足し引きではなく、そのつど数え直します。 前の集計に 1 を足し引きする形ではないので、ずれが積み重なりにくい形です。ただし、何人かが同時にステータスを変えると、読む順と書く順によっては古い数が後から書かれることがあり、完全には防げません（ステータス変更の起動は、ボタンと違ってロックを取りません）。ずれたら［ステータス別に全部数え直す］で合わせます。
• 設定を反映した直後は、開いていた画面を読み直してから試します。 開いたままの画面は前の設定で動くので、1 回目のステータス変更で何も起きないことがあります。

設定の要点

設定	ステータス別に集計	ステータス別に全部数え直す
種類	レコード	アプリ（レコードを選ばずに動く）
起動	ステータス変更	一覧のパネル（区分「受注」）
論理アプリ	受注 = ボタンを置くアプリ、ステータス別集計 = 集計のアプリ	同じ
パラメーター	なし（SQL で @_status〈変更後〉と @_prev_status〈変更前〉を宣言するだけ。どちらも予約名で、値はプラグインが入れる）	なし
確認	なし（イベントは確認なしに決まっている）	オン
書き込みの上限	10 件	10 件
イベントの記録	失敗だけ	（ボタンは毎回ログアプリに記録）

2 つ目のボタンが @_status / @_prev_status を使わないのは、この 2 つがステータス変更のときにしか入らないためです。ボタンから押すと空になるので、回復用のボタンは全件を数える形にしています。

SQL の全文

ステータス別に集計（ステータス変更で動く）

-- @ksql dialect: 1
DECLARE @_status = '';
DECLARE @_prev_status = '';

-- 変更前と変更後のステータスだけ数え直す。
-- 0 件になった側も必ず 1 行書くため、0 の行を UNION ALL で足してから集計する
CREATE TEMP TABLE #t AS
SELECT @_prev_status AS 状態, 0 AS 件数, 0 AS 金額
UNION ALL
SELECT @_status AS 状態, 0 AS 件数, 0 AS 金額
UNION ALL
SELECT ステータス AS 状態, 1 AS 件数, 金額 AS 金額
  FROM LAPP_受注
 WHERE ステータス IN (@_status, @_prev_status);

UPSERT INTO LAPP_ステータス別集計 (状態, 件数, 金額合計, 集計日時)
SELECT 状態, SUM(件数) AS 件数, SUM(金額) AS 金額合計, @NOW() AS 集計日時
  FROM #t GROUP BY 状態
ON DUPLICATE (状態);

ステータス別に全部数え直す（一覧のボタン）

-- @ksql dialect: 1

-- 受注の全件をステータスごとに数え、今の集計の行を「0 の行」として足す
-- （レコードが無くなったステータスも 0 件で書き直すため）
CREATE TEMP TABLE #t AS
SELECT ステータス AS 状態, COUNT(*) AS 件数, SUM(金額) AS 金額
  FROM LAPP_受注
 GROUP BY ステータス
UNION ALL
SELECT 状態, 0 AS 件数, 0 AS 金額
  FROM LAPP_ステータス別集計;

UPSERT INTO LAPP_ステータス別集計 (状態, 件数, 金額合計, 集計日時)
SELECT 状態, SUM(件数) AS 件数, SUM(金額) AS 金額合計, @NOW() AS 集計日時
  FROM #t GROUP BY 状態
ON DUPLICATE (状態);

読むときのポイントです。

• @_status と @_prev_status は、ステータス変更の起動でプラグインが入れる、変更後と変更前のステータスです。言語ごとの表示名を付けていても、既定の名称で入ります。
• 0 の行を 2 つ足します。 変更前のステータスのレコードが 0 件になると、受注からは 1 行も返りません。0 の行を足しておくと、0 件として書き直されます。
• WHERE ステータス IN (@_status, @_prev_status) は kintone の絞り込みにそのまま渡るので、2 つのステータスのレコードだけを読みます。
• 全部数え直すほうは、全顧客の集計を作り直すと同じ形です（今の集計の行を 0 の行として足してから集計する）。ただし、0 件の行は消しません。 ステータスの種類は決まっているので、「処理中 0 件」も行として残すほうが見やすいためです。
• GROUP BY ステータス でまとめるときも、表示名ではなく既定の名称でまとまります（この例の「完了」の行は、表示名の「かんりょう」ではなく「完了」で入りました）。
• 受注は 1 行ずつ「件数 1」として並べてから足しています（1 つ目）。2 つ目は COUNT(*) で先にまとめています。どちらも結果は同じです。

AI への頼み方

この設定は、AI（Claude Code）に kSQL アクションのオーサリングツール（kact）を使わせて、2 回に分けて作りました。

1 回目（ステータス変更で数え直す）の依頼の文です。

別アプリとしてステータス（文字列ユニーク）を作成して、イベント処理でステータス別に集計する処理を組み込んで

AI がしたこと:

• 集計のアプリ（状態・件数・金額合計・集計日時）を作り、受注アプリの設定に論理アプリとアクションを足した
• 「状態」を、依頼のとおり文字列（値の重複を禁止する）にした。ドロップダウンは、書き込むときの目印に使えないため
• 実機でステータスを 2 回変えて、変更前と変更後の両方が 1 回で数え直されることと、0 件になった側も行が書かれることを確かめた

実機で分かったこと:

• 集計日時を最初は文字列の項目で作っていて、日時の項目に直した
• 設定を反映した直後、開いていた画面では 1 回目のステータス変更で何も起きなかった（画面を読み直すと動いた）

2 回目（全部数え直すボタン）は、この事例集を書くときに AI が気づいたことから足しました。

• AI が、集計アプリに「完了」の行が無いこと（一度も変わっていないステータスは載らない）と、レコードの追加・削除では数え直されないことを見つけて、全部数え直すボタンを足す案を出した
• 案に沿って、アプリの種類のアクションを 1 つ足し（今の設定に足して全置換）、検査・実行計画・設定画面への取り込み・実機での照合までした

1 回目の依頼は「ステータスが変わったら数え直す」だけで、始めるときや、ステータスの変更以外でずれたときのことは入っていませんでした。イベントで動く集計を頼むときは、「ずれたときに合わせ直すボタンも」と一緒に頼んでおくと、1 回で済みます。

詳しい記事

• ステータス変更で動かす・回復用のボタン: ⑥ イベント編
• 言語ごとの表示名と既定の名称: ⑪ 多言語編
• 「0 の行」を足して集計する形: ③ 集計編
• イベントがロックを取らないこと・ログアプリ: ④ 運用編

関連記事

• rex0220 kSQL アクションプラグイン（概要）
• 事例集（やりたいことから探す）

機能ごとの記事: 概要 / ① 詳細画面 / ② 一覧 / ③ 集計 / ④ 運用 / ⑤ 事例 / ⑥ イベント / ⑦ オーサリング / ⑧ 請求データ / ⑨ 締めの画面 / ⑩ どこに出すか / ⑪ 多言語 / ⑫ オーサリング改善