Documentation

Tenant isolation

Tenant identity comes from your authenticated backend. Filter by a tenant column or run each tenant in its own schema; pass tenantId on ask() and JWTs, and QueryPanel scopes every query.

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.

attachPostgres with isolation
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.

  1. 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.
  2. Sync and annotate the schema of one tenant (the template schema). Build dashboards and knowledge against it once; they serve every tenant.
  3. 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 against group_1001_indexed.
Your backend: same JWT as always
// 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):

attachRedshift with a tenant schema
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.

ask() and createJwt share the same tenant
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