@rex0220/kintone-sql-tools 3.31.1 → 3.33.0

package/dist-cli/ksql.js

@@ -4260,6 +4260,15 @@ function containsStatisticalAggregate(value, seen = /* @__PURE__ */ new Set()) {
   if (record.type === "FIELD" && typeof record.field === "string" && /^(STDDEV_POP|STDDEV_SAMP|VAR_POP|VAR_SAMP|MEDIAN|MODE)\(/i.test(record.field)) return true;
   return Object.values(record).some((child) => Array.isArray(child) ? child.some((entry) => containsStatisticalAggregate(entry, seen)) : containsStatisticalAggregate(child, seen));
 }
+function containsAggregate(value, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value !== "object") return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  const record = value;
+  if ((record.type === "AGGREGATE" || record.type === "AGG_REF") && typeof record.func === "string" && !STATISTICAL_AGGREGATES.has(record.func)) return true;
+  if (record.type === "FIELD" && typeof record.field === "string" && /^(COUNT|SUM|AVG|MIN|MAX|GROUP_CONCAT)\(/i.test(record.field)) return true;
+  return Object.values(record).some((child) => Array.isArray(child) ? child.some((entry) => containsAggregate(entry, seen)) : containsAggregate(child, seen));
+}
 function completeInputReasons(stmt) {
   const reasons = /* @__PURE__ */ new Set();
   if (isDmlType(stmt.type)) {
@@ -4289,6 +4298,7 @@ function completeInputReasons(stmt) {
       break;
   }
   if (containsStatisticalAggregate(stmt)) reasons.add("STATISTICAL_AGGREGATE");
+  if (containsAggregate(stmt)) reasons.add("AGGREGATE");
   return reasons;
 }
 function requiresCompleteInput(stmt) {
@@ -4297,11 +4307,15 @@ function requiresCompleteInput(stmt) {
 function unionCompleteInputReasons(stmt) {
   const reasons = stmt.left.type === "SELECT" ? selectCompleteInputReasons(stmt.left) : unionCompleteInputReasons(stmt.left);
   addReasons(reasons, selectCompleteInputReasons(stmt.right));
+  if (!stmt.all) reasons.add("DISTINCT");
   return reasons;
 }
 function selectCompleteInputReasons(stmt) {
   const reasons = /* @__PURE__ */ new Set();
-  if (normalizeGroupingSpec(stmt).type === "GROUPING_SETS") reasons.add("GROUPING_SETS");
+  const grouping = normalizeGroupingSpec(stmt);
+  if (grouping.type === "GROUPING_SETS") reasons.add("GROUPING_SETS");
+  if (grouping.type === "PLAIN") reasons.add("GROUP_BY");
+  if (stmt.distinct) reasons.add("DISTINCT");
   if (stmt.orderBy.length > 0) reasons.add("LOCAL_ORDER");
   for (const column of stmt.columns) {
     if (column.type === "WINDOW_COL" && column.orderBy.length > 0) reasons.add("WINDOW_ORDER");
@@ -4313,6 +4327,7 @@ function selectCompleteInputReasons(stmt) {
   addReasons(reasons, whereCompleteInputReasons(stmt.where));
   addReasons(reasons, whereCompleteInputReasons(stmt.having));
   if (containsStatisticalAggregate(stmt)) reasons.add("STATISTICAL_AGGREGATE");
+  if (containsAggregate(stmt)) reasons.add("AGGREGATE");
   return reasons;
 }
 function whereCompleteInputReasons(where) {
@@ -6505,19 +6520,19 @@ function collectNonAggregateFieldRefs(node, out) {
   }
   Object.values(value).forEach((item) => collectNonAggregateFieldRefs(item, out));
 }
-function containsAggregate(node) {
+function containsAggregate2(node) {
   if (node === null || typeof node !== "object") return false;
-  if (Array.isArray(node)) return node.some(containsAggregate);
+  if (Array.isArray(node)) return node.some(containsAggregate2);
   const value = node;
   if (value["type"] === "AGG_REF" || value["type"] === "AGG_ARITH") return true;
   if (value["type"] === "SELECT" || value["type"] === "SCALAR_SUBQUERY") return false;
-  return Object.values(value).some(containsAggregate);
+  return Object.values(value).some(containsAggregate2);
 }
 function isAggregateMaterializedAlias(column) {
   if (!("alias" in column) || column.alias === null) return false;
   if (column.type === "AGGREGATE" || column.type === "ARITH_AGG_COL") return true;
   if (column.type === "STRFUNC_COL" || column.type === "SCALAR_VALUE_COL") {
-    return containsAggregate(column);
+    return containsAggregate2(column);
   }
   return false;
 }
@@ -10893,8 +10908,9 @@ function getLastId(records) {
   return Number.isFinite(id) ? id : 0;
 }
 var FetchAllLimitError = class extends Error {
-  constructor(message) {
+  constructor(message, completeInputWrapped = false) {
     super(message);
+    this.completeInputWrapped = completeInputWrapped;
     this.name = "FetchAllLimitError";
   }
 };
@@ -12405,7 +12421,7 @@ function classifyPreGroupAlias(column) {
     case "STRFUNC_COL":
     case "SCALAR_VALUE_COL":
     case "SCALAR_SUBQUERY_COL":
-      return containsAggregate(column) || containsAggregateColumnNode(column) ? "AGGREGATE_DEPENDENT" : "SAFE";
+      return containsAggregate2(column) || containsAggregateColumnNode(column) ? "AGGREGATE_DEPENDENT" : "SAFE";
   }
 }
 var SUBTABLE_SYSTEM_COLUMNS = ["_pid", "_rid", "_idx"];
@@ -12530,11 +12546,11 @@ var EMPTY_WILDCARD_FIELD_TYPE_POLICY = {
   UPDATED_TIME: "RECORD",
   USER_SELECT: "RECORD"
 };
-function fieldPolicy(fieldType) {
+function fieldPolicy(fieldType, fieldCode) {
   const policy = EMPTY_WILDCARD_FIELD_TYPE_POLICY[fieldType];
   if (policy === void 0) {
     throw new Error(
-      `InternalError: empty SELECT * schema policy is not defined for field type ${fieldType}.`
+      `ArgumentError: getFields returned unknown fieldType "${fieldType}" for field "${fieldCode}". getFields must return only the fields from /k/v1/app/form/fields.json; $id and $revision are synthesized by the engine and must not be added.`
     );
   }
   return policy;
@@ -12549,10 +12565,10 @@ async function deriveEmptyWildcardColumns(fields, subtableCode, loadProcessStatu
     ];
   }
   const topLevel = fields.filter((field) => !field.inSubtable);
-  const needsProcessSettings = topLevel.some((field) => fieldPolicy(field.fieldType) === "PROCESS");
+  const needsProcessSettings = topLevel.some((field) => fieldPolicy(field.fieldType, field.code) === "PROCESS");
   const processEnabled = needsProcessSettings ? (await loadProcessStatuses()).enable : false;
   const columns = topLevel.filter((field) => {
-    const policy = fieldPolicy(field.fieldType);
+    const policy = fieldPolicy(field.fieldType, field.code);
     return policy === "RECORD" || policy === "PROCESS" && processEnabled;
   }).map((field) => field.code);
   return [...columns, "$revision", "$id"];
@@ -15448,11 +15464,21 @@ function createEmptyMetrics() {
     cursorCreateOutcomeUnknown: 0,
     cursorQuarantinedCurrent: 0,
     fetchedRows: 0,
+    limitReached: false,
+    limitReachedApps: [],
     elapsedMs: 0
   };
 }
+var LIMIT_METRICS_SINK = /* @__PURE__ */ Symbol("limitMetricsSink");
+function markLimitReached(client, appId) {
+  const metrics = client[LIMIT_METRICS_SINK];
+  if (!metrics) return;
+  metrics.limitReached = true;
+  if (!metrics.limitReachedApps.includes(appId)) metrics.limitReachedApps.push(appId);
+}
 function wrapClientWithMetrics(client, metrics) {
   return {
+    [LIMIT_METRICS_SINK]: metrics,
     getRecords: async (params) => {
       metrics.getCalls += 1;
       const res = await client.getRecords(params);
@@ -15652,7 +15678,7 @@ async function executeParsedStatement(stmt, client, options, cacheContext) {
       return executeExistingRecordValidation(stmt, client, options, cacheContext);
     case "SELECT":
       return executeSelect(
-        stmt,
+        markCountTotalCountRoot(stmt),
         client,
         options,
         cacheContext,
@@ -16788,7 +16814,7 @@ async function executeSelect(stmt, client, options, cacheContext, cteCache, capt
     cteCache
   );
   await resolveSelectCaseSubqueries(stmt, client, options, cacheContext, cteCache);
-  const whereCapability = await resolveSelectWhereCapability(stmt, client, cacheContext, cteCache);
+  const whereCapability = rememberSelectWhereCapability(stmt, await resolveSelectWhereCapability(stmt, client, cacheContext, cteCache));
   if (whereCapability.capability === "UNSUPPORTED") {
     throw new Error(`ArgumentError: WHERE predicate is unsupported (${formatWhereCapabilityFailure(whereCapability)}).`);
   }
@@ -17054,11 +17080,21 @@ async function validateSelectGroupingPlanning(stmt, client, cacheContext, materi
 }
 function completeInputErrorPrefix(reasons) {
   const reasonList = [...reasons].join(", ");
-  const subject = reasons.size === 1 && reasons.has("STATISTICAL_AGGREGATE") ? "\u7D71\u8A08\u96C6\u7D04\u306E\u6B63\u3057\u3044\u7D50\u679C" : reasons.size === 1 && reasons.has("GROUPING_SETS") ? "\u5C0F\u8A08\u30FB\u7DCF\u8A08\u306E\u6B63\u3057\u3044\u7D50\u679C" : reasons.has("GROUPING_SETS") ? "\u30AF\u30A8\u30EA\u306E\u6B63\u3057\u3044\u7D50\u679C" : "ORDER BY\u306E\u6B63\u3057\u3044\u7D50\u679C";
+  const aggregateSubjects = [
+    ["GROUPING_SETS", "\u5C0F\u8A08\u30FB\u7DCF\u8A08\u306E\u6B63\u3057\u3044\u7D50\u679C"],
+    ["STATISTICAL_AGGREGATE", "\u7D71\u8A08\u96C6\u7D04\u306E\u6B63\u3057\u3044\u7D50\u679C"],
+    ["AGGREGATE", "\u96C6\u8A08\u306E\u6B63\u3057\u3044\u7D50\u679C"],
+    ["GROUP_BY", "\u30B0\u30EB\u30FC\u30D7\u96C6\u8A08\u306E\u6B63\u3057\u3044\u7D50\u679C"],
+    ["DISTINCT", "DISTINCT \u306E\u6B63\u3057\u3044\u7D50\u679C"]
+  ];
+  const hasAggregateReason = aggregateSubjects.some(([reason]) => reasons.has(reason));
+  const hasOrderReason = reasons.has("LOCAL_ORDER") || reasons.has("WINDOW_ORDER");
+  const legacySubject = reasons.size === 1 && reasons.has("STATISTICAL_AGGREGATE") ? "\u7D71\u8A08\u96C6\u7D04\u306E\u6B63\u3057\u3044\u7D50\u679C" : reasons.size === 1 && reasons.has("GROUPING_SETS") ? "\u5C0F\u8A08\u30FB\u7DCF\u8A08\u306E\u6B63\u3057\u3044\u7D50\u679C" : reasons.size === 1 && reasons.has("AGGREGATE") ? "\u96C6\u8A08\u306E\u6B63\u3057\u3044\u7D50\u679C" : reasons.size === 1 && reasons.has("GROUP_BY") ? "\u30B0\u30EB\u30FC\u30D7\u96C6\u8A08\u306E\u6B63\u3057\u3044\u7D50\u679C" : reasons.size === 1 && reasons.has("DISTINCT") ? "DISTINCT \u306E\u6B63\u3057\u3044\u7D50\u679C" : reasons.has("GROUPING_SETS") ? "\u30AF\u30A8\u30EA\u306E\u6B63\u3057\u3044\u7D50\u679C" : "ORDER BY\u306E\u6B63\u3057\u3044\u7D50\u679C";
+  const subject = reasons.has("DML") || reasons.has("VALIDATE") ? legacySubject : hasAggregateReason && hasOrderReason ? "\u30AF\u30A8\u30EA\u306E\u6B63\u3057\u3044\u7D50\u679C" : hasAggregateReason ? aggregateSubjects.find(([reason]) => reasons.has(reason))[1] : "ORDER BY\u306E\u6B63\u3057\u3044\u7D50\u679C";
   return `${subject}\u306B\u306F\u5B8C\u5168\u306A\u5019\u88DC\u96C6\u5408\u304C\u5FC5\u8981\u3067\u3059\u3002complete input reason: ${reasonList}\u3002`;
 }
 function buildCompleteInputPolicy(stmt, options, orderPlan) {
-  const reasons = orderPlan?.kind === "CANONICAL_REST_TOP_N" || orderPlan?.kind === "KORDER_NATIVE" || orderPlan?.kind === "KORDER_CURSOR" ? completeInputReasons({ ...stmt, orderBy: [] }) : completeInputReasons(stmt);
+  const reasons = stmt.type === "SELECT" && (orderPlan?.kind === "CANONICAL_REST_TOP_N" || orderPlan?.kind === "KORDER_NATIVE" || orderPlan?.kind === "KORDER_CURSOR") ? completeInputReasons({ ...stmt, orderBy: [] }) : completeInputReasons(stmt);
   const truncateWasDisabled = reasons.size > 0 && options.onLimitReached === "truncate";
   return {
     reasons,
@@ -17067,9 +17103,10 @@ function buildCompleteInputPolicy(stmt, options, orderPlan) {
   };
 }
 function throwCompleteInputError(policy, error) {
-  if (policy.reasons.size > 0 && error instanceof FetchAllLimitError) {
+  if (policy.reasons.size > 0 && error instanceof FetchAllLimitError && !error.completeInputWrapped) {
     throw new FetchAllLimitError(
-      completeInputErrorPrefix(policy.reasons) + (policy.truncateWasDisabled ? "onLimit=truncate\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\u3002" : "") + error.message
+      completeInputErrorPrefix(policy.reasons) + (policy.truncateWasDisabled ? "onLimit=truncate\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\u3002" : "") + error.message,
+      true
     );
   }
   throw error;
@@ -17214,6 +17251,7 @@ async function executeSimpleSelect(stmt, client, options, cacheContext, orderPla
         onLimit,
         onTruncate: (max) => {
           warnings.add(`\u53D6\u5F97\u4E0A\u9650\uFF08${max} \u4EF6\uFF09\u306B\u9054\u3057\u305F\u305F\u3081\u3001${max} \u4EF6\u3067\u6253\u3061\u5207\u3063\u3066\u8868\u793A\u3057\u3066\u3044\u307E\u3059\u3002`);
+          markLimitReached(client, stmt.from.appId);
         }
       }
     );
@@ -18099,7 +18137,55 @@ function buildSelectFieldTypeResolvers(stmt, fieldTypesByApp) {
   };
   return { row, having };
 }
+var countTotalCountRootSelects = /* @__PURE__ */ new WeakSet();
+var resolvedWhereCapabilities = /* @__PURE__ */ new WeakMap();
+function markCountTotalCountRoot(stmt) {
+  countTotalCountRootSelects.add(stmt);
+  return stmt;
+}
+function rememberSelectWhereCapability(stmt, capability) {
+  resolvedWhereCapabilities.set(stmt, capability);
+  return capability;
+}
+function isCountStarTotalCountEligible(stmt, whereCapability) {
+  if (whereCapability.capability !== "EXACT_PUSHDOWN") return false;
+  if (stmt.columns.length !== 1) return false;
+  const column = stmt.columns[0];
+  if (column?.type !== "AGGREGATE" || column.func !== "COUNT" || column.distinct || column.arg.type !== "WILDCARD") {
+    return false;
+  }
+  return !stmt.distinct && normalizeGroupingSpec(stmt).type === "NONE" && stmt.having === null && stmt.joins.length === 0 && stmt.from.cteName === null && !stmt.from.subtableCode && stmt.limit === null && stmt.offset === null;
+}
+function isValidTotalCount(value) {
+  return typeof value === "string" && /^(?:0|[1-9]\d*)$/.test(value);
+}
+async function tryCountStarWithTotalCount(stmt, client) {
+  const countColumn = stmt.columns[0];
+  if (countColumn?.type !== "AGGREGATE") return null;
+  const baseQuery = stmt.where === null ? "" : whereToKintone(stmt.where);
+  const response = await client.getRecords({
+    app: stmt.from.appId,
+    query: `${baseQuery}${baseQuery ? " " : ""}limit 1`,
+    fields: ["$id"],
+    totalCount: true
+  });
+  if (response.searchAborted) throw new SearchAbortedError();
+  if (!isValidTotalCount(response.totalCount)) return null;
+  const column = countColumn.alias ?? "COUNT(*)";
+  return {
+    type: "SELECT",
+    rows: [{ [column]: response.totalCount }],
+    columns: [column],
+    rowCount: 1,
+    warnings: []
+  };
+}
 async function executeFullScanSelect(stmt, client, options, cacheContext, cteCache, allowOriginalWherePushdown = true, preloadedOrderMeta, prefilterPlan, plainGroupByPlan) {
+  const whereCapability = resolvedWhereCapabilities.get(stmt);
+  if (countTotalCountRootSelects.has(stmt) && whereCapability !== void 0 && isCountStarTotalCountEligible(stmt, whereCapability)) {
+    const totalCountResult = await tryCountStarWithTotalCount(stmt, client);
+    if (totalCountResult !== null) return totalCountResult;
+  }
   const maxRecords = options.maxRecords ?? 1e4;
   const warnings = /* @__PURE__ */ new Set();
   const parallel = options.fetchParallel ?? 1;
@@ -18253,26 +18339,53 @@ async function executeFullScanSelect(stmt, client, options, cacheContext, cteCac
   return { type: "SELECT", rows, columns, rowCount: rows.length, warnings: [...warnings] };
 }
 async function executeUnion(stmt, client, options, cacheContext, captureColumnMeta = false, forLibraryCapture = false) {
-  const [leftResult, rightResult] = await Promise.all([
-    stmt.left.type === "UNION" ? executeUnion(stmt.left, client, options, cacheContext, captureColumnMeta, forLibraryCapture) : executeSelect(stmt.left, client, options, cacheContext, void 0, captureColumnMeta, forLibraryCapture),
-    executeSelect(stmt.right, client, options, cacheContext, void 0, captureColumnMeta, forLibraryCapture)
-  ]);
-  const leftCols = leftResult.columns;
-  const rightCols = rightResult.columns;
-  const remappedRight = rightResult.rows.map((row) => {
-    const mapped = {};
-    leftCols.forEach((col, i) => {
-      mapped[col] = row[rightCols[i] ?? col] ?? "";
+  const completePolicy = buildCompleteInputPolicy(stmt, options, null);
+  return withCompleteInputPolicy(completePolicy, async () => {
+    const effectiveOptions = completePolicy.effectiveOptions;
+    const [leftResult, rightResult] = await Promise.all([
+      stmt.left.type === "UNION" ? executeUnion(
+        stmt.left,
+        client,
+        effectiveOptions,
+        cacheContext,
+        captureColumnMeta,
+        forLibraryCapture
+      ) : executeSelect(
+        stmt.left,
+        client,
+        effectiveOptions,
+        cacheContext,
+        void 0,
+        captureColumnMeta,
+        forLibraryCapture
+      ),
+      executeSelect(
+        stmt.right,
+        client,
+        effectiveOptions,
+        cacheContext,
+        void 0,
+        captureColumnMeta,
+        forLibraryCapture
+      )
+    ]);
+    const leftCols = leftResult.columns;
+    const rightCols = rightResult.columns;
+    const remappedRight = rightResult.rows.map((row) => {
+      const mapped = {};
+      leftCols.forEach((col, i) => {
+        mapped[col] = row[rightCols[i] ?? col] ?? "";
+      });
+      return mapped;
     });
-    return mapped;
+    const combined = [...leftResult.rows, ...remappedRight];
+    const rows = stmt.all ? combined : deduplicateRows(combined, leftCols);
+    const result = { type: "SELECT", rows, columns: leftCols, rowCount: rows.length };
+    if (captureColumnMeta) {
+      materializedMetaBySelectResult.set(result, mergeUnionColumnMeta(leftResult, rightResult));
+    }
+    return result;
   });
-  const combined = [...leftResult.rows, ...remappedRight];
-  const rows = stmt.all ? combined : deduplicateRows(combined, leftCols);
-  const result = { type: "SELECT", rows, columns: leftCols, rowCount: rows.length };
-  if (captureColumnMeta) {
-    materializedMetaBySelectResult.set(result, mergeUnionColumnMeta(leftResult, rightResult));
-  }
-  return result;
 }
 function deduplicateRows(rows, columns) {
   const seen = /* @__PURE__ */ new Set();
@@ -18540,6 +18653,7 @@ async function fetchTableRecordsForFullScan(stmt, table, client, maxRecords, par
   const fields = selectToFetchAllFields(stmt, table, plainGroupByPlan);
   const onTruncate = (max) => {
     warnings.add(`\u53D6\u5F97\u4E0A\u9650\uFF08${max} \u4EF6\uFF09\u306B\u9054\u3057\u305F\u305F\u3081\u3001${max} \u4EF6\u3067\u6253\u3061\u5207\u3063\u3066\u8868\u793A\u3057\u3066\u3044\u307E\u3059\u3002`);
+    markLimitReached(client, table.appId);
   };
   if (!table.subtableCode) {
     const baseQuery = isMainTable && allowOriginalWherePushdown ? selectToFetchAllParams(stmt, table.appId).query : "";
@@ -18695,6 +18809,7 @@ async function tryFetchJoinRecordsBySourceKeys(stmt, join2, tables, client, maxR
   const fields = selectToFetchAllFields(stmt, join2.table, plainGroupByPlan);
   const onTruncate = (max) => {
     warnings.add(`\u53D6\u5F97\u4E0A\u9650\uFF08${max} \u4EF6\uFF09\u306B\u9054\u3057\u305F\u305F\u3081\u3001${max} \u4EF6\u3067\u6253\u3061\u5207\u3063\u3066\u8868\u793A\u3057\u3066\u3044\u307E\u3059\u3002`);
+    markLimitReached(client, join2.table.appId);
   };
   const chunks = splitChunks(values, JOIN_IN_CHUNK_SIZE);
   const merged = [];
@@ -22714,11 +22829,12 @@ function buildValidatePlan(stmt, label) {
   lines.push("  records/mutation API during EXPLAIN: none; violation count unavailable");
   return lines;
 }
-function buildSelectPlan(stmt, label, capabilities, orderPlans, plainGroupByPlans) {
+function buildSelectPlan(stmt, label, capabilities, orderPlans, plainGroupByPlans, allowTotalCountPlan = true) {
   const whereCapability = capabilities?.get(stmt) ?? (capabilities ? [...capabilities].find(([candidate]) => JSON.stringify(candidate) === JSON.stringify(stmt))?.[1] : void 0);
   const orderPlan = orderPlans?.get(stmt) ?? (orderPlans ? [...orderPlans].find(([candidate]) => JSON.stringify(candidate) === JSON.stringify(stmt))?.[1] : void 0);
   const plainGroupByPlan = plainGroupByPlans?.get(stmt) ?? (plainGroupByPlans ? [...plainGroupByPlans].find(([candidate]) => JSON.stringify(candidate) === JSON.stringify(stmt))?.[1] : void 0);
-  const mode = orderPlan?.kind === "CANONICAL_LOCAL" ? "FULL_SCAN" : whereCapability && whereCapability.capability !== "EXACT_PUSHDOWN" ? "FULL_SCAN" : resolveSelectMode(stmt);
+  const totalCountPlan = allowTotalCountPlan && whereCapability !== void 0 && isCountStarTotalCountEligible(stmt, whereCapability);
+  const mode = totalCountPlan ? "COUNT_TOTAL_COUNT" : orderPlan?.kind === "CANONICAL_LOCAL" ? "FULL_SCAN" : whereCapability && whereCapability.capability !== "EXACT_PUSHDOWN" ? "FULL_SCAN" : resolveSelectMode(stmt);
   const reasons = collectFullScanReasons(stmt);
   if (whereCapability && whereCapability.capability !== "EXACT_PUSHDOWN") {
     reasons.push(...whereCapability.reasons.map((reason) => reason.code));
@@ -22765,6 +22881,20 @@ function buildSelectPlan(stmt, label, capabilities, orderPlans, plainGroupByPlan
       }
     }
   }
+  if (totalCountPlan) {
+    const baseQuery = stmt.where === null ? "" : whereToKintone(stmt.where);
+    lines.push(`  app:           APP${stmt.from.appId} (${stmt.from.appId})`);
+    lines.push(
+      `  kintone query: ${baseQuery}${baseQuery ? " " : ""}limit 1`
+    );
+    lines.push("  fields:        $id");
+    lines.push("  fetch API:     GET records.json (totalCount=true)");
+    lines.push("  REST execution: single GET");
+    lines.push("  record limit:  maxRecords/onLimitReached not applied");
+    lines.push("  fallback:      full record scan when totalCount is missing or invalid");
+    lines.push("  search abort:  fail-closed (SearchAbortedError)");
+    return lines;
+  }
   if (orderPlan) {
     lines.push(`  order plan:    ${orderPlan.kind}`);
     if (orderPlan.reasonCodes.length > 0) lines.push(`  order reason:  ${orderPlan.reasonCodes.join(", ")}`);
@@ -22901,7 +23031,7 @@ function buildUnionPlan(stmt, capabilities, orderPlans, plainGroupByPlans) {
   const lines = [];
   selects.forEach((sel, i) => {
     if (i > 0) lines.push("");
-    lines.push(...buildSelectPlan(sel, `[union:${i + 1}]`, capabilities, orderPlans, plainGroupByPlans));
+    lines.push(...buildSelectPlan(sel, `[union:${i + 1}]`, capabilities, orderPlans, plainGroupByPlans, false));
   });
   return lines;
 }
@@ -22909,7 +23039,7 @@ function buildWithPlan(stmt, capabilities, orderPlans, plainGroupByPlans) {
   const lines = [];
   for (const cte of stmt.ctes) {
     if (cte.query.type === "SELECT") {
-      lines.push(...buildSelectPlan(cte.query, `[cte: ${cte.name}]`, capabilities, orderPlans, plainGroupByPlans));
+      lines.push(...buildSelectPlan(cte.query, `[cte: ${cte.name}]`, capabilities, orderPlans, plainGroupByPlans, false));
       lines.push("");
     }
   }
@@ -22928,7 +23058,7 @@ function buildWithPlan(stmt, capabilities, orderPlans, plainGroupByPlans) {
   if (canInlineSingleCte(stmt)) {
     lines.push("");
     const inlined = buildInlinedQuery(stmt);
-    lines.push(...buildSelectPlan(inlined, "[effective: inlined CTE]", capabilities, orderPlans, plainGroupByPlans));
+    lines.push(...buildSelectPlan(inlined, "[effective: inlined CTE]", capabilities, orderPlans, plainGroupByPlans, false));
   }
   return lines;
 }
@@ -22970,16 +23100,16 @@ function collectSubqueryPlans(stmt, capabilities, orderPlans, plainGroupByPlans)
       case "BINARY":
         if (w.right.type === "SCALAR_SUBQUERY") {
           lines.push("");
-          lines.push(...buildSelectPlan(w.right.query, `[subquery:${idx++}]`, capabilities, orderPlans, plainGroupByPlans));
+          lines.push(...buildSelectPlan(w.right.query, `[subquery:${idx++}]`, capabilities, orderPlans, plainGroupByPlans, false));
         }
         if (w.right.type === "SUBQUERY_IN_LIST") {
           lines.push("");
-          lines.push(...buildSelectPlan(w.right.query, `[subquery:${idx++}]`, capabilities, orderPlans, plainGroupByPlans));
+          lines.push(...buildSelectPlan(w.right.query, `[subquery:${idx++}]`, capabilities, orderPlans, plainGroupByPlans, false));
         }
         break;
       case "EXISTS":
         lines.push("");
-        lines.push(...buildSelectPlan(w.query, `[subquery:${idx++}]`, capabilities, orderPlans, plainGroupByPlans));
+        lines.push(...buildSelectPlan(w.query, `[subquery:${idx++}]`, capabilities, orderPlans, plainGroupByPlans, false));
         break;
       case "LOGICAL":
         visitWhere(w.left);
@@ -22999,7 +23129,7 @@ function collectSubqueryPlans(stmt, capabilities, orderPlans, plainGroupByPlans)
   for (const col of stmt.columns) {
     if (col.type === "SCALAR_SUBQUERY_COL") {
       lines.push("");
-      lines.push(...buildSelectPlan(col.query, `[subquery:${idx++}]`, capabilities, orderPlans, plainGroupByPlans));
+      lines.push(...buildSelectPlan(col.query, `[subquery:${idx++}]`, capabilities, orderPlans, plainGroupByPlans, false));
     }
   }
   if (stmt.having) visitWhere(stmt.having);
@@ -23025,7 +23155,7 @@ function buildInsertSelectPlan(stmt, label, capabilities, orderPlans, plainGroup
   lines.push(`  fields:  ${stmt.fields.join(", ")}`);
   lines.push(`  api:     POST /k/v1/records.json\uFF08\u4EF6\u6570\u306F SELECT \u7D50\u679C\u306B\u4F9D\u5B58\u3001100 \u4EF6\u3054\u3068\u306B\u30D0\u30C3\u30C1\uFF09`);
   lines.push("");
-  lines.push(...buildSelectPlan(stmt.select, "[source SELECT]", capabilities, orderPlans, plainGroupByPlans));
+  lines.push(...buildSelectPlan(stmt.select, "[source SELECT]", capabilities, orderPlans, plainGroupByPlans, false));
   return lines;
 }
 function buildUpdatePlan(stmt, label, capabilities, orderPlans, dmlMaxRows = 100, dmlMaxSubtableRows = DEFAULT_APPLY_MAX_SUBTABLE_ROWS, maxRecords = 1e4) {
@@ -23072,7 +23202,7 @@ function buildUpdatePlan(stmt, label, capabilities, orderPlans, dmlMaxRows = 100
   for (const a of stmt.assignments) {
     if (a.value.type === "SCALAR_SUBQUERY") {
       lines.push("");
-      lines.push(...buildSelectPlan(a.value.query, `[subquery: ${a.field}]`, capabilities, orderPlans));
+      lines.push(...buildSelectPlan(a.value.query, `[subquery: ${a.field}]`, capabilities, orderPlans, void 0, false));
     }
   }
   return lines;
@@ -23189,7 +23319,7 @@ function buildUpsertSelectPlan(stmt, label, capabilities, orderPlans, plainGroup
     `  api:        GET /k/v1/records.json\uFF08\u91CD\u8907\u5224\u5B9A\uFF09\u2192 POST \u307E\u305F\u306F PUT /k/v1/records.json\uFF08100 \u4EF6\u3054\u3068\u306B\u30D0\u30C3\u30C1\uFF09`,
     ``
   ];
-  lines.push(...buildSelectPlan(stmt.select, "[source SELECT]", capabilities, orderPlans, plainGroupByPlans));
+  lines.push(...buildSelectPlan(stmt.select, "[source SELECT]", capabilities, orderPlans, plainGroupByPlans, false));
   return lines;
 }
 function buildReorderPlan(stmt, label) {
@@ -24493,7 +24623,8 @@ function createNodeKintoneConnection(baseUrl, tokenResolver) {
       const queryPart = `query=${encodeURIComponent(params.query)}`;
       const appPart = `app=${encodeURIComponent(String(params.app))}`;
       const fieldParts = params.fields.map((f) => `fields[]=${encodeURIComponent(f)}`);
-      const qs = [appPart, queryPart, ...fieldParts].join("&");
+      const totalCountPart = params.totalCount === true ? ["totalCount=true"] : [];
+      const qs = [appPart, queryPart, ...fieldParts, ...totalCountPart].join("&");
       if (tokenResolver.debug) {
         tokenResolver.log?.(
           `[debug] getRecords app=${params.app} query="${params.query}" fields=${params.fields.length > 0 ? params.fields.join(",") : "(all)"} auth=${tokenResolver.auth.type}`