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

package/dist/index.d.cts

@@ -360,10 +360,15 @@ interface ChartCreateInput {
     title: string;
     prompt?: string;
     description?: string;
-    sql: string;
+    /**
+     * Required when `query_id` is not provided. Ignored (with `sql_params`) when
+     * `query_id` is present: the server saves the SQL and params it stored for that query.
+     */
+    sql?: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec: Record<string, unknown>;
     spec_type?: 'vega-lite' | 'vizspec';
+    /** Server-issued query id from ask() / modifyChart(). Preferred over `sql`. */
     query_id?: string;
     target_db?: string;
 }
@@ -373,6 +378,8 @@ interface ChartUpdateInput {
     description?: string;
     sql?: string;
     sql_params?: Record<string, unknown>;
+    /** When present, the server replaces sql / sql_params with the stored query. */
+    query_id?: string;
     vega_lite_spec?: Record<string, unknown>;
     spec_type?: 'vega-lite' | 'vizspec';
     target_db?: string;
@@ -917,11 +924,22 @@ interface VizModifications {
  */
 interface ChartModifyInput {
     /**
-     * The SQL query to modify or re-execute.
+     * Server-issued id of the query to modify or re-execute.
+     * From ask() / modifyChart() response: response.queryId
+     * From saved chart: chart.query_id
+     *
+     * Preferred over `sql`: when present the SQL and params are loaded from the server
+     * (scoped to the authenticated tenant) and `sql` / `params` are ignored.
+     */
+    queryId?: string;
+    /**
+     * The SQL query to modify or re-execute. Required when `queryId` is not provided.
      * From ask() response: response.sql
      * From saved chart: chart.sql
+     *
+     * Kept for backward compatibility; prefer `queryId`.
      */
-    sql: string;
+    sql?: string;
     /**
      * The original natural language question.
      * Used when regenerating SQL with modifications.
@@ -1313,7 +1331,13 @@ declare class QueryPanelSdkAPI {
      * to be attached (e.g. via attachPostgres) and options.tenantId.
      */
     runSqlForDashboard(input: {
-        sql: string;
+        /**
+         * Server-issued id from ask() / modifyChart(). Takes priority: the stored SQL
+         * and params are executed and `sql` / `params` are ignored.
+         */
+        queryId?: string;
+        /** Required when `queryId` is not provided (backward compatible raw SQL). */
+        sql?: string;
         params?: Record<string, unknown>;
         database?: string;
     }, options: {

package/dist/index.d.ts

@@ -360,10 +360,15 @@ interface ChartCreateInput {
     title: string;
     prompt?: string;
     description?: string;
-    sql: string;
+    /**
+     * Required when `query_id` is not provided. Ignored (with `sql_params`) when
+     * `query_id` is present: the server saves the SQL and params it stored for that query.
+     */
+    sql?: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec: Record<string, unknown>;
     spec_type?: 'vega-lite' | 'vizspec';
+    /** Server-issued query id from ask() / modifyChart(). Preferred over `sql`. */
     query_id?: string;
     target_db?: string;
 }
@@ -373,6 +378,8 @@ interface ChartUpdateInput {
     description?: string;
     sql?: string;
     sql_params?: Record<string, unknown>;
+    /** When present, the server replaces sql / sql_params with the stored query. */
+    query_id?: string;
     vega_lite_spec?: Record<string, unknown>;
     spec_type?: 'vega-lite' | 'vizspec';
     target_db?: string;
@@ -917,11 +924,22 @@ interface VizModifications {
  */
 interface ChartModifyInput {
     /**
-     * The SQL query to modify or re-execute.
+     * Server-issued id of the query to modify or re-execute.
+     * From ask() / modifyChart() response: response.queryId
+     * From saved chart: chart.query_id
+     *
+     * Preferred over `sql`: when present the SQL and params are loaded from the server
+     * (scoped to the authenticated tenant) and `sql` / `params` are ignored.
+     */
+    queryId?: string;
+    /**
+     * The SQL query to modify or re-execute. Required when `queryId` is not provided.
      * From ask() response: response.sql
      * From saved chart: chart.sql
+     *
+     * Kept for backward compatibility; prefer `queryId`.
      */
-    sql: string;
+    sql?: string;
     /**
      * The original natural language question.
      * Used when regenerating SQL with modifications.
@@ -1313,7 +1331,13 @@ declare class QueryPanelSdkAPI {
      * to be attached (e.g. via attachPostgres) and options.tenantId.
      */
     runSqlForDashboard(input: {
-        sql: string;
+        /**
+         * Server-issued id from ask() / modifyChart(). Takes priority: the stored SQL
+         * and params are executed and `sql` / `params` are ignored.
+         */
+        queryId?: string;
+        /** Required when `queryId` is not provided (backward compatible raw SQL). */
+        sql?: string;
         params?: Record<string, unknown>;
         database?: string;
     }, options: {

package/dist/index.js

@@ -1921,11 +1921,17 @@ function buildSchemaRequest(databaseName, adapter, introspection, metadata) {
     dialect,
     tables
   };
-  if (metadata?.tenantFieldName && metadata?.tenantFieldType && metadata?.enforceTenantIsolation !== void 0) {
+  if (metadata?.enforceTenantIsolation === false) {
+    request.tenant_settings = {
+      tenantFieldName: metadata.tenantFieldName ?? "",
+      tenantFieldType: metadata.tenantFieldType ?? "String",
+      enforceTenantIsolation: false
+    };
+  } else if (metadata?.tenantFieldName && metadata?.tenantFieldType) {
     request.tenant_settings = {
       tenantFieldName: metadata.tenantFieldName,
       tenantFieldType: metadata.tenantFieldType,
-      enforceTenantIsolation: metadata.enforceTenantIsolation
+      enforceTenantIsolation: true
     };
   }
   return request;
@@ -1953,11 +1959,17 @@ async function ask(client, queryEngine, question, options, signal) {
     const databaseName = options.database ?? queryEngine.getDefaultDatabase();
     const metadata = databaseName ? queryEngine.getDatabaseMetadata(databaseName) : void 0;
     let tenantSettings;
-    if (metadata?.tenantFieldName) {
+    if (metadata?.enforceTenantIsolation === false) {
+      tenantSettings = {
+        tenantFieldName: metadata.tenantFieldName ?? "",
+        tenantFieldType: metadata.tenantFieldType ?? "String",
+        enforceTenantIsolation: false
+      };
+    } else if (metadata?.tenantFieldName) {
       tenantSettings = {
         tenantFieldName: metadata.tenantFieldName,
         tenantFieldType: metadata.tenantFieldType,
-        enforceTenantIsolation: metadata.enforceTenantIsolation
+        enforceTenantIsolation: true
       };
     }
     const queryResponse = await client.postWithHeaders(
@@ -2135,6 +2147,25 @@ function anonymizeResults(rows) {
   });
 }
 
+// src/routes/queries.ts
+async function resolveQuery(client, queryEngine, queryId, options, signal) {
+  const response = await client.get(
+    `/v2/queries/${encodeURIComponent(queryId)}`,
+    options.tenantId,
+    options.userId,
+    options.scopes,
+    signal
+  );
+  const paramMetadata = Array.isArray(response.params) ? response.params : [];
+  return {
+    queryId: response.queryId,
+    sql: response.sql,
+    params: queryEngine.mapGeneratedParams(paramMetadata),
+    paramMetadata,
+    dialect: response.dialect
+  };
+}
+
 // src/routes/modify.ts
 function buildModifiedQuestion(originalQuestion, modifications, pipeline, hasSessionContext = false) {
   const hints = [];
@@ -2289,11 +2320,28 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   const hasCustomSql = !!input.sqlModifications?.customSql;
   const pipeline = resolveQueryPipeline(options?.pipeline);
   const queryEndpoint = pipeline === "v2" ? "/v2/query" : "/query";
-  let finalSql = input.sql;
+  let currentSql = input.sql;
   let finalParams = input.params ?? {};
   let paramMetadata = [];
   let rationale;
   let queryId;
+  if (input.queryId) {
+    const resolved = await resolveQuery(
+      client,
+      queryEngine,
+      input.queryId,
+      { tenantId, userId: options?.userId, scopes: options?.scopes },
+      signal
+    );
+    currentSql = resolved.sql;
+    finalParams = resolved.params;
+    paramMetadata = resolved.paramMetadata;
+    queryId = resolved.queryId;
+  }
+  if (!currentSql) {
+    throw new Error("modifyChart requires either queryId or sql.");
+  }
+  let finalSql = currentSql;
   let sqlChanged = false;
   let finalQuestion = input.question;
   const databaseName = input.database ?? queryEngine.getDefaultDatabase();
@@ -2304,17 +2352,24 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   }
   const metadata = queryEngine.getDatabaseMetadata(databaseName);
   let tenantSettings;
-  if (metadata?.tenantFieldName) {
+  if (metadata?.enforceTenantIsolation === false) {
+    tenantSettings = {
+      tenantFieldName: metadata.tenantFieldName ?? "",
+      tenantFieldType: metadata.tenantFieldType ?? "String",
+      enforceTenantIsolation: false
+    };
+  } else if (metadata?.tenantFieldName) {
     tenantSettings = {
       tenantFieldName: metadata.tenantFieldName,
       tenantFieldType: metadata.tenantFieldType,
-      enforceTenantIsolation: metadata.enforceTenantIsolation
+      enforceTenantIsolation: true
     };
   }
   if (hasCustomSql) {
     finalSql = input.sqlModifications.customSql;
     finalParams = {};
     paramMetadata = [];
+    queryId = void 0;
     sqlChanged = true;
   } else if (hasSqlMods && !hasCustomSql) {
     const modifiedQuestion = buildModifiedQuestion(
@@ -2331,7 +2386,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       {
         question: modifiedQuestion,
         session_id: querypanelSessionId,
-        previous_sql: input.sql,
+        previous_sql: currentSql,
         ...options?.maxRetry ? { max_retry: options.maxRetry } : {},
         ...tenantSettings ? { tenant_settings: tenantSettings } : {},
         ...databaseName ? { database: databaseName } : {},
@@ -2356,7 +2411,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     }
     rationale = queryResponse.rationale;
     queryId = queryResponse.queryId;
-    sqlChanged = finalSql !== input.sql;
+    sqlChanged = finalSql !== currentSql;
   }
   const execution = await queryEngine.validateAndExecute(
     finalSql,
@@ -2564,6 +2619,12 @@ var ALL_VIZ_CHART_TYPES = [
 ];
 
 // src/index.ts
+function resolveAttachEnforceTenantIsolation(tenantFieldName, enforceTenantIsolation) {
+  if (enforceTenantIsolation !== void 0) {
+    return enforceTenantIsolation;
+  }
+  return tenantFieldName ? true : void 0;
+}
 var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
   /**
    * @param workspaceId - Workspace UUID (same value as your org in the dashboard). Passed to the API as JWT claim `organizationId`.
@@ -2634,7 +2695,10 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       tags: options?.tags,
       tenantFieldName: options?.tenantFieldName,
       tenantFieldType: options?.tenantFieldType ?? "String",
-      enforceTenantIsolation: options?.tenantFieldName ? options?.enforceTenantIsolation ?? true : void 0
+      enforceTenantIsolation: resolveAttachEnforceTenantIsolation(
+        options?.tenantFieldName,
+        options?.enforceTenantIsolation
+      )
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
@@ -2647,7 +2711,10 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       tags: options?.tags,
       tenantFieldName: options?.tenantFieldName,
       tenantFieldType: options?.tenantFieldType ?? "String",
-      enforceTenantIsolation: options?.tenantFieldName ? options?.enforceTenantIsolation ?? true : void 0
+      enforceTenantIsolation: resolveAttachEnforceTenantIsolation(
+        options?.tenantFieldName,
+        options?.enforceTenantIsolation
+      )
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
@@ -2660,7 +2727,10 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       tags: options?.tags,
       tenantFieldName: options?.tenantFieldName,
       tenantFieldType: options?.tenantFieldType ?? "String",
-      enforceTenantIsolation: options?.tenantFieldName ? options?.enforceTenantIsolation ?? true : void 0
+      enforceTenantIsolation: resolveAttachEnforceTenantIsolation(
+        options?.tenantFieldName,
+        options?.enforceTenantIsolation
+      )
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
@@ -2786,9 +2856,23 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       throw new Error("tenantId is required");
     }
     const databaseName = input.database ?? "db";
-    const params = input.params ?? {};
+    let sql = input.sql;
+    let params = input.params ?? {};
+    if (input.queryId) {
+      const resolved = await resolveQuery(
+        this.client,
+        this.queryEngine,
+        input.queryId,
+        { tenantId }
+      );
+      sql = resolved.sql;
+      params = resolved.params;
+    }
+    if (!sql) {
+      throw new Error("Either queryId or sql is required");
+    }
     const result = await this.queryEngine.validateAndExecute(
-      input.sql,
+      sql,
       params,
       databaseName,
       tenantId