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

package/README.md

@@ -286,9 +286,37 @@ const { data, missingIds } = await qp.getChartsByIds(
 Saved charts now include the original `prompt` so you can show the question
 alongside chart history or reuse it in follow-up workflows.
 
+## Referencing Queries by `queryId` (recommended)
+
+`ask()` and `modifyChart()` return a server-issued `queryId`. The server stores the generated SQL and bind params for that id, scoped to the authenticated workspace and tenant. **Pass the id instead of SQL** so your clients never send executable SQL or bind params:
+
+```ts
+const response = await qp.ask("revenue by country", { tenantId, database: "analytics" });
+
+// Modify: SQL and params are loaded from the server, client `sql` / `params` are ignored
+const modified = await qp.modifyChart(
+  { queryId: response.queryId, question: "revenue by country", database: "analytics",
+    vizModifications: { chartType: "bar" } },
+  { tenantId },
+);
+
+// Run a stored query (e.g. in a dashboard)
+await qp.runSqlForDashboard({ queryId: response.queryId, database: "analytics" }, { tenantId });
+
+// Save a chart: the server stores the SQL and params it holds for `query_id`
+await qp.createChart({ title: "Revenue", query_id: modified.queryId, vega_lite_spec: spec }, { tenantId });
+```
+
+- When `queryId` / `query_id` is present it **takes priority**: any `sql` / `sql_params` you also send is ignored.
+- An id that belongs to another tenant, or does not exist, is rejected (`404`).
+- `sql` is still accepted when no id is sent, for backward compatibility. Charts saved without a `query_id` (for example older charts) keep using their stored SQL.
+- `modifyChart()` returns the input `queryId` when only visualization changes, and a new `queryId` when SQL is regenerated. Custom SQL (`customSql`) has no id.
+- Generation fails if the server cannot record the query, so a successful `ask()` always returns a `queryId`.
+- Requires an API that supports `GET /v2/queries/:id`; upgrade the API before the SDK.
+
 ## Modifying Charts
 
-The `modifyChart()` method allows you to edit SQL and/or visualization settings, then re-execute and regenerate charts. It works with both fresh `ask()` responses and saved charts.
+The `modifyChart()` method allows you to edit SQL and/or visualization settings, then re-execute and regenerate charts. It works with both fresh `ask()` responses and saved charts. Prefer `queryId` over `sql` (see above).
 
 ### Changing Visualization Settings
 

package/dist/index.cjs

@@ -2194,6 +2194,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 = [];
@@ -2348,11 +2367,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();
@@ -2380,6 +2416,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalSql = input.sqlModifications.customSql;
     finalParams = {};
     paramMetadata = [];
+    queryId = void 0;
     sqlChanged = true;
   } else if (hasSqlMods && !hasCustomSql) {
     const modifiedQuestion = buildModifiedQuestion(
@@ -2396,7 +2433,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 } : {},
@@ -2421,7 +2458,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,
@@ -2866,9 +2903,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