「rex0220 kSQL アクションプラグイン」の事例です。やりたいことから探せる事例集の 1 件です。
この記事は、ひとつの業務を、画面・設定・SQL・AI への頼み方まで通して見せます。設定の要点・SQL の全文・AI への頼み方は畳んであります（開くと読めます）。機能ごとの説明は、末尾の「関連記事」にある概要と ①〜⑫ の記事にまとめてあります。
やりたいこと
受注を年ごと・顧客ごとにまとめて、件数と売上を別のアプリ（年別顧客別集計）に入れておきたい。顧客ごとの年の推移を、一覧やグラフで見るためです。
事例: 全顧客の集計を作り直すは、押すたびに受注を全件読み直す形でした。受注が少ないうちはそれで足りますが、何年分も溜まると、毎回全部を読み直すのは無理があります。この事例では、年で分けて作り直します。
なぜ年で分けるのか
1. 1 回に読める件数には上限があります。 共通設定の「読み取りの上限」は既定で 10,000 件です（100,000 件まで上げられます）。全期間を毎回読む形は、受注が増えるほど読む件数が増え、いつか上限に当たります。
この例（受注 10,442 件）で、比べるために全期間を 1 回で読む形も置いて押したところ、読み取りの上限で止まりました。途中までの件数で集計することはせず、集計アプリには何も書いていません（画面にも「書き込みはしていません」と出ます）。
2. 上限を上げても、重さは受注の総数に比例して増え続けます。 読む件数も、かかる時間も、kintone に問い合わせる回数（500 件ごとに 1 回）も、全期間を読む限り毎年増えます。
3. 過去の年は、ほとんど変わりません。 動くのは今年の受注（と、締めが終わるまでの前年）です。年で分けた集計なら、作り直すのもその年だけで足ります。
4. 何年分も作り直すときは、ループで年ごとに分けます。 読み取りの上限は 1 回ごとに数え直されるので、各年の受注が上限に収まっていれば、全期間の合計が上限を超えていても作り直せます。ただし、ループで全期間を作り直しても、受注を読む件数の合計は 1 回で読む場合と変わりません（分けて読むだけです）。読む量そのものが減るのは、ふだんの「今年だけ」のほうです。
| 全期間を 1 回で | 年ごとに（ループ 5 回） | 今年だけ | |
|---|---|---|---|
| 1 回に読む受注 | 10,442 件（上限を超える） | 約 2,100 件 × 5 回 | 1,890 件 |
| 結果 | 最初の文で止まった | 5 回・11 秒・書き込み 125 件 | 1 秒・更新 25 件 |
画面と結果
使うアクションは 2 つです（比べるために置いた 3 つ目は、ふだんは置きません）。
| アクション | いつ使うか | 読む範囲 |
|---|---|---|
| 全期間を年ごとに作り直す | 始めるとき・データを入れ直したあと | 2022 年から今年まで、1 年ずつ |
| 年を選んで作り直す | ふだん（月末など） | 選んだ 1 年（今年か前年） |
始めるときは、一覧のパネルの［全期間を年ごとに作り直す］を押します。「5 回に分けて実行します」の確認が実行の前に 1 回だけ出て、実行中は「1 / 5 回 …」と進みます（［中止］を押すと回の切れ目で止まります）。
集計アプリに 125 行（25 社 × 5 年）ができました。年ごとの件数の合計は、受注の件数と一致します（2022 年 2,126 件・2023 年 2,139 件・2024 年 2,150 件・2025 年 2,140 件・2026 年 1,887 件）。
ふだんは、［年を選んで作り直す］で年を選んで実行します。候補は今年と前年です。試しに、うみかぜ物産（K03）の今年の受注を 3 件足してから、2026 年を作り直しました。
| うみかぜ物産（K03） | 件数 | 売上 | 集計日時 |
|---|---|---|---|
| 2022 年 | 93 件 | 14,894,000 円 | 6:30（全期間を作り直したとき） |
| 2023 年 | 80 件 | 13,274,000 円 | 6:30 |
| 2024 年 | 90 件 | 12,580,000 円 | 6:30 |
| 2025 年 | 83 件 | 12,797,000 円 | 6:30 |
| 2026 年 | 69 件（66 件から 3 件増） | 11,438,000 円 | 6:31（今年だけ作り直したとき） |
- 書き直したのは 2026 年の 25 行だけです。2022〜2025 年の行は読みも書きもしていません（集計日時がそのまま）。
- 2026 年の件数の合計（1,890 件）は、受注の 2026 年の件数と一致します。
自分のアプリで使うとき
SQL の中では、アプリを番号ではなく名前で書いています（LAPP_受注 のような名前。設定の「論理アプリ」で、名前とアプリ番号を結び付けます）。そのため、アプリ番号は論理アプリの表を直すだけで差し替えられます。
ただし、項目は合わせる必要があります。下の「使うアプリと項目」の表にある項目コード・種類・「値の重複を禁止する」の設定が違うと、そのままでは動きません。違うところは、表の下の「変えるところ」を見て SQL を直してください。
使うアプリと項目
受注（年別）（ボタンを置くアプリ。論理アプリ「受注」）
| 項目名 | 項目コード | 種類 | メモ |
|---|---|---|---|
| 顧客コード | 顧客コード | 文字列（1行） | 必須 |
| 顧客名 | 顧客名 | 文字列（1行） | 同じ顧客コードなら同じ名前、を前提にしている |
| 受注日 | 受注日 | 日付 | 必須 |
| 金額 | 金額 | 数値 | |
| 年 | 年 | 文字列（1行）・自動計算 | 式は DATE_FORMAT(受注日, "YYYY", "Asia/Tokyo")。年で絞るための項目
|
「年」の項目を足しておくと、SQL で
WHERE 年 = @yearと書くだけで、その年の受注だけを kintone の絞り込みで読めます（実行計画で、絞り込みがそのまま kintone に渡ることを確かめました）。受注日の範囲（1 月 1 日〜12 月 31 日）で絞る書き方もできますが、年から日付を 2 つ作る式が要ります。年の項目にしておけば、パラメーターは 1 つで済み、受注の一覧やグラフでも年で絞れます。
年別顧客別集計（論理アプリ「年別集計」）
| 項目名 | 項目コード | 種類 | メモ |
|---|---|---|---|
| 集計キー | 集計キー | 文字列（1行） |
値の重複を禁止する。「年-顧客コード」（例 2026-K03） |
| 年 | 年 | 文字列（1行） | |
| 顧客コード | 顧客コード | 文字列（1行） | |
| 顧客名 | 顧客名 | 文字列（1行） | |
| 件数 | 件数 | 数値 | |
| 売上 | 売上 | 数値 | |
| 集計日時 | 集計日時 | 日時 | 作り直した時刻を入れる |
変えるところ
- 論理アプリの表（「受注」「年別集計」）を、自分のアプリに向ける
- 始まりの年（2022）は、ループの式
DATE_FORMAT("TODAY", "YYYY") - 2021とパラメーターの式2022 + $valの 2 か所で直す（回数は今年まで自動で数えるので、来年は 6 回になる） - 1 年でも多すぎるなら、年の代わりに年月の項目（
DATE_FORMAT(受注日, "YYYY-MM", "Asia/Tokyo")）を作り、月で分ける（集計キーも「年月-顧客コード」に） - 年度（4 月始まりなど）で分けるなら、「年」を年度を計算する項目に置き換える
- 書き込みの上限は、年を選ぶほうが「顧客の数」、全期間のほうが「顧客の数 × 年の数」に、消える見込みの行の 2 倍を足して決める（この例は 100 件と 300 件）
気をつけること
- 年で分けても、1 年分が読み取りの上限を超えると止まります。 そのときは月で分けるか（上の「変えるところ」）、上限を上げてください。
- 受注日を別の年に直したときは、両方の年が変わります。 2025 年 12 月の受注を 2026 年 1 月に直すと、2025 年の集計からは減り、2026 年には増えます。［年を選んで作り直す］は 1 年しか作り直さないので、2 つの年を順に作り直すか、［全期間を年ごとに作り直す］を押してください。
- 年を選ぶ候補は今年と前年だけです。 それより前の年を直したときは、［全期間を年ごとに作り直す］を押します（候補の式を変えて、選べる年を増やすこともできます）。
- 途中で止まったときは、それまでの年（回）で書いた分が残ります。 元の受注が同じなら、押し直しても件数と売上は同じになります（集計日時は押した時刻に変わります）。原因を取り除いてから押し直してください。ループは「回が失敗したら停止」にしているので、止まった年より後の年は流れません。
-
対象の年に限るのは、受注の読み取り・今の集計の読み取り（0 の行）・消す文の 3 か所です。 書き込み（
UPSERT）は、その年だけをまとめた一時テーブルから書くので、ほかの年の行には触れません。ループで分けるときは、こうして回どうしが重ならない形にします（⑧ 請求データ編の「ループ値は必ず WHERE に入れる」）。 - 設定を反映した直後は、開いていた画面を読み直してから押します。 この例でも、反映した直後はパネルが出ず、強制再読み込みで出ました。
- ログアプリを設定していないので、2 人が同時に押すと止められません。押す人を決めておくか、ログアプリを設定してください（④ 運用編）。
設定の要点
| 設定 | 年を選んで作り直す | 全期間を年ごとに作り直す |
|---|---|---|
| 種類 | アプリ（レコードを選ばずに動く） | アプリ |
| 出し方 | 一覧のパネル（区分なし） | 一覧のパネル（区分なし） |
| 論理アプリ | 受注 = ボタンを置くアプリ、年別集計 = 集計のアプリ | 同じ |
| パラメーター |
year（実行時に聞く） |
year（計算式 2022 + $val。$val はループの回の値 0〜4） |
| 入力項目 | 作り直す年（選択・必須）。候補は計算式 ARRAY(DATE_FORMAT("TODAY", "YYYY"), DATE_ADD("TODAY", -1, "year", "YYYY"))（今年と前年） |
なし |
| ループ | なし |
DATE_FORMAT("TODAY", "YYYY") - 2021（2026 年なら 5 回）。回が失敗したら停止 |
| 確認 | オン | オン（実行の前に 1 回だけ） |
| 書き込みの上限 | 100 件 | 300 件（ループでは必須） |
2 つのアクションの SQL は同じです。違うのは、@year に入る値を「人が選ぶ」か「ループが 2022 年から順に入れる」かだけです。
SQL の全文
-- @ksql dialect: 1
DECLARE @year = '';
-- 1) 集める。その年の受注だけを顧客別にまとめ、その年の今の集計を「0 の行」として足す
CREATE TEMP TABLE #raw AS
SELECT 顧客コード, MAX(顧客名) AS 顧客名, COUNT(*) AS 件数, SUM(金額) AS 売上
FROM LAPP_受注 WHERE 年 = @year
GROUP BY 顧客コード
UNION ALL
SELECT 顧客コード, 顧客名, 0 AS 件数, 0 AS 売上
FROM LAPP_年別集計 WHERE 年 = @year;
-- 2) まとめる（kintone には行かない）
CREATE TEMP TABLE #agg AS
SELECT 顧客コード, MAX(顧客名) AS 顧客名, SUM(件数) AS 件数, SUM(売上) AS 売上
FROM #raw GROUP BY 顧客コード;
-- 3) 書き込む。キーは「年-顧客コード」
UPSERT INTO LAPP_年別集計 (集計キー, 年, 顧客コード, 顧客名, 件数, 売上, 集計日時)
SELECT CONCAT(@year, '-', 顧客コード) AS 集計キー, @year AS 年, 顧客コード, 顧客名, 件数, 売上, @NOW() AS 集計日時
FROM #agg
ON DUPLICATE (集計キー);
-- 4) その年に受注が無くなった顧客の行を消す（消すのは集計のあと）
DELETE FROM LAPP_年別集計 WHERE 年 = @year AND 件数 = 0;
読むときのポイントです。
-
WHERE 年 = @yearが 3 か所にあります（受注を読むところ、今の集計を 0 の行として足すところ、消すところ）。どれか 1 つでも抜けると、その文だけ全期間に当たり、年で分けた意味が薄れます。3) のUPSERTにはWHEREがありませんが、書く元が「その年だけをまとめた一時テーブル」なので、書くのはその年の行だけです。 - 「0 の行」を足すのは、事例: 全顧客の集計を作り直すと同じ形です。 その年に受注が無くなった顧客も 0 件として結果に出て、3) で 0 に書き直され、4) で消えます。
-
MAX(顧客名)は、顧客コードごとに顧客名を 1 つにまとめるための書き方です。同じ顧客コードなら顧客名も同じ、を前提にしています。MAXは文字の並びで大きいほうを残すだけで、新しい名前を選ぶものではありません（受注の名前と、今の集計に残っている名前の両方から選ぶので、社名を変えても古い名前が残ることがあります）。名前が変わる運用なら、顧客マスターから名前を引くなど、名前を決める元を別に用意してください。 -
集計キーは
CONCAT(@year, '-', 顧客コード)で、SELECTの列で作ります。WHEREには関数を書かず、項目と値の比較（年 = @year）だけにしています（書き込みの文のWHEREに関数を書くと、実行時に止まります。⑧ 請求データ編）。 -
@NOW()は押した時刻です。ループでは回ごとではなく、起動 1 回で同じ値になります（この例では 5 年分とも 6:30）。
比べるために置いた「全期間を一度に作り直す」は、この SQL から WHERE 年 = @year を外し、年 を GROUP BY と集計キーに足した形です（CONCAT(年, '-', 顧客コード)）。受注を全件読もうとして、最初の文で読み取りの上限に当たって止まりました。
AI への頼み方
この事例は、AI（Claude Code）に kSQL アクションのオーサリングツール（kact）を使わせて作りました。渡した依頼の文です。
追加された事例は、全レコードを対象にしているが、毎回何年か分の全レコードを集計するのは無理がある。
年別顧客別のような事例を理由とともに追加して。
顧客別に数百件程度のレコードを用意
AI が自分で決めたこと
- 受注アプリに、受注日から年を作る自動計算の項目「年」を足して、
WHERE 年 = @yearで絞る（WHEREに関数を書かずに年で分けるため） - アクションを 2 つにする（ふだんは今年か前年を選んで 1 年だけ、始めるときはループで全期間を年ごとに）
- 理由を見せるために、データを 25 社 × 約 420 件（計 10,442 件）にして、全期間が既定の読み取りの上限 10,000 件を超えるようにする。比べるために、全期間を 1 回で読む形も置いて押す
- 年の候補は今年と前年、ループの回数は今年まで自動で数える式にする（式は先に試してから入れた）
- 書き込みの上限は 100 件と 300 件（25 社 × 1 年、25 社 × 5 年に余裕を見た）
作った後に AI がしたこと
- 設定の検査（エラー 0、注意 0）と、文ごとの実行計画の確認。年の条件が読み取り・0 の行・消す文のどれでも kintone の絞り込みに渡っていること、比較用は全件を読むことを見た
- 設定画面への取り込み（この回は、Claude in Chrome で画面を操作させた）と、3 つの形の実行
- 結果の照合。125 行すべてが受注から計算した値と一致すること、今年だけ作り直したときに過去の年の行が変わらないこと
今回は、依頼の文に「理由とともに」とあったので、理由を説明するだけでなく、比べる形を実機で押して見せる段取りを AI が組みました。依頼の文に見せたいこと（理由・比較・数字）を書いておくと、記事や説明の材料までそろいます。
詳しい記事
- ループで年ごとに分ける・ループ値は
WHEREに入れる: ⑧ 請求データ編 - 10 年・9.4 万件を年ごとに集計する: ⑤ 事例編
- 月を選んで作り直す・部品表を下へたどる: 事例: 所要量を計算する
- 「0 の行」を足して集計する形: ③ 集計編
- 確認・書き込みの上限・ログアプリ: ④ 運用編
- 設定を AI に作ってもらう: ⑦ オーサリング編・⑫ オーサリング改善編
関連記事
機能ごとの記事: 概要 / ① 詳細画面 / ② 一覧 / ③ 集計 / ④ 運用 / ⑤ 事例 / ⑥ イベント / ⑦ オーサリング / ⑧ 請求データ / ⑨ 締めの画面 / ⑩ どこに出すか / ⑪ 多言語 / ⑫ オーサリング改善