QueryPanel supports two isolation models. With a tenant column, every tenant shares the same tables and queries filter by that column. With one schema per tenant, each tenant has its own schema with the same tables and queries run against the caller's schema. Either way you pass tenantId from your authenticated backend on every ask()call and every embed JWT; the browser never chooses which tenant's data to load.
Attach with a tenant field
Set tenantFieldName to the column that partitions customer rows (often tenant_id). enforceTenantIsolation: true tells generation that a filter is required. tenantFieldType (for example String) helps the generator bind the parameter correctly.
qp.attachPostgres("analytics", createPostgresClient(), {
database: "analytics_db",
description: "Customer analytics database",
tenantFieldName: "tenant_id",
tenantFieldType: "String",
enforceTenantIsolation: true,
});One schema per tenant
If each tenant lives in its own schema with identical tables or views (for example group_4048_indexed, group_4049_indexed), set a tenant schema template instead of a tenant column. Postgres and Redshift only.
- On the datasource, set Tenant schema template to a schema name with one
{tenant}placeholder, e.g.group_{tenant}_indexed. No tenant field is needed. - Sync and annotate the schema of one tenant (the template schema). Build dashboards and knowledge against it once; they serve every tenant.
- Mint the usual embed JWT with the tenant's id as
tenantId. QueryPanel reads it from the verified token and fills the placeholder:tenantId: "1001"runs every query againstgroup_1001_indexed.
// tenantId is only the part that fills {tenant}: "1001", not "group_1001_indexed"
const jwt = await qp.createJwt({ tenantId: session.groupId });Generated and saved SQL names the template schema; before it runs, QueryPanel rewrites it to the caller's schema. A query that still names another tenant's schema, or reads a table outside the tenant's schema, its CTEs or the shared schemas, is refused. Embed requests without a tenantId are rejected, so a token can never fall back to the template schema.
Onboarding a tenant needs no QueryPanel API call: create its schema, then sign JWTs with its id. A tenant whose schema does not exist yet gets a database error, never another tenant's data. tenantId must be 1–64 letters, digits or _ (it is lowercased).
Running queries headless with the Node SDK? Attach with tenantSchema instead of tenantFieldName (you cannot set both):
qp.attachRedshift("analytics", createRedshiftClient(), {
database: "analytics",
tenantSchema: {
template: "group_{tenant}_indexed",
sharedSchemas: ["lookups"], // optional: schemas every tenant may also read
},
});
await qp.ask("How many members joined last month?", {
database: "analytics",
tenantId: "1001", // runs against group_1001_indexed
});Pass tenantId from auth, not the client
Resolve the logged-in organization in your session or middleware, then pass that id. Do not accept tenantId from a query string, request body, or React state as the source of truth.
const tenantId = req.user.tenantId; // from your auth layer
const result = await qp.ask("Show monthly revenue", {
database: "analytics",
tenantId,
});
const jwt = await qp.createJwt({ tenantId });Related
- ask() — natural language to tenant-scoped SQL.
- Mint a tenant JWT — the embed token carries the same tenantId.
- Tenant isolation for customer-facing analytics — product-level explainer.