Models in Unity Catalog
Databricks · Machine Learning & AI
Theory
Models in Unity Catalog is the model registry on Databricks. A registered model lives in the same three-level namespace as tables, for example main.sales.churn_model, so the same grants, lineage, audit and cross-workspace access apply. Each time you register a new trained model it becomes a new version (1, 2, 3...). Instead of the old Staging/Production stages of the legacy Workspace Model Registry, you assign aliases such as @champion and @challenger to versions; serving endpoints and batch jobs load models by alias, so promoting a model means just moving the alias. Lineage links each version back to the run and the tables it was trained on.
Example: Asha registers the best churn run as version 3 of main.sales.churn_model and moves the champion alias from version 2 to 3; the nightly scoring job that loads models:/main.sales.churn_model@champion picks up version 3 automatically.
Why we use it
Teams need one governed place to store approved models, control who can use or change them, and promote or roll back safely. Unity Catalog gives models the same governance as data, and aliases make deployment a metadata change instead of a code change.
When to use it
Use Models in Unity Catalog for every model you plan to deploy or share. The legacy Workspace Model Registry and its stages are for older projects only. Use aliases for promotion, and grant EXECUTE on the model to consumers.
How it works
- Best run chosen in the experiment
- Register the model to main.sales.churn_model (new version)
- Validate the new version against the current champion
- Is the new version better? Yes: Move the @champion alias to it. No: Keep the old champion, tag new as challenger.
- Serving endpoints and jobs using @champion pick it up
Syntax
mlflow.set_registry_uri("databricks-uc")
mlflow.register_model("runs:/<run_id>/model", "<catalog>.<schema>.<model>")
or log_model(..., registered_model_name="<catalog>.<schema>.<model>")
MlflowClient().set_registered_model_alias("<cat.sch.model>", "champion", <version>)
mlflow.pyfunc.load_model("models:/<cat.sch.model>@champion")
GRANT EXECUTE ON MODEL <cat.sch.model> TO `group`;Example
import mlflow
from mlflow import MlflowClient
mlflow.set_registry_uri("databricks-uc")
MODEL = "main.sales.churn_model"
# Register the best run's model as a new version
mv = mlflow.register_model(f"runs:/{best.run_id}/model", MODEL)
# Promote it by moving the alias
client = MlflowClient()
client.set_registered_model_alias(MODEL, "champion", mv.version)
# Batch scoring job always loads the champion
churn = mlflow.pyfunc.spark_udf(spark, f"models:/{MODEL}@champion")
scored = spark.table("main.sales.customer_features").withColumn(
"churn_score", churn("orders_90d", "spend_90d", "days_since_last"))
-- SQL: let the analytics team use it
-- GRANT EXECUTE ON MODEL main.sales.churn_model TO `analysts`;Key points
- Models live at catalog.schema.model, governed like tables
- Each registration creates a new numbered version
- Aliases (@champion, @challenger) replace legacy Staging/Production stages
- Loading by alias means promotion and rollback need no code change
- Lineage links versions to the training run and source tables
- Consumers need EXECUTE on the model plus USE CATALOG/USE SCHEMA