w.model_registry: Model Registry

class databricks.sdk.service.ml.ModelRegistryAPI

Note: This API reference documents APIs for the Workspace Model Registry. Databricks recommends using [Models in Unity Catalog](/api/workspace/registeredmodels) instead. Models in Unity Catalog provides centralized model governance, cross-workspace access, lineage, and deployment. Workspace Model Registry will be deprecated in the future.

The Workspace Model Registry is a centralized model repository and a UI and set of APIs that enable you to manage the full lifecycle of MLflow Models.

approve_transition_request(name: str, version: str, stage: str, archive_existing_versions: bool [, comment: Optional[str]]) → ApproveTransitionRequestResponse

Approves a model version stage transition request.

Parameters:

• name – str Name of the model.

• version – str Version of the model.

• stage –

  str Target stage of the transition. Valid values are:

  • None: The initial stage of a model version.

  • Staging: Staging or pre-production stage.

  • Production: Production stage.

  • Archived: Archived stage.

• archive_existing_versions – bool Specifies whether to archive all current model versions in the target stage.

• comment – str (optional) User-provided comment on the action.

Returns:

ApproveTransitionRequestResponse

create_comment(name: str, version: str, comment: str) → CreateCommentResponse

Usage:

import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}")

mv = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp")

created = w.model_registry.create_comment(
    comment=f"sdk-{time.time_ns()}",
    name=mv.model_version.name,
    version=mv.model_version.version,
)

# cleanup
w.model_registry.delete_comment(id=created.comment.id)

Posts a comment on a model version. A comment can be submitted either by a user or programmatically to display relevant information about the model. For example, test results or deployment errors.

Parameters:

• name – str Name of the model.

• version – str Version of the model.

• comment – str User-provided comment on the action.

Returns:

CreateCommentResponse

create_model(name: str [, description: Optional[str], tags: Optional[List[ModelTag]]]) → CreateModelResponse

Usage:

import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}")

created = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp")

Creates a new registered model with the name specified in the request body. Throws RESOURCE_ALREADY_EXISTS if a registered model with the given name exists.

Parameters:

• name – str Register models under this name

• description – str (optional) Optional description for registered model.

• tags – List[ModelTag] (optional) Additional metadata for registered model.

Returns:

CreateModelResponse

create_model_version(name: str, source: str [, description: Optional[str], run_id: Optional[str], run_link: Optional[str], tags: Optional[List[ModelVersionTag]]]) → CreateModelVersionResponse

Usage:

import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}")

created = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp")

Creates a model version.

Parameters:

• name – str Register model under this name

• source – str URI indicating the location of the model artifacts.

• description – str (optional) Optional description for model version.

• run_id – str (optional) MLflow run ID for correlation, if source was generated by an experiment run in MLflow tracking server

• run_link – str (optional) MLflow run link - this is the exact link of the run that generated this model version, potentially hosted at another instance of MLflow.

• tags – List[ModelVersionTag] (optional) Additional metadata for model version.

Returns:

CreateModelVersionResponse

create_transition_request(name: str, version: str, stage: str [, comment: Optional[str]]) → CreateTransitionRequestResponse

Creates a model version stage transition request.

Parameters:

• name – str Name of the model.

• version – str Version of the model.

• stage –

  str Target stage of the transition. Valid values are:

  • None: The initial stage of a model version.

  • Staging: Staging or pre-production stage.

  • Production: Production stage.

  • Archived: Archived stage.

• comment – str (optional) User-provided comment on the action.

Returns:

CreateTransitionRequestResponse

create_webhook(events: List[RegistryWebhookEvent] [, description: Optional[str], http_url_spec: Optional[HttpUrlSpec], job_spec: Optional[JobSpec], model_name: Optional[str], status: Optional[RegistryWebhookStatus]]) → CreateWebhookResponse

Usage:

import time

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import ml

w = WorkspaceClient()

created = w.model_registry.create_webhook(
    description=f"sdk-{time.time_ns()}",
    events=[ml.RegistryWebhookEvent.MODEL_VERSION_CREATED],
    http_url_spec=ml.HttpUrlSpec(url=w.config.host),
)

# cleanup
w.model_registry.delete_webhook(id=created.webhook.id)

NOTE: This endpoint is in Public Preview. Creates a registry webhook.

Parameters:

• events –

  List[RegistryWebhookEvent] Events that can trigger a registry webhook: * MODEL_VERSION_CREATED: A new model version was created for the associated model.

  • MODEL_VERSION_TRANSITIONED_STAGE: A model version’s stage was changed.

  • TRANSITION_REQUEST_CREATED: A user requested a model version’s stage be transitioned.

  • COMMENT_CREATED: A user wrote a comment on a registered model.

  • REGISTERED_MODEL_CREATED: A new registered model was created. This event type can only be

  specified for a registry-wide webhook, which can be created by not specifying a model name in the create request.

  • MODEL_VERSION_TAG_SET: A user set a tag on the model version.

  • MODEL_VERSION_TRANSITIONED_TO_STAGING: A model version was transitioned to staging.

  • MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: A model version was transitioned to production.

  • MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: A model version was archived.

  • TRANSITION_REQUEST_TO_STAGING_CREATED: A user requested a model version be transitioned to

  staging.

  • TRANSITION_REQUEST_TO_PRODUCTION_CREATED: A user requested a model version be transitioned to

  production.

  • TRANSITION_REQUEST_TO_ARCHIVED_CREATED: A user requested a model version be archived.

• description – str (optional) User-specified description for the webhook.

• http_url_spec – HttpUrlSpec (optional) External HTTPS URL called on event trigger (by using a POST request).

• job_spec – JobSpec (optional) ID of the job that the webhook runs.

• model_name – str (optional) If model name is not specified, a registry-wide webhook is created that listens for the specified events across all versions of all registered models.

• status –

  RegistryWebhookStatus (optional) Enable or disable triggering the webhook, or put the webhook into test mode. The default is ACTIVE: * ACTIVE: Webhook is triggered when an associated event happens.

  • DISABLED: Webhook is not triggered.

  • TEST_MODE: Webhook can be triggered through the test endpoint, but is not triggered on a real

  event.

Returns:

CreateWebhookResponse

delete_comment(id: str)

Deletes a comment on a model version.

Parameters:

id – str Unique identifier of an activity

delete_model(name: str)

Deletes a registered model.

Parameters:

name – str Registered model unique name identifier.

delete_model_tag(name: str, key: str)

Deletes the tag for a registered model.

Parameters:

• name – str Name of the registered model that the tag was logged under.

• key – str Name of the tag. The name must be an exact match; wild-card deletion is not supported. Maximum size is 250 bytes.

delete_model_version(name: str, version: str)

Deletes a model version.

Parameters:

• name – str Name of the registered model

• version – str Model version number

delete_model_version_tag(name: str, version: str, key: str)

Deletes a model version tag.

Parameters:

• name – str Name of the registered model that the tag was logged under.

• version – str Model version number that the tag was logged under.

• key – str Name of the tag. The name must be an exact match; wild-card deletion is not supported. Maximum size is 250 bytes.

delete_transition_request(name: str, version: str, stage: str, creator: str [, comment: Optional[str]]) → DeleteTransitionRequestResponse

Cancels a model version stage transition request.

Parameters:

• name – str Name of the model.

• version – str Version of the model.

• stage –

  str Target stage of the transition request. Valid values are:

  • None: The initial stage of a model version.

  • Staging: Staging or pre-production stage.

  • Production: Production stage.

  • Archived: Archived stage.

• creator – str Username of the user who created this request. Of the transition requests matching the specified details, only the one transition created by this user will be deleted.

• comment – str (optional) User-provided comment on the action.

Returns:

DeleteTransitionRequestResponse

delete_webhook(id: str)

NOTE: This endpoint is in Public Preview. Deletes a registry webhook.

Parameters:

id – str Webhook ID required to delete a registry webhook.

get_latest_versions(name: str [, stages: Optional[List[str]]]) → Iterator[ModelVersion]

Gets the latest version of a registered model.

Parameters:

• name – str Registered model unique name identifier.

• stages – List[str] (optional) List of stages.

Returns:

Iterator over ModelVersion

get_model(name: str) → GetModelResponse

Usage:

import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

created = w.model_registry.create_model(name=f"sdk-{time.time_ns()}")

model = w.model_registry.get_model(name=created.registered_model.name)

Get the details of a model. This is a Databricks workspace version of the [MLflow endpoint] that also returns the model’s Databricks workspace ID and the permission level of the requesting user on the model.

[MLflow endpoint]: https://www.mlflow.org/docs/latest/rest-api.html#get-registeredmodel

Parameters:

name – str Registered model unique name identifier.

Returns:

GetModelResponse

get_model_version(name: str, version: str) → GetModelVersionResponse

Get a model version.

Parameters:

• name – str Name of the registered model

• version – str Model version number

Returns:

GetModelVersionResponse

get_model_version_download_uri(name: str, version: str) → GetModelVersionDownloadUriResponse

Gets a URI to download the model version.

Parameters:

• name – str Name of the registered model

• version – str Model version number

Returns:

GetModelVersionDownloadUriResponse

get_permission_levels(registered_model_id: str) → GetRegisteredModelPermissionLevelsResponse

Gets the permission levels that a user can have on an object.

Parameters:

registered_model_id – str The registered model for which to get or manage permissions.

Returns:

GetRegisteredModelPermissionLevelsResponse

get_permissions(registered_model_id: str) → RegisteredModelPermissions

Gets the permissions of a registered model. Registered models can inherit permissions from their root object.

Parameters:

registered_model_id – str The registered model for which to get or manage permissions.

Returns:

RegisteredModelPermissions

list_models([, max_results: Optional[int], page_token: Optional[str]]) → Iterator[Model]

Usage:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import ml

w = WorkspaceClient()

all = w.model_registry.list_models(ml.ListModelsRequest())

Lists all available registered models, up to the limit specified in __max_results__.

Parameters:

• max_results – int (optional) Maximum number of registered models desired. Max threshold is 1000.

• page_token – str (optional) Pagination token to go to the next page based on a previous query.

Returns:

Iterator over Model

list_transition_requests(name: str, version: str) → Iterator[Activity]

Gets a list of all open stage transition requests for the model version.

Parameters:

• name – str Name of the registered model.

• version – str Version of the model.

Returns:

Iterator over Activity

list_webhooks([, events: Optional[List[RegistryWebhookEvent]], max_results: Optional[int], model_name: Optional[str], page_token: Optional[str]]) → Iterator[RegistryWebhook]

Usage:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import ml

w = WorkspaceClient()

all = w.model_registry.list_webhooks(ml.ListWebhooksRequest())

NOTE: This endpoint is in Public Preview. Lists all registry webhooks.

Parameters:

• events –

  List[RegistryWebhookEvent] (optional) Events that trigger the webhook. * MODEL_VERSION_CREATED: A new model version was created for the associated model.

  • MODEL_VERSION_TRANSITIONED_STAGE: A model version’s stage was changed.

  • TRANSITION_REQUEST_CREATED: A user requested a model version’s stage be transitioned.

  • COMMENT_CREATED: A user wrote a comment on a registered model.

  • REGISTERED_MODEL_CREATED: A new registered model was created. This event type can only be

  specified for a registry-wide webhook, which can be created by not specifying a model name in the create request.

  • MODEL_VERSION_TAG_SET: A user set a tag on the model version.

  • MODEL_VERSION_TRANSITIONED_TO_STAGING: A model version was transitioned to staging.

  • MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: A model version was transitioned to production.

  • MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: A model version was archived.

  • TRANSITION_REQUEST_TO_STAGING_CREATED: A user requested a model version be transitioned to

  staging.

  • TRANSITION_REQUEST_TO_PRODUCTION_CREATED: A user requested a model version be transitioned to

  production.

  • TRANSITION_REQUEST_TO_ARCHIVED_CREATED: A user requested a model version be archived.

  If events is specified, any webhook with one or more of the specified trigger events is included in the output. If events is not specified, webhooks of all event types are included in the output.

• max_results – int (optional)

• model_name – str (optional) Registered model name If not specified, all webhooks associated with the specified events are listed, regardless of their associated model.

• page_token – str (optional) Token indicating the page of artifact results to fetch

Returns:

Iterator over RegistryWebhook

reject_transition_request(name: str, version: str, stage: str [, comment: Optional[str]]) → RejectTransitionRequestResponse

Rejects a model version stage transition request.

Parameters:

• name – str Name of the model.

• version – str Version of the model.

• stage –

  str Target stage of the transition. Valid values are:

  • None: The initial stage of a model version.

  • Staging: Staging or pre-production stage.

  • Production: Production stage.

  • Archived: Archived stage.

• comment – str (optional) User-provided comment on the action.

Returns:

RejectTransitionRequestResponse

rename_model(name: str [, new_name: Optional[str]]) → RenameModelResponse

Renames a registered model.

Parameters:

• name – str Registered model unique name identifier.

• new_name – str (optional) If provided, updates the name for this registered_model.

Returns:

RenameModelResponse

search_model_versions([, filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str]]) → Iterator[ModelVersion]

Searches for specific model versions based on the supplied __filter__.

Parameters:

• filter – str (optional) String filter condition, like “name=’my-model-name’”. Must be a single boolean condition, with string values wrapped in single quotes.

• max_results – int (optional) Maximum number of models desired. Max threshold is 10K.

• order_by – List[str] (optional) List of columns to be ordered by including model name, version, stage with an optional “DESC” or “ASC” annotation, where “ASC” is the default. Tiebreaks are done by latest stage transition timestamp, followed by name ASC, followed by version DESC.

• page_token – str (optional) Pagination token to go to next page based on previous search query.

Returns:

Iterator over ModelVersion

search_models([, filter: Optional[str], max_results: Optional[int], order_by: Optional[List[str]], page_token: Optional[str]]) → Iterator[Model]

Search for registered models based on the specified __filter__.

Parameters:

• filter – str (optional) String filter condition, like “name LIKE ‘my-model-name’”. Interpreted in the backend automatically as “name LIKE ‘%my-model-name%’”. Single boolean condition, with string values wrapped in single quotes.

• max_results – int (optional) Maximum number of models desired. Default is 100. Max threshold is 1000.

• order_by – List[str] (optional) List of columns for ordering search results, which can include model name and last updated timestamp with an optional “DESC” or “ASC” annotation, where “ASC” is the default. Tiebreaks are done by model name ASC.

• page_token – str (optional) Pagination token to go to the next page based on a previous search query.

Returns:

Iterator over Model

set_model_tag(name: str, key: str, value: str)

Sets a tag on a registered model.

Parameters:

• name – str Unique name of the model.

• key – str Name of the tag. Maximum size depends on storage backend. If a tag with this name already exists, its preexisting value will be replaced by the specified value. All storage backends are guaranteed to support key values up to 250 bytes in size.

• value – str String value of the tag being logged. Maximum size depends on storage backend. All storage backends are guaranteed to support key values up to 5000 bytes in size.

set_model_version_tag(name: str, version: str, key: str, value: str)

Sets a model version tag.

Parameters:

• name – str Unique name of the model.

• version – str Model version number.

• key – str Name of the tag. Maximum size depends on storage backend. If a tag with this name already exists, its preexisting value will be replaced by the specified value. All storage backends are guaranteed to support key values up to 250 bytes in size.

• value – str String value of the tag being logged. Maximum size depends on storage backend. All storage backends are guaranteed to support key values up to 5000 bytes in size.

set_permissions(registered_model_id: str [, access_control_list: Optional[List[RegisteredModelAccessControlRequest]]]) → RegisteredModelPermissions

Sets permissions on an object, replacing existing permissions if they exist. Deletes all direct permissions if none are specified. Objects can inherit permissions from their root object.

Parameters:

• registered_model_id – str The registered model for which to get or manage permissions.

• access_control_list – List[RegisteredModelAccessControlRequest] (optional)

Returns:

RegisteredModelPermissions

test_registry_webhook(id: str [, event: Optional[RegistryWebhookEvent]]) → TestRegistryWebhookResponse

NOTE: This endpoint is in Public Preview. Tests a registry webhook.

Parameters:

• id – str Webhook ID

• event – RegistryWebhookEvent (optional) If event is specified, the test trigger uses the specified event. If event is not specified, the test trigger uses a randomly chosen event associated with the webhook.

Returns:

TestRegistryWebhookResponse

transition_stage(name: str, version: str, stage: str, archive_existing_versions: bool [, comment: Optional[str]]) → TransitionStageResponse

Transition a model version’s stage. This is a Databricks workspace version of the [MLflow endpoint] that also accepts a comment associated with the transition to be recorded.

[MLflow endpoint]: https://www.mlflow.org/docs/latest/rest-api.html#transition-modelversion-stage

Parameters:

• name – str Name of the model.

• version – str Version of the model.

• stage –

  str Target stage of the transition. Valid values are:

  • None: The initial stage of a model version.

  • Staging: Staging or pre-production stage.

  • Production: Production stage.

  • Archived: Archived stage.

• archive_existing_versions – bool Specifies whether to archive all current model versions in the target stage.

• comment – str (optional) User-provided comment on the action.

Returns:

TransitionStageResponse

update_comment(id: str, comment: str) → UpdateCommentResponse

Usage:

import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}")

mv = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp")

created = w.model_registry.create_comment(
    comment=f"sdk-{time.time_ns()}",
    name=mv.model_version.name,
    version=mv.model_version.version,
)

_ = w.model_registry.update_comment(comment=f"sdk-{time.time_ns()}", id=created.comment.id)

# cleanup
w.model_registry.delete_comment(id=created.comment.id)

Post an edit to a comment on a model version.

Parameters:

• id – str Unique identifier of an activity

• comment – str User-provided comment on the action.

Returns:

UpdateCommentResponse

update_model(name: str [, description: Optional[str]]) → UpdateModelResponse

Usage:

import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}")

created = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp")

w.model_registry.update_model_version(
    description=f"sdk-{time.time_ns()}",
    name=created.model_version.name,
    version=created.model_version.version,
)

Updates a registered model.

Parameters:

• name – str Registered model unique name identifier.

• description – str (optional) If provided, updates the description for this registered_model.

Returns:

UpdateModelResponse

update_model_version(name: str, version: str [, description: Optional[str]]) → UpdateModelVersionResponse

Usage:

import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

model = w.model_registry.create_model(name=f"sdk-{time.time_ns()}")

created = w.model_registry.create_model_version(name=model.registered_model.name, source="dbfs:/tmp")

w.model_registry.update_model_version(
    description=f"sdk-{time.time_ns()}",
    name=created.model_version.name,
    version=created.model_version.version,
)

Updates the model version.

Parameters:

• name – str Name of the registered model

• version – str Model version number

• description – str (optional) If provided, updates the description for this registered_model.

Returns:

UpdateModelVersionResponse

update_permissions(registered_model_id: str [, access_control_list: Optional[List[RegisteredModelAccessControlRequest]]]) → RegisteredModelPermissions

Updates the permissions on a registered model. Registered models can inherit permissions from their root object.

Parameters:

• registered_model_id – str The registered model for which to get or manage permissions.

• access_control_list – List[RegisteredModelAccessControlRequest] (optional)

Returns:

RegisteredModelPermissions

update_webhook(id: str [, description: Optional[str], events: Optional[List[RegistryWebhookEvent]], http_url_spec: Optional[HttpUrlSpec], job_spec: Optional[JobSpec], status: Optional[RegistryWebhookStatus]]) → UpdateWebhookResponse

Usage:

import time

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import ml

w = WorkspaceClient()

created = w.model_registry.create_webhook(
    description=f"sdk-{time.time_ns()}",
    events=[ml.RegistryWebhookEvent.MODEL_VERSION_CREATED],
    http_url_spec=ml.HttpUrlSpec(url=w.config.host),
)

w.model_registry.update_webhook(id=created.webhook.id, description=f"sdk-{time.time_ns()}")

# cleanup
w.model_registry.delete_webhook(id=created.webhook.id)

NOTE: This endpoint is in Public Preview. Updates a registry webhook.

Parameters:

• id – str Webhook ID

• description – str (optional) User-specified description for the webhook.

• events –

  List[RegistryWebhookEvent] (optional) Events that can trigger a registry webhook: * MODEL_VERSION_CREATED: A new model version was created for the associated model.

  • MODEL_VERSION_TRANSITIONED_STAGE: A model version’s stage was changed.

  • TRANSITION_REQUEST_CREATED: A user requested a model version’s stage be transitioned.

  • COMMENT_CREATED: A user wrote a comment on a registered model.

  • REGISTERED_MODEL_CREATED: A new registered model was created. This event type can only be

  specified for a registry-wide webhook, which can be created by not specifying a model name in the create request.

  • MODEL_VERSION_TAG_SET: A user set a tag on the model version.

  • MODEL_VERSION_TRANSITIONED_TO_STAGING: A model version was transitioned to staging.

  • MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: A model version was transitioned to production.

  • MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: A model version was archived.

  • TRANSITION_REQUEST_TO_STAGING_CREATED: A user requested a model version be transitioned to

  staging.

  • TRANSITION_REQUEST_TO_PRODUCTION_CREATED: A user requested a model version be transitioned to

  production.

  • TRANSITION_REQUEST_TO_ARCHIVED_CREATED: A user requested a model version be archived.

• http_url_spec – HttpUrlSpec (optional)

• job_spec – JobSpec (optional)

• status – RegistryWebhookStatus (optional)

Returns:

UpdateWebhookResponse