How do I refactor 2-level (schema.table) names to Unity Catalog's 3-level namespace across multiple workspaces?

Summary

• Unity Catalog's 3-level namespace (catalog.schema.table) centralizes governance across workspaces, but legacy 2-level references (schema.table) must be refactored or mapped via aliases to avoid runtime failures.
• The best strategy depends on your multi-workspace topology: single logical catalog per workspace with cross-workspace queries, or a shared enterprise catalog and workspace-local schemas.
• Automated analysis of job definitions, notebooks, and SQL code reveals which references are hardcoded 2-level, which are dynamic, and which can be safely refactored in bulk vs. by hand.
• A phased approach (identify, prioritize by blast radius, test aliases, then refactor) minimizes risk and gives teams confidence before switching to full 3-level governance.

How do I refactor 2-level (schema.table) names to Unity Catalog's 3-level namespace across multiple workspaces?
Refactoring from Hive metastore (2-level: schema.table) to Unity Catalog (3-level: catalog.schema.table) in a multi-workspace setup is fundamentally a query rewriting problem. Once you migrate to Unity Catalog, legacy code that assumes a default schema breaks. Your strategy depends on whether you want to maintain workspace isolation or unify governance across workspaces.

Two common architectures

Single enterprise catalog with workspace-local schemas. One catalog for the enterprise, each workspace owns its own schemas within it. Queries become catalog.workspace_schema.table. This centralizes governance but requires every query to specify the catalog.
Workspace-local catalogs with cross-workspace federation. Each workspace has its own catalog, but Lakeflow Federation or external table references allow queries to reach tables in other catalogs. This preserves workspace isolation but adds latency and complexity to cross-workspace queries.

Architecture	Query Pattern	Governance	Rollout Complexity
Enterprise catalog, workspace schemas	catalog.ws_schema.table	Centralized	Parallel testing per workspace, then cutover
Workspace catalogs, federation	Each workspace: catalog.schema.table; cross-workspace: federation	Distributed	Phased, one workspace at a time

Five-step refactoring strategy

Step 1: Audit legacy code. Inventory where 2-level references appear: job definitions, notebooks, SQL files, DBT manifests, Python code. Categorize as hardcoded 2-level (schema.table), dynamic (schema and table names assembled from variables at runtime), or implicit defaults (a bare table name). Use regex search, query lineage tools, and code scanning to find them.
Step 2: Create alias layer (optional). For zero-downtime migration, create a temporary alias layer. Each 2-level reference (schema.table) gets a 3-level alias (catalog.alias_schema.table) pointing to the real 3-level table. Legacy code runs unchanged while you refactor. Trade-off: aliases add query indirection.
Step 3: Refactor by priority. High-priority: jobs and production pipelines with defined SLAs. Medium-priority: shared notebooks called by multiple teams. Low-priority: ad-hoc user notebooks. Refactor in order to control blast radius.
Step 4: Test in parallel. Create a parallel 3-level namespace in a test catalog. Refactor one job or notebook family at a time. Run old and new code side-by-side to validate identical outputs. Promote to production only when both match.
Step 5: Handle special cases. Hive metastore views with hardcoded references must be recreated with 3-level paths. External tables pointing to cloud storage (S3, ADLS) are re-registered under new 3-level names (location paths don't change). Old lineage entries remain in 2-level namespace. Shared compute across workspaces requires explicit catalog and schema in every query.

Databricks best practices

Use Unity Catalog APIs to scan references. The Databricks SDK and REST API let you list all objects and identify 2-level references in job definitions and notebook metadata automatically.
Declare a default catalog per workspace. Each workspace can have a default catalog (via workspace settings). This allows a query that references schema.table to resolve to default_catalog.schema.table. Explicit naming is safer and more portable.
Use Git Folders for notebook versioning. Store notebooks in Git, test on branches, and deploy via CI/CD. This gives audit trails and rollback capability.
Use Delta Lake version history for rollback. Delta Lake tables retain old versions. If a refactored job produces wrong output, query old versions or revert to a previous job definition via Databricks Declarative Automation Bundles.

FAQs

Can I avoid refactoring with search_path or default schemas?

Unity Catalog does not support search_path. Every query must explicitly specify the catalog (or rely on workspace defaults). For portability, explicit 3-level naming is strongly recommended in multi-workspace environments.

What happens to my data during refactoring?

Refactoring is metadata-only. Delta Lake data files don't move. The table gets a new 3-level name under a new catalog namespace. Data remains in the same S3 or ADLS location. Only the table reference changes.

How do I handle cross-workspace queries?

Use Lakeflow Federation or external table references. After migration, queries must include the full 3-level name. Ensure the source table in the other workspace is registered in Unity Catalog and you have permissions.

Can I migrate incrementally?

Yes. Migrate one workspace to UC while others remain on Hive metastore, bridging them with aliases or external references. This lets you learn and iterate before migrating the rest.