MLflow Prompt Registry on Databricks: Register, Version, Alias and Load a Prompt

What this deep dive adds

Chapter 40 of the course teaches the model: versions never change, aliases move, and promotion is never a branch merge or an overwritten file. This post is the working version: names and privileges in Unity Catalog, both template formats, every call from registration to rollback, how an app should load a prompt, and the frameworks that need single braces.

Prompt version control is a Section 4 (Assembling and Deploying Applications) objective in the 18 March 2026 exam guide, and the guide's sample question 7 is about it. How prompt promotion fits a wider release pipeline is Chapter 41 of the course.

Names and privileges

On Databricks a prompt is a Unity Catalog object, so its name has three parts, catalog.schema.prompt_name, and access is governed like any other UC object. To view or create prompts you need CREATE FUNCTION, EXECUTE and MANAGE on the schema. Point the session at Databricks first:

import mlflow

mlflow.set_tracking_uri("databricks")
mlflow.set_registry_uri("databricks-uc")

NAME = "main.support.ticket_summary"

An experiment tag, mlflow.promptRegistryLocation set to catalog.schema, records a default location so tools can find the schema without it being repeated everywhere.

Names, privileges and the experiment tag from the Databricks pages "Prompt Registry" and "Create and edit prompts".

Register a prompt and its versions

The first register_prompt() call creates the prompt as version 1. Every later call with the same name adds the next version. Variables use double braces:

v1 = mlflow.genai.register_prompt(
    name=NAME,
    template=(
        "Summarise this ticket for {{audience}} "
        "in {{num_sentences}} sentences: {{ticket}}"
    ),
    commit_message="First version",
    tags={"owner": "support-ai", "task": "summarization"},
)

v2 = mlflow.genai.register_prompt(
    name=NAME,
    template=[
        {"role": "system", "content": "You write support summaries for {{audience}}."},
        {"role": "user", "content": "Summarise in {{num_sentences}} sentences: {{ticket}}"},
    ],
    commit_message="Split into system and user messages",
)

v1.version, v2.version   # (1, 2)

• Two formats. A string is a simple prompt; a list of role and content dicts is a conversation prompt. Both use {{variable}} placeholders, and .variables lists them.
• Commit messages and tags are stored with the version, so the history says who changed what and why. The UI's Compare view diffs the template text between versions.
• Versions are immutable. There is no call that edits version 1. Every change is a new version, which is what makes the history an audit trail and rollback exact.

Aliases: promote and roll back

An alias is a named pointer to one version. Point production at the tested version and staging at the candidate:

mlflow.genai.set_prompt_alias(name=NAME, alias="production", version=1)
mlflow.genai.set_prompt_alias(name=NAME, alias="staging", version=2)

Promotion after the candidate passes evaluation is one more pointer move. Saving the old target first under another alias makes rollback a single call too:

# Promote: remember the current production version, then move the alias
current = mlflow.genai.load_prompt(f"prompts:/{NAME}@production")
mlflow.genai.set_prompt_alias(NAME, "production-previous", current.version)
mlflow.genai.set_prompt_alias(NAME, "production", 2)

# Roll back: point production at the saved version
previous = mlflow.genai.load_prompt(f"prompts:/{NAME}@production-previous")
mlflow.genai.set_prompt_alias(NAME, "production", previous.version)

delete_prompt_alias(NAME, "staging") removes a pointer and leaves the versions in place; delete_prompt() removes a version or the whole prompt.

Calls and the promotion pattern from the Databricks page "Use prompts in deployed applications". Every snippet in this post was run against MLflow 3.18 with a local registry (a plain prompt name instead of a Unity Catalog one): versions 1 and 2, promotion to 2, rollback to 1, and the loads shown.

Loading the prompt in an application

Application code loads an alias, never a version number, so a promotion takes effect without a redeploy. Reading the alias from an environment variable lets the same code run against staging in one deployment and production in another:

import os

alias = os.getenv("PROMPT_ALIAS", "production")
prompt = mlflow.genai.load_prompt(f"prompts:/{NAME}@{alias}")

text = prompt.format(
    audience="a store manager",
    num_sentences=2,
    ticket="Printer jams on tray 2 after the firmware update.",
)

format() fills the variables and returns a string for a simple prompt or a list of messages for a conversation prompt. The MLflow client caches loaded templates, so reading from the registry adds no per-request latency. In MLflow 3.18 an alias load is cached for 60 seconds by default, so a running app picks up a promotion within about a minute; a version load is cached with no expiry, since that version can never change. load_prompt(..., cache_ttl_seconds=0) bypasses the cache.

LangChain, LlamaIndex and other libraries expect single-brace ({variable}) templates. prompt.to_single_brace_format() converts the template, so the registry stays the source of truth while the framework gets the syntax it needs.

What this means for the exam

A second trap is hard-coding a version number in the application, which turns every promotion back into a redeploy.

FAQ