Run Unity Catalog managed tables on OneLake

Hands-on · Verified 18 September 2026

This walkthrough uses the Microsoft Fabric Azure Databricks Storage item as the managed-storage root for an Azure Databricks Unity Catalog catalog. It then exposes a Delta table through a Mirrored Azure Databricks Catalog.

The release status is part of the design: Azure Databricks Storage is Preview, the Databricks-to-OneLake external-location capability is Beta, and the Fabric-initiated mirrored catalog used for consumption is generally available. Treat the storage path as an evaluation or controlled-workload pattern until the preview features reach GA.

The architecture

Azure Databricks
  -> Unity Catalog managed Delta table
  -> Azure Databricks Storage (OneLake /Files)
  -> Mirrored Azure Databricks Catalog
  -> Fabric SQL endpoint, Lakehouse shortcut, or Direct Lake

The first integration makes OneLake the managed-storage root. The second synchronizes catalog metadata and creates shortcuts. It does not copy table data.

This is not OneLake catalog federation. Federation exposes existing Fabric data inside Databricks. Here, Databricks owns the table, OneLake stores the bytes, and Fabric provides a read-only consumption surface.

Prerequisites and names

• a capacity-backed Fabric workspace for the storage item;
• a second Fabric workspace for the mirrored catalog and consumers;
• Unity Catalog-enabled Azure Databricks;
• Databricks Runtime 18.1 or later, or serverless compute;
• an Access Connector for Azure Databricks with managed identity;
• Unity Catalog privileges to create storage credentials, external locations, and catalogs; and
• a user or service principal for the Fabric-to-Databricks connection.

1. Enable the settings

1. In Azure Databricks, ask a workspace administrator to enable the OneLake external-location feature on the Previews page.
2. In Fabric, open Settings → Admin portal → Tenant settings and enable Users can create Azure Databricks Storage items for the intended admin group.
3. In dbx-onelake-storage, open Workspace settings → Delegated settings → OneLake settings and enable Authenticate with OneLake user-delegated SAS tokens.

2. Create and authorize the Access Connector

1. Create ac-dbx-onelake in Azure and enable its managed identity.
2. Copy its resource ID:

/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Databricks/accessConnectors/ac-dbx-onelake

3. In dbx-onelake-storage, select Workspace settings → Manage access → Add people or groups.
4. Add the managed identity and assign Contributor, the minimum documented role for this write path.

Keep this workspace dedicated. Admins, Members, and Contributors can read, write, and delete data in the storage item even without the equivalent Unity Catalog grant.

3. Create Azure Databricks Storage

In dbx-onelake-storage:

1. select + New item → Azure Databricks Storage;
2. name it uc_managed_storage; and
3. copy the workspace and item IDs from the browser URL.

FABRIC_STORAGE_WORKSPACE_ID = <workspace-guid>
DATABRICKS_STORAGE_ITEM_ID  = <item-guid>

Build this exact path:

abfss://<FABRIC_STORAGE_WORKSPACE_ID>@onelake.dfs.fabric.microsoft.com/<DATABRICKS_STORAGE_ITEM_ID>/Files/

Use GUIDs, not names, and include /Files/.

4. Create the Unity Catalog storage credential

In Azure Databricks Catalog:

1. select the configuration menu and Create a credential;
2. select Azure Managed Identity;
3. name it onelake_mi_credential;
4. paste the Access Connector resource ID;
5. provide the managed identity ID for a user-assigned identity; and
6. create it.

5. Create and test the external location

In Catalog Explorer:

1. open Connect → External locations → Create external location;
2. name it onelake_uc_root;
3. select OneLake and onelake_mi_credential;
4. paste the GUID-based ABFSS path;
5. create it; and
6. select Test connection.

The warning skipped file events read is expected for OneLake paths. For 403 Forbidden, check the identity’s workspace role, active capacity, both GUIDs, and /Files/.

6. Create a deterministic Delta table

Run on Databricks Runtime 18.1+ or serverless. Replace both GUIDs:

CREATE CATALOG IF NOT EXISTS onelake_demo
MANAGED LOCATION 'abfss://<FABRIC_STORAGE_WORKSPACE_ID>@onelake.dfs.fabric.microsoft.com/<DATABRICKS_STORAGE_ITEM_ID>/Files/uc-managed';

CREATE SCHEMA IF NOT EXISTS onelake_demo.sales;

CREATE OR REPLACE TABLE onelake_demo.sales.orders
USING DELTA AS
SELECT * FROM VALUES
 ('O-1001', DATE '2026-09-01', 'Contoso Retail',   'Web',     CAST(129.99 AS DECIMAL(12,2))),
 ('O-1002', DATE '2026-09-02', 'Fabrikam Stores', 'Store',   CAST( 49.50 AS DECIMAL(12,2))),
 ('O-1003', DATE '2026-09-03', 'Adventure Works', 'Web',     CAST(220.00 AS DECIMAL(12,2))),
 ('O-1004', DATE '2026-09-04', 'Northwind',       'Mobile',  CAST( 15.99 AS DECIMAL(12,2))),
 ('O-1005', DATE '2026-09-05', 'Tailspin Toys',   'Partner', CAST(314.87 AS DECIMAL(12,2)))
AS t(order_id, order_date, customer_name, channel, net_amount);

SELECT COUNT(*) AS row_count,
       CAST(SUM(net_amount) AS DECIMAL(18,2)) AS total_net_amount
FROM onelake_demo.sales.orders;

DESCRIBE DETAIL onelake_demo.sales.orders;

The aggregate must return 5 and 730.35. DESCRIBE DETAIL should show format = delta and a location under the storage item’s GUID path.

7. Authorize the mirror identity

Enable external data access in Catalog → gear icon → Metastore → Details → External data access, then grant:

GRANT USE CATALOG ON CATALOG onelake_demo
TO `<FABRIC_CONNECTION_PRINCIPAL>`;

GRANT USE SCHEMA ON SCHEMA onelake_demo.sales
TO `<FABRIC_CONNECTION_PRINCIPAL>`;

GRANT SELECT ON TABLE onelake_demo.sales.orders
TO `<FABRIC_CONNECTION_PRINCIPAL>`;

GRANT EXTERNAL USE SCHEMA ON SCHEMA onelake_demo.sales
TO `<FABRIC_CONNECTION_PRINCIPAL>`;

EXTERNAL USE SCHEMA is not included in ALL PRIVILEGES and is not granted automatically to schema owners.

8. Create the mirrored catalog

In dbx-onelake-consumption:

1. select + New item → Mirrored Azure Databricks catalog;
2. use Organizational account or Service principal authentication;
3. select onelake_demo, sales, and orders;
4. keep future schema synchronization enabled; and
5. create the item.

Query the generated endpoint:

SELECT COUNT_BIG(*) AS row_count,
       CAST(SUM(net_amount) AS DECIMAL(18,2)) AS total_net_amount
FROM [sales].[orders];

Expect 5 and 730.35. For Spark, create a Lakehouse and use Get data in your lakehouse → New shortcut → Microsoft OneLake, then select the mirrored catalog and sales.orders.

Synchronization has two clocks

1. Unity Catalog to the mirrored item synchronizes catalog structure. Automatic sync tracks selected schema and table additions and deletions. Renames are unsupported.
2. Delta files to the SQL endpoint can take seconds to minutes. A successful Databricks write does not mean immediate endpoint visibility.

Diagnose one layer at a time: query Databricks, inspect DESCRIBE DETAIL, verify the mirror principal, check object selection and support, then investigate endpoint freshness.

Security has four boundaries

To secure the mirrored item:

1. open Manage OneLake security;
2. create a Grant role with Read and Selected data;
3. add the intended Entra group;
4. give consumers Viewer or item-level Read;
5. inspect DefaultReader; and
6. test with a non-admin identity.

Admins, Members, and Contributors already have data access. Unity Catalog row filters, column masks, and ABAC policies do not propagate into Fabric. Define the equivalent Fabric controls and keep both policy sets aligned.

Limits

• Use Delta for this combined path.
• The mirrored Fabric surface is read-only.
• Do not edit Unity Catalog managed-table files directly.
• Fabric Runtime must be at least Spark 3.4 / Delta 2.4 for Spark use.
• Databricks-initiated Publish to OneLake is a separate Public Preview whole-catalog path.

Conclusion

The robust pattern is asymmetric: Databricks writes and governs, OneLake stores the bytes, and Fabric mirrors metadata and applies downstream permissions. The operational work is restricting the storage workspace, granting EXTERNAL USE SCHEMA, allowing for asynchronous visibility, and treating Unity Catalog and OneLake as separate policy planes.

Authoritative sources

1. Connect Azure Databricks to a OneLake external location
2. Create an Azure Databricks Storage item
3. Microsoft Fabric with Azure Databricks
4. Configure a Mirrored Azure Databricks Catalog
5. Mirroring Azure Databricks Unity Catalog
6. Secure mirrored Azure Databricks data in Fabric
7. Mirrored Azure Databricks catalog limitations
8. Mirrored Azure Databricks catalog FAQ
9. Enable external data access to Unity Catalog
10. How OneLake security controls data access
11. Create and manage OneLake security roles
12. SQL analytics endpoint metadata sync