Unity Catalog Governance

Unity Catalog defines the governance foundation of your platform. While compute and workspaces determine how workloads execute, Unity Catalog governs how data is organized, secured, and shared across environments.

This section outlines guiding principles for structuring Unity Catalog—catalogs, schemas, and access controls—in ways that align with your business and deployment model, enabling strong governance, clear accountability, and sustainable growth.

For additional context, see Data governance with Unity Catalog.

Reference implementation: See how Firefly implements SSO-SPN authentication and Unity Catalog governance. For a detailed technical deep-dive, see Databricks Identity Authentication Architecture.

Single-Tenant: Catalog per Customer

When each customer has their own workspace, the recommended approach is to provision a dedicated catalog per customer. This pattern is appropriate when customers need to bring their own data or require authoring capabilities to create their own data assets.

Workspace Binding

Workspace bindings allow admins to restrict which workspaces can access specific catalogs. This capability allows partners to easily share a centrally managed catalog with their customers, enabling a hub-and-spoke model that can scale with your customers.

Hub and Spoke Model

The hub-and-spoke model provides a balance between centralized governance and customer autonomy:

Catalog Type	Description
Hub (Partner Catalog)	A central catalog owned by the partner/platform provider, shared with customers with read-only access and governance controls
Spoke (Customer Catalog)	Dedicated catalog where customers can write and manage their own assets

Structure Example:

metastore/
├── partner_hub/              # Hub: Partner-owned (read-only for customers)
│   ├── reference_data/
│   │   ├── dim_products
│   │   ├── dim_regions
│   │   └── dim_currency
│   └── shared_models/
│       └── ml_scoring_model
│
├── customer_a/               # Spoke: Customer writes and manages assets
│   ├── raw/
│   ├── curated/
│   └── analytics/
│
└── customer_b/               # Spoke: Customer writes and manages assets
    ├── raw/
    ├── curated/
    └── analytics/

Grants Structure:

-- Hub catalog: Read-only for customers
GRANT USE CATALOG ON CATALOG partner_hub TO `customer_a_group`;
GRANT USE SCHEMA ON SCHEMA partner_hub.reference_data TO `customer_a_group`;
GRANT SELECT ON SCHEMA partner_hub.reference_data TO `customer_a_group`;

-- Spoke catalog: Permissions for customer
GRANT ALL PRIVILEGES ON CATALOG customer_a TO `customer_a_admin`;
GRANT USE CATALOG ON CATALOG customer_a TO `customer_a_group`;

Multi-Tenant Deployment Patterns

For multi-tenant workspace deployments, three primary patterns are available. The choice depends on scale, isolation requirements, and operational preferences.

See Unity Catalog best practices for additional governance recommendations.

Factor	Schema per Tenant	Multi-Tenant Tables	Table per Customer
Scale Limit	10,000 schemas/catalog	Unlimited tenants	10,000 tables/schema
Flexibility	Add tables, views, functions as needs evolve	Uniform schema	Tables only; limited extensibility
Migration Overhead	Apply per schema	Apply once	Apply per table
Offboarding	DROP SCHEMA CASCADE	DELETE + audit	DROP multiple tables
Object Support	Tables, views, functions, volumes, models	Shared objects only	Tables only

Schema per Tenant

Schema-per-tenant provides strong isolation with clean namespace boundaries. This is the recommended approach for most multi-tenant deployments and can support thousands of tenants.

Structure with Shared Common Schema:

catalog/
├── common/                    # Shared schema (read-only for tenants)
│   ├── dim_products
│   ├── dim_regions
│   └── dim_currency
│
├── customer_a/                # Tenant schema
│   ├── fact_orders
│   ├── fact_inventory
│   └── dim_locations          # Tenant-specific dimension
│
└── customer_b/
    ├── fact_orders
    ├── fact_inventory
    └── dim_cost_centers       # Different tenant-specific dimension

Grants Structure:

-- Every tenant gets read access to common
GRANT USE SCHEMA ON SCHEMA catalog.common TO `customer_a_group`;
GRANT SELECT ON SCHEMA catalog.common TO `customer_a_group`;

-- Tenant-specific access to their schema
GRANT ALL PRIVILEGES ON SCHEMA catalog.customer_a TO `customer_a_group`;

Multi-Tenant Tables

Multi-tenant tables store all tenant data in a single table, typically partitioned by tenant_id. This approach offers operational simplicity but requires careful consideration of tradeoffs.

When Multi-Tenant Tables Make Sense	When to Avoid
High-scale SaaS with thousands of small tenants	Tenants need custom columns or additional tables
All tenants have identical data structures	Tenant-specific transformations required
Operational simplicity: single schema migration	High tenant churn—DROP SCHEMA CASCADE is cleaner
Onboarding is as simple as adding rows	Contractual requirements for physical separation

Security Implementation:

Row filters enforce tenant isolation at the table level. See Row filters and column masks for implementation guidance.

-- Create row filter function
-- Note: Function logic must match your tenant identity mechanism
-- (session variables, group membership, custom attributes, etc.)
CREATE FUNCTION tenant_filter(tenant_id STRING)
RETURNS BOOLEAN
RETURN tenant_id = SESSION_USER() OR IS_ACCOUNT_GROUP_MEMBER(tenant_id);

-- Apply row filter to table
ALTER TABLE catalog.production.fact_orders
SET ROW FILTER tenant_filter ON (tenant_id);

note

Row-level security requires trust in the implementation. Schema-level grants are often cleaner than row-filter policies at scale. For scalable policy management, consider attribute-based access control (ABAC) using tags.

Table per Customer

Table-per-customer is generally not recommended. Since Unity Catalog supports 10,000 schemas per catalog and 10,000 tables per schema, the scale ceiling is equivalent. However, schema-per-tenant provides significantly more flexibility: if customer requirements change and they need an additional table, view, function, or volume, you simply add it to their schema.

Hybrid Approach

Some organizations benefit from combining patterns based on data sensitivity:

• Operational data — Multi-tenant tables for simplicity and performance
• Sensitive/regulated data — Schema-per-customer for isolation and compliance

This adds complexity but can be the right tradeoff when you have mixed requirements.

Access Control Patterns

Use views or row/column-level security to control data access. These patterns provide clean query semantics while maintaining proper isolation.

See Access control in Unity Catalog for a comprehensive overview.

View-Based Access (Recommended)

Views abstract the underlying storage structure while providing tenant-specific access.

Pattern: Shared Storage with Tenant Views

catalog/
├── _internal/                 # Physical storage (hidden from tenants)
│   ├── fact_orders            # All tenant data, partitioned by tenant_id
│   └── fact_inventory
│
├── customer_a/                # Tenant-facing views
│   ├── orders      → VIEW     # SELECT * FROM _internal.fact_orders
│   └── inventory   → VIEW     #   WHERE tenant_id = 'customer_a'
│
└── customer_b/
    ├── orders      → VIEW
    └── inventory   → VIEW

View Definition:

CREATE VIEW catalog.customer_a.orders AS
SELECT
  order_id,
  product_id,
  quantity,
  order_date
  -- Exclude tenant_id from projection
FROM catalog._internal.fact_orders
WHERE tenant_id = 'customer_a';

Benefits:

• Single schema migration: Alter the internal table once; all views inherit changes
• Cross-tenant analytics: Internal teams query _internal directly
• Clean tenant experience: Tenants write simple queries without tenant_id filters
• Partition pruning: Views with WHERE tenant_id = 'x' prune efficiently

Row and Column Level Security

Unity Catalog supports row filters and column masks directly on tables, providing an alternative to views.

Aspect	Views	Row/Column Filters
Namespace	Clean per-tenant namespace	Shared namespace
Object Management	More objects to manage	Fewer objects
Query Experience	Intuitive (tenant sees 'orders')	Must know table names
Security Model	Explicit per-tenant	Automatic/invisible

Decision Framework

If You Have...	Recommendation
Workspace per customer, customer brings own data	Catalog per customer (Hub & Spoke)
Multi-tenant, unique customer assets needed	Schema per tenant
Multi-tenant, uniform schema	Multi-tenant tables with RLS
Contractual physical separation requirements	Catalog per customer
Critical cross-tenant analytics	Multi-tenant tables or views over shared storage
High churn (frequent onboard/offboard)	Schema per customer (clean deletion)
Per-tenant schema customization needed	Schema per tenant

What's Next

• Scale & Limits — Unity Catalog and workspace limits
• Cost Management — Tagging for cost attribution
• Onboarding — Customer and user onboarding workflows