@querypanel/node-sdk 1.3.1 → 1.3.3

package/dist/index.d.cts

@@ -990,6 +990,13 @@ interface ChartModifyOptions {
      * Omit this field; chart modifications always use v2.
      */
     pipeline?: "v2";
+    /**
+     * Fast path for structured controls (pinned charts): date-only changes
+     * substitute params or call `/v2/rewrite-datefilter` instead of `/v2/query`,
+     * and chart generation is skipped when the caller keeps its own encoding
+     * (`chart.vizSpec` / `vegaLiteSpec` are then omitted). Default: false.
+     */
+    lightweight?: boolean;
     /**
      * QueryPanel session ID for context-aware follow-ups.
      * Pass the querypanelSessionId from a previous ask() response

package/dist/index.d.ts

@@ -990,6 +990,13 @@ interface ChartModifyOptions {
      * Omit this field; chart modifications always use v2.
      */
     pipeline?: "v2";
+    /**
+     * Fast path for structured controls (pinned charts): date-only changes
+     * substitute params or call `/v2/rewrite-datefilter` instead of `/v2/query`,
+     * and chart generation is skipped when the caller keeps its own encoding
+     * (`chart.vizSpec` / `vegaLiteSpec` are then omitted). Default: false.
+     */
+    lightweight?: boolean;
     /**
      * QueryPanel session ID for context-aware follow-ups.
      * Pass the querypanelSessionId from a previous ask() response

package/dist/index.js

@@ -2245,6 +2245,7 @@ function buildModifiedQuestion(originalQuestion, modifications, hasSessionContex
   }
   return `${originalQuestion} (${hints.join(", ")})`;
 }
+var REWRITE_DATEFILTER_ENDPOINT = "/v2/rewrite-datefilter";
 var START_PARAM_KEY_REGEX = /(^|_)(start|from)(_|$)/i;
 var END_PARAM_KEY_REGEX = /(^|_)(end|to)(_|$)/i;
 var ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z?$/;
@@ -2281,31 +2282,118 @@ function normalizeGeneratedParamKey(param, index) {
   const nameCandidate = typeof param.name === "string" && param.name.trim() || typeof param.placeholder === "string" && param.placeholder.trim() || typeof param.position === "number" && String(param.position) || String(index + 1);
   return nameCandidate.replace(/[{}]/g, "").replace(/(.+):.*$/, "$1").replace(/^[:$]/, "").trim();
 }
-function applyDateRangeOverrides(dateRange, params, paramMetadata) {
+function collectParamKeys(params, paramMetadata) {
+  const keys = new Set(Object.keys(params));
+  for (let i = 0; i < paramMetadata.length; i++) {
+    const param = paramMetadata[i];
+    if (!param) continue;
+    keys.add(normalizeGeneratedParamKey(param, i));
+  }
+  return [...keys];
+}
+function placeholderKey(token) {
+  if (token.startsWith("$") || token.startsWith("@")) return token.slice(1);
+  return token.slice(1, -1).replace(/:.+$/, "").trim();
+}
+function isDateLike(value) {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value.trim());
+}
+function dateBoundKeysFromSql(sql) {
+  const start = /* @__PURE__ */ new Set();
+  const end = /* @__PURE__ */ new Set();
+  const comparison = /(>=|<=|>|<)\s*(\$\d+|\{[^}]+\}|@[A-Za-z_][\w]*)/g;
+  const between = /BETWEEN\s+(\$\d+|\{[^}]+\}|@[A-Za-z_][\w]*)\s+AND\s+(\$\d+|\{[^}]+\}|@[A-Za-z_][\w]*)/gi;
+  for (const match of sql.matchAll(comparison)) {
+    const key = placeholderKey(match[2] ?? "");
+    if (!key) continue;
+    if (match[1] === ">=" || match[1] === ">") start.add(key);
+    else end.add(key);
+  }
+  for (const match of sql.matchAll(between)) {
+    const startKey = placeholderKey(match[1] ?? "");
+    const endKey = placeholderKey(match[2] ?? "");
+    if (startKey) start.add(startKey);
+    if (endKey) end.add(endKey);
+  }
+  return { start, end };
+}
+function paramValueForKey(key, params, paramMetadata) {
+  if (key in params) return params[key];
+  for (let i = 0; i < paramMetadata.length; i++) {
+    const param = paramMetadata[i];
+    if (!param) continue;
+    if (normalizeGeneratedParamKey(param, i) === key) return param.value;
+  }
+  return void 0;
+}
+function dateBoundKeys(sql, params, paramMetadata, boundary) {
+  const fromSql = dateBoundKeysFromSql(sql)[boundary];
+  const keys = [];
+  for (const key of collectParamKeys(params, paramMetadata)) {
+    const named = keyLooksLikeDateBoundary(key, boundary);
+    if (!named && !fromSql.has(key)) continue;
+    if (!isDateLike(paramValueForKey(key, params, paramMetadata))) continue;
+    keys.push(key);
+  }
+  return keys;
+}
+function canSubstituteDateRangeParams(dateRange, sql, params, paramMetadata = []) {
+  if (!dateRange) return false;
+  const from = normalizeDateInput(dateRange.from);
+  const to = normalizeDateInput(dateRange.to);
+  if (!from && !to) return false;
+  if (from && dateBoundKeys(sql, params, paramMetadata, "start").length === 0) {
+    return false;
+  }
+  if (to && dateBoundKeys(sql, params, paramMetadata, "end").length === 0) {
+    return false;
+  }
+  return true;
+}
+function isDateRangeOnlySqlModification(modifications) {
+  if (!modifications?.dateRange) return false;
+  if (modifications.customSql) return false;
+  if (modifications.timeGranularity) return false;
+  if (typeof modifications.additionalInstructions === "string" && modifications.additionalInstructions.trim().length > 0) {
+    return false;
+  }
+  return true;
+}
+function applyDateRangeOverrides(dateRange, sql, params, paramMetadata) {
   if (!dateRange) return;
   const from = normalizeDateInput(dateRange.from);
   const to = normalizeDateInput(dateRange.to);
   if (!from && !to) return;
+  const startKeys = new Set(
+    from ? dateBoundKeys(sql, params, paramMetadata, "start") : []
+  );
+  const endKeys = new Set(
+    to ? dateBoundKeys(sql, params, paramMetadata, "end") : []
+  );
   for (const [key, value] of Object.entries(params)) {
-    if (from && keyLooksLikeDateBoundary(key, "start")) {
-      params[key] = formatDateOverride(from, "start", value);
+    if (startKeys.has(key)) {
+      params[key] = formatDateOverride(from ?? "", "start", value);
     }
-    if (to && keyLooksLikeDateBoundary(key, "end")) {
-      params[key] = formatDateOverride(to, "end", value);
+    if (endKeys.has(key)) {
+      params[key] = formatDateOverride(to ?? "", "end", value);
     }
   }
   for (let i = 0; i < paramMetadata.length; i++) {
     const param = paramMetadata[i];
     if (!param) continue;
     const key = normalizeGeneratedParamKey(param, i);
-    if (from && keyLooksLikeDateBoundary(key, "start")) {
-      param.value = formatDateOverride(from, "start", param.value);
+    if (startKeys.has(key)) {
+      param.value = formatDateOverride(from ?? "", "start", param.value);
     }
-    if (to && keyLooksLikeDateBoundary(key, "end")) {
-      param.value = formatDateOverride(to, "end", param.value);
+    if (endKeys.has(key)) {
+      param.value = formatDateOverride(to ?? "", "end", param.value);
     }
   }
 }
+function buildPreviousParams(params, paramMetadata) {
+  if (paramMetadata.length > 0) return paramMetadata;
+  return Object.entries(params).map(([name, value]) => ({ name, value }));
+}
 function buildVizHints(modifications) {
   const hints = {};
   if (modifications.kind) {
@@ -2356,6 +2444,9 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   const hasSqlMods = !!input.sqlModifications;
   const hasVizMods = !!input.vizModifications;
   const hasCustomSql = !!input.sqlModifications?.customSql;
+  const lightweight = options?.lightweight === true;
+  const dateOnly = lightweight && isDateRangeOnlySqlModification(input.sqlModifications);
+  const skipChartLlm = lightweight && !hasCustomSql && (dateOnly || hasVizMods && !hasSqlMods);
   resolveQueryPipeline(options?.pipeline);
   const queryEndpoint = "/v2/query";
   let currentSql = input.sql;
@@ -2409,6 +2500,20 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     paramMetadata = [];
     queryId = void 0;
     sqlChanged = true;
+  } else if (dateOnly && canSubstituteDateRangeParams(
+    input.sqlModifications?.dateRange,
+    finalSql,
+    finalParams,
+    paramMetadata
+  )) {
+    finalParams = { ...finalParams };
+    applyDateRangeOverrides(
+      input.sqlModifications?.dateRange,
+      finalSql,
+      finalParams,
+      paramMetadata
+    );
+    sqlChanged = false;
   } else if (hasSqlMods && !hasCustomSql) {
     const modifiedQuestion = buildModifiedQuestion(
       input.question,
@@ -2416,18 +2521,36 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       hasQuerypanelSessionContext
     );
     finalQuestion = modifiedQuestion;
-    const queryResponse = await client.post(
+    const sharedBody = {
+      session_id: querypanelSessionId,
+      previous_sql: currentSql,
+      ...tenantSettings ? { tenant_settings: tenantSettings } : {},
+      ...databaseName ? { database: databaseName } : {},
+      ...metadata?.dialect ? { dialect: metadata.dialect } : {},
+      debug: options?.debug ?? false
+    };
+    const [endpoint, body] = dateOnly ? [
+      REWRITE_DATEFILTER_ENDPOINT,
+      {
+        ...sharedBody,
+        question: input.question,
+        previous_params: buildPreviousParams(finalParams, paramMetadata),
+        date_range: {
+          from: normalizeDateInput(input.sqlModifications?.dateRange?.from),
+          to: normalizeDateInput(input.sqlModifications?.dateRange?.to)
+        }
+      }
+    ] : [
       queryEndpoint,
       {
+        ...sharedBody,
         question: modifiedQuestion,
-        session_id: querypanelSessionId,
-        previous_sql: currentSql,
-        ...options?.maxRetry ? { max_retry: options.maxRetry } : {},
-        ...tenantSettings ? { tenant_settings: tenantSettings } : {},
-        ...databaseName ? { database: databaseName } : {},
-        ...metadata?.dialect ? { dialect: metadata.dialect } : {},
-        debug: options?.debug ?? false
-      },
+        ...options?.maxRetry ? { max_retry: options.maxRetry } : {}
+      }
+    ];
+    const queryResponse = await client.post(
+      endpoint,
+      body,
       tenantId,
       options?.userId,
       options?.scopes,
@@ -2439,6 +2562,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalParams = queryEngine.mapGeneratedParams(paramMetadata);
     applyDateRangeOverrides(
       input.sqlModifications?.dateRange,
+      finalSql,
       finalParams,
       paramMetadata
     );
@@ -2459,7 +2583,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   };
   const vizHints = hasVizMods ? buildVizHints(input.vizModifications) : {};
   const vizHintsForChart = chartType === "vizspec" ? vizHints : stripVizSpecOnlyHints(vizHints);
-  if (chartType === "vizspec") {
+  if (!skipChartLlm && chartType === "vizspec") {
     const vizspecResponse = await client.post(
       "/vizspec",
       {
@@ -2486,7 +2610,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       specType: "vizspec",
       notes: rows.length === 0 ? vizspecResponse.notes ?? "Query returned no rows." : vizspecResponse.notes
     };
-  } else {
+  } else if (!skipChartLlm) {
     const chartResponse = await client.post(
       "/chart",
       {