rex0220 kSQL アクションプラグイン

Last updated at 2026-11-08Posted at 2026-11-01

kintone のレコード画面・一覧画面に、「請求を作成する」「売上を集計する」「関連アプリを更新する」といった業務のボタンを追加するプラグインです。ボタンを押すと、あらかじめ設定した kSQL（SQL ライク構文）が実行され、複数アプリのレコードを集計・追加・更新できます。

SQL と計算式を書くのはアプリの管理者です（プラグイン設定に登録します）。利用者が SQL を書く必要はありません — 利用者はボタンを押すだけです。レコード保存後・ステータス変更後の自動実行や、一覧で選択したレコードの一括処理にも対応します。

ジョブ管理やネットワークのアプリは使いません。 SQL と計算式はこのアプリのプラグイン設定の中に置き、実行も利用者のブラウザーの中で完結します。用意するアプリは、実行の記録と二重実行の防止が要るときにログアプリを 1 つだけです（任意。テンプレートから作れます）。個別の JavaScript カスタマイズを作らずに、業務のボタンを設定で組めます（SQL を使うローコードです）。

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

主な機能

ボタンで kSQL を実行: 詳細画面のボタン、一覧のメニュー、一覧ヘッダー部のアクションパネルから、設定したアクションを起動します
レコード保存のイベントで実行: レコードの追加・編集の保存後、ステータス変更後に、自動で kSQL を実行できます（関連レコード集計と同じ方式）
一覧で選択したレコードの一括処理: 選択の渡し方を 1 件ずつ / まとめて 1 回 / グループごとから選べます
実行時の入力: 金額や期間などを型つきのダイアログで聞き、SQL のパラメーターとして渡します（SQL の文字列へ直接連結しない方式です）
計算式で制御: ボタンの表示条件、実行条件、パラメーターの値、結果メッセージを計算式プラグインと同じ式で書けます
確認と上限: 書き込みの前に件数を確認するか、確認なし + 書き込み上限で運用するかをアクションごとに選べます
任意のログアプリ: 指定すると実行の記録と、別ユーザーとの二重実行の防止（ロック）ができます

使い方の例

受注の詳細画面の「請求を作成する」ボタンで、請求アプリへレコードを追加する
月次集計ボタンで、入力した対象月の受注を集計アプリへまとめて反映する
一覧で選択した受注を 1 件ずつ「処理済」へ更新する
レコードの保存後に、関連アプリの集計値を自動で更新する
ステータスが「承認済み」に変わったら、履歴アプリへ記録を追加する

※ Ver.1（2026/XX）

初版

やりたいことから読む

実践編は 11 本ありますが、順番に全部読む必要はありません。近いものを 1 本選んでください。

やりたいこと	読む記事	書く SQL
ボタンを 1 つ置いて、まず動かしたい	① 詳細画面編	短いものを 1 本
一覧で選んだレコードをまとめて処理したい	② 一覧編	短いものを 1 本
顧客別・月別に集計して別アプリへ書きたい	③ 集計編	集計の SQL
保存やステータス変更で自動で動かしたい	⑥ イベント編	集計の SQL
SQL を書かずに、AI に設定を作らせたい	⑦ オーサリング編	書かない
失敗・二重実行・権限が心配	④ 運用編	設定だけ
月次の請求を何度でも作り直したい	⑧ 請求データ編	複数アプリの SQL
締めの押し忘れに気づける画面がほしい	⑨ 締めの画面編	設定だけ
10 万件の規模でも動くのか知りたい	⑤ 事例編	集計の SQL
ボタンが増えてきて、どこに出すか迷う	⑩ どこに出すか	設定だけ
日本語以外の言語で使う人がいる	⑪ 多言語編	設定だけ
自分の業務に近い例から探したい	事例集（事例ごとに 1 本）	事例ごとに全文

現場の利用者は、どれも読まなくて構いません。 SQL を書くのはアプリの管理者で、ふだん使う人はボタンを押すだけです。管理者も、⑦ のように AI に作らせて実行計画で確かめる進め方があります。

概要 — kSQL と計算式の役割分担

このプラグインでは、2 つのエンジンを役割分担して使います。

担当	エンジン	内容
アプリの読み書き	kSQL	他アプリ・自アプリのレコードの集計・追加・更新・削除。書き込みはすべて kSQL の文で行います
条件と値	計算式	ボタンの表示条件、実行条件、パラメーターの値、結果メッセージ。読み取り専用（計算式がレコードを書き換えることはありません）

SQL と計算式を書けるのはアプリの管理者だけ（プラグイン設定）です。現場の利用者は、固定されたアクションをボタンで押すだけで使えます。

アクションの種類と起動

アクションの種類は「レコード」と「アプリ」の 2 つです。レコードには「一覧でも使う」を足せるので、起動する場所は次の 3 通りになります。

種類	文脈	起動	例
レコード	表示中のレコード（`@_record`）	詳細画面のボタン、保存後・ステータス変更のイベント	請求を作成する
レコード＋「一覧でも使う」	選択した各レコード（1 件ずつ / まとめて / グループごと）	上に加えて、一覧のメニューとアクションパネル	選択分を処理済へ
アプリ	レコードに依らない	一覧のメニュー、アクションパネル	売上を月次集計

レコードの処理を一覧でも使いたいときは、同じ行に「一覧でも使う」を入れるだけです。同じ処理をもう 1 行作る必要はありません。

詳細画面のボタン

設定したアクションが、詳細画面のヘッダーにボタンで出ます。表示条件（計算式）でレコードごとに出し分けできます。

押すと、実行条件の検証 → 入力ダイアログ（入力項目があるとき）→ 書き込みの確認 → 実行 → 結果表示、の順に動きます。画面は自動で再読み込みせず、このアプリに書いたときだけ結果に［画面を更新］が出ます。

ボタンのほかに、レコードの保存後・ステータス変更後に自動で動かすこともできます（関連レコード集計プラグインと同じ方式）。実行のときに金額や期間などを聞く入力ダイアログも作れます。選択肢は計算式でも出せるので、「前月・当月・翌月から請求月を選ばせる」「担当者を表示名で選ばせて、SQL にはログイン名を渡す」といった形にできます。数値の範囲や文字数も決められます。

イベントの実行は、ブラウザーでのレコード保存・ステータス変更が対象です。REST API や CSV 読み込みによる更新では動きません。

詳しくは ① 詳細画面編（ボタンとイベント）

一覧画面

一覧のヘッダー部（ツールバーの下）に、折りたたみ式のアクションパネルを出せます。アクションの名前と説明が並び、ここから実行します。アクションが増えたら「区分」で業務ごとに束ねられ、区分ごとに色と畳み方を決められます。

区分を付けると、同じ区分のアクションがパネルの 1 つの節になり、節ごとに畳めます。区分は 1 行に最大 6 個まで並べられます（既定は 1 個＝縦積み）。ボタンの少ない区分が幅いっぱいを占めて右が空くときに詰められます。ボタンの幅も設定でき（120〜400px。既定 200）、狭くすると 1 行に並ぶボタンが増えます。画面が狭いときは列が自動で減ります。ログアプリを指定していれば、「最近の実行」を帯のアイコンから浮かせて出せます。ボタンの右上の時計アイコン（そのアクションのログ一覧）は設定で出せます（既定では出しません。下の画像は出した状態です）。

どの一覧にどの区分を出すかは 画面 × 区分の表で決めます。区分を足して名前を入れるとその場で列が出て、列の見出しから一覧ぜんぶ同じ出し方にそろえられます。

どの一覧に何をどう出すかは画面 × 区分の表で決めます。一覧ごとに「パネル」「メニュー」「出さない」から選ぶだけなので、「アクション専用の一覧」を 1 つ作ってそこだけに出す運用もできます。

「選択したレコードのみ一括処理」をオンにすると、一覧にチェックボックスの列が出ます。選んだレコードの渡し方は 3 つあります。

選択の渡し方	動き	向いている処理
1 件ずつ	選んだレコードごとに同じ SQL を実行します	状態の更新、レコードごとの転記
まとめて 1 回	選んだ ID を `@_selected` に配列で渡し、SQL は 1 回だけ実行します	複数レコードを 1 つのテーブルにまとめる
グループごと	分ける式の値でまとめ、グループの数だけ実行します	顧客別・月別の集計

1 回の上限は既定 300 件です。進捗は「n / m 件」で出て、結果は「対象 / 成功 / 失敗 / 条件外 / 未処理」の内訳で表示します。

詳しくは ② 一覧編（選択したレコードをまとめて処理する）

モバイル

PC で作った設定が、そのままモバイル（スマートフォン）でも効きます。モバイル専用の設定はありません。

詳細画面: ボタンはヘッダーの下に並びます。区分を付けたアクションは区分ごとのメニューにまとまります（横幅が狭いため。PC の詳細画面は区分を見ず、ボタンを並べます）
一覧画面: 一覧（表）の画面で使えます。「選択したレコードのみ一括処理」を入れると各行にチェックが出ます。表のない画面（カレンダーなど）や 0 件の一覧では、一括のボタンを出しません（押しても選べないボタンを作らないため）
アクションパネル: 畳んだ状態で始まり、中は 1 列・ボタンは幅いっぱいです（ボタンの幅の設定はモバイルには効きません）。説明はボタンの横の i を押すと吹き出しで出ます。ログ一覧へのリンクは帯にあり、同じ画面で開きます（kintone のモバイルアプリの中でも開けるように）。ボタンの横のリンクは、PC と同じ設定で出し入れします
確認・入力・結果のダイアログは PC と同じ中身で、指で押せる大きさ（44px 目安）にしています

パネルと区分の開閉は一覧ごとに覚えます（その人のブラウザーに保存します。PC も同じです）。［パネル・区分］の「開いて出す」「畳む」は、覚えていないときの初めの状態です。

詳細画面（ボタンと区分のメニュー）	一覧画面（アクションパネルと選択の一括）

SQL と計算式の書き方

アプリの読み書きは kSQL の Flow 形式（dialect 1）で書きます。1 本のアクションに最大 20 文、各文は ; で区切ります。アプリは LAPP_<論理アプリ名> で書き、プラグイン設定の対応表でアプリ ID に解決するので、設定を他の環境に移しても SQL はそのまま使えます。

-- @ksql dialect: 1
DECLARE @code = '';   -- パラメーター（顧客コード）。実行時に値が入り、無ければこの既定値
CREATE TEMP TABLE t AS
SELECT 顧客コード, 金額 FROM LAPP_受注 WHERE 顧客コード = @code;
ASSERT (SELECT COUNT(*) FROM t) >= 1, '対象のレコードがありません';
UPSERT INTO LAPP_集計 (顧客コード, 売上, 件数, 集計日時)
SELECT @code AS 顧客コード, SUM(金額) AS 売上, COUNT(*) AS 件数, @NOW() AS 集計日時 FROM t
ON DUPLICATE (顧客コード);

条件と値は計算式（計算式プラグインと同じ式）で書きます。使える場所は表示条件・実行条件・実行条件 NG のメッセージ・パラメーター・結果メッセージの 5 つで、すべて読み取り専用です。

関連レコード集計のように「集計先の 1 行（親）と明細をまとめて書き直す」形もよく使います。明細は別アプリにも、親レコードのテーブル（サブテーブル）にも書けます。

詳しくは ③ 集計編（顧客別集計とテーブルへの書き戻し）

確認と安全

書き込みの前に件数を確認するか、確認なし + 書き込み上限で運用するかを、アクションごとに選べます
アクションごとに、実行できる人（ユーザー・組織・グループ）を絞れます
アクションは押した人の権限で動きます（API トークンは使いません）。kintone の権限はアプリに付くので、「決まった SQL でだけ書かせる」ことはできません。対象のアプリは集計・記録の専用にする、権限を必要な分だけにする、などで備えてください
この処理はトランザクションではありません。途中で失敗しても、前の文が書いた分は残ります

ログアプリ（任意）

プラグイン設定でログアプリを指定すると、実行のたびに記録を残し、別ユーザーとの二重実行を防ぎます（ロック）。ログアプリは kSQL Flow と同じ形式で、テンプレートから作れます。記録するのは状態・件数・所要時間・実行者などだけで、業務データの値・SQL の本文・パラメーターの値は書きません。

指定しないときは、記録はレコードの更新者・変更履歴（kintone 標準）だけになり、別ユーザーの同時実行は防げません。

詳しくは ④ 運用編（ログアプリ・二重実行の防止・権限）

プラグインの追加

kintone システム管理の「プラグイン」で読み込み、アプリの設定「プラグイン」で追加します。

プラグインの設定

一覧の 1 行が 1 アクションです。コード・名前・種類・確認・書き込み上限などは表のセルで直接直せます。起動・条件とメッセージ・パラメーターと入力・SQL・実行を許す人は、要約のセルをダブルクリックするか、セルの右端の鉛筆を押すと、それぞれのダイアログで直せます。ボタンの並ぶ順は、行の左端をつかんで動かして決めます。

パラメーターと入力項目は、行ごとに「有効」のチェックがあります。外すとその行だけ渡さない・聞かないので、試しているときに 1 つだけ止めたり、入力項目を全部外してイベント起動に切り替えたりできます（消さずに残せます）。

ツールバーの［共通設定］には、アプリ全体の設定をまとめています。

論理アプリ: SQL の LAPP_<名前> をアプリ ID に解決する対応表です。自アプリも名前で登録します
ログアプリ（任意）: アプリ ID・ログ一覧・一覧パネルの「最近の実行」（出すか / 既定で開くか / 件数 / 自動更新の分）。ゲストスペースにあるかは選んだアプリから自動で決まるので、入れる欄はありません
制限: 読み取りの上限件数、一時テーブルの行数、タイムアウト、一括の最大件数、タイムゾーン、処理中の表示
詳細設定: 実行環境名（ログに書く名前。二重実行を防ぐロックのキーの先頭にも使います）

一覧パネルの設定だけは、区分の定義と画面 × 区分の表が横に広いので、隣の［パネル・区分］という別のボタンで開きます。

SQL を検査

SQL のダイアログの「SQL を検査」で、その場で構文・使える文・パラメーターの対応を検査できます。保存のときにも、有効なアクションすべてを同じ内容で検査します（誤りがあるときは保存できません）。無効にしたアクションは検査せずに下書きとして保存できます。

設定の保存とバックアップ

設定はダウンロード / アップロードできます。アップロードした設定も、保存のときに同じ検査を通ります。

アップロードは、ファイルを選んだ後に取り込み方を選べます。

取り込み方	すること
全置換	設定全体（共通設定もアクションも）をファイルの内容にします
一部置換	ファイルのアクションごとに、置き換える今のアクションを選びます（既定は同じコードの行）
追加	選んだアクションを末尾に足します（コードが重なれば `code_2` になります）

一部置換と追加では共通設定は今のままで、取り込むものを項目ごとにチェックで選べます（論理アプリ・ログアプリ・制限・パネル・区分・タイムゾーンと処理中の表示・NOTE と説明）。
SQL は論理アプリ名（LAPP_…）を見るので、論理アプリを足すチェックだけは既定で入っています。
共通の文（下の「多言語」）は、ファイルにしか無いコードだけを足します。今の設定にある文は上書きしません（上書きすると、取り込んでいないアクションの表示まで変わってしまうためです）。

多言語（日本語・英語・中国語）

プラグインの画面は、利用者の言語で切り替わります。見分けるのは日本語・英語・中国語（簡体字）の 3 つで、それ以外の言語を選んでいる人には英語で出ます。

設定した人が書いた文字も、言語ごとに出し分けられます。アクションの名前と説明、パネルの帯、区分の見出し、実行時に聞く札と選択肢です。設定画面のツールバーの「列」を「多言語」にすると、日(ja) / 英(en) / 中(zh) の欄が出ます。入れた言語だけが切り替わり、空の欄は既定の文字が出ます。

画面に出す文は、ツールバーの［メッセージ］で共通の表にまとめます。m_ で始まる名前を付けて、計算式では $m_done、SQL では @m_done のように呼びます。同じ文を複数のアクションで使い回せて、直すのは 1 か所なので、1 言語しか使わない場合にも役に立ちます。

ログに残す名前は翻訳しません。同じアクションのログが、押した人によって違う名前で残らないようにするためです。実行時に聞く選択肢も、見え方だけを訳して SQL に入る値は変えません。

詳しくは ⑪ 日本語・英語・中国語で使う（共通の文と多言語）

既存プラグインとの違い

プラグイン	位置づけ
データ生成・関連レコード集計・アプリ集計	設定の型に沿った生成・集計。kSQL アクションは SQL で自由に組める汎用版です（置き換えではなく併売です）
kSQL ジョブ実行	管理者・運用向け（SQL を見て確認しながら実行、複数ジョブ・再開・ログ必須）。kSQL アクションは現場向け（固定した SQL をボタンで押す）
kSQL Flow（CLI）	無人・定期・大量の実行。ブラウザーの外で動きます

動作環境・注意事項

PC とモバイル（スマートフォン）で使えます。設定画面は PC だけです
追加・編集画面では動きません（編集中のレコードとの競合を避けるため）
実行は押した人のブラウザーで行います。タブを閉じると実行は止まります
書き込みの途中で失敗した場合、前の文が書いた分は残ります（トランザクションではありません）
ログアプリを指定しない場合、別ユーザーの同時実行は防げません

機能ごとの詳しい説明は、次の 7 本に分けています。

更新情報

Ver.1（2026/XX）初版

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up