Publish a Unity Catalog catalog to Microsoft Fabric

Important

This feature is in Beta.

This page explains how to publish a Unity Catalog catalog to Microsoft Fabric. When you publish a Unity Catalog catalog, the Unity Catalog tables become available as read-only mirrored tables on Fabric.

You can query Unity Catalog tables on Fabric. Mirrored tables reflect the data and schema in Azure Databricks.

Mirrored tables are read-only in Fabric. All writes must go through Azure Databricks.

Note

To read Unity Catalog data from Microsoft Fabric using OneLake shortcuts instead, see Use Microsoft Fabric to read data that is registered in Unity Catalog.

Prerequisites

  • Serverless compute, or compute on Databricks Runtime 18.1 or above.
  • An Azure Databricks workspace with Unity Catalog enabled.
  • External data access must be enabled on the Unity Catalog metastore. See Enable external data access to Unity Catalog.
  • A user account or Microsoft Entra ID service principal to authenticate the Fabric connection, registered in both Microsoft Entra ID and Azure Databricks. For service principals, see _.
  • An active Fabric workspace with capacity assigned. For more information, see the Microsoft documentation.
  • The same identity must have at least the Contributor role in the Fabric workspace. See the Microsoft Fabric documentation.

Step 1: Grant privileges

Grant the user or service principal the Unity Catalog privileges required for mirroring in Fabric.

Catalog Explorer

Grant the user or service principal the following privileges on the catalog you want to connect to from Fabric:

  • USE CATALOG
  • USE SCHEMA
  • EXTERNAL USE SCHEMA

For detailed instructions, see Grant permissions on an object.

SQL

Run the following in a SQL editor or notebook attached to the Azure Databricks workspace.

Service principal:

GRANT USE CATALOG ON CATALOG my_catalog TO `<service_principal_application_id>`;
GRANT USE SCHEMA ON CATALOG my_catalog TO `<service_principal_application_id>`;
GRANT EXTERNAL USE SCHEMA ON CATALOG my_catalog TO `<service_principal_application_id>`;

User account:

GRANT USE CATALOG ON CATALOG my_catalog TO `<user@example.com>`;
GRANT USE SCHEMA ON CATALOG my_catalog TO `<user@example.com>`;
GRANT EXTERNAL USE SCHEMA ON CATALOG my_catalog TO `<user@example.com>`;

Step 2: Create a Fabric connection to an Azure Databricks workspace

Create a Fabric connection that points to your Azure Databricks workspace. Fabric uses this connection to authenticate and read Unity Catalog metadata.

  1. In Microsoft Fabric, click the Settings gear icon.

  2. Go to Manage connections and gateways.

  3. Click + New.

  4. In the New connection pane, select Cloud.

  5. Enter a name for the connection.

  6. Set Connection type to Azure Databricks workspace.

  7. Enter the Azure Databricks workspace URL.

  8. Select OAuth 2.0 or service principal as the authentication method.

    • If selecting service principal, enter the following information:

      • Tenant ID: The Microsoft Entra tenant ID of your Azure Databricks workspace. The service principal and the Fabric workspace must be in this same tenant.
      • service principal ID: The application (client) ID of the service principal you registered in Azure Databricks.
      • service principal key: The client secret for the service principal.

    • If selecting OAuth 2.0, click Edit credentials and sign in to Azure Databricks through the popup.

  9. Select Allow this connection to be utilized with either on-premises data gateways or VNet data gateways. to enable sharing.

  10. Select your Privacy level.

  11. Click Create. The new connection appears in your connections list.

Step 3: Publish the catalog from Catalog Explorer

Publish the catalog from the Azure Databricks UI:

  1. In your Azure Databricks workspace, click Data icon. Catalog.

  2. Select the catalog you want to publish.

  3. Click the Share button and select Publish to OneLake.

  4. Click Connect to Microsoft Entra ID and authenticate with your account.

  5. After authentication, select a connection and Fabric workspace:

    • If only one connection matches this Azure Databricks workspace, it's selected automatically.
    • If multiple matching connections exist, select the one you want to use.

    Note

    Only Fabric connections that match the current Azure Databricks workspace URL are shown. You can create multiple connections from the same workspace to the same Fabric tenant.

  6. Review the Display name. The field is pre-populated with the catalog name. You can edit it.

    Note

    Display names must contain only alphanumeric characters and underscores. Hyphens and other special characters are not allowed.

  7. Click Publish to Fabric. The message Creating mirrored catalog... is displayed while the operation completes. This can take up to 20 seconds.

  8. After publishing succeeds, a confirmation appears with an Open in Fabric button.

Step 4: Access tables in Fabric

After publishing succeeds, click Open in Fabric to open the mirrored catalog, or find the mirrored Azure Databricks catalog item in your Fabric workspace.

If the catalog is empty, click Manage catalog on the Fabric item to confirm that schema names from the Unity Catalog catalog are shown. To refresh the mirrored item, click the refresh icon.

You can publish the same Unity Catalog catalog to multiple Fabric workspaces independently.

Limitations

  • Mirrored tables are read-only in Fabric. Writes must go through Azure Databricks.
  • Display names support alphanumeric characters and underscores only. Maximum length is 255 characters.
  • Tables must use Delta Lake, or Iceberg with UniForm, to mirror to Fabric.

Troubleshooting

Error Resolution
403 Forbidden when clicking Publish to Fabric The Fabric workspace has no active capacity assignment. A 403 error means no capacity is assigned, while a 404 error means capacity is assigned but not active. Assign or activate Fabric capacity and retry.
No Azure Databricks connections found No Fabric connection matches this Azure Databricks workspace URL. In Fabric, go to Settings > Manage connections and gateways > New connection and create an Azure Databricks workspace connection with the correct workspace URL and OAuth 2.0 authentication.
Microsoft Entra ID popup closed or canceled An error appears in the publish modal if the sign-in popup is closed. Click Connect to Microsoft Entra ID to retry.
Invalid display name Display names cannot contain hyphens or special characters. Use alphanumeric characters and underscores only, up to 255 characters.
Duplicate display name A mirrored item with that name already exists in the target Fabric workspace. Enter a different name.
Publish times out after 5 minutes Large catalogs can take longer to mirror. Check the Fabric workspace directly. The item might still be processing.
Tables do not appear in Fabric after publishing Click Manage catalog on the Fabric item to confirm that schema names appear. Verify that tables use Delta Lake, or Iceberg with UniForm.
Fabric shows Couldn't Access Data when previewing a table Verify that the service principal has USE CATALOG, USE SCHEMA, and EXTERNAL USE SCHEMA on the catalog and that all prerequisites are met.
Permission error during publish Verify that the publishing user has the Contributor role or above on the target Fabric workspace. Confirm the service principal has the EXTERNAL USE SCHEMA privilege on the Unity Catalog catalog and that external data access is enabled on the metastore.
Microsoft Entra ID token expires during publish An authentication error appears if the token expires mid-publish. Re-authenticate and retry. Tokens refresh silently during normal use.

Additional resources

  • Last updated on