Skip to main content

​
Overview

Tenancy management ensures each user only sees their relevant data through configurable filters. A tenant represents a group of users sharing the same data access permissions. Tenants can be registered via the Backend Setup endpoint or created manually through the interface.

​
Filtering Types

​
Schema-Level Filtering

Isolates tenants to separate database schemas/databases. When enabled, all SQL queries for that tenant will be rewritten to reference tables from their designated schema/database instead of the default.
  • When to use: Complete data separation, compliance requirements, performance isolation
  • Benefits: Maximum security, database-level isolation
  • Example: customer_schema_1, tenant_db_123
Only applies when configured: Schema-level filtering only affects tenants who have a schemaPreFilter value set. Tenants without this configuration will query the default schema. This allows you to mix schema-based and column-based tenancy within the same connection.

​
Supported Data Sources

Data SourceSupportedHow It Works
MySQL✅The schemaPreFilter value replaces the database name in all queries. MySQL treats databases as schemas.
Clickhouse✅The schemaPreFilter value replaces the database name. Clickhouse uses databases as schemas (similar to MySQL).
Data Plane✅The schemaPreFilter value is appended to or replaces the schema portion of multi-part identifiers.
Postgres❌Use Column Pre-Filtering instead
BigQuery❌Use Column Pre-Filtering instead
Snowflake❌Use Column Pre-Filtering instead
MS SQL❌Use Column Pre-Filtering instead

​
Setting Up Schema-Level Filtering

Via API (Backend Setup): 
{
  "displayName": "Customer ABC Corp",
  "schemaPreFilter": "customer_abc_database",
  "prefilters": {},
  "tenantEditingPermissions": {
    "editCharts": false,
    "addChart": false
  }
}
Via UI:
  1. Navigate to Home → Deploy → Registered Tenants → Create tenant
  2. Enter the tenant display name
  3. In the Schema Pre-filter field, enter the database/schema name (e.g., customer_abc_database)
  4. Save the tenant

​
How Query Rewriting Works

When a tenant with schemaPreFilter: "customer_db" runs a query, all table references are rewritten: 
-- Original query (references default database)
SELECT * FROM orders WHERE status = 'active'

-- Rewritten query (references tenant's database)
SELECT * FROM customer_db.orders WHERE status = 'active'
This ensures complete isolation—the tenant cannot access tables outside their designated database.

​
Connection Configuration for Schema-Based Tenancy

When using schema-based tenancy, you need to configure your connection with a Default Schema. This setting:
  1. Filters metadata: Only tables from the specified database/schema are included when computing metadata. This means your catalog will show tables as A, B, C instead of (schema_one) A, (schema_one) B, (schema_two) A, etc.
  2. Sets the default for admins: Admin users (those with empty prefilters) will query from this default database.
  3. Falls back for tenants without schema: Tenants that don’t have a schemaPreFilter configured will also use this default database.
1

Navigate to Connection Settings

Go to Connect → Select your connection → Edit
2

Set Default Database/Schema

Configure the default database for schema-based tenancy: - MySQL: Enter the database name in the Default Database (for Database Tenancy) field - Clickhouse: Enter the database name in the Default Database (for Database Tenancy) field - Data Plane: Enable schema-based tenancy and select the Default Schema from the dropdown
3

Refresh Metadata

After setting the default database/schema, click Compute Metadata to recompute the table catalog. The metadata will now only include tables from your specified database.
4

Register Tenants with Schema Prefilters

When registering tenants, set their schemaPreFilter to their specific database name. Each tenant will only see data from their designated database.
Important: If you have multiple databases with identically-named tables (e.g., tenant_a.orders and tenant_b.orders), you must set a Default Schema on your connection. Otherwise, metadata computation will rename tables to avoid conflicts (e.g., (tenant_a) orders, (tenant_b) orders), which will break schema-based tenancy.

​
Column Pre-Filtering

Filters data using column values within shared schemas.
  • When to use: Shared database with tenant identifiers, flexible multi-column filtering
  • Benefits: Granular control, multiple filter combinations
  • Example: customer_id = 'user_123' AND region = 'us-east'

​
Creating Tenants

Navigate to Home → Deploy → Registered Tenants → Create tenant

​
Required Fields

Tenant Display Name
  • Human-readable identifier
  • Example: Customer ABC Corp
Filtering (Choose one or both)
  • Schema Pre-filter: Database/schema name for schema-level filtering
  • Column Pre-filters: Column name + value pairs for row-level filtering
    • Multiple filters supported (AND logic)
    • Required if no schema pre-filter specified

​
Optional Configuration

You can register a tenant by following the Backend Setup instructions. Tenant Editing Permissions
  • Add/Remove/Create/Edit Charts
  • Add Filters
  • AI Insights
Custom Metadata
  • Key-value pairs for additional tenant information
  • Example: billing_tier: premium, region: us-east
If you have completed the Backend Setup, you can view the dashboard as one of your customers.

​
Validation Rules

  • Tenant name required
  • Either schema OR Column Pre-Filtering must be configured
  • Empty filter names/keys not allowed
  • Warning: No filtering = admin access to all data

​
Preview Mode

Test tenant configurations by previewing dashboards as specific tenants.
Preview tenant selection

​
Sample Dataset Examples

Column Pre-Filtering:
  • Name: Customer-1
  • Column Pre-Filter: CustomerID = User_1
Schema Filtering:
  • Name: Schema-Customer
  • Schema: customer_schema_1
Tenant creation form

​
Best Practices

  • Index Column Pre-Filter columns for performance
  • Grant minimal permissions required
  • Validate all tenant configurations to prevent admin access
  • Schema filtering generally performs better than complex Column Pre-Filtering
  • Regular audits of tenant permissions and access