結論（3 行）

kintone に JOIN・GROUP BY・ウィンドウ関数・一括更新を SQL で持ち込めます。REST の 500 件ページングも SQL の裏に隠れます

ただし kintone は SQL データベースではありません。JOIN は等式 1 本、LIKE は JavaScript、数値は比較だけ 10 進厳密、トランザクション無し——差分は方言として明示されています

この記事は SQL を書ける人向けに、その差分の早見表と、SQL が kintone の REST API にどう翻訳されるか（EXPLAIN）を 30 分で読める形にまとめたものです

この記事の前提

対象は SQL を書ける開発者です。kintone のカスタマイズやプラグイン、データ連携、運用スクリプトを書いていて、次のどれかで困ったことがある人を想定しています。

複数アプリをまたぐ集計を、REST で全件取ってから自前で突き合わせている
レコードの一括更新に dry-run が無く、本番前の確認が「目視」しかない
「月別推移」「上位 N 社」「案件の無い顧客」のような集計を、kintone の一覧とグラフで作り切れない

逆に、SELECT や GROUP BY の意味は書きません。書くのは標準 SQL との差分と実行の仕組みだけです。

題材は kintone 公式のサンプルアプリ「SFA（営業支援）パック」（顧客管理・担当者管理・案件管理・活動履歴の 4 アプリ）です。
アプリストアから「サンプルデータを含める」をオンにして追加すると、そのまま使えます。
記事中のアプリ番号（顧客管理 APP4148、案件管理 APP4149）は私の環境のものなので、読み替えてください。
なお、件数や取得回数の実測は、第 6 回で扱う手順（CSV を IMPORT で流し込む）で顧客管理を 215 件に増やした環境で取っています。素のパック（顧客 9 件・案件 20 件）でも SQL はすべてそのまま動きます。

私は kintone を SQL 風の構文で操作する
kintone-sql-tools（kSQL）を開発しています。
以下は v3.77.0 時点の内容です。なお kSQL は Apache Kafka の ksqlDB とは無関係の別ツールです。

1. 実行モデル — SQL は REST API の呼び出し計画に翻訳される

kintone にはクエリエンジンがありません。kSQL がやっているのはこれです。

SQL を解析し、kintone のクエリ文字列に変換できる条件を選り分ける
アプリごとに records API を呼ぶ（通常は GET /k/v1/records.json のページング。KORDER BY の大規模窓では Cursor API）。変換できた条件はクエリに載せ、サーバー側で絞る（押し下げ）
返ってきたレコードをインメモリで JOIN・集計・並べ替えする
集計・GROUP BY・DISTINCT・ローカル並べ替えのように完全な入力が要るクエリは、上限（maxRecords）に達したら部分結果を返さずエラーで止まる（fail-closed）。単純な明細だけが onLimit の設定に従う

流れを 1 枚にするとこうなります。

fetch summary は、この分析と取得計画の結果です。WHERE 全体を kintone のクエリへ忠実に変換できれば EXACT、
全体は変換できなくても AND でつながった安全な条件を一部押し下げられれば PREFILTERED（押し下げとインメモリ再評価の両方が働く）、
押し下げられる条件が無ければ ALL（それでも records API で全件取る）です。
JOIN や UNION ではソースごとに fetch が決まり、fetch summary はそれらを要約した値です。
JOIN ではさらに、先に取れた側の結合キーで相手アプリを絞る最適化が INNER JOIN にだけ加わります（第 1 回）。

つまり性能と安全性は「何が押し下がり、何件取りに行くか」で決まります。それを実行前に見せるのが EXPLAIN です。
取得量を知るには先頭の fetch summary 行、途中で止まる可能性まで見るなら complete input 行を読みます。

`fetch`	意味
`COUNT_ONLY`	件数だけ。全件を走査せず、`limit 1` で最大 1 件だけ取得し、1 リクエストで `totalCount` を得る
`EXACT`	WHERE 全体が kintone 側へ渡った。レコード取得を伴う方式の中では、最も絞り込みが効いている
`PREFILTERED`	一部だけ kintone 側で絞り、残りをインメモリで評価
`ALL`	全件取得。上限に注意
`NONE`	kintone から取るソースが無い（一時テーブルや生成系列だけ）。構造化された計画上の値で、テキスト表示では `fetch summary` 行自体が出ないことがある

以下の 3 例は、プラグインの実行画面に SQL を貼って EXPLAIN ボタンを押した出力です（EXPLAIN を SQL の先頭に付けても同じ計画が出ます）。

例 1: 件数だけなら `COUNT_ONLY`

SELECT COUNT(*) FROM APP4149 WHERE 商談フェーズ IN ('受注')

fetch summary: COUNT_ONLY
metadata API: form definition APP4149
mode: COUNT_TOTAL_COUNT
app: APP4149 (4149)
kintone query: 商談フェーズ in ("受注") limit 1
fetch: COUNT_ONLY (limit 1)
fields: $id
fetch API: GET records.json (totalCount=true)
REST execution: single GET
record limit: maxRecords/onLimitReached not applied
fallback: full record scan when totalCount is missing or invalid
search abort: fail-closed (SearchAbortedError)

totalCount=true の 1 リクエストで終わり、全件分のページングは発生しません。転送されるレコードは limit 1 の最大 1 件（フィールドは $id だけ）で、maxRecords の影響も受けません。
件数に比例したレコード取得やページングが発生しないので、総件数の KPI は maxRecords を気にせず書けます。
ただし条件は狭く、物理アプリに対する SELECT COUNT(*) で、JOIN・サブテーブル・CTE・GROUP BY・HAVING・DISTINCT・LIMIT / OFFSET が無く、WHERE 全体を押し下げられる場合だけです。

例 2: 同じ WHERE でも GROUP BY を足すと取りに行く（`EXACT`）

SELECT 商談フェーズ, COUNT(*) AS 件数, SUM(売上) AS 売上合計
FROM APP4149
WHERE 商談フェーズ IN ('受注')
GROUP BY 商談フェーズ

fetch summary: EXACT
metadata API: form definition APP4149
mode: FULL_SCAN
group key 商談フェーズ: PHYSICAL (source=0, field=商談フェーズ)
complete input: required (onLimit=truncate disabled)
complete input reason: GROUP_BY, AGGREGATE
onLimit=truncate: disabled
reason: GROUP BY あり, 集計関数（COUNT / SUM 等）あり
app: APP4149 AS APP4149 (4149)
kintone query: 商談フェーズ in ("受注")
fetch: EXACT
pushdown applied: 商談フェーズ in ("受注")
relation: exact
fields: 商談フェーズ, 売上

集計はインメモリなので mode: FULL_SCAN になりますが、WHERE は丸ごと押し下がっているので（fetch: EXACT）、取ってくるのは受注フェーズの行だけです。
fields 行にも注目してください。この SQL の評価に必要なフィールドだけを取得します。必要な列は SELECT だけでなく WHERE・JOIN・GROUP BY・HAVING・ORDER BY から決まります。
complete input: required は「集計は入力が欠けると値が誤るので、上限に達したら打ち切りではなくエラーにする」という宣言です。

例 3: フィールドを関数で包むと押し下がらない（`ALL`）

SELECT 案件名, 売上 FROM APP4149 WHERE DATE_FORMAT(受注予定日, '%Y-%m') = '2026-08'

fetch summary: ALL
metadata API: form definition APP4149
mode: FULL_SCAN
reason: WHERE 句に JS 評価が必要な式, WHERE_EXPRESSION_LOCAL_ONLY
app: APP4149 AS APP4149 (4149)
kintone query: (全件取得)
fetch: ALL
fields: 案件名, 売上, 受注予定日

DATE_FORMAT(受注予定日, …) は kintone のクエリ構文に無いので、全件取ってからインメモリで評価します。
同じ意図なら WHERE 受注予定日 >= '2026-08-01' AND 受注予定日 <= '2026-08-31' か、相対日付関数 WHERE 受注予定日 = THIS_MONTH() と書けば EXACT になります。
「WHERE に書く日付」と「SELECT で整形する日付」は別物、というのが第 2 回の主題の一つです。

上限は fail-closed

取得上限は CLI 既定 500 件・MCP 既定 500 件・プラグイン既定 3,000 件・エンジン既定 10,000 件です。
上限に達したとき、集計・GROUP BY・DISTINCT・ローカル ORDER BY を含むクエリは部分結果を返さずエラーになります（誤った合計や誤った上位 N を返さないため）。
素の明細は onLimit=truncate を指定した場合だけ打ち切り表示します。
「動いていたのにデータが増えたら突然エラーになった」は、たいてい fetch: ALL のクエリが上限に当たったものです。EXPLAIN を見れば事前に分かります。

2. 標準 SQL との差分早見表

MySQL / PostgreSQL の感覚で書いて引っかかる点を、引っかかる順に並べました。★は「エラーにならず静かに違う結果になる」ものです。

項目	標準 SQL の感覚	kSQL	備考
テーブル名	`orders`	`APP4149`。サブテーブルは `APP4149$明細` の仮想テーブル	CLI は `APP4149@prod`、論理名 `LAPP_案件管理` も可
識別子	英数字	日本語フィールドコードをそのまま書ける。空白や予約語はバッククォート	ラベル≠フィールドコード。「〒」のコードは `郵便番号`。`DESCRIBE APP4148` で確認
JOIN	任意の条件	`ON` はフィールド同士の等式 1 本だけ。`ON a.顧客No = b.顧客No_` は可、`ON a.x = b.x AND a.y = b.y` と `ON a.日付 BETWEEN b.開始 AND b.終了` は不可。`ON` に式や関数も書けない。INNER / LEFT / RIGHT / CROSS。FULL OUTER 無し	複合キーは kintone の計算フィールド、CTE、一時テーブルのどれかで `CONCAT(a, '::', b)` の連結キー列を先に作り、その列同士を結ぶ。区切り文字が元データに現れないことを保証する（`'A::'`+`'B'` と `'A'`+`'::B'` は衝突する）。CTE 化すると取得計画が変わるので `EXPLAIN` で確認。今回使う SFA パックでは、ルックアップのコピー先フィールドが結合キーになる
派生テーブル	`FROM (SELECT …) t`	不可。`WITH`（CTE）か `CREATE TEMP TABLE #t AS SELECT …`	一時テーブルはバッチ（`;` 区切り）内で有効、既定 10,000 行まで
サブクエリ	相関可	非相関の `IN` / `EXISTS` / スカラーのみ。相関サブクエリ不可	DML の WHERE には `IN (SELECT …)` を書けない（第 5 回）
`LIKE` ★	DB の照合順序	JavaScript の文字列意味論で評価し、`LIKE` 自体は押し下げない。単独なら `ALL`、押し下がる条件と `AND` で組めば `PREFILTERED`	kintone の全文検索が欲しいときは別演算子 `KLIKE`（10 万件で打ち切りあり）
`ORDER BY` ★	照合順序	型ごとの正準順。テキストは Unicode コードポイント順（日本語の辞書順ではない）	kintone の REST と同じ並びが要るときは `KORDER BY`
数値 ★	DECIMAL / DOUBLE	比較は最大 30 桁の 10 進厳密（`1.10 = 1.1`）。算術・`SUM` / `AVG` は IEEE 754 倍精度（`3000 * 1.1` = `3300.0000000000005`）	精度が要る計算は kintone の計算フィールドに寄せる
空セル ★	NULL	未設定値は空文字として扱う。数値の空セルは算術では 0、型付き比較と並べ替えでは最小側	`WHERE 金額 != ''` で除外（押し下がる）。`IS NULL` / `IS NOT NULL` 自体は押し下がらず、その条件単独では `ALL`、押し下がる条件と `AND` で組めば `PREFILTERED`（v3.77.0 で実測）。選択系の未選択は `IN ('')` なら押し下がる
選択系の比較	`=`	ドロップダウン・ラジオ・ステータスは `=` でよい（`IN` に正規化して押し下げ）。チェックボックス・複数選択・ユーザー選択は `IN` / `NOT IN` 必須	定義に無い値との `=` は正規化されず、その条件単独なら全件取得のうえ 0 行
日付の条件	`date >= '…'`	リテラル比較は押し下がる。相対日付関数（`TODAY()` / `THIS_MONTH()` / `FROM_TODAY(n, unit)` …）も押し下がるが WHERE 専用	`DATE_FORMAT` / `YEAR()` で包むと押し下がらない（例 3）。`DATE_ADD(列, n, 'MONTH')` の引数順に注意、`DATE_SUB` と `INTERVAL` は無い
集計とウィンドウ	同じ SELECT に書ける	同じ SELECT に書けない。CTE で段を分ける	`GROUP BY` にはエイリアスも書ける
結果列名	そのまま	英字は小文字に正規化される（`AS ランクA` → `ランクa`）	ダッシュボードの列設定で参照するときに効く
トランザクション	BEGIN / ROLLBACK	無し。バッチは非アトミック、常に fail-fast。書き込み API は自動リトライしない	代わりに `VALIDATE ONLY`・`ASSERT`・`ON ERROR SKIP` で事前検証と早期停止（第 5 回）
静的検証	パーサ + カタログ	MCP の `ksql_validate`（第 9 回）は構文と静的検査だけ。フォーム定義は読まないので、存在しないフィールドコードでも `ok` になりうる	最後に確かめるのは実行結果
文字列リテラル	`'it''s'`	同じ。シングルクォート、`''` でエスケープ	ダブルクォートは識別子ではなく使えない

★は、エラーにはならないものの、DB で期待した意味と異なる可能性がある項目です。値が返ってくるぶんエラーより厄介です。
特に数値は「比較は 10 進厳密、算術は倍精度」、空セルは「算術では 0、比較では最小側」と、操作によって意味が変わります。第 4 回で「静かに間違う」例をまとめて扱います。

3. 道具の使い分けと準備

面	向いていること	書き込み	接続・認証設定
kintone プラグイン	画面内で書いて実行し、その場で見る。EXPLAIN ボタン・履歴・表表示・フィルタ・`;` 区切りのバッチ・一時テーブル・IMPORT（ファイル選択）	文ごとの確認ダイアログ	不要（ログイン中のユーザー権限で動く）
CLI `ksql`	スクリプト・CI・スケジューラ。`-f file.sql`、`--format json\|csv`、CSV export、profile で環境切替	`--allow-dml` で可（確認プロンプトあり）	設定ファイルと API トークン
MCP サーバー	Claude などの AI クライアントから。read-only ツールと mutate ツールが分離	`ksql_mutate` のみ	同上
無償版 Dashboard プラグイン	集計 SQL を表と棒グラフのペインにして一覧画面に置く	不可（read-only）	不要（ログイン中の権限）
engine ライブラリ	自作プラグイン・カスタマイズに read-only エンジンを組み込む	不可	組み込み側からクライアントを渡す

このシリーズは第 6 回までプラグインで進めます。接続設定が要らず、EXPLAIN もバッチも一括更新も画面内で試せるからです。
このシリーズで CLI が必要になるのは「ファイルに書き出す」「別環境で同じ SQL を使う」「自動で回す」の 3 つで、その必要が出る第 7 回で導入します。

SFA パックを追加したら、kSQL 側の準備は 2 つの zip だけです。v3.77.0 の release フォルダから
ksql-plugin-v3.77.0.zip を kintone のプラグイン画面で読み込み（kintone のシステム管理権限が要ります）、
ksql-app-template-v1.11.0.zip からテンプレートで専用アプリを作ります。
専用アプリは設定済みなので追加設定はありません。使い方の詳細は rex0220 kSQL プラグインにあります。
第 5 回以降はレコードを書き換えるので、本番アプリではなく、サンプルデータを入れた検証環境で進めてください。

最初の 1 本を専用アプリの実行画面に貼って実行し、続けて同じ SQL のまま EXPLAIN ボタンを押してください。

SELECT 商談フェーズ, COUNT(*) AS 件数
FROM APP4149
GROUP BY 商談フェーズ
ORDER BY 件数 DESC

EXPLAIN は fetch summary: ALL になります。WHERE が無いので当然ですが、complete input reason: GROUP_BY, LOCAL_ORDER, AGGREGATE の行に、
集計と ORDER BY 件数 がどちらもインメモリで、入力が欠けたら止まる、という宣言が出ています。20 件のアプリでは何も起きませんが、
この行が出るクエリは、データが増えたときに上限の対象になる、と覚えておいてください。
プラグインの上限は「⚙ オプション → 取得」の「最大取得件数」（既定 3,000 件。下の画像の環境では 500 に下げてあります）で、以降の回ではこれを意図的に下げて fail-closed を実演します。

他の面の導入は、必要になる回で扱います。

CLI（第 7 回）: CLI チュートリアル
MCP（第 9 回・Claude Desktop）: kSQL MCPB Claude Desktop インストール手順
Dashboard（各回の出口）: kSQL Dashboard プラグイン
言語仕様の正本: 言語リファレンス（§22 制限事項・§24 EXPLAIN）

4. シリーズの構成

以降は業務課題 1 つにつき 1 本、「課題 → 標準 SQL ならこう書く → kSQL ではこう → EXPLAIN で仕組み → 落とし穴 → 運用に載せる」の型で進めます。

回	課題	主な差分・機能
1	アプリをまたいで集計する	INNER JOIN・押し下げの 2 種（WHERE 述語と結合キー）・LEFT JOIN の上限
2	期間で集計する	相対日付・`GENERATE_SERIES` で無い月を 0 埋め・`LAG` 前月比
3	ABC 分析	ウィンドウ関数（順位・構成比・累積）・`ROLLUP`
4	データ品質を監査する	`VALIDATE APPn INTO #err`・重複・文字列の罠（コードポイント順・サロゲートペア）
5	安全に一括更新する	一時テーブルで確保・`ASSERT`・`UPSERT`・`VALIDATE ONLY`・`ON ERROR SKIP`・冪等性
6	CSV を IMPORT して検証環境を大きくする	`IMPORT CSV/JSON`（プラグインのファイル選択）・テストデータ増量
7	CLI を導入して定期運用に載せる	CSV export（Shift_JIS）・`--format json`・`DECLARE @param`・profile と `LAPP_`・スケジューラ
8	kSQL Flow へ載せる	dialect 1・`ASSERT` / `EXIT` ゲート・as-of・再実行
9	AI に書かせて人間がレビューする	MCP・構文カタログ・`EXPLAIN` をレビューに使う

Claude に頼むなら（MCP 導入済みの読者向け・任意）

各回の末尾に、同じ課題を Claude に頼むときの依頼文を 1 つ置きます。
kSQL MCP は第 9 回で導入します。すでに導入済みなら次の依頼文を試せます。未導入ならここは飛ばしてください。

kSQL MCP で、APP4149（案件管理）のうち受注予定日が今年の案件について、商談フェーズ別の件数と売上合計を出す SQL を書いてください。
日付条件には THIS_YEAR() を使い、YEAR() や DATE_FORMAT() は使わないでください。
ksql_validate で検証したうえで、ksql_explain の fetch summary 行が EXACT になっていることを確認してください。実行はしないでください。

次回は第 1 回「アプリをまたいで集計する」です。顧客管理と案件管理をルックアップのキーで結合し、EXPLAIN の「pushdown applied」と「join key prefilter」を別々に読みます。

リポジトリ・ドキュメント:

https://github.com/rex0220/kintone-sql-tools
npm: @rex0220/kintone-sql-tools（CLI / プラグイン / MCP サーバー同梱）