Skip to main content

Migrate workflows and models to Unity Catalog

Databricks recommends using Models in Unity Catalog for improved governance, easy sharing across workspaces and environments, and more flexible MLOps workflows. This page steps you through migrating models in the Workspace Model Registry to Unity Catalog.

Introduction to models in Unity Catalog​

Models in Unity Catalog extends the benefits of Unity Catalog to ML models, including centralized access control, auditing, lineage, and model sharing and discovery across workspaces. Models in Unity Catalog also provides greater flexibility in managing the model lifecycle.

When you migrate models to Unity Catalog, some model lifecycle steps are done differently:

Step 1. Create a model in Unity Catalog​

See Train and register Unity Catalog-compatible models.

Step 2. Assign Unity Catalog permissions to the model​

Unity Catalog has a unified permission model. To learn how to assign permissions to models in Unity Catalog, see Control access to models.

The following table shows the relationship between permissions in the workspace model registry and privileges in Unity Catalog. In addition to the privileges shown in the table, all actions also require USE CATALOG and USE SCHEMA privileges.

Workspace model registry

Unity Catalog

Notes

Can read

EXECUTE

Can edit

CREATE MODEL VERSION + APPLY TAG

Users with these privileges are not able to edit the Description of models or model versions.

Can manage staging versions

APPLY TAG + deployment job

In Unity Catalog, deployment jobs are used to control the movement of model versions through lifecycle stages. For details, see MLflow 3 deployment jobs.

Can manage production versions

APPLY TAG + deployment job

In Unity Catalog, deployment jobs are used to control the movement of model versions through lifecycle stages. For details, see MLflow 3 deployment jobs.

Can manage

MANAGE

Step 3. Copy model versions​

To copy model versions, use copy_model_version() with MLflow client >= 3.4.0.

Python
import mlflow
from mlflow import MLflowClient

# Registry must be set to workspace registry
mlflow.set_registry_uri("databricks")
client = MlflowClient(registry_uri="databricks")

src_model_uri = f"models:/my_wmr_model/1"
uc_migrated_copy = client.copy_model_version(
   src_model_uri, "mycatalog.myschema.my_uc_model"
)

If the destination model does not exist in Unity Catalog, it is created by this API call.

Models in Unity Catalog require a signature. If the workspace model version doesn't have a signature, Databricks recommends that you create one by following the instructions in the MLflow documentation. Another alternative is to use the environment variable MLFLOW_SKIP_SIGNATURE_CHECK_FOR_UC_REGISTRY_MIGRATION. This environment variable is only available when you use copy_model_version() and requires MLflow version 3.4.0 or above. When this environment variable is set to "true", a signature is not required.

For a script that you can use to migrate all of the model versions of a model in your workspace model registry to a destination Unity Catalog model, see Migrate model versions from Workspace Model Registry to Unity Catalog.

Step 4. Migrate model metadata​

This section describes how to map workspace registry-level metadata to Unity Catalog model and model version metadata, such as stages, tags, and descriptions.

Stages​

The Workspace Model Registry used the concept of "stages", such as Staging and Production, to track the model lifecycle. You could search for or call models by stage. In Unity Catalog, stages have been replaced by aliases for calling a model and by tags for labeling models.

For simple migration of Workspace Model Registry stages, you can directly use "Production" and "Staging" or any other alias names you prefer. In the Workspace Model Registry, multiple model versions could be in the same stage, and the latest version was called when you referenced a model version. In Unity Catalog, an alias is assigned to a unique model version.

For simple migration of stage labels, use tags to label model versions as "Production", "Staging", or "Archived". You can use any other label as well. For more info on tags, see Tags.

In the Workspace Model Registry, the lifecycle of a model version was tracked by stage, and human approval was required for a transition request. In Unity Catalog, the lifecycle of a model version is managed by a deployment job. Each task in the deployment job corresponds to a "stage". Deployment jobs allow you to customize the model lifecycle and accommodate more complicated workflows than the Workspace Model Registry. Deployment jobs still accommodate human approvals. For details, see MLflow 3 deployment jobs.

Tags​

In Unity Catalog, you create tags on the model or model version.

Add tags button in Unity Catalog model version UI.

To search for a model by tag in Catalog Explorer, type the key or value into the search box:

Search for models by tag in the Unity Catalog model UI.

In Catalog Explorer, you can use tags only to search for models, not model versions. The MLflow client does not support searching for models by Unity Catalog tags. Unity Catalog allows at most 50 tags per object.

Description and comments​

You can add descriptions to the model and model version. Unity Catalog also provides the option of an AI-generated description for the model.

Add model or model version description in Unity Catalog.

Models in Unity Catalog don't have a corresponding location for the information shown in the Activities section on the model version page in the workspace model registry. If there is information in that section that you want to transfer with the model version, copy it into the Description section of the model version page in Unity Catalog.

Step 5. Update all workloads and endpoints​

After you migrate models and model versions to Unity Catalog, update all jobs, notebooks, and other workloads, including model serving endpoints, to use the versions in Unity Catalog.

Step 6. (Optional) Create a deployment job​

A deployment job automatically triggers whenever a new model version is created and automates the evaluation, approval, and deployment workflow. For details, see MLflow 3 deployment jobs.

You can set notifications to trigger on events such as the creation or approval of a model version. See Add notifications on a job.

If you had email notifications set up for events in the Workspace Model Registry, migrate them as follows:

  • New model version was created: Set up a deployment job that is triggered when a new model version is created, and an email notification when the job is triggered.
  • Stage transition request: Stage transition requests correspond to approval tasks. Set an email notification for the approval task's success or failure.
  • Stage transitions: Stage transitions correspond to job tasks. Set an email notification for the task's success or failure.
  • New comments: Comments are not supported in Unity Catalog.

If you had webhooks set up for events, you can implement them in Unity Catalog as model event job triggers. Model triggers allow you to automate Lakeflow Jobs based on the creation of new models, model versions, or model aliases in Unity Catalog. Model triggers are in Private Preview. Contact your Databricks representative for more information.

More information​

The pages linked below describe how to migrate workflows (model training and batch inference jobs) from the Workspace Model Registry to Unity Catalog.

Last updated on