@rex0220/kintone-sql-tools 3.72.0 → 3.74.0

package/README.md

@@ -289,6 +289,15 @@ try {
 }
 ```
 
+読取上限は既定 10,000 件（`maxRecords`）です。一時テーブルの実体化には**独立の** `tempTableMaxRows`（既定 10,000 行・超過は常にエラー）が適用されるため、大きなバッチでは両方を併せて指定してください:
+
+```ts
+const ctx = createExecutionContext({ client, script: source, maxRecords: 25000, tempTableMaxRows: 25000 });
+await explainScript(source, { client, maxRecords: 25000 }); // EXPLAIN 面にも同じ上限を渡せる
+```
+
+`executeStatement` / `previewStatement` は実行コンテキストの `maxRecords` を共有します（3 面同値）。詳細は[言語リファレンス §27.9](docs/ksql_language_reference.md)。
+
 ### エンジンバージョン × dialect 対応表
 
 | エンジン | dialect 0（既定・宣言なし） | dialect 1（`-- @ksql dialect: 1`） | ksql-flow |

package/dist-cli/ksql.js

@@ -18466,6 +18466,24 @@ var materializedMetaBySelectResult = /* @__PURE__ */ new WeakMap();
 var materializedMetaByValidationResult = /* @__PURE__ */ new WeakMap();
 var importSourceByDmlStatement = /* @__PURE__ */ new WeakMap();
 var statementEvaluationContextKey = /* @__PURE__ */ Symbol("statementEvaluationContext");
+var nativeUpsertExecutionKey = /* @__PURE__ */ Symbol("nativeUpsertExecution");
+var nativeUpsertExplainCapabilityKey = /* @__PURE__ */ Symbol("nativeUpsertExplainCapability");
+function withNativeUpsertExecutionOption(options, enabled, explainClientCapability) {
+  return {
+    ...options,
+    [nativeUpsertExecutionKey]: enabled,
+    ...explainClientCapability === void 0 ? {} : { [nativeUpsertExplainCapabilityKey]: explainClientCapability }
+  };
+}
+function nativeUpsertExecutionEnabled(options) {
+  return options[nativeUpsertExecutionKey] === true;
+}
+function hasNativeUpsertExecutionOption(options) {
+  return nativeUpsertExecutionKey in options;
+}
+function nativeUpsertExplainClientCapability(options) {
+  return options[nativeUpsertExplainCapabilityKey];
+}
 function bindStatementEvaluationContext(options) {
   const internal = options;
   if (internal[statementEvaluationContextKey]) return options;
@@ -18530,6 +18548,7 @@ function createEmptyMetrics() {
     getCalls: 0,
     postCalls: 0,
     putCalls: 0,
+    nativeUpsertCalls: 0,
     deleteCalls: 0,
     fieldCalls: 0,
     numberPrecisionCalls: 0,
@@ -18558,7 +18577,7 @@ function markLimitReached(client, appId) {
   if (!metrics.limitReachedApps.includes(appId)) metrics.limitReachedApps.push(appId);
 }
 function wrapClientWithMetrics(client, metrics) {
-  return {
+  const wrapped = {
     [LIMIT_METRICS_SINK]: metrics,
     getRecords: async (params) => {
       metrics.getCalls += 1;
@@ -18637,6 +18656,14 @@ function wrapClientWithMetrics(client, metrics) {
       return client.getProcessStatuses(appId);
     }
   };
+  if (clientHasNativeUpsert(client)) {
+    wrapped.upsertRecords = (params) => {
+      metrics.putCalls += 1;
+      metrics.nativeUpsertCalls += 1;
+      return client.upsertRecords(params);
+    };
+  }
+  return wrapped;
 }
 var SEARCH_ABORT_FAIL_CLOSED = /* @__PURE__ */ Symbol("searchAbortFailClosed");
 function wrapClientWithSearchAbort(client, collector, failClosed) {
@@ -18809,7 +18836,13 @@ async function executeParsedStatement(stmt, client, options, cacheContext) {
         relativeDatePlan,
         options.recursiveCteMaxDepth,
         options.recursiveCteMaxRows,
-        options.recursiveCteMaxExpansions
+        options.recursiveCteMaxExpansions,
+        options.resolveMetadata !== false,
+        hasNativeUpsertExecutionOption(options) ? {
+          surface: "CLI",
+          enableNativeUpsert: nativeUpsertExecutionEnabled(options),
+          clientHasNativeUpsert: nativeUpsertExplainClientCapability(options) ?? clientHasNativeUpsert(client)
+        } : { surface: "DOCUMENT_ONLY" }
       );
     // 一時テーブルはバッチスコープのため単文実行では拒否する（executeBatch を使う）
     case "CREATE_TEMP_TABLE":
@@ -22813,6 +22846,206 @@ function upsertCompositeKey(parts) {
 function upsertNormalizedKey(parts, numericKey) {
   return JSON.stringify(parts.map((p, i) => numericKey[i] ? normalizeKeyPart(p) : p));
 }
+var NATIVE_UPSERT_CONDITION_NAMES = {
+  1: "CLIENT_CAPABILITY",
+  2: "OPT_IN",
+  3: "KEY_SCHEMA",
+  4: "PLAIN_UPSERT",
+  5: "EMPTY_KEY",
+  6: "SOURCE_DUPLICATE"
+};
+function nativeUpsertExplainReason(condition, unknown, surface, unknownConditions = []) {
+  if (unknown) {
+    if (condition === 1) return "\u901A\u5E38\u5B9F\u884C client \u306E native \u80FD\u529B\u304C\u4E0D\u660E";
+    if (condition === 2) return "native \u8A2D\u5B9A\u304C\u4E0D\u660E";
+    if (condition === 3) return "\u30D5\u30A9\u30FC\u30E0\u30E1\u30BF\u30C7\u30FC\u30BF\u672A\u53D6\u5F97";
+    if (condition === 5 || unknownConditions.includes(5)) return "\u30BD\u30FC\u30B9\u884C\u672A materialize";
+    if (condition === 6) return "\u30AD\u30FC\u578B\u60C5\u5831\u304C\u672A\u78BA\u5B9A\u306E\u305F\u3081\u91CD\u8907\u5224\u5B9A\u4E0D\u80FD";
+  }
+  if (condition === 1) return "client \u304C upsertRecords \u80FD\u529B\u3092\u6301\u305F\u306A\u3044";
+  if (condition === 2) return surface === "CLI" ? "--native-upsert \u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u306A\u3044" : "enableNativeUpsert \u304C false";
+  if (condition === 3) return "\u30AD\u30FC\u9805\u76EE\u306F\u91CD\u8907\u7981\u6B62\u306E SINGLE_LINE_TEXT \u307E\u305F\u306F NUMBER \u3067\u306F\u306A\u3044";
+  if (condition === 4) return "CHECK / APPLY / IMPORT / VALIDATE ONLY / ON ERROR SKIP \u3092\u4F34\u3046\u7D20\u3067\u306A\u3044 UPSERT";
+  if (condition === 5) return "\u30BD\u30FC\u30B9\u306B\u7A7A\u6587\u5B57\u30AD\u30FC\u304C\u3042\u308B";
+  return "\u30BD\u30FC\u30B9\u5185\u306B\u540C\u4E00\u30AD\u30FC\u304C\u3042\u308B";
+}
+function renderNativeUpsertEligibilityResult(label, result, surface) {
+  if (result.status === "ELIGIBLE") {
+    return `  ${label}: ELIGIBLE\uFF08${label.includes("statement/data") ? "\u6761\u4EF6 3\u301C6 \u3092" : "6 \u6761\u4EF6\u3092\u3059\u3079\u3066"}\u6E80\u305F\u3059\uFF09`;
+  }
+  if (result.status === "INELIGIBLE") {
+    return `  ${label}: INELIGIBLE\uFF08\u6761\u4EF6 ${result.condition}: ${NATIVE_UPSERT_CONDITION_NAMES[result.condition]} \u2014 ${nativeUpsertExplainReason(result.condition, false, surface)}\uFF09`;
+  }
+  const unknownConditionNumbers = result.unknownConditions.map(({ condition }) => condition);
+  const details = result.unknownConditions.map(
+    ({ condition }) => `\u6761\u4EF6 ${condition}: ${NATIVE_UPSERT_CONDITION_NAMES[condition]} \u2014 ${nativeUpsertExplainReason(condition, true, surface, unknownConditionNumbers)}`
+  );
+  return `  ${label}: UNKNOWN\uFF08${details.join("; ")}\uFF09`;
+}
+function renderNativeUpsertEligibility(evaluation, surface) {
+  if (surface === "DOCUMENT_ONLY") {
+    return [
+      renderNativeUpsertEligibilityResult("native UPSERT statement/data eligibility", evaluation.statement, surface),
+      `  native UPSERT execution surface: NOT_APPLICABLE\uFF08\u3053\u306E\u9762\u3067\u306F\u5B9F\u884C\u3057\u306A\u3044${evaluation.statement.status === "ELIGIBLE" ? "\u3002/flow \u307E\u305F\u306F CLI --native-upsert \u3067\u306F native \u5019\u88DC" : ""}\uFF09`
+    ];
+  }
+  const lines = [renderNativeUpsertEligibilityResult("native UPSERT eligibility", evaluation.execution, surface)];
+  if (evaluation.conditions[1].state === "FAIL" || evaluation.conditions[2].state === "FAIL") {
+    lines.push(renderNativeUpsertEligibilityResult("native UPSERT statement/data eligibility", evaluation.statement, surface));
+  }
+  return lines;
+}
+function explainNativeUpsertStatement(statement) {
+  const candidate = statement.type === "EXPLAIN" ? statement.query : statement;
+  return candidate.type === "UPSERT" || candidate.type === "UPSERT_SELECT" ? candidate : null;
+}
+function nativeUpsertExplainEvaluation(statement, fieldInfos, options) {
+  let rowKeyValues = null;
+  if (statement.type === "UPSERT") {
+    try {
+      rowKeyValues = buildUpsertRowKeyValues(statement);
+    } catch {
+    }
+  }
+  return evaluateNativeUpsertEligibility({
+    surface: options.surface === "DOCUMENT_ONLY" ? "DOCUMENT_ONLY" : "EXECUTION",
+    clientCapability: options.surface === "DOCUMENT_ONLY" ? null : options.clientHasNativeUpsert ?? null,
+    enabled: options.surface === "DOCUMENT_ONLY" ? null : options.surface === "FLOW" ? options.enableNativeUpsert !== false : options.enableNativeUpsert === true,
+    statement: {
+      kind: statement.type === "UPSERT" ? "VALUES" : "SELECT",
+      keyFields: statement.keyFields,
+      hasCheck: Boolean(statement.checkGroups?.length),
+      hasApply: statement.type === "UPSERT" && Boolean(statement.onInsertApplyBlocks?.length || statement.onUpdateApplyBlocks?.length),
+      validateOnly: statement.validateOnly === true,
+      onErrorSkip: statement.onErrorSkip === true,
+      importDerived: importSourceByDmlStatement.has(statement)
+    },
+    fieldInfos,
+    rowKeyValues
+  });
+}
+async function nativeUpsertExplainLines(statement, cacheContext, options) {
+  const upsert = explainNativeUpsertStatement(statement);
+  if (!upsert) return [];
+  const fieldInfos = await getFieldsIfCached(upsert.appId, cacheContext);
+  return renderNativeUpsertEligibility(
+    nativeUpsertExplainEvaluation(upsert, fieldInfos, options),
+    options.surface
+  );
+}
+function evaluateNativeUpsertEligibility(input) {
+  const keyField = input.statement.keyFields.length === 1 ? input.statement.keyFields[0] : void 0;
+  const keyInfo = keyField === void 0 || input.fieldInfos === null ? void 0 : input.fieldInfos.find((field) => field.code === keyField);
+  const supportedKeyType = keyInfo?.fieldType === "SINGLE_LINE_TEXT" || keyInfo?.fieldType === "NUMBER";
+  const schemaPass = input.fieldInfos === null ? null : Boolean(
+    keyField !== void 0 && keyInfo && supportedKeyType && keyInfo.isUnique === true
+  );
+  const plain = !input.statement.hasCheck && !input.statement.hasApply && !input.statement.validateOnly && !input.statement.onErrorSkip && !(input.statement.kind === "SELECT" && input.statement.importDerived);
+  const rows = input.rowKeyValues;
+  const noEmpty = rows === null ? null : rows.every((parts) => parts.every((part) => part !== ""));
+  let noDuplicates = null;
+  if (rows !== null && keyField !== void 0 && supportedKeyType) {
+    const seen = /* @__PURE__ */ new Set();
+    noDuplicates = true;
+    for (const parts of rows) {
+      const normalized = upsertNormalizedKey([...parts], [keyInfo.fieldType === "NUMBER"]);
+      if (seen.has(normalized)) {
+        noDuplicates = false;
+        break;
+      }
+      seen.add(normalized);
+    }
+  }
+  const state = (value, reason) => ({
+    state: value === null ? "UNKNOWN" : value ? "PASS" : "FAIL",
+    reason
+  });
+  const conditions = {
+    1: input.surface === "DOCUMENT_ONLY" ? { state: "NOT_APPLICABLE", reason: "client capability is not applicable on this surface" } : state(input.clientCapability, "client does not provide upsertRecords"),
+    2: input.surface === "DOCUMENT_ONLY" ? { state: "NOT_APPLICABLE", reason: "native setting is not applicable on this surface" } : state(input.enabled, "native UPSERT is disabled"),
+    3: state(schemaPass, "update key schema is not a single unique text or number field"),
+    4: state(plain, "statement is not a plain UPSERT"),
+    5: state(noEmpty, "source contains an empty update key"),
+    6: state(noDuplicates, "source contains duplicate update keys")
+  };
+  const summarize = (ordered) => {
+    const failed = ordered.find((condition) => conditions[condition].state === "FAIL");
+    if (failed !== void 0) return { status: "INELIGIBLE", condition: failed, reason: conditions[failed].reason };
+    const unknownConditions = ordered.filter((condition) => conditions[condition].state === "UNKNOWN").map((condition) => ({ condition, reason: conditions[condition].reason }));
+    return unknownConditions.length > 0 ? { status: "UNKNOWN", unknownConditions } : { status: "ELIGIBLE" };
+  };
+  return {
+    conditions,
+    execution: summarize([1, 2, 3, 4, 5, 6]),
+    statement: summarize([3, 4, 5, 6])
+  };
+}
+function clientHasNativeUpsert(client) {
+  return "upsertRecords" in client && typeof client.upsertRecords === "function";
+}
+function nativeEligibilityInput(stmt, client, options, fieldInfos, rowKeyValues) {
+  return {
+    surface: "EXECUTION",
+    clientCapability: clientHasNativeUpsert(client),
+    enabled: nativeUpsertExecutionEnabled(options),
+    statement: {
+      kind: stmt.type === "UPSERT" ? "VALUES" : "SELECT",
+      keyFields: stmt.keyFields,
+      hasCheck: Boolean(stmt.checkGroups?.length),
+      hasApply: stmt.type === "UPSERT" && Boolean(stmt.onInsertApplyBlocks?.length || stmt.onUpdateApplyBlocks?.length),
+      validateOnly: stmt.validateOnly === true,
+      onErrorSkip: stmt.onErrorSkip === true,
+      importDerived: importSourceByDmlStatement.has(stmt)
+    },
+    fieldInfos,
+    rowKeyValues
+  };
+}
+var NativeUpsertResponseError = class extends Error {
+  constructor() {
+    super("NativeUpsertResponseError: upsertRecords returned an invalid response.");
+    this.name = "NativeUpsertResponseError";
+  }
+};
+function validateNativeUpsertResponse(response, expectedRecords) {
+  if (!response || !Array.isArray(response.records) || response.records.length !== expectedRecords) {
+    throw new NativeUpsertResponseError();
+  }
+  let insertedCount = 0;
+  let updatedCount = 0;
+  for (const record of response.records) {
+    if (!record || typeof record.id !== "string" || typeof record.revision !== "string" || record.operation !== "INSERT" && record.operation !== "UPDATE") {
+      throw new NativeUpsertResponseError();
+    }
+    if (record.operation === "INSERT") insertedCount += 1;
+    else updatedCount += 1;
+  }
+  return { insertedCount, updatedCount };
+}
+async function executeNativeUpsertRecords(appId, keyField, records, rowKeyValues, client, options) {
+  if (records.length === 0) return { type: "UPSERT", insertedCount: 0, updatedCount: 0 };
+  if (options.confirm) {
+    const ok = await options.confirm(records.length, "UPDATE");
+    if (!ok) throw new OperationCancelledError("UPDATE", records.length);
+  }
+  let insertedCount = 0;
+  let updatedCount = 0;
+  for (let offset = 0; offset < records.length; offset += 100) {
+    const nativeRecords = records.slice(offset, offset + 100).map((record, index) => {
+      const payload = {};
+      for (const [field, value] of Object.entries(record)) if (field !== keyField) payload[field] = value;
+      return {
+        updateKey: { field: keyField, value: rowKeyValues[offset + index][0] },
+        record: payload
+      };
+    });
+    const response = await client.upsertRecords({ app: appId, upsert: true, records: nativeRecords });
+    const counts = validateNativeUpsertResponse(response, nativeRecords.length);
+    insertedCount += counts.insertedCount;
+    updatedCount += counts.updatedCount;
+  }
+  return { type: "UPSERT", insertedCount, updatedCount };
+}
 function lookupUpsertTarget(index, keyParts) {
   const exact = index.raw.get(upsertCompositeKey(keyParts));
   if (exact !== void 0) return exact;
@@ -23029,6 +23262,10 @@ async function getFieldsCached(appId, client, cacheContext) {
   setScopedCacheValue(fieldInfoCache, cacheContext, appId, loading);
   return loading;
 }
+async function getFieldsIfCached(appId, cacheContext) {
+  const cached = getScopedCacheValue(fieldInfoCache, cacheContext, appId);
+  return cached ? await cached : null;
+}
 async function getNumberPrecisionCached(appId, client, cacheContext) {
   const cached = getScopedCacheValue(numberPrecisionCache, cacheContext, appId);
   if (cached) return cached;
@@ -25596,6 +25833,16 @@ async function executeDelete(stmt, client, options, cacheContext) {
   }
   return { type: "DELETE", deletedCount: ids.length };
 }
+function materializeUpsertValueRecords(stmt, fieldTypes, options) {
+  return stmt.values.map((row) => {
+    const record = {};
+    stmt.fields.forEach((field, index) => {
+      const value = row[index];
+      record[field] = { value: value.type === "CASE_VALUE" ? evalCaseWhenValue(value.expr, {}, fieldTypes.get(field), statementEvaluationContext(options)) : toKintoneValue(value, fieldTypes.get(field)) };
+    });
+    return record;
+  });
+}
 async function executeUpsert(stmt, client, options, cacheContext) {
   if (stmt.onInsertApplyBlocks?.length || stmt.onUpdateApplyBlocks?.length) {
     return executeApplyUpsert(stmt, client, options, cacheContext);
@@ -25607,6 +25854,14 @@ async function executeUpsert(stmt, client, options, cacheContext) {
   const toUpdate = [];
   const fieldTypes = await getFieldTypeMap(stmt.appId, client, cacheContext);
   const rowKeyValues = buildUpsertRowKeyValues(stmt);
+  const nativeEligibility = evaluateNativeUpsertEligibility(
+    nativeEligibilityInput(stmt, client, options, fieldInfos, rowKeyValues)
+  );
+  if (nativeEligibility.execution.status === "ELIGIBLE") {
+    const records = materializeUpsertValueRecords(stmt, fieldTypes, options);
+    assertValidDmlRecords(records, stmt.fields, fieldInfos, numberPrecision);
+    return executeNativeUpsertRecords(stmt.appId, stmt.keyFields[0], records, rowKeyValues, client, options);
+  }
   const targetIndex = await resolveUpsertTargets(stmt.appId, stmt.keyFields, rowKeyValues, client, options, fieldTypes);
   stmt.values.forEach((row, rowIdx) => {
     const record = {};
@@ -26095,6 +26350,12 @@ async function executeUpsertSelect(stmt, client, options, cacheContext, cteCache
   const rowKeyValues = records.map(
     (record) => stmt.keyFields.map((key) => String(record[key]?.value ?? ""))
   );
+  const nativeEligibility = evaluateNativeUpsertEligibility(
+    nativeEligibilityInput(stmt, client, options, fieldInfos, rowKeyValues)
+  );
+  if (nativeEligibility.execution.status === "ELIGIBLE") {
+    return executeNativeUpsertRecords(stmt.appId, stmt.keyFields[0], records, rowKeyValues, client, options);
+  }
   if (importSourceByDmlStatement.has(stmt)) {
     const numericKey = stmt.keyFields.map((key) => fieldTypes.get(key) === "NUMBER");
     const sourceKeys = /* @__PURE__ */ new Set();
@@ -26524,6 +26785,10 @@ async function buildExplainWhereAnalysis(query, client, cacheContext, maxRecords
       return;
     }
     const typed = node;
+    if (typed["type"] === "UPSERT" || typed["type"] === "UPSERT_SELECT") {
+      const upsert = node;
+      await getFieldsCached(upsert.appId, tracedClient, cacheContext);
+    }
     if (typed["type"] === "SELECT") {
       const select = node;
       await validateSelectGroupingPlanning(select, tracedClient, cacheContext);
@@ -27146,7 +27411,7 @@ var EXPLAIN_FETCH_PLAN = /* @__PURE__ */ Symbol("ksql.explainFetchPlan");
 function setExplainFetchPlan(result, plan) {
   result[EXPLAIN_FETCH_PLAN] = plan;
 }
-async function buildBatchExplainPlans(sql, client, injectedVariables, cacheContext = "batch-explain", maxRecords = 1e4, cursorMaxActive = 2, enableImport = false, dmlMaxRows = 100, dmlMaxSubtableRows = DEFAULT_APPLY_MAX_SUBTABLE_ROWS, resolveMetadata = true, recursiveCteMaxDepth, recursiveCteMaxRows, recursiveCteMaxExpansions, asOf, timezone) {
+async function buildBatchExplainPlans(sql, client, injectedVariables, cacheContext = "batch-explain", maxRecords = 1e4, cursorMaxActive = 2, enableImport = false, dmlMaxRows = 100, dmlMaxSubtableRows = DEFAULT_APPLY_MAX_SUBTABLE_ROWS, resolveMetadata = true, recursiveCteMaxDepth, recursiveCteMaxRows, recursiveCteMaxExpansions, asOf, timezone, nativeUpsertOptions = { surface: "DOCUMENT_ONLY" }) {
   const asOfClock = createAsOfClock(asOf ?? /* @__PURE__ */ new Date(), timezone);
   const recursiveLimits = resolveRecursiveCteLimits({
     recursiveCteMaxDepth,
@@ -27245,10 +27510,15 @@ async function buildBatchExplainPlans(sql, client, injectedVariables, cacheConte
         maxRecords,
         dmlMaxRows
       ) : [];
+      const nativeUpsertPlan = await nativeUpsertExplainLines(
+        planStmt,
+        invocationCacheContext,
+        nativeUpsertOptions
+      );
       plans.push({
         index: i,
         type: analysis.statements[i].statementType,
-        plan: statementPlan.length === 0 ? [...metadataPlan, ...dialect1Estimate] : [statementPlan[0], ...metadataPlan, ...statementPlan.slice(1), ...dialect1Estimate]
+        plan: statementPlan.length === 0 ? [...metadataPlan, ...nativeUpsertPlan, ...dialect1Estimate] : [statementPlan[0], ...metadataPlan, ...statementPlan.slice(1), ...nativeUpsertPlan, ...dialect1Estimate]
       });
       fetchStatements.push({
         index: i,
@@ -27562,21 +27832,29 @@ var explainMaterializedTables = /* @__PURE__ */ new WeakMap();
 function defaultRecursiveExplainContext() {
   return { maxRecords: 1e4, recursiveLimits: resolveRecursiveCteLimits({}) };
 }
-async function executeExplain(stmt, client, cacheContext, maxRecords, cursorMaxActive, dmlMaxRows = 100, dmlMaxSubtableRows = DEFAULT_APPLY_MAX_SUBTABLE_ROWS, relativeDatePlan, recursiveCteMaxDepth, recursiveCteMaxRows, recursiveCteMaxExpansions) {
+async function executeExplain(stmt, client, cacheContext, maxRecords, cursorMaxActive, dmlMaxRows = 100, dmlMaxSubtableRows = DEFAULT_APPLY_MAX_SUBTABLE_ROWS, relativeDatePlan, recursiveCteMaxDepth, recursiveCteMaxRows, recursiveCteMaxExpansions, resolveMetadata = true, nativeUpsertOptions = { surface: "DOCUMENT_ONLY" }) {
   const recursiveLimits = resolveRecursiveCteLimits({
     recursiveCteMaxDepth,
     recursiveCteMaxRows,
     recursiveCteMaxExpansions
   });
   const sharedPlan = relativeDatePlan ?? await resolveRelativeDateExecutionPlan(stmt.query, client, cacheContext);
-  const analysis = await buildExplainWhereAnalysis(
+  const analysis = resolveMetadata ? await buildExplainWhereAnalysis(
     stmt.query,
     client,
     cacheContext,
     maxRecords,
     sharedPlan,
     explainMaterializedTables.get(stmt)
-  );
+  ) : {
+    capabilities: /* @__PURE__ */ new Map(),
+    orderPlans: /* @__PURE__ */ new Map(),
+    plainGroupByPlans: /* @__PURE__ */ new Map(),
+    fieldApps: /* @__PURE__ */ new Set(),
+    processStatusApps: /* @__PURE__ */ new Set(),
+    numberPrecisionApps: /* @__PURE__ */ new Set(),
+    relativeDatePlan: sharedPlan
+  };
   const fetchCollector = { sources: [] };
   const relativeLines = relativeDateExplainLines(sharedPlan);
   const planLines = sharedPlan.hasServerOnlyWhereFunction && !sharedPlan.allowed ? [...explainMetadataLines(analysis), ...relativeLines] : [
@@ -27600,7 +27878,8 @@ async function executeExplain(stmt, client, cacheContext, maxRecords, cursorMaxA
       cursorMaxActive
     )
   ];
-  const lines = addFetchSummary(planLines, fetchCollector.sources);
+  const nativeUpsertPlan = await nativeUpsertExplainLines(stmt, cacheContext, nativeUpsertOptions);
+  const lines = addFetchSummary([...planLines, ...nativeUpsertPlan], fetchCollector.sources);
   const result = {
     type: "SELECT",
     columns: ["plan"],
@@ -29523,7 +29802,7 @@ var RequestGate = class {
   }
 };
 function withRequestGate(client, gate) {
-  return {
+  const wrapped = {
     getRecords: (params) => gate.runReadOnly(() => client.getRecords(params)),
     openCursor: async (params) => {
       const handle = await gate.runCursorStep(() => client.openCursor(params));
@@ -29541,6 +29820,10 @@ function withRequestGate(client, gate) {
     putRecords: (params) => gate.runMutation(() => client.putRecords(params)),
     deleteRecords: (params) => gate.runMutation(() => client.deleteRecords(params))
   };
+  if ("upsertRecords" in client && typeof client.upsertRecords === "function") {
+    wrapped.upsertRecords = (params) => gate.runMutation(() => client.upsertRecords(params));
+  }
+  return wrapped;
 }
 var globalGate = null;
 function getGlobalRequestGate(options) {
@@ -30297,6 +30580,16 @@ function createNodeKintoneConnection(baseUrl, tokenResolver) {
         _params.app
       );
     },
+    async upsertRecords(_params) {
+      return requestJson(
+        `${apiBasePath}/records.json`,
+        {
+          method: "PUT",
+          body: JSON.stringify({ app: _params.app, upsert: true, records: _params.records })
+        },
+        _params.app
+      );
+    },
     async deleteRecords(_params) {
       await requestJson(
         `${apiBasePath}/records.json`,
@@ -30696,6 +30989,9 @@ var CLI_HELP_TEXT = HELP_TEXT.replace(
   "  --max-records <n>          Max records to fetch (default: 500)",
   `  --max-records <n>          Max records to fetch (default: 500)
 ${RECURSIVE_CTE_HELP_LINES}`
+).replace(
+  "  --allow-dml                Enable UPDATE/DELETE/INSERT/UPSERT/REORDER execution",
+  "  --allow-dml                Enable UPDATE/DELETE/INSERT/UPSERT/REORDER execution\n  --native-upsert            Allow eligible plain UPSERT to use kintone native UPSERT"
 );
 var CLI_IMPORT_SOURCE_REQUIRED_MESSAGE = "IMPORT \u306B\u306F\u30BD\u30FC\u30B9\u304C\u5FC5\u8981\u3067\u3059\u3002--import-csv <name=path> \u307E\u305F\u306F --import-json <name=path> \u3067\u30D5\u30A1\u30A4\u30EB\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044\u3002";
 function toCliImportError(error, importEnabled) {
@@ -30747,6 +31043,7 @@ function parseArgs(argv) {
     debugHeaders: false,
     exitOnEmpty: false,
     allowDml: false,
+    nativeUpsert: false,
     yes: false,
     allowWithoutWhere: false,
     continueOnError: false,
@@ -30819,6 +31116,10 @@ function parseArgs(argv) {
       out.allowDml = true;
       continue;
     }
+    if (a === "--native-upsert") {
+      out.nativeUpsert = true;
+      continue;
+    }
     if (a === "--yes") {
       out.yes = true;
       continue;
@@ -31656,6 +31957,7 @@ function buildReplExecArgv(base, sql, dryRun, format) {
   if (base.exitOnEmpty) argv.push("--exit-on-empty");
   if (base.allowDml) argv.push("--yes");
   if (base.allowDml) argv.push("--allow-dml");
+  if (base.nativeUpsert) argv.push("--native-upsert");
   if (base.allowWithoutWhere) argv.push("--allow-without-where");
   if (base.continueOnError) argv.push("--continue-on-error");
   return argv;
@@ -31832,7 +32134,8 @@ async function runConsole(base) {
       `  auth=${base.auth ?? "(auto)"}`,
       `  format=${format ?? "(default)"}`,
       `  dryrun=${dryRun ? "on" : "off"}`,
-      `  allow-dml=${base.allowDml ? "on" : "off"}`
+      `  allow-dml=${base.allowDml ? "on" : "off"}`,
+      `  native-upsert=${base.nativeUpsert ? "on" : "off"}`
     ].join("\n") + "\n"
   );
   try {
@@ -31963,6 +32266,7 @@ async function runConsole(base) {
             `app=${base.app ?? "(from SQL or config)"}`,
             `resolved-app-profiles=${lastResolvedProfiles}`,
             `allow-dml=${base.allowDml ? "on" : "off"}`,
+            `native-upsert=${base.nativeUpsert ? "on" : "off"}`,
             `dml-max-rows=${base.dmlMaxRows ?? "(default)"}`,
             `dml-max-subtable-rows=${base.dmlMaxSubtableRows ?? "(default)"}`
           ];
@@ -32335,7 +32639,8 @@ async function run() {
     appProfileByApp.set(appId, appBindingByMappedApp.get(appId)?.profile ?? profileName.toLowerCase());
   }
   const cacheContext = buildCacheContext(profileName, appBindingByMappedApp);
-  if (args.dryRun && (!dryRunNeedsMetadata || dryRunUsesStaticTypedPlan)) {
+  const fullyOfflineDryRun = args.dryRun && (!dryRunNeedsMetadata || dryRunUsesStaticTypedPlan);
+  if (fullyOfflineDryRun) {
     client = createDryRunClient();
   } else {
     for (const explicitProfile of appProfileByApp.values()) {
@@ -32545,6 +32850,14 @@ async function run() {
         if (!routed) throw new Error(`AuthError: profile "${pName}" is not resolved for APP${params.app}.`);
         return routed.putRecords({ ...params, app: binding.appId });
       },
+      upsertRecords: (params) => {
+        const binding = appBindingByMappedApp.get(params.app) ?? { appId: params.app, profile: profileName.toLowerCase() };
+        const routed = profileClientMap.get(binding.profile);
+        if (!routed || typeof routed.upsertRecords !== "function") {
+          throw new Error(`AuthError: native UPSERT client is not resolved for APP${params.app}.`);
+        }
+        return routed.upsertRecords({ ...params, app: binding.appId });
+      },
       deleteRecords: (params) => {
         const binding = appBindingByMappedApp.get(params.app) ?? { appId: params.app, profile: profileName.toLowerCase() };
         const pName = binding.profile;
@@ -32595,10 +32908,17 @@ async function run() {
         Object.keys(args.importCsv).length > 0 || Object.keys(args.importJson).length > 0,
         dmlMaxRows,
         dmlMaxSubtableRows,
-        !dryRunUsesStaticTypedPlan,
+        !fullyOfflineDryRun,
         recursiveCteMaxDepth,
         recursiveCteMaxRows,
-        recursiveCteMaxExpansions
+        recursiveCteMaxExpansions,
+        void 0,
+        void 0,
+        {
+          surface: "CLI",
+          enableNativeUpsert: args.nativeUpsert,
+          clientHasNativeUpsert: true
+        }
       );
       const out = [];
       const restoredStatements = sqlDiagnosticContext ? restoreSqlDiagnosticValue(plans.statements, sqlDiagnosticContext.appBindingByMappedApp) : plans.statements;
@@ -32679,7 +32999,7 @@ query=${label}`);
           return 2;
         }
       }
-      let batchResult = await executeBatch(sql, client, {
+      let batchResult = await executeBatch(sql, client, withNativeUpsertExecutionOption({
         maxRecords,
         fetchParallel,
         onLimitReached: effectiveOnLimit,
@@ -32717,7 +33037,7 @@ query=${label}`);
           }
           return true;
         } : void 0
-      });
+      }, args.nativeUpsert, true));
       if (sqlDiagnosticContext) {
         batchResult = {
           ...batchResult,
@@ -32734,7 +33054,7 @@ query=${label}`);
       }
       return writeBatchOutput(batchResult, { format, noHeader, pretty, displayOptions, outputPath, quiet });
     }
-    let result = args.dryRun ? await execute(`EXPLAIN ${sql}`, client, {
+    let result = args.dryRun ? await execute(`EXPLAIN ${sql}`, client, withNativeUpsertExecutionOption({
       maxRecords,
       onLimitReached: onLimit,
       cacheContext,
@@ -32745,8 +33065,9 @@ query=${label}`);
       dmlMaxSubtableRows,
       recursiveCteMaxDepth,
       recursiveCteMaxRows,
-      recursiveCteMaxExpansions
-    }) : await execute(sql, client, {
+      recursiveCteMaxExpansions,
+      resolveMetadata: !fullyOfflineDryRun
+    }, args.nativeUpsert, true)) : await execute(sql, client, withNativeUpsertExecutionOption({
       maxRecords,
       fetchParallel,
       onLimitReached: effectiveOnLimit,
@@ -32764,7 +33085,7 @@ query=${label}`);
         dmlMaxSubtableRows
       } : {},
       ...containsApplyMutation ? { allowApplyMutation: true } : {}
-    });
+    }, args.nativeUpsert, true));
     if ((args.dryRun || parsedStatements[0]?.type === "EXPLAIN") && sqlDiagnosticContext) {
       result = restoreSqlDiagnosticValue(result, sqlDiagnosticContext.appBindingByMappedApp);
     }