@querypanel/node-sdk 1.2.6 → 1.2.8

package/dist/index.d.cts

@@ -737,6 +737,11 @@ interface AskOptions {
      * Sent to `POST /vizspec` as `supported_chart_types`. Omitted allows all standard types.
      */
     supportedChartTypes?: ChartType[];
+    /**
+     * When true, rationale includes engineer-style schema detail (tables, columns).
+     * When false (default), rationale is client-safe for end users.
+     */
+    debug?: boolean;
 }
 /**
  * Intent analysis result from the v2 pipeline.
@@ -961,6 +966,11 @@ interface ChartModifyOptions {
      * Restrict VizSpec chart types for this call (merged with SDK default from constructor when omitted).
      */
     supportedChartTypes?: ChartType[];
+    /**
+     * When true, rationale includes engineer-style schema detail (tables, columns).
+     * When false (default), rationale is client-safe for end users.
+     */
+    debug?: boolean;
 }
 /**
  * Response from modifyChart(), extending AskResponse with modification metadata.
@@ -1233,7 +1243,7 @@ declare class QueryPanelSdkAPI {
      * It handles the complete flow: SQL generation → validation → execution → chart generation.
      *
      * @param question - Natural language question (e.g., "Show revenue by country")
-     * @param options - Query options including tenantId, database, and retry settings
+     * @param options - Query options including tenantId, database, retry settings, and optional `debug` for engineer-style rationale
      * @param signal - Optional AbortSignal for cancellation
      * @returns Response with SQL, executed data rows, and generated chart
      * @throws {Error} When SQL generation or execution fails after all retries

package/dist/index.d.ts

@@ -737,6 +737,11 @@ interface AskOptions {
      * Sent to `POST /vizspec` as `supported_chart_types`. Omitted allows all standard types.
      */
     supportedChartTypes?: ChartType[];
+    /**
+     * When true, rationale includes engineer-style schema detail (tables, columns).
+     * When false (default), rationale is client-safe for end users.
+     */
+    debug?: boolean;
 }
 /**
  * Intent analysis result from the v2 pipeline.
@@ -961,6 +966,11 @@ interface ChartModifyOptions {
      * Restrict VizSpec chart types for this call (merged with SDK default from constructor when omitted).
      */
     supportedChartTypes?: ChartType[];
+    /**
+     * When true, rationale includes engineer-style schema detail (tables, columns).
+     * When false (default), rationale is client-safe for end users.
+     */
+    debug?: boolean;
 }
 /**
  * Response from modifyChart(), extending AskResponse with modification metadata.
@@ -1233,7 +1243,7 @@ declare class QueryPanelSdkAPI {
      * It handles the complete flow: SQL generation → validation → execution → chart generation.
      *
      * @param question - Natural language question (e.g., "Show revenue by country")
-     * @param options - Query options including tenantId, database, and retry settings
+     * @param options - Query options including tenantId, database, retry settings, and optional `debug` for engineer-style rationale
      * @param signal - Optional AbortSignal for cancellation
      * @returns Response with SQL, executed data rows, and generated chart
      * @throws {Error} When SQL generation or execution fails after all retries

package/dist/index.js

@@ -338,10 +338,15 @@ var ClickHouseAdapter = class {
       return;
     }
     const allowedSet = new Set(this.allowedTables);
-    const tablePattern = /(?:FROM|JOIN)\s+(?:FINAL\s+)?(?:(?:[a-zA-Z_][a-zA-Z0-9_]*)\.)?(["'`]?[a-zA-Z_][a-zA-Z0-9_]*["'`]?)/gi;
+    const tablePattern = /\b(FROM|JOIN)\s+(?:FINAL\s+)?(?:(?:[a-zA-Z_][a-zA-Z0-9_]*)\.)?(["'`]?[a-zA-Z_][a-zA-Z0-9_]*["'`]?)/gi;
     const matches = sql.matchAll(tablePattern);
     for (const match of matches) {
-      const table = match[1]?.replace(/["'`]/g, "");
+      const clause = match[1]?.toUpperCase();
+      const matchIndex = match.index ?? -1;
+      if (clause === "JOIN" && matchIndex >= 0 && isArrayJoinClause(sql, matchIndex)) {
+        continue;
+      }
+      const table = match[2]?.replace(/["'`]/g, "");
       if (table) {
         if (!allowedSet.has(table)) {
           throw new Error(
@@ -409,6 +414,11 @@ function normalizeTableFilter2(tables) {
   }
   return normalized;
 }
+function isArrayJoinClause(sql, joinIndex) {
+  const beforeJoin = sql.slice(0, joinIndex);
+  const previousToken = beforeJoin.trim().split(/\s+/).pop()?.toUpperCase();
+  return previousToken === "ARRAY";
+}
 function transformColumnRow(row) {
   const unwrappedType = unwrapTypeModifiers(row.type);
   const column = {
@@ -1788,7 +1798,6 @@ async function ask(client, queryEngine, question, options, signal) {
   let previousSql = options.previousSql;
   const queryEndpoint = options.pipeline === "v2" ? "/v2/query" : "/query";
   while (attempt <= maxRetry) {
-    console.log({ lastError, previousSql });
     const databaseName = options.database ?? queryEngine.getDefaultDatabase();
     const metadata = databaseName ? queryEngine.getDatabaseMetadata(databaseName) : void 0;
     let tenantSettings;
@@ -1811,7 +1820,8 @@ 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() } : {}
+        ...options.pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {},
+        debug: options.debug ?? false
       },
       tenantId,
       options.userId,
@@ -1932,9 +1942,14 @@ async function ask(client, queryEngine, question, options, signal) {
       }
       lastError = error instanceof Error ? error.message : String(error);
       previousSql = queryResponse.data.sql ?? previousSql;
-      console.warn(
-        `SQL execution failed (attempt ${attempt}/${maxRetry + 1}): ${lastError}. Retrying...`
-      );
+      console.warn("SQL execution failed, retrying query generation", {
+        attempt,
+        maxAttempts: maxRetry + 1,
+        error: lastError,
+        sql: queryResponse.data.sql ?? null,
+        paramMetadata,
+        params: paramValues
+      });
     }
   }
   throw new Error("Unexpected error in ask retry loop");
@@ -2160,7 +2175,8 @@ async function modifyChart(client, queryEngine, input, options, signal) {
         ...options?.maxRetry ? { max_retry: options.maxRetry } : {},
         ...tenantSettings ? { tenant_settings: tenantSettings } : {},
         ...databaseName ? { database: databaseName } : {},
-        ...metadata?.dialect ? { dialect: metadata.dialect } : {}
+        ...metadata?.dialect ? { dialect: metadata.dialect } : {},
+        debug: options?.debug ?? false
       },
       tenantId,
       options?.userId,
@@ -2541,7 +2557,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
    * It handles the complete flow: SQL generation → validation → execution → chart generation.
    *
    * @param question - Natural language question (e.g., "Show revenue by country")
-   * @param options - Query options including tenantId, database, and retry settings
+   * @param options - Query options including tenantId, database, retry settings, and optional `debug` for engineer-style rationale
    * @param signal - Optional AbortSignal for cancellation
    * @returns Response with SQL, executed data rows, and generated chart
    * @throws {Error} When SQL generation or execution fails after all retries