Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท MLflow and ML

The Model Registry in Unity Catalog

Register models in Unity Catalog with MLflow: three-level model names, versions, aliases like champion, loading by alias, permissions, and a runnable registry stand-in.

A tracked run produces a model file. A registry turns it into something other people and jobs can rely on: a named model with numbered versions, labels like "champion", documentation and permissions. In Databricks, the recommended registry is Models in Unity Catalog: models are securable objects just like tables, living in catalog.schema.model_name.

Databricks cannot run on this site, so MLflow calls are read-only. Runnable blocks are plain Python stand-ins that reproduce versioning and alias logic.

Registering a model

Point MLflow at the Unity Catalog registry once per notebook, then register while logging, or afterwards from a run:

Python
import mlflow
mlflow.set_registry_uri("databricks-uc")

# while logging
mlflow.sklearn.log_model(
    model, "model",
    registered_model_name="prod.ml.price_model",
    input_example=X_train.head(3),
)

# or from an existing run
mlflow.register_model("runs:/<run_id>/model", "prod.ml.price_model")

Each registration creates a new version (1, 2, 3, ...) of the same model name. A version stores the files, the signature (input and output schema), the run it came from and the lineage to its training data when available.

Older workspace-level registries used fixed stages (Staging, Production). In Unity Catalog you use aliases instead, which are more flexible. Treat stage-based code in old tutorials as legacy.

Aliases

An alias is a movable label pointing at one version. Common aliases:

  • champion: the version serving production traffic.
  • challenger: a candidate being tested.
Python
from mlflow import MlflowClient
client = MlflowClient()

client.set_registered_model_alias("prod.ml.price_model", "challenger", 4)
# after tests pass, promote:
client.set_registered_model_alias("prod.ml.price_model", "champion", 4)

Consumers load by alias, so promoting a model is a metadata change with no code edits:

Python
model = mlflow.pyfunc.load_model("models:/prod.ml.price_model@champion")
predictions = model.predict(new_data)

Loading by explicit number (models:/prod.ml.price_model/3) is also possible and is right when you need an exact, frozen version.

Documentation and tags

Add a description and tags to versions so people know what they are:

Python
client.update_model_version("prod.ml.price_model", 4, description="RF depth 8, trained on data v3")
client.set_model_version_tag("prod.ml.price_model", 4, "validated", "true")

Registry stand-in

This model is not MLflow. It implements the same rules: auto-incrementing versions, an alias map, and loading by alias or number.

Python Stand-in: versions and aliases

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A promotion gate

Promotion should depend on evidence, not a feeling. A typical check compares the challenger to the champion on the same test set, plus a few sanity tests.

Python Stand-in: promote only if the challenger wins

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Permissions

A registered model is a Unity Catalog object, so the usual grants apply (see Grants and Privileges):

SQL
GRANT EXECUTE ON MODEL prod.ml.price_model TO `ml-consumers`;
GRANT CREATE MODEL ON SCHEMA prod.ml TO `ml-engineers`;

Data scientists register in dev.ml, CI promotes to prod.ml, and application service principals only get EXECUTE. Lineage links a model back to its training tables.

Good practice

  • Always log a signature and input example so inputs are validated.
  • Register from tracked runs only: the run is the model's provenance.
  • Use challenger/champion aliases and automated gates.
  • Keep model documentation (purpose, data, limits) in the description.
  • Separate dev and prod schemas and have CI do the promotion.
  • Deleting versions that served production is a decision to audit, not casual cleanup.

Models can then be served or scored in batch: see Feature Engineering and Model Serving.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a Unity Catalog model name like?

    Models live in schemas and use three-level names.
  2. 2. What does an alias such as champion do?

    Aliases are movable labels, so promotion needs no code change.
  3. 3. How do you load whatever version is currently champion?

    The @alias URI form resolves the alias at load time.
  4. 4. Which privilege lets an application call a registered model?

    Models are used with EXECUTE.

Summary

  • Register models in Unity Catalog: catalog.schema.model, with automatic version numbers.
  • Aliases (champion, challenger) replace legacy stages and make promotion a metadata change.
  • Gate promotion on measurable checks; govern models with grants.
  • Log signatures and keep provenance through tracked runs.

Next: Feature Engineering and Model Serving