Skip to main content

Model Version

View as Markdown

ModelVersion object​

A version of a registered model in the Workspace Model Registry. Each version points to the model artifacts it was registered from and moves through the stages None, Staging, Production and Archived.

namestring

Name of the registered model that the version belongs to.

versionstring

Version number of the model version, as a string. Version numbers start at 1 for each registered model.

creation_timestampint64

Time when the model version was created, as a Unix timestamp in milliseconds.

last_updated_timestampint64

Time when the metadata of the model version was last updated, as a Unix timestamp in milliseconds.

user_idstring

User that created this model_version.

current_stagestring

Current stage of the model version. Valid values are None, Staging, Production and Archived. A new model version starts in None.

descriptionstring

User-provided description of the model version.

sourcestring

URI of the model artifacts that the model version was registered from, as given in the create request.

run_idstring

ID of the MLflow run that produced the model artifacts, if source comes from a run in the MLflow tracking server.

statusstring

Registration status of the model version. The version can be used once the status is READY.

Values:

  • PENDING_REGISTRATION
  • FAILED_REGISTRATION
  • READY
status_messagestring

Details on the current status, such as the reason why registration failed.

tagsarray of object

Key-value tags attached to the model version.

Show child attributesHide child attributes
keystring

The tag key.

valuestring

The tag value.

Get a model version GA​

GET /api/2.0/mlflow/model-versions/get

Get a model version.

API scopes: mlflow

Parameters​

namestringRequiredquery

Name of the registered model

versionstringRequiredquery

Model version number

Response​

model_versionobject
Show child attributesHide child attributes
namestring

Name of the registered model that the version belongs to.

versionstring

Version number of the model version, as a string. Version numbers start at 1 for each registered model.

creation_timestampint64

Time when the model version was created, as a Unix timestamp in milliseconds.

last_updated_timestampint64

Time when the metadata of the model version was last updated, as a Unix timestamp in milliseconds.

user_idstring

User that created this model_version.

current_stagestring

Current stage of the model version. Valid values are None, Staging, Production and Archived. A new model version starts in None.

descriptionstring

User-provided description of the model version.

sourcestring

URI of the model artifacts that the model version was registered from, as given in the create request.

run_idstring

ID of the MLflow run that produced the model artifacts, if source comes from a run in the MLflow tracking server.

statusstring

Registration status of the model version. The version can be used once the status is READY.

Values:

  • PENDING_REGISTRATION
  • FAILED_REGISTRATION
  • READY
status_messagestring

Details on the current status, such as the reason why registration failed.

tagsarray of object

Key-value tags attached to the model version.

Show child attributesHide child attributes
keystring

The tag key.

valuestring

The tag value.

Create a model version GA​

POST /api/2.0/mlflow/model-versions/create

1 more path

POST /api/2.0/preview/mlflow/model-versions/create

Creates a model version.

API scopes: mlflow

Request body​

namestringRequired

Name of the existing registered model to create the version under.

sourcestringRequired

URI of the model artifacts to register, such as the artifact path of an MLflow run or a models:/<model_name>/<version> URI of an existing READY model version. The registry copies the artifacts asynchronously, so the new version starts in PENDING_REGISTRATION status.

Example: dbfs:/databricks/mlflow-tracking/1234567890123456/0123456789abcdef0123456789abcdef/artifacts/model

run_idstring

ID of the MLflow run that produced the model artifacts, if source comes from a run in the MLflow tracking server. The ID is at most 32 characters long.

tagsarray of object

Tags to set on the new model version.

Show child attributesHide child attributes
keystring

The tag key.

valuestring

The tag value.

descriptionstring

Description of the model version.

Response​

model_versionobject

The new model version, including the version number that the registry assigned.

Show child attributesHide child attributes
namestring

Name of the registered model that the version belongs to.

versionstring

Version number of the model version, as a string. Version numbers start at 1 for each registered model.

creation_timestampint64

Time when the model version was created, as a Unix timestamp in milliseconds.

last_updated_timestampint64

Time when the metadata of the model version was last updated, as a Unix timestamp in milliseconds.

user_idstring

User that created this model_version.

current_stagestring

Current stage of the model version. Valid values are None, Staging, Production and Archived. A new model version starts in None.

descriptionstring

User-provided description of the model version.

sourcestring

URI of the model artifacts that the model version was registered from, as given in the create request.

run_idstring

ID of the MLflow run that produced the model artifacts, if source comes from a run in the MLflow tracking server.

statusstring

Registration status of the model version. The version can be used once the status is READY.

Values:

  • PENDING_REGISTRATION
  • FAILED_REGISTRATION
  • READY
status_messagestring

Details on the current status, such as the reason why registration failed.

tagsarray of object

Key-value tags attached to the model version.

Show child attributesHide child attributes
keystring

The tag key.

valuestring

The tag value.

Update model version GA​

PATCH /api/2.0/mlflow/model-versions/update

1 more path

PATCH /api/2.0/preview/mlflow/model-versions/update

Updates the description of a model version.

API scopes: mlflow

Request body​

namestringRequired

Name of the registered model

versionstringRequired

Model version number

descriptionstring

New description for the model version.

Response​

model_versionobject

The updated model version.

Show child attributesHide child attributes
namestring

Name of the registered model that the version belongs to.

versionstring

Version number of the model version, as a string. Version numbers start at 1 for each registered model.

creation_timestampint64

Time when the model version was created, as a Unix timestamp in milliseconds.

last_updated_timestampint64

Time when the metadata of the model version was last updated, as a Unix timestamp in milliseconds.

user_idstring

User that created this model_version.

current_stagestring

Current stage of the model version. Valid values are None, Staging, Production and Archived. A new model version starts in None.

descriptionstring

User-provided description of the model version.

sourcestring

URI of the model artifacts that the model version was registered from, as given in the create request.

run_idstring

ID of the MLflow run that produced the model artifacts, if source comes from a run in the MLflow tracking server.

statusstring

Registration status of the model version. The version can be used once the status is READY.

Values:

  • PENDING_REGISTRATION
  • FAILED_REGISTRATION
  • READY
status_messagestring

Details on the current status, such as the reason why registration failed.

tagsarray of object

Key-value tags attached to the model version.

Show child attributesHide child attributes
keystring

The tag key.

valuestring

The tag value.

Delete a model version GA​

DELETE /api/2.0/mlflow/model-versions/delete

Deletes a model version.

API scopes: mlflow

Parameters​

namestringRequiredquery

Name of the registered model

versionstringRequiredquery

Model version number

Search model versions GA​

GET /api/2.0/mlflow/model-versions/search

Searches for specific model versions based on the supplied filter.

API scopes: mlflow

Parameters​

filterstringquery

Filter condition on name, run_id, source or tags.<key>. The filter must constrain at least one of name, run_id or source. Conditions use =, !=, LIKE or ILIKE, and run_id also supports IN. String values are wrapped in single quotes, and several conditions can be combined with AND.

Example: name='search_ads_model'

max_resultsint64<= 10000query

Maximum number of models desired. Max threshold is 10K.

Default: 10000

order_byarray of stringquery

Columns to order the results by, each given as name, version, current_stage or last_updated_timestamp with an optional ASC or DESC suffix, where ASC is the default. Tiebreaks are done by latest stage transition timestamp, followed by name ASC, followed by version DESC.

Example: version DESC

page_tokenstringquery

Pagination token to go to next page based on previous search query.

Response​

Returns a list of ModelVersion objects.

Get a model version URI GA​

GET /api/2.0/mlflow/model-versions/get-download-uri

Gets a URI to download the model version.

API scopes: mlflow

Parameters​

namestringRequiredquery

Name of the registered model

versionstringRequiredquery

Model version number

Response​

artifact_uristring

URI corresponding to where artifacts for this model version are stored.

Set a version tag GA​

POST /api/2.0/mlflow/model-versions/set-tag

1 more path

POST /api/2.0/preview/mlflow/model-versions/set-tag

Sets a model version tag.

API scopes: mlflow

Request body​

namestringRequired

Unique name of the model.

versionstringRequired

Model version number.

keystringRequired

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.

valuestringRequired

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.

Delete a model version tag GA​

DELETE /api/2.0/mlflow/model-versions/delete-tag

Deletes a model version tag.

API scopes: mlflow

Parameters​

namestringRequiredquery

Name of the registered model that the tag was logged under.

versionstringRequiredquery

Model version number that the tag was logged under.

keystringRequiredquery

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

Transition a stage GA​

POST /api/2.0/mlflow/databricks/model-versions/transition-stage

1 more path

POST /api/2.0/preview/mlflow/databricks/model-versions/transition-stage

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.

API scopes: mlflow

Request body​

namestring[ 1 .. 100 ] charactersRequired

Name of the model.

Example: search_ads_model

versionstringRequired

Version of the model.

Example: 1

stagestringRequired

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_versionsbooleanRequired

Specifies whether to archive all current model versions in the target stage.

Example: true

commentstring[ 1 .. 65535 ] characters

User-provided comment on the action.

Example: This version is great!

Response​

model_version_databricksobject

Updated model version

Show child attributesHide child attributes
namestring[ 1 .. 100 ] characters

Name of the model.

Example: search_ads_model

versionstring

Version of the model.

Example: 1

creation_timestampint64

Creation time of the object, as a Unix timestamp in milliseconds.

Example: 1594437249910

last_updated_timestampint64

Time of the object at last update, as a Unix timestamp in milliseconds.

Example: 1594437549910

user_idstringemail

The username of the user that created the object.

Example: jane.doe@example.com

current_stagestring

Current stage of the model version. Valid values are None, Staging, Production and Archived.

descriptionstring<= 65535 characters

User-specified description for the object.

Example: Here's some extra info.

sourcestring

URI that indicates the location of the source model artifacts. This is used when creating the model version.

Example: dbfs:/databricks/mlflow-tracking/run123/model

run_idstringuuid

Unique identifier for the MLflow tracking run associated with the source model artifacts.

Example: 6fc74c92704341aaa49e74dcc6031057

statusstring

Registration status of the model version. The version can be used once the status is READY.

Values:

  • PENDING_REGISTRATION
  • FAILED_REGISTRATION
  • READY
status_messagestring

Details on the current status, for example why registration failed.

Example: Source could not be found.

open_requestsarray of object

Open stage transition requests for the model version.

Show child attributesHide child attributes
creation_timestampint64

Creation time of the object, as a Unix timestamp in milliseconds.

Example: 1594437249910

user_idstringemail

The username of the user that created the object.

Example: jane.doe@example.com

activity_typestring

Type of activity. Valid values are:

  • APPLIED_TRANSITION: User applied the corresponding stage transition.

  • REQUESTED_TRANSITION: User requested the corresponding stage transition.

  • CANCELLED_REQUEST: User cancelled an existing transition request.

  • APPROVED_REQUEST: User approved the corresponding stage transition.

  • REJECTED_REQUEST: User rejected the coressponding stage transition.

  • SYSTEM_TRANSITION: For events performed as a side effect, such as archiving existing model versions in a stage.

Values:

  • APPLIED_TRANSITION
  • REQUESTED_TRANSITION
  • CANCELLED_REQUEST
  • APPROVED_REQUEST
  • REJECTED_REQUEST
  • NEW_COMMENT
  • SYSTEM_TRANSITION
commentstring[ 1 .. 65535 ] characters

User-provided comment associated with the activity, comment, or transition request.

Example: This version is great!

last_updated_timestampint64

Time of the object at last update, as a Unix timestamp in milliseconds.

Example: 1594437549910

from_stagestring

Source stage of the transition (if the activity is stage transition related). Valid values are:

  • None: The initial stage of a model version.

  • Staging: Staging or pre-production stage.

  • Production: Production stage.

  • Archived: Archived stage.

to_stagestring

Target stage of the transition (if the activity is stage transition related). Valid values are:

  • None: The initial stage of a model version.

  • Staging: Staging or pre-production stage.

  • Production: Production stage.

  • Archived: Archived stage.

system_commentstring

Comment made by system, for example explaining an activity of type SYSTEM_TRANSITION. It usually describes a side effect, such as a version being archived as part of another version's stage transition, and may not be returned for some activity types.

available_actionsarray of string

Array of actions on the activity allowed for the current viewer.

Values:

  • APPROVE_TRANSITION_REQUEST
  • REJECT_TRANSITION_REQUEST
  • CANCEL_TRANSITION_REQUEST
  • EDIT_COMMENT
  • DELETE_COMMENT
idstringuuid

Unique identifier for the object.

Example: 6fc74c92704341aaa49e74dcc6031057

permission_levelstring

Permission level of the requesting user on the registered model that the version belongs to.

Values:

  • CAN_MANAGE
  • CAN_EDIT
  • CAN_READ
  • CAN_MANAGE_STAGING_VERSIONS
  • CAN_MANAGE_PRODUCTION_VERSIONS
  • CAN_CREATE_REGISTERED_MODEL
tagsarray of object

Array of tags that are associated with the model version.

Show child attributesHide child attributes
keystring

The tag key.

valuestring

The tag value.

email_subscription_statusstring

Email Subscription Status: This is the subscription status of the user to the model version Users get subscribed by interacting with the model version.

Values:

  • ALL_EVENTS
  • DEFAULT
  • SUBSCRIBED
  • UNSUBSCRIBED
feature_listobject

Feature lineage of model_version.

Show child attributesHide child attributes
featuresarray of object
Show child attributesHide child attributes
feature_table_namestring

Feature table name

feature_namestring

Feature name

feature_table_idstring

Feature table id