Unity Catalog naming conventions and catalog design patterns

Summary

• The most common naming patterns are environment-based (dev, staging, prod), domain-based (sales, finance, engineering), hybrid (sales_prod), and data-lifecycle-based (raw, curated, analytics).
• Environment-based catalogs are the recommended default for most organizations, providing clear isolation and preventing accidental production changes.
• Domain-based catalogs work best for federated governance models and data mesh architectures where business units own their data.
• Keep the total number of catalogs between 3-10 per metastore to reduce administrative overhead while maintaining organizational clarity.
• Use schemas, not catalogs, to organize data within a team or project; catalogs are the primary unit of governance and isolation.

Unity Catalog naming conventions and catalog design patterns
A clear naming scheme and organizational structure for catalogs becomes essential as data governance scales. Unity Catalog's three-level namespace (catalog.schema.table) makes catalogs the primary unit of isolation and access control, so how you name and structure them directly affects both usability and security. Choose a pattern that reflects your organization's governance model, environment strategy, and data ownership structure.

What is a catalog?

In Unity Catalog, a catalog is the top-level container for data objects. Each catalog contains schemas, which in turn contain tables, volumes, and other assets. Catalogs are the primary boundary for governance: you grant access at the catalog level, apply retention policies to catalogs, and audit data access per catalog. A three-catalog minimum per metastore is typical (dev, staging, prod); many organizations use 5-10.

Key design patterns to evaluate

Pattern	Use When	Examples	Trade-offs
Environment-based	You want simple, clear separation by SDLC stage	dev, staging, prod	Best for most teams; limits cross-environment reuse
Domain-based	You operate as a data mesh or have strong business unit ownership	sales, finance, engineering, marketing	Promotes autonomy; requires clear data contracts between domains
Hybrid	You combine environment and domain governance	sales_prod, sales_dev, finance_prod	Most flexible; higher catalog count and naming complexity
Data-lifecycle	You follow medallion architecture at the catalog level	raw, curated, analytics	Clear data maturity progression; requires upfront architecture planning

How Databricks approaches catalog organization

Databricks documents recommend environment-based catalogs as the organizational default. This pattern isolates dev and staging experiments from production data, preventing accidental changes and supporting promotion workflows. A team moving code through dev → staging → prod runs the same pipeline against different catalogs, leaving data intact.
For organizations with multiple business units or a data mesh model, domain-based catalogs work well. Each domain owns a catalog (sales, finance, engineering) and controls who can read or write within it. This approach aligns catalog structure with team boundaries and encourages data product thinking. Hybrid patterns (combining both environment and domain, e.g., sales_prod, finance_dev) are common in large enterprises.
Instead of creating new catalogs for individual teams or projects, use schemas. The pattern catalog.my_team.my_project is far simpler than my_team_my_project_catalog. Catalogs are expensive to manage; schemas are lightweight. Limit catalogs to the truly distinct governance boundaries in your organization.
Key practices:

• Use consistent naming across all catalogs (all lowercase, underscores for multi-word names).
• Document catalog purpose and ownership in the catalog's comment field.
• Assign production catalogs to groups, not individuals.
• Use catalog grants to control who can create schemas and tables.

Use cases

Financial services: A capital-markets firm runs a hybrid model: prod for live analytics dashboards, dev for analyst experiments, and a risk_prod catalog for regulatory models. Each environment is completely isolated, and promotion from dev to prod happens via job scripts that compare results before advancing.
Data mesh adoption: A retail company moves to domain-based catalogs: supply_chain, customer_engagement, finance, inventory. Each domain team owns and publishes data products in their catalog. Other teams access them via shared views and published tables with clear SLAs.
Large enterprise: A technology company combines both: prod, staging, dev for environment separation, plus domain-specific paths within each (prod.sales, prod.analytics, dev.sales). This balances global governance with team autonomy.

FAQs

Should we create one big catalog or multiple smaller ones?

Start with 3-5 catalogs (dev, staging, prod minimum). Each represents a distinct governance boundary. Most organizations plateau at 5-10. Creating catalogs per team or project leads to administrative chaos and makes cross-team discovery harder. Use schemas within a catalog instead.

Can we rename a catalog without losing data?

No. You must create a new catalog and migrate data to it using Databricks utilities or third-party tools. Plan your naming scheme upfront. If you must rename, automate the migration with a script to avoid manual errors.

How do we handle cross-catalog queries and data sharing?

Unity Catalog allows cross-catalog queries within a metastore. You can grant SELECT on a table in catalog A to users who primarily work in catalog B. For sharing across metastores or clouds, use Databricks Partner Connect or Iceberg REST catalog federation.

What naming style should we use for catalogs?

Use lowercase with underscores (sales_prod, not SalesProd or Sales.Prod). This convention minimizes escaping issues in SQL and works consistently across APIs and UIs. Document your convention in an internal style guide.

How do we migrate from no governance to catalogs?

Start in dev and staging first. Test your naming scheme and access patterns before promoting to production. Use schemas aggressively to organize existing data, minimizing the number of new catalogs you create. Then move production workloads over with a cutover plan.