@querypanel/node-sdk 1.2.10 → 1.3.0-beta.1

package/README.md

@@ -73,6 +73,7 @@ const response = await qp.ask("Top countries by revenue", {
   tenantId: "tenant_123",
   database: "analytics",
 });
+// Defaults to pipeline "v2" (POST /v2/query). Pass pipeline: "v1" only for legacy.
 
 console.log(response.sql);
 console.log(response.params);
@@ -82,17 +83,18 @@ console.log(response.chart.vegaLiteSpec);
 
 ### Custom system instructions (v2 pipeline)
 
-If you need to enforce tenant-specific policies that should apply to every query (for example, data retention windows), you can inject additional **system prompt** instructions into the v2 pipeline:
+If you need to enforce tenant-specific policies that should apply to every query (for example, data retention windows), you can inject additional **system prompt** instructions into the v2 pipeline (the default):
 
 ```ts
 const response = await qp.ask("Revenue by product", {
   tenantId: "tenant_123",
   database: "analytics",
-  pipeline: "v2",
   systemPrompt: "Retention policy: only query data from the last 30 days.",
 });
 ```
 
+> **Deprecated:** `pipeline: "v1"` still hits `POST /query` for compatibility. Prefer omitting `pipeline` or passing `"v2"`.
+
 ### Restricting VizSpec chart types
 
 If your UI only supports a subset of VizSpec chart kinds (for example no area or scatter), set **`supportedChartTypes`** on the SDK constructor or on each `ask` / `modifyChart` call. The API’s `/vizspec` step then steers generation toward allowed types only (`line`, `bar`, `column`, `area`, `scatter`, `pie`). This applies whenever you use **`chartType: "vizspec"`** (including the default v2 flow after SQL runs).

package/dist/index.cjs

@@ -38,7 +38,10 @@ __export(index_exports, {
   QueryErrorCode: () => QueryErrorCode,
   QueryPanelSdkAPI: () => QueryPanelSdkAPI,
   QueryPipelineError: () => QueryPipelineError,
-  anonymizeResults: () => anonymizeResults
+  anonymizeResults: () => anonymizeResults,
+  mapGeneratedParams: () => mapGeneratedParams,
+  normalizeSqlParamsInput: () => normalizeSqlParamsInput,
+  resolveQueryPipeline: () => resolveQueryPipeline
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -497,6 +500,37 @@ function toNumber(value) {
 }
 
 // src/adapters/postgres.ts
+function maxPostgresPlaceholderIndex(sql) {
+  let max = 0;
+  for (const match of sql.matchAll(/\$(\d+)\b/g)) {
+    const index = Number.parseInt(match[1], 10);
+    if (Number.isFinite(index) && index > max) {
+      max = index;
+    }
+  }
+  return max;
+}
+function filterParamsForPostgresSql(sql, params) {
+  if (!params || Object.keys(params).length === 0) {
+    return void 0;
+  }
+  const placeholderCount = maxPostgresPlaceholderIndex(sql);
+  if (placeholderCount === 0) {
+    return void 0;
+  }
+  const hasNumericKeys = Object.keys(params).some((key) => /^\d+$/.test(key));
+  if (hasNumericKeys) {
+    const filtered = {};
+    for (let index = 1; index <= placeholderCount; index += 1) {
+      const key = String(index);
+      if (key in params) {
+        filtered[key] = params[key];
+      }
+    }
+    return Object.keys(filtered).length > 0 ? filtered : void 0;
+  }
+  return params;
+}
 var PostgresAdapter = class {
   constructor(clientFn, options = {}) {
     this.clientFn = clientFn;
@@ -514,9 +548,10 @@ var PostgresAdapter = class {
     if (this.allowedTables) {
       this.validateQueryTables(sql);
     }
+    const boundParams = filterParamsForPostgresSql(sql, params);
     let paramArray;
-    if (params) {
-      paramArray = this.convertNamedToPositionalParams(params);
+    if (boundParams) {
+      paramArray = this.convertNamedToPositionalParams(sql, boundParams);
     }
     const result = await this.clientFn(sql, paramArray);
     const fields = result.fields.map((f) => f.name);
@@ -546,36 +581,43 @@ var PostgresAdapter = class {
     }
   }
   /**
-   * Convert params to positional array for PostgreSQL.
-   * PostgreSQL expects $1, $2, $3 in SQL and an array of values [val1, val2, val3].
-   * When the record has numeric keys ("1", "2", "3") — e.g. from mapGeneratedParams —
-   * use only those in order so placeholder order matches SQL. Otherwise fall back to
-   * named keys in alphabetical order for backward compatibility.
+   * Convert params to positional array for PostgreSQL ($1, $2, …).
+   * Values must align with v2 generation order via numeric keys from mapGeneratedParams.
    */
-  convertNamedToPositionalParams(params) {
-    const numericKeys = Object.keys(params).filter((k) => /^\d+$/.test(k)).map((k) => Number.parseInt(k, 10)).sort((a, b) => a - b);
-    if (numericKeys.length > 0) {
-      const positionalParams = [];
-      for (const key of numericKeys) {
-        let val = params[String(key)];
-        if (typeof val === "string") {
-          const match = val.match(/^<([a-zA-Z0-9_]+)>$/);
-          const namedKey = match?.[1];
-          if (namedKey && namedKey in params) {
-            val = params[namedKey];
-          }
+  convertNamedToPositionalParams(sql, params) {
+    const placeholderCount = maxPostgresPlaceholderIndex(sql);
+    if (placeholderCount === 0) {
+      return [];
+    }
+    const positionalParams = [];
+    for (let index = 1; index <= placeholderCount; index += 1) {
+      const key = String(index);
+      let val = params[key];
+      if (val === void 0 && placeholderCount === 1) {
+        const namedKeys = Object.keys(params).filter((k) => !/^\d+$/.test(k));
+        if (namedKeys.length === 1) {
+          val = params[namedKeys[0]];
+        }
+      }
+      if (val === void 0) {
+        throw new Error(`Missing value for PostgreSQL parameter $${index}`);
+      }
+      if (typeof val === "string") {
+        const match = val.match(/^<([a-zA-Z0-9_]+)>$/);
+        const namedKey = match?.[1];
+        if (namedKey && namedKey in params) {
+          val = params[namedKey];
         }
-        positionalParams.push(val);
       }
-      return positionalParams;
+      positionalParams.push(val);
     }
-    const namedKeys = Object.keys(params).filter((k) => !/^\d+$/.test(k)).sort();
-    return namedKeys.map((key) => params[key]);
+    return positionalParams;
   }
   async validate(sql, params) {
+    const boundParams = filterParamsForPostgresSql(sql, params);
     let paramArray;
-    if (params) {
-      paramArray = this.convertNamedToPositionalParams(params);
+    if (boundParams) {
+      paramArray = this.convertNamedToPositionalParams(sql, boundParams);
     }
     await this.clientFn(`EXPLAIN ${sql}`, paramArray);
   }
@@ -1218,6 +1260,45 @@ var CallbackApiClient = class {
   }
 };
 
+// src/core/map-generated-params.ts
+function mapGeneratedParams(params) {
+  const record = {};
+  params.forEach((param, index) => {
+    const value = param.value;
+    if (value === void 0) {
+      return;
+    }
+    record[String(index + 1)] = value;
+    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);
+    const key = nameCandidate.replace(/[{}:$]/g, "").trim();
+    record[key] = value;
+  });
+  return record;
+}
+function normalizeSqlParamsInput(params) {
+  if (params == null) {
+    return {};
+  }
+  if (Array.isArray(params)) {
+    if (params.length === 0) {
+      return {};
+    }
+    const first = params[0];
+    if (first && typeof first === "object" && "value" in first) {
+      return mapGeneratedParams(params);
+    }
+    const positional = {};
+    params.forEach((value, index) => {
+      positional[String(index + 1)] = value;
+    });
+    return positional;
+  }
+  if (typeof params === "object") {
+    return params;
+  }
+  return {};
+}
+
 // src/core/query-engine.ts
 var QueryEngine = class {
   constructor() {
@@ -1288,18 +1369,7 @@ var QueryEngine = class {
    * - Named keys remain for tenant isolation / other lookups.
    */
   mapGeneratedParams(params) {
-    const record = {};
-    params.forEach((param, index) => {
-      const value = param.value;
-      if (value === void 0) {
-        return;
-      }
-      record[String(index + 1)] = value;
-      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);
-      const key = nameCandidate.replace(/[{}:$]/g, "").trim();
-      record[key] = value;
-    });
-    return record;
+    return mapGeneratedParams(params);
   }
   ensureTenantIsolation(sql, params, metadata, tenantId) {
     if (!metadata.tenantFieldName || metadata.enforceTenantIsolation === false) {
@@ -1319,8 +1389,10 @@ var QueryEngine = class {
       params[tenantField] = tenantId;
       tenantPredicate = `${tenantField} = @${tenantField}`;
     } else {
-      const escapedId = tenantId.replace(/'/g, "''");
-      tenantPredicate = `${tenantField} = '${escapedId}'`;
+      const paramIndex = this.nextPostgresPlaceholderIndex(sql, params);
+      params[String(paramIndex)] = tenantId;
+      params[tenantField] = tenantId;
+      tenantPredicate = `${tenantField} = $${paramIndex}`;
     }
     if (/\bwhere\b/i.test(sql)) {
       return sql.replace(
@@ -1330,6 +1402,23 @@ var QueryEngine = class {
     }
     return `${sql} WHERE ${tenantPredicate}`;
   }
+  nextPostgresPlaceholderIndex(sql, params) {
+    let max = 0;
+    for (const match of sql.matchAll(/\$(\d+)\b/g)) {
+      const index = Number.parseInt(match[1], 10);
+      if (Number.isFinite(index) && index > max) {
+        max = index;
+      }
+    }
+    if (max > 0) {
+      return max + 1;
+    }
+    const numericKeys = Object.keys(params).filter((key) => /^\d+$/.test(key)).map((key) => Number.parseInt(key, 10)).filter((index) => Number.isFinite(index));
+    if (numericKeys.length > 0) {
+      return Math.max(...numericKeys) + 1;
+    }
+    return 1;
+  }
 };
 
 // src/routes/charts.ts
@@ -1864,6 +1953,7 @@ function resolveTenantId4(client, tenantId) {
 function buildSchemaRequest(databaseName, adapter, introspection, metadata) {
   const dialect = adapter.getDialect();
   const tables = introspection.tables.map((table) => ({
+    schema_name: table.schema,
     table_name: table.name,
     description: table.comment ?? `Table ${table.name}`,
     columns: table.columns.map((column) => ({
@@ -1893,6 +1983,9 @@ var import_node_crypto4 = __toESM(require("crypto"), 1);
 
 // src/routes/query.ts
 var import_node_crypto3 = __toESM(require("crypto"), 1);
+function resolveQueryPipeline(pipeline) {
+  return pipeline ?? "v2";
+}
 async function ask(client, queryEngine, question, options, signal) {
   const tenantId = resolveTenantId5(client, options.tenantId);
   const sessionId = import_node_crypto3.default.randomUUID();
@@ -1901,7 +1994,8 @@ async function ask(client, queryEngine, question, options, signal) {
   let attempt = 0;
   let lastError = options.lastError;
   let previousSql = options.previousSql;
-  const queryEndpoint = options.pipeline === "v2" ? "/v2/query" : "/query";
+  const pipeline = resolveQueryPipeline(options.pipeline);
+  const queryEndpoint = pipeline === "v2" ? "/v2/query" : "/query";
   while (attempt <= maxRetry) {
     const databaseName = options.database ?? queryEngine.getDefaultDatabase();
     const metadata = databaseName ? queryEngine.getDatabaseMetadata(databaseName) : void 0;
@@ -1925,7 +2019,7 @@ async function ask(client, queryEngine, question, options, signal) {
         ...databaseName ? { database: databaseName } : {},
         ...metadata?.dialect ? { dialect: metadata.dialect } : {},
         ...options.model?.trim() ? { model: options.model.trim() } : {},
-        ...options.pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {},
+        ...pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {},
         debug: options.debug ?? false
       },
       tenantId,
@@ -2240,7 +2334,8 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   const hasSqlMods = !!input.sqlModifications;
   const hasVizMods = !!input.vizModifications;
   const hasCustomSql = !!input.sqlModifications?.customSql;
-  const queryEndpoint = options?.pipeline === "v2" ? "/v2/query" : "/query";
+  const pipeline = resolveQueryPipeline(options?.pipeline);
+  const queryEndpoint = pipeline === "v2" ? "/v2/query" : "/query";
   let finalSql = input.sql;
   let finalParams = input.params ?? {};
   let paramMetadata = [];
@@ -2272,10 +2367,10 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     const modifiedQuestion = buildModifiedQuestion(
       input.question,
       input.sqlModifications,
-      options?.pipeline,
+      pipeline,
       hasQuerypanelSessionContext
     );
-    if (options?.pipeline === "v2") {
+    if (pipeline === "v2") {
       finalQuestion = modifiedQuestion;
     }
     const queryResponse = await client.post(
@@ -2299,7 +2394,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalSql = queryResponse.sql;
     paramMetadata = Array.isArray(queryResponse.params) ? queryResponse.params : [];
     finalParams = queryEngine.mapGeneratedParams(paramMetadata);
-    if (options?.pipeline === "v2") {
+    if (pipeline === "v2") {
       applyDateRangeOverrides(
         input.sqlModifications?.dateRange,
         finalParams,
@@ -3540,6 +3635,9 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
   QueryErrorCode,
   QueryPanelSdkAPI,
   QueryPipelineError,
-  anonymizeResults
+  anonymizeResults,
+  mapGeneratedParams,
+  normalizeSqlParamsInput,
+  resolveQueryPipeline
 });
 //# sourceMappingURL=index.cjs.map