@rex0220/kintone-sql-tools 3.69.0 → 3.71.0

package/README.md

@@ -267,7 +267,7 @@ npm パッケージは 2 つのサブパスを **semver 対象の公開 API**
 | サブパス | 用途 | 主な export |
 |---|---|---|
 | `@rex0220/kintone-sql-tools/engine` | **read-only** のクエリ実行（ダッシュボード等）。書込 API は構造的に遮断 | `runQuery` / `runBatch` / `explainQuery` / `createReadonlyKintoneClient` / `KsqlEngineError` / `version` |
-| `@rex0220/kintone-sql-tools/flow` | **Flow dialect 1**（→ [言語リファレンス §27](docs/ksql_language_reference.md)）のスクリプト解析・検証・**文単位実行**（バッチランナー向け・書込可能） | `parseScript` / `validateScript` / `explainScript` / `createExecutionContext` / `executeStatement` / `disposeExecutionContext` / `createKintoneClient` / `version` |
+| `@rex0220/kintone-sql-tools/flow` | **Flow dialect 1**（→ [言語リファレンス §27](docs/ksql_language_reference.md)）のスクリプト解析・検証・**文単位実行**（バッチランナー向け・書込可能） | `parseScript` / `validateScript` / `explainScript`（`asOf`/`timezone` 注入可） / `createExecutionContext`（`onChunkWritten` 書込チャンク通知） / `executeStatement` / `previewStatement`（dry-run 差分プレビュー・書込 0 回） / `disposeExecutionContext` / `createKintoneClient` / `isDmlResult`（`FlowDmlResult` 型ガード） / `version` |
 
 `/flow` の典型的な使い方（1 文ずつ実行して結果で継続判断する）:
 

package/dist-cli/ksql.js

@@ -18725,7 +18725,7 @@ async function executeParsedStatement(stmt, client, options, cacheContext) {
   if (stmt.type !== "EXPLAIN") assertRelativeDatePushdownPlan(relativeDatePlan);
   const unresolved = findVariableRef(stmt);
   if (unresolved !== null && !isApplyParentKlikeStatement(stmt)) {
-    throw new Error(`ParseError: variable @${unresolved} is not defined in a batch.`);
+    throw new Error(undefinedBatchVariableMessage(unresolved, "in a batch"));
   }
   assertApplyScope("phase15b", stmt);
   assertApplyExecutionScope("phase15b", stmt);
@@ -19597,6 +19597,9 @@ function evaluateScalarExpr(expr, evaluationContext = {}) {
 function resolveBatchVariableReferences(node, variables) {
   return resolveBatchVariableReferencesInternal(node, variables, false);
 }
+function undefinedBatchVariableMessage(name, location2) {
+  return asOfFunctionNameFromVariable(name) === null ? `ParseError: variable @${name} is not defined ${location2}.` : `ParseError: @NOW() \u306A\u3069\u306E as-of \u95A2\u6570\u306F\u57FA\u6E96\u6642\u523B\u304C\u521D\u671F\u5316\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002`;
+}
 function resolveBatchVariableReferencesInternal(node, variables, numericArithmeticOperand) {
   if (Array.isArray(node)) {
     return node.map((v) => resolveBatchVariableReferencesInternal(v, variables, false));
@@ -19606,7 +19609,7 @@ function resolveBatchVariableReferencesInternal(node, variables, numericArithmet
     if (obj["type"] === "VARIABLE" && typeof obj["name"] === "string") {
       const value = variables.get(obj["name"]);
       if (value === void 0) {
-        throw new Error(`ParseError: variable @${obj["name"]} is not defined in this batch.`);
+        throw new Error(undefinedBatchVariableMessage(obj["name"], "in this batch"));
       }
       if (value.type === "array") {
         throw new Error(`ParseError: array variable @${obj["name"]} can only be used as IN @${obj["name"]}.`);
@@ -19629,7 +19632,7 @@ function resolveBatchVariableReferencesInternal(node, variables, numericArithmet
     }
     if (obj["type"] === "VARIABLE_COL" && typeof obj["name"] === "string" && (typeof obj["alias"] === "string" || obj["alias"] === null)) {
       const value = variables.get(obj["name"]);
-      if (value === void 0) throw new Error(`ParseError: variable @${obj["name"]} is not defined in this batch.`);
+      if (value === void 0) throw new Error(undefinedBatchVariableMessage(obj["name"], "in this batch"));
       if (value.type === "array") throw new Error(`ParseError: array variable @${obj["name"]} cannot be used as a SELECT column.`);
       if (value.type === "relative-date") {
         throw new Error(`InternalError: RELATIVE_DATE variable @${obj["name"]} reached a SELECT column.`);
@@ -19655,7 +19658,7 @@ function resolveBatchVariableReferencesInternal(node, variables, numericArithmet
       const right = resolved["right"];
       if (right?.["type"] === "VARIABLE_IN_LIST" && typeof right["name"] === "string") {
         const value = variables.get(right["name"]);
-        if (value === void 0) throw new Error(`ParseError: variable @${right["name"]} is not defined in this batch.`);
+        if (value === void 0) throw new Error(undefinedBatchVariableMessage(right["name"], "in this batch"));
         if (value.type !== "array") {
           throw new Error(`ParseError: scalar variable @${right["name"]} cannot be used as IN @${right["name"]}; use IN (@${right["name"]}) instead.`);
         }
@@ -22788,11 +22791,16 @@ function lookupUpsertTarget(index, keyParts) {
   if (!index.numericKey.some(Boolean)) return void 0;
   return index.normalized.get(upsertNormalizedKey(keyParts, index.numericKey));
 }
-async function resolveUpsertTargets(appId, keyFields, rowKeyValues, client, options, fieldTypes) {
+async function resolveUpsertTargets(appId, keyFields, rowKeyValues, client, options, fieldTypes, previewFields) {
   const maxRecords = options.maxRecords ?? 1e4;
   const parallel = options.fetchParallel ?? 1;
   const numericKey = keyFields.map((f) => fieldTypes.get(f) === "NUMBER");
-  const index = { raw: /* @__PURE__ */ new Map(), normalized: /* @__PURE__ */ new Map(), numericKey };
+  const index = {
+    raw: /* @__PURE__ */ new Map(),
+    normalized: /* @__PURE__ */ new Map(),
+    numericKey,
+    ...previewFields ? { snapshots: /* @__PURE__ */ new Map() } : {}
+  };
   const setMax = (map, key, id) => {
     const cur = map.get(key);
     if (cur === void 0 || id > cur) map.set(key, id);
@@ -22813,20 +22821,26 @@ async function resolveUpsertTargets(appId, keyFields, rowKeyValues, client, opti
     if (parts.some((p) => p === "")) perRowKeys.push(parts);
     else batchFirstKeys.add(parts[0]);
   }
-  const fields = ["$id", ...keyFields];
+  const fields = previewFields ? [.../* @__PURE__ */ new Set(["$id", ...keyFields, ...previewFields])] : ["$id", ...keyFields];
   for (const chunk3 of splitChunks([...batchFirstKeys], UPSERT_IN_CHUNK_SIZE)) {
     const query = `${keyFields[0]} in (${chunk3.map(sqlQuote).join(",")})`;
     const records = await fetchAll(client.getRecords, appId, query, fields, { maxRecords, parallel });
     for (const rec of records) {
       const id = Number(rec["$id"]?.value);
       if (!Number.isFinite(id)) continue;
+      index.snapshots?.set(id, rec);
       addRecordToIndex(keyFields.map((f) => toScalarText(rec[f]?.value)), id);
     }
   }
   for (const parts of perRowKeys) {
     const query = keyFields.map((f, i) => `${f} = ${sqlQuote(parts[i])}`).join(" and ");
-    const existing = await fetchAll(client.getRecords, appId, query, ["$id"], { maxRecords, parallel });
+    const perRowFields = previewFields ? [.../* @__PURE__ */ new Set(["$id", ...previewFields])] : ["$id"];
+    const existing = await fetchAll(client.getRecords, appId, query, perRowFields, { maxRecords, parallel });
     if (existing.length === 0) continue;
+    for (const rec of existing) {
+      const id = Number(rec["$id"]?.value);
+      if (Number.isFinite(id)) index.snapshots?.set(id, rec);
+    }
     addRecordToIndex(parts, maxRecordId(existing));
   }
   return index;
@@ -27101,7 +27115,8 @@ 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) {
+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) {
+  const asOfClock = createAsOfClock(asOf ?? /* @__PURE__ */ new Date(), timezone);
   const recursiveLimits = resolveRecursiveCteLimits({
     recursiveCteMaxDepth,
     recursiveCteMaxRows,
@@ -27114,6 +27129,9 @@ async function buildBatchExplainPlans(sql, client, injectedVariables, cacheConte
     const normalizedInjectedVariables = validateDeclaredBatchVariables(statements, injectedVariables);
     const relativeDateVariables = prepareRelativeDateVariables(statements, normalizedInjectedVariables);
     const variables = /* @__PURE__ */ new Map();
+    for (const [name, value] of Object.entries(asOfClock.values)) {
+      variables.set(asOfVariableName(name), { type: "string", value });
+    }
     const literalDeclareDefaults = /* @__PURE__ */ new Map();
     const tempSchemaLedger = /* @__PURE__ */ new Map();
     const plans = [];