@querypanel/node-sdk 1.3.6 → 1.3.8

package/README.md

@@ -621,6 +621,20 @@ The SDK will:
 
 Without `maxRetry`, execution errors throw immediately (default behavior).
 
+#### Retry when the query returns nothing
+
+A query can run fine and still return nothing because a filter value does not match how the data stores it (`state = 'approved'` when the column holds `APPROVE`). With `retryOnEmptyResult`, the SDK treats an empty result, or a single row of only zeros/NULLs such as `COUNT(*) = 0`, like an execution error and asks for a repaired query within the same `maxRetry` budget:
+
+```ts
+const response = await qp.ask("How many transactions were declined?", {
+  tenantId: "tenant_123",
+  maxRetry: 1,
+  retryOnEmptyResult: true,
+});
+```
+
+Only the fact that the result was empty and the previous SQL are sent back; no rows or values leave your backend. If the last attempt is still empty, it is returned as is (no error). Off by default; each retry is one more generation round, so expect a few extra seconds on those questions.
+
 ## Need more?
 
 Open an issue or extend the SDK: the public class is in `src/index.ts` and each API route has a module under `src/routes/`. Pull requests are welcome for additional adapters, richer param coercion, or convenience helpers around charts/annotations.

package/dist/index.cjs

@@ -2492,6 +2492,15 @@ function resolveQueryPipeline(pipeline) {
   }
   return "v2";
 }
+var EMPTY_RESULT_ERROR = "The query ran but returned no rows (or only zero/NULL values). A filter value probably does not match how the data stores it (case, spelling, codes such as 'APPROVE' vs 'approved'), or a filter is narrower than the question. Check each filter value against the column's documented values and fix it; keep every filter the question asks for.";
+function isEmptyLikeResult(rows) {
+  if (rows.length === 0) return true;
+  if (rows.length > 1) return false;
+  const row = rows[0];
+  if (!row || typeof row !== "object") return false;
+  const values = Object.values(row);
+  return values.length > 0 && values.every((v) => v === null || v === 0 || v === "0" || v === 0n);
+}
 async function ask(client, queryEngine, question, options, signal) {
   const tenantId = resolveTenantId5(client, options.tenantId);
   const sessionId = import_node_crypto3.default.randomUUID();
@@ -2574,6 +2583,17 @@ async function ask(client, queryEngine, question, options, signal) {
         tenantId
       );
       const rows = execution.rows ?? [];
+      if (options.retryOnEmptyResult && attempt < maxRetry && isEmptyLikeResult(rows)) {
+        attempt++;
+        lastError = EMPTY_RESULT_ERROR;
+        previousSql = sql;
+        console.warn("Query returned no data, retrying query generation", {
+          attempt,
+          maxAttempts: maxRetry + 1,
+          sql
+        });
+        continue;
+      }
       const chartType = options.chartType ?? "vega-lite";
       let chart = {
         specType: chartType,
@@ -3660,7 +3680,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
    * @param input - VizSpec generation input with question, SQL, and result data
    * @param options - Optional settings for tenant and retries
    * @param signal - Optional AbortSignal for cancellation
-   * @returns VizSpec specification for chart, table, or metric visualization
+   * @returns VizSpec specification for chart, table, metric, or map visualization
    *
    * @example
    * ```typescript