@querypanel/node-sdk 1.3.7 → 1.3.9

package/README.md

@@ -578,6 +578,26 @@ const response = await qp.ask("Show top products", {
 
 BigQuery is attached the same way with `attachBigQuery(name, clientFn, options)`. Any other engine can be plugged in with `attachDatabase(name, adapter)` and your own `DatabaseAdapter` implementation.
 
+## One schema per tenant
+
+If each tenant has its own schema with the same tables (for example `group_4048_indexed`, `group_4049_indexed`), attach with `tenantSchema` instead of `tenantFieldName`. Sync the schema of one tenant; the SQL QueryPanel generates names that schema, and the SDK rewrites it to the caller's schema (`{tenant}` replaced by `tenantId`) before running it:
+
+```ts
+qp.attachRedshift("analytics", createClient, {
+  tenantSchema: {
+    template: "group_{tenant}_indexed",
+    sharedSchemas: ["lookups"], // optional: schemas every tenant may also read
+  },
+});
+
+await qp.ask("How many members joined last month?", { tenantId: "4048" });
+// runs against group_4048_indexed
+```
+
+Queries that read anything outside the tenant's schema, a shared schema or a CTE are refused, so a tenant cannot reach another tenant's schema. `allowedTables` written for the template schema (`group_4048_indexed.users`) applies to every tenant's schema. `tenantId` must be 1–64 letters, digits or `_`. Postgres and Redshift only. Adding a tenant needs no QueryPanel call: create its schema, then sign JWTs with its `tenantId`.
+
+For embedded dashboards, set the same template as **Tenant schema template** on the datasource in QueryPanel and mint the usual JWT; `tenantId` is only the part that fills `{tenant}` (`"4048"`, not `"group_4048_indexed"`). See [Tenant isolation](https://querypanel.io/docs/tenant-isolation#schema-per-tenant).
+
 ## Building locally
 
 ```bash
@@ -621,6 +641,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

@@ -39,10 +39,14 @@ __export(index_exports, {
   QueryPanelSdkAPI: () => QueryPanelSdkAPI,
   QueryPipelineError: () => QueryPipelineError,
   SchemaTooLargeError: () => SchemaTooLargeError,
+  TenantSchemaError: () => TenantSchemaError,
   anonymizeResults: () => anonymizeResults,
   mapGeneratedParams: () => mapGeneratedParams,
   normalizeSqlParamsInput: () => normalizeSqlParamsInput,
-  resolveQueryPipeline: () => resolveQueryPipeline
+  parseTenantSchemaTemplate: () => parseTenantSchemaTemplate,
+  resolveQueryPipeline: () => resolveQueryPipeline,
+  resolveTenantSchema: () => resolveTenantSchema,
+  rewriteTenantSchema: () => rewriteTenantSchema
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -629,6 +633,248 @@ function toNumber(value) {
   return Number.isNaN(parsed) ? void 0 : parsed;
 }
 
+// src/core/sql-relations.ts
+function tokenize(sql) {
+  const tokens = [];
+  let i = 0;
+  while (i < sql.length) {
+    const ch = sql[i];
+    const next = sql[i + 1];
+    if (/\s/.test(ch)) {
+      i++;
+    } else if (ch === "-" && next === "-") {
+      while (i < sql.length && sql[i] !== "\n") i++;
+    } else if (ch === "/" && next === "*") {
+      const end = sql.indexOf("*/", i + 2);
+      i = end < 0 ? sql.length : end + 2;
+    } else if (ch === "'") {
+      i++;
+      while (i < sql.length) {
+        if (sql[i] === "\\") i += 2;
+        else if (sql[i] === "'" && sql[i + 1] === "'") i += 2;
+        else if (sql[i] === "'") break;
+        else i++;
+      }
+      i++;
+    } else if (ch === "$" && /[A-Za-z_$]/.test(next ?? "")) {
+      const tag = /^\$[A-Za-z_]*\$/.exec(sql.slice(i))?.[0];
+      if (tag) {
+        const end = sql.indexOf(tag, i + tag.length);
+        i = end < 0 ? sql.length : end + tag.length;
+      } else {
+        i++;
+      }
+    } else if (ch === '"') {
+      const start = i;
+      let text = "";
+      i++;
+      while (i < sql.length) {
+        if (sql[i] === '"' && sql[i + 1] === '"') {
+          text += '"';
+          i += 2;
+        } else if (sql[i] === '"') break;
+        else text += sql[i++];
+      }
+      i++;
+      tokens.push({ kind: "word", text, quoted: true, start, end: i });
+    } else if (/[A-Za-z_]/.test(ch)) {
+      const start = i;
+      while (i < sql.length && /[A-Za-z0-9_$]/.test(sql[i])) i++;
+      tokens.push({ kind: "word", text: sql.slice(start, i), quoted: false, start, end: i });
+    } else if (/[0-9]/.test(ch)) {
+      while (i < sql.length && /[0-9.eE]/.test(sql[i])) i++;
+    } else {
+      tokens.push({ kind: "punct", text: ch, start: i, end: i + 1 });
+      i++;
+    }
+  }
+  return tokens;
+}
+var identifier = (t) => t?.kind === "word" ? t.quoted ? t.text : t.text.toLowerCase() : void 0;
+var isKeyword = (t, word) => t?.kind === "word" && !t.quoted && t.text.toLowerCase() === word;
+var isPunct = (t, p) => t?.kind === "punct" && t.text === p;
+var CLAUSE_WORDS = /* @__PURE__ */ new Set([
+  "where",
+  "group",
+  "order",
+  "limit",
+  "having",
+  "union",
+  "intersect",
+  "except",
+  "join",
+  "inner",
+  "left",
+  "right",
+  "full",
+  "cross",
+  "natural",
+  "on",
+  "using",
+  "window",
+  "qualify",
+  "offset",
+  "fetch",
+  "for",
+  "lateral",
+  "as"
+]);
+var FROM_CLAUSE_END = /* @__PURE__ */ new Set([
+  "where",
+  "group",
+  "having",
+  "order",
+  "limit",
+  "offset",
+  "fetch",
+  "union",
+  "intersect",
+  "except",
+  "window",
+  "qualify",
+  "for",
+  "returning"
+]);
+function cteNames(tokens) {
+  const names = /* @__PURE__ */ new Set();
+  for (let k = 0; k + 2 < tokens.length; k++) {
+    const value = identifier(tokens[k]);
+    if (!value) continue;
+    if (isKeyword(tokens[k + 1], "as") && isPunct(tokens[k + 2], "(")) names.add(value);
+    if (isPunct(tokens[k + 1], "(")) {
+      let j = k + 2;
+      while (j < tokens.length && !isPunct(tokens[j], ")")) j++;
+      if (isKeyword(tokens[j + 1], "as") && isPunct(tokens[j + 2], "(")) names.add(value);
+    }
+  }
+  return names;
+}
+function findRelations(sql) {
+  const tokens = tokenize(sql);
+  const ctes = cteNames(tokens);
+  const relations = [];
+  const readItem = (start) => {
+    let k = start;
+    if (isKeyword(tokens[k], "lateral")) k++;
+    const first = identifier(tokens[k]);
+    if (!first) return k;
+    const parts = [first];
+    k++;
+    while (isPunct(tokens[k], ".") && identifier(tokens[k + 1])) {
+      parts.push(identifier(tokens[k + 1]));
+      k += 2;
+    }
+    if (isPunct(tokens[k], "(")) return k;
+    if (!(parts.length === 1 && ctes.has(first))) relations.push({ parts });
+    if (isKeyword(tokens[k], "as")) k++;
+    const alias = tokens[k];
+    if (alias?.kind === "word" && (alias.quoted || !CLAUSE_WORDS.has(alias.text.toLowerCase()))) k++;
+    return k;
+  };
+  const selectAtDepth = [false];
+  const inFromAtDepth = [false];
+  const top = () => selectAtDepth.length - 1;
+  for (let k = 0; k < tokens.length; k++) {
+    const token = tokens[k];
+    if (isPunct(token, "(")) {
+      selectAtDepth.push(false);
+      inFromAtDepth.push(false);
+    } else if (isPunct(token, ")")) {
+      if (selectAtDepth.length > 1) {
+        selectAtDepth.pop();
+        inFromAtDepth.pop();
+      }
+    } else if (isKeyword(token, "select")) {
+      selectAtDepth[top()] = true;
+      inFromAtDepth[top()] = false;
+    } else if (isKeyword(token, "join")) {
+      k = readItem(k + 1) - 1;
+    } else if (isKeyword(token, "from") && selectAtDepth[top()] && !isKeyword(tokens[k - 1], "distinct")) {
+      inFromAtDepth[top()] = true;
+      k = readItem(k + 1) - 1;
+    } else if (isPunct(token, ",") && inFromAtDepth[top()]) {
+      k = readItem(k + 1) - 1;
+    } else if (token?.kind === "word" && !token.quoted && FROM_CLAUSE_END.has(token.text.toLowerCase())) {
+      inFromAtDepth[top()] = false;
+    }
+  }
+  return relations;
+}
+
+// src/core/tenant-schema.ts
+var TenantSchemaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TenantSchemaError";
+  }
+};
+var PLACEHOLDER = "{tenant}";
+var TEMPLATE_PART = /^[a-z0-9_]*$/;
+var TENANT_ID = /^[A-Za-z0-9_]{1,64}$/;
+function parseTenantSchemaTemplate(template) {
+  const value = template.trim().toLowerCase();
+  const index = value.indexOf(PLACEHOLDER);
+  if (index < 0 || value.indexOf(PLACEHOLDER, index + 1) >= 0) {
+    throw new TenantSchemaError(
+      `Tenant schema template must contain ${PLACEHOLDER} exactly once`
+    );
+  }
+  const prefix = value.slice(0, index);
+  const suffix = value.slice(index + PLACEHOLDER.length);
+  if (!TEMPLATE_PART.test(prefix) || !TEMPLATE_PART.test(suffix) || !(prefix || suffix)) {
+    throw new TenantSchemaError(
+      "Tenant schema template may only use a-z, 0-9 and _ around {tenant}"
+    );
+  }
+  return { prefix, suffix };
+}
+function matchesTemplate({ prefix, suffix }, schema) {
+  const value = schema.toLowerCase();
+  return value.length > prefix.length + suffix.length && value.startsWith(prefix) && value.endsWith(suffix) && /^[a-z0-9_]+$/.test(value.slice(prefix.length, value.length - suffix.length));
+}
+function resolveTenantSchema(template, tenantId) {
+  const { prefix, suffix } = parseTenantSchemaTemplate(template);
+  const id = tenantId.trim();
+  if (!TENANT_ID.test(id)) {
+    throw new TenantSchemaError(
+      "tenantId must be 1-64 characters of letters, digits or _ for schema-per-tenant isolation"
+    );
+  }
+  return `${prefix}${id.toLowerCase()}${suffix}`;
+}
+function rewriteTenantSchema(sql, template, tenantId) {
+  const parsed = parseTenantSchemaTemplate(template);
+  const tenantSchema = resolveTenantSchema(template, tenantId);
+  const tokens = tokenize(sql);
+  let rewritten = "";
+  let cursor = 0;
+  for (let k = 0; k < tokens.length; k++) {
+    const token = tokens[k];
+    const value = identifier(token);
+    if (!token || !value || !isPunct(tokens[k + 1], ".")) continue;
+    if (!matchesTemplate(parsed, value) || value.toLowerCase() === tenantSchema) continue;
+    const replacement = token.kind === "word" && token.quoted ? `"${tenantSchema}"` : tenantSchema;
+    rewritten += sql.slice(cursor, token.start) + replacement;
+    cursor = token.end;
+  }
+  rewritten += sql.slice(cursor);
+  const pattern = new RegExp(`${escapeRegex(parsed.prefix)}[a-z0-9_]+${escapeRegex(parsed.suffix)}`, "gi");
+  for (const match of rewritten.matchAll(pattern)) {
+    if (match[0].toLowerCase() !== tenantSchema) {
+      throw new TenantSchemaError("Query references another tenant's schema");
+    }
+  }
+  return rewritten;
+}
+var TENANT_SCHEMA_KEY = PLACEHOLDER;
+function tenantSchemaKey(template) {
+  const parsed = parseTenantSchemaTemplate(template);
+  return (schema) => matchesTemplate(parsed, schema) ? TENANT_SCHEMA_KEY : schema.toLowerCase();
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // src/adapters/postgres.ts
 var WILDCARD = "*";
 function maxPostgresPlaceholderIndex(sql) {
@@ -675,6 +921,11 @@ var PostgresAdapter = class {
         this.defaultSchema
       );
     }
+    this.allowsRelation = buildRelationAllowlist(
+      this.allowedTables,
+      options.tenantSchema,
+      this.defaultSchema
+    );
   }
   clientFn;
   databaseName;
@@ -682,9 +933,11 @@ var PostgresAdapter = class {
   kind;
   dialect;
   allowedTables;
+  /** Undefined when queries are unrestricted. */
+  allowsRelation;
   async execute(sql, params) {
-    if (this.allowedTables) {
-      this.validateQueryTables(sql);
+    if (this.allowsRelation) {
+      this.validateQueryTables(sql, this.allowsRelation);
     }
     const boundParams = filterParamsForPostgresSql(sql, params);
     let paramArray;
@@ -695,29 +948,11 @@ var PostgresAdapter = class {
     const fields = result.fields.map((f) => f.name);
     return { fields, rows: result.rows };
   }
-  validateQueryTables(sql) {
-    if (!this.allowedTables || this.allowedTables.length === 0) {
-      return;
-    }
-    const allowedSet = new Set(
-      this.allowedTables.map((t) => tableKey2(t.schema, t.table))
-    );
-    const allowedSchemas = new Set(
-      this.allowedTables.filter((t) => t.table === WILDCARD).map((t) => t.schema)
-    );
-    const neutralizedSql = sql.replace(/EXTRACT\s*\([^)]*FROM\s+[^)]+\)/gi, "EXTRACT(/*neutralized*/)").replace(/SUBSTRING\s*\([^)]*FROM\s+[^)]+\)/gi, "SUBSTRING(/*neutralized*/)").replace(/TRIM\s*\([^)]*FROM\s+[^)]+\)/gi, "TRIM(/*neutralized*/)").replace(/POSITION\s*\([^)]*FROM\s+[^)]+\)/gi, "POSITION(/*neutralized*/)");
-    const tablePattern = /(?:FROM|JOIN)\s+(?:ONLY\s+)?(?:([a-zA-Z_][a-zA-Z0-9_]*)\.)?(["']?[a-zA-Z_][a-zA-Z0-9_]*["']?)/gi;
-    const matches = neutralizedSql.matchAll(tablePattern);
-    for (const match of matches) {
-      const schema = match[1] ?? this.defaultSchema;
-      const table = match[2]?.replace(/['"]/g, "");
-      if (table) {
-        const key = tableKey2(schema, table);
-        if (!allowedSet.has(key) && !allowedSchemas.has(schema)) {
-          throw new Error(
-            `Query references table "${schema}.${table}" which is not in the allowed tables list`
-          );
-        }
+  validateQueryTables(sql, allows) {
+    for (const relation of findRelations(sql)) {
+      if (!allows(relation)) {
+        const name = relation.parts.length === 1 ? `${this.defaultSchema}.${relation.parts[0]}` : relation.parts.join(".");
+        throw new Error(`Query references table "${name}" which is not in the allowed tables list`);
       }
     }
   }
@@ -755,6 +990,9 @@ var PostgresAdapter = class {
     return positionalParams;
   }
   async validate(sql, params) {
+    if (this.allowsRelation) {
+      this.validateQueryTables(sql, this.allowsRelation);
+    }
     const boundParams = filterParamsForPostgresSql(sql, params);
     let paramArray;
     if (boundParams) {
@@ -1044,6 +1282,27 @@ function buildListTablesQuery(dialect, options) {
   LIMIT ${limit};`;
   return { sql, params };
 }
+function buildRelationAllowlist(allowedTables, tenantSchema, defaultSchema) {
+  if (!allowedTables?.length && !tenantSchema) return void 0;
+  const schemaKey = tenantSchema ? tenantSchemaKey(tenantSchema.template) : (schema) => schema.toLowerCase();
+  const entries = [
+    ...allowedTables?.length ? allowedTables : [{ schema: TENANT_SCHEMA_KEY, table: WILDCARD }],
+    ...(tenantSchema?.sharedSchemas ?? []).map((schema) => ({ schema, table: WILDCARD }))
+  ];
+  const tables = /* @__PURE__ */ new Set();
+  const wildcardSchemas = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    const schema = entry.schema === TENANT_SCHEMA_KEY ? entry.schema : schemaKey(entry.schema);
+    if (entry.table === WILDCARD) wildcardSchemas.add(schema);
+    else tables.add(tableKey2(schema, entry.table.toLowerCase()));
+  }
+  return ({ parts }) => {
+    if (parts.length > 2) return false;
+    const table = parts[parts.length - 1].toLowerCase();
+    const schema = schemaKey(parts.length === 2 ? parts[0] : defaultSchema);
+    return wildcardSchemas.has(schema) || tables.has(tableKey2(schema, table));
+  };
+}
 function tableKey2(schema, table) {
   return `${schema}.${table}`;
 }
@@ -1648,7 +1907,9 @@ var QueryEngine = class {
     const adapter = this.getDatabase(databaseName);
     const metadata = this.getDatabaseMetadata(databaseName);
     let finalSql = sql;
-    if (metadata) {
+    if (metadata?.tenantSchema) {
+      finalSql = rewriteTenantSchema(sql, metadata.tenantSchema.template, tenantId);
+    } else if (metadata) {
       finalSql = this.ensureTenantIsolation(sql, params, metadata, tenantId);
     }
     await adapter.validate(finalSql, params);
@@ -2492,6 +2753,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 +2844,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,
@@ -3377,6 +3658,9 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
   attachPostgres(name, clientFn, options) {
+    if (options?.tenantSchema && options.tenantFieldName) {
+      throw new Error("Use either tenantSchema or tenantFieldName for tenant isolation, not both");
+    }
     const adapter = new PostgresAdapter(clientFn, options);
     const metadata = {
       name,
@@ -3388,7 +3672,8 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       enforceTenantIsolation: resolveAttachEnforceTenantIsolation(
         options?.tenantFieldName,
         options?.enforceTenantIsolation
-      )
+      ),
+      tenantSchema: options?.tenantSchema
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
@@ -4443,9 +4728,13 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
   QueryPanelSdkAPI,
   QueryPipelineError,
   SchemaTooLargeError,
+  TenantSchemaError,
   anonymizeResults,
   mapGeneratedParams,
   normalizeSqlParamsInput,
-  resolveQueryPipeline
+  parseTenantSchemaTemplate,
+  resolveQueryPipeline,
+  resolveTenantSchema,
+  rewriteTenantSchema
 });
 //# sourceMappingURL=index.cjs.map