Uc Registered Models

View as Markdown

Manage governed AI assets and services

Delete Model VersionDELETE /api/2.1/unity-catalog/models/{full_name_arg}/versions/{version_arg}Delete Registered Model AliasDELETE /api/2.1/unity-catalog/models/{full_name_arg}/aliases/{alias_arg}Get Model VersionGET /api/2.1/unity-catalog/models/{full_name_arg}/versions/{version_arg}Get Model Version By AliasGET /api/2.1/unity-catalog/models/{full_name_arg}/aliases/{alias_arg}List Registered ModelsGET /api/2.1/unity-catalog/modelsSet Registered Model AliasPUT /api/2.1/unity-catalog/models/{full_name_arg}/aliases/{alias_arg}Update Model VersionPATCH /api/2.1/unity-catalog/models/{full_name_arg}/versions/{version_arg}

Delete Model Version GA

DELETE /api/2.1/unity-catalog/models/{full_name_arg}/versions/{version_arg}

Deletes a model version from the specified registered model. Any aliases assigned to the model version will also be deleted.

The caller must be a metastore admin or an owner of the parent registered model. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

API scopes: unity-catalog

Parameters

full_name_argstringpath

The three-level (fully qualified) name of the model version

version_argint64path

The integer version number of the model version

View as Markdown

Response

{}

Delete Registered Model Alias GA

DELETE /api/2.1/unity-catalog/models/{full_name_arg}/aliases/{alias_arg}

Deletes a registered model alias.

The caller must be a metastore admin or an owner of the registered model. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

API scopes: unity-catalog

Parameters

full_name_argstringpath

The three-level (fully qualified) name of the registered model

alias_argstringpath

The name of the alias

View as Markdown

Response

{}

Get Model Version GA

GET /api/2.1/unity-catalog/models/{full_name_arg}/versions/{version_arg}

Get a model version.

The caller must be a metastore admin or an owner of (or have the EXECUTE privilege on) the parent registered model. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

API scopes: unity-catalog

Parameters

full_name_argstringpath

The three-level (fully qualified) name of the model version

version_argint64path

The integer version number of the model version

include_aliasesbooleanquery

Whether to include aliases associated with the model version in the response

include_browsebooleanquery

Whether to include model versions in the response for which the principal can only access selective metadata for

Response

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

sourcestring

URI indicating the location of the source artifacts (files) for the model version

commentstring

The comment attached to the model version

Constraints: [ 1 .. 65536 ] characters

run_idstring

MLflow run ID used when creating the model version, if source was generated by an experiment run stored in an MLflow tracking server

run_workspace_idint64

ID of the <Databricks> workspace containing the MLflow run that generated this model version, if applicable

model_version_dependenciesobject

Model version dependencies, for feature-store packaged models

Show child attributesHide child attributes

dependenciesarray of object

Array of dependencies.

Show child attributesHide child attributes

tableobjectRequired

Show child attributesHide child attributes

table_full_namestring

Full name of the dependent table, in the form of catalog_name.schema_name.table_name.

functionobjectRequired

Show child attributesHide child attributes

function_full_namestring

Full name of the dependent function, in the form of catalog_name.schema_name.function_name.

connectionobjectRequired

Show child attributesHide child attributes

connection_namestring

Full name of the dependent connection, in the form of connection_name.

credentialobjectRequired

Show child attributesHide child attributes

credential_namestring

Full name of the dependent credential, in the form of credential_name.

statusstring

Current status of the model version. Newly created model versions start in PENDING_REGISTRATION status, then move to READY status once the model version files are uploaded and the model version is finalized. Only model versions in READY status can be loaded for inference or served.

Values: MODEL_VERSION_STATUS_UNKNOWN, PENDING_REGISTRATION, FAILED_REGISTRATION, READY

versionint64

Integer model version number, used to reference the model version in API requests.

storage_locationstring

The storage location on the cloud under which model version data files are stored

metastore_idstring

The unique identifier of the metastore containing the model version

created_atint64

created_bystring

The identifier of the user who created the model version

updated_atint64

updated_bystring

The identifier of the user who updated the model version last time

idstring

The unique identifier of the model version

aliasesarray of object

List of aliases associated with the model version

Show child attributesHide child attributes

alias_namestring

Name of the alias, e.g. 'champion' or 'latest_stable'

version_numint64

Integer version number of the model version to which this alias points.

idstring

The unique identifier of the alias

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

View as Markdown

Response

{
  "model_name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "source": "string",
  "comment": "string",
  "run_id": "string",
  "run_workspace_id": 0,
  "model_version_dependencies": {
    "dependencies": [
      {}
    ]
  },
  "status": "string",
  "version": 0,
  "storage_location": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "id": "string",
  "aliases": [
    {
      "alias_name": "string",
      "version_num": 0,
      "id": "string",
      "model_name": "string",
      "catalog_name": "string",
      "schema_name": "string"
    }
  ]
}

Get Model Version By Alias GA

GET /api/2.1/unity-catalog/models/{full_name_arg}/aliases/{alias_arg}

Get a model version by alias.

The caller must be a metastore admin or an owner of (or have the EXECUTE privilege on) the registered model. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

API scopes: unity-catalog

Parameters

full_name_argstringpath

The three-level (fully qualified) name of the registered model

alias_argstringpath

The name of the alias

include_aliasesbooleanquery

Whether to include aliases associated with the model version in the response

Response

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

sourcestring

URI indicating the location of the source artifacts (files) for the model version

commentstring

The comment attached to the model version

Constraints: [ 1 .. 65536 ] characters

run_idstring

MLflow run ID used when creating the model version, if source was generated by an experiment run stored in an MLflow tracking server

run_workspace_idint64

ID of the <Databricks> workspace containing the MLflow run that generated this model version, if applicable

model_version_dependenciesobject

Model version dependencies, for feature-store packaged models

Show child attributesHide child attributes

dependenciesarray of object

Array of dependencies.

Show child attributesHide child attributes

tableobjectRequired

Show child attributesHide child attributes

table_full_namestring

Full name of the dependent table, in the form of catalog_name.schema_name.table_name.

functionobjectRequired

Show child attributesHide child attributes

function_full_namestring

Full name of the dependent function, in the form of catalog_name.schema_name.function_name.

connectionobjectRequired

Show child attributesHide child attributes

connection_namestring

Full name of the dependent connection, in the form of connection_name.

credentialobjectRequired

Show child attributesHide child attributes

credential_namestring

Full name of the dependent credential, in the form of credential_name.

statusstring

Current status of the model version. Newly created model versions start in PENDING_REGISTRATION status, then move to READY status once the model version files are uploaded and the model version is finalized. Only model versions in READY status can be loaded for inference or served.

Values: MODEL_VERSION_STATUS_UNKNOWN, PENDING_REGISTRATION, FAILED_REGISTRATION, READY

versionint64

Integer model version number, used to reference the model version in API requests.

storage_locationstring

The storage location on the cloud under which model version data files are stored

metastore_idstring

The unique identifier of the metastore containing the model version

created_atint64

created_bystring

The identifier of the user who created the model version

updated_atint64

updated_bystring

The identifier of the user who updated the model version last time

idstring

The unique identifier of the model version

aliasesarray of object

List of aliases associated with the model version

Show child attributesHide child attributes

alias_namestring

Name of the alias, e.g. 'champion' or 'latest_stable'

version_numint64

Integer version number of the model version to which this alias points.

idstring

The unique identifier of the alias

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

View as Markdown

Response

{
  "model_name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "source": "string",
  "comment": "string",
  "run_id": "string",
  "run_workspace_id": 0,
  "model_version_dependencies": {
    "dependencies": [
      {}
    ]
  },
  "status": "string",
  "version": 0,
  "storage_location": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "id": "string",
  "aliases": [
    {
      "alias_name": "string",
      "version_num": 0,
      "id": "string",
      "model_name": "string",
      "catalog_name": "string",
      "schema_name": "string"
    }
  ]
}

List Registered Models GA

GET /api/2.1/unity-catalog/models

List registered models. You can list registered models under a particular schema, or list all registered models in the current metastore.

The returned models are filtered based on the privileges of the calling user. For example, the metastore admin is able to list all the registered models. A regular user needs to be the owner or have the EXECUTE privilege on the registered model to receive the registered models in the response. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

There is no guarantee of a specific ordering of the elements in the response.

PAGINATION BEHAVIOR: The API is by default paginated, a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

Parameters

catalog_namestringquery

The identifier of the catalog under which to list registered models. If specified, schema_name must be specified.

schema_namestringquery

The identifier of the schema under which to list registered models. If specified, catalog_name must be specified.

include_browsebooleanquery

Whether to include registered models in the response for which the principal can only access selective metadata for

max_resultsint64query

Max number of registered models to return.

If both catalog and schema are specified:

• when max_results is not specified, the page length is set to a server configured value (10000, as of 4/2/2024).
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value (10000, as of 4/2/2024);
• when set to 0, the page length is set to a server configured value (10000, as of 4/2/2024);
• when set to a value less than 0, an invalid parameter error is returned;

If neither schema nor catalog is specified:

• when max_results is not specified, the page length is set to a server configured value (100, as of 4/2/2024).
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value (1000, as of 4/2/2024);
• when set to 0, the page length is set to a server configured value (100, as of 4/2/2024);
• when set to a value less than 0, an invalid parameter error is returned;

Constraints: <= 100

page_tokenstringquery

Opaque token to send for the next page of results (pagination).

Response

registered_modelsarray of object

Show child attributesHide child attributes

namestring

The name of the registered model

catalog_namestring

The name of the catalog where the schema and the registered model reside

schema_namestring

The name of the schema where the registered model resides

ownerstring

The identifier of the user who owns the registered model

commentstring

The comment attached to the registered model

Constraints: [ 1 .. 65536 ] characters

storage_locationstring

The storage location on the cloud under which model version data files are stored

metastore_idstring

The unique identifier of the metastore

full_namestring

The three-level (fully qualified) name of the registered model

created_atint64

Creation timestamp of the registered model in milliseconds since the Unix epoch

created_bystring

The identifier of the user who created the registered model

updated_atint64

Last-update timestamp of the registered model in milliseconds since the Unix epoch

updated_bystring

The identifier of the user who updated the registered model last time

aliasesarray of object

List of aliases associated with the registered model

Show child attributesHide child attributes

alias_namestring

Name of the alias, e.g. 'champion' or 'latest_stable'

version_numint64

Integer version number of the model version to which this alias points.

idstring

The unique identifier of the alias

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

browse_onlyboolean

Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

next_page_tokenstring

Opaque token for pagination. Omitted if there are no more results. page_token should be set to this value for fetching the next page.

View as Markdown

Response

{
  "registered_models": [
    {
      "name": "string",
      "catalog_name": "string",
      "schema_name": "string",
      "owner": "string",
      "comment": "string",
      "storage_location": "string",
      "metastore_id": "string",
      "full_name": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "aliases": [
        {}
      ],
      "browse_only": true
    }
  ],
  "next_page_token": "string"
}

Set Registered Model Alias GA

PUT /api/2.1/unity-catalog/models/{full_name_arg}/aliases/{alias_arg}

Set an alias on the specified registered model.

The caller must be a metastore admin or an owner of the registered model. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

API scopes: unity-catalog

Parameters

full_name_argstringpath

The three-level (fully qualified) name of the registered model

alias_argstringpath

The name of the alias

Request body

version_numint64

The version number of the model version to which the alias points

Response

alias_namestring

Name of the alias, e.g. 'champion' or 'latest_stable'

version_numint64

Integer version number of the model version to which this alias points.

idstring

The unique identifier of the alias

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

View as Markdown

Request

{
  "version_num": 0
}

Response

{
  "alias_name": "string",
  "version_num": 0,
  "id": "string",
  "model_name": "string",
  "catalog_name": "string",
  "schema_name": "string"
}

Update Model Version GA

PATCH /api/2.1/unity-catalog/models/{full_name_arg}/versions/{version_arg}

Updates the specified model version.

The caller must be a metastore admin or an owner of the parent registered model. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

Currently only the comment of the model version can be updated.

API scopes: unity-catalog

Parameters

full_name_argstringpath

The three-level (fully qualified) name of the model version

version_argint64path

The integer version number of the model version

Request body

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

sourcestring

URI indicating the location of the source artifacts (files) for the model version

commentstring

The comment attached to the model version

Constraints: [ 1 .. 65536 ] characters

run_idstring

MLflow run ID used when creating the model version, if source was generated by an experiment run stored in an MLflow tracking server

run_workspace_idint64

ID of the <Databricks> workspace containing the MLflow run that generated this model version, if applicable

model_version_dependenciesobject

Model version dependencies, for feature-store packaged models

Show child attributesHide child attributes

dependenciesarray of object

Array of dependencies.

Show child attributesHide child attributes

tableobjectRequired

Show child attributesHide child attributes

table_full_namestring

Full name of the dependent table, in the form of catalog_name.schema_name.table_name.

functionobjectRequired

Show child attributesHide child attributes

function_full_namestring

Full name of the dependent function, in the form of catalog_name.schema_name.function_name.

connectionobjectRequired

Show child attributesHide child attributes

connection_namestring

Full name of the dependent connection, in the form of connection_name.

credentialobjectRequired

Show child attributesHide child attributes

credential_namestring

Full name of the dependent credential, in the form of credential_name.

statusstring

Current status of the model version. Newly created model versions start in PENDING_REGISTRATION status, then move to READY status once the model version files are uploaded and the model version is finalized. Only model versions in READY status can be loaded for inference or served.

Values: MODEL_VERSION_STATUS_UNKNOWN, PENDING_REGISTRATION, FAILED_REGISTRATION, READY

versionint64

Integer model version number, used to reference the model version in API requests.

storage_locationstring

The storage location on the cloud under which model version data files are stored

metastore_idstring

The unique identifier of the metastore containing the model version

created_atint64

created_bystring

The identifier of the user who created the model version

updated_atint64

updated_bystring

The identifier of the user who updated the model version last time

idstring

The unique identifier of the model version

aliasesarray of object

List of aliases associated with the model version

Show child attributesHide child attributes

alias_namestring

Name of the alias, e.g. 'champion' or 'latest_stable'

version_numint64

Integer version number of the model version to which this alias points.

idstring

The unique identifier of the alias

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

Response

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

sourcestring

URI indicating the location of the source artifacts (files) for the model version

commentstring

The comment attached to the model version

Constraints: [ 1 .. 65536 ] characters

run_idstring

MLflow run ID used when creating the model version, if source was generated by an experiment run stored in an MLflow tracking server

run_workspace_idint64

ID of the <Databricks> workspace containing the MLflow run that generated this model version, if applicable

model_version_dependenciesobject

Model version dependencies, for feature-store packaged models

Show child attributesHide child attributes

dependenciesarray of object

Array of dependencies.

Show child attributesHide child attributes

tableobjectRequired

Show child attributesHide child attributes

table_full_namestring

Full name of the dependent table, in the form of catalog_name.schema_name.table_name.

functionobjectRequired

Show child attributesHide child attributes

function_full_namestring

Full name of the dependent function, in the form of catalog_name.schema_name.function_name.

connectionobjectRequired

Show child attributesHide child attributes

connection_namestring

Full name of the dependent connection, in the form of connection_name.

credentialobjectRequired

Show child attributesHide child attributes

credential_namestring

Full name of the dependent credential, in the form of credential_name.

statusstring

Current status of the model version. Newly created model versions start in PENDING_REGISTRATION status, then move to READY status once the model version files are uploaded and the model version is finalized. Only model versions in READY status can be loaded for inference or served.

Values: MODEL_VERSION_STATUS_UNKNOWN, PENDING_REGISTRATION, FAILED_REGISTRATION, READY

versionint64

Integer model version number, used to reference the model version in API requests.

storage_locationstring

The storage location on the cloud under which model version data files are stored

metastore_idstring

The unique identifier of the metastore containing the model version

created_atint64

created_bystring

The identifier of the user who created the model version

updated_atint64

updated_bystring

The identifier of the user who updated the model version last time

idstring

The unique identifier of the model version

aliasesarray of object

List of aliases associated with the model version

Show child attributesHide child attributes

alias_namestring

Name of the alias, e.g. 'champion' or 'latest_stable'

version_numint64

Integer version number of the model version to which this alias points.

idstring

The unique identifier of the alias

model_namestring

The name of the parent registered model of the model version, relative to parent schema

catalog_namestring

The name of the catalog containing the model version

schema_namestring

The name of the schema containing the model version, relative to parent catalog

View as Markdown

Request

{
  "model_name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "source": "string",
  "comment": "string",
  "run_id": "string",
  "run_workspace_id": 0,
  "model_version_dependencies": {
    "dependencies": [
      {}
    ]
  },
  "status": "string",
  "version": 0,
  "storage_location": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "id": "string",
  "aliases": [
    {
      "alias_name": "string",
      "version_num": 0,
      "id": "string",
      "model_name": "string",
      "catalog_name": "string",
      "schema_name": "string"
    }
  ]
}

Response

{
  "model_name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "source": "string",
  "comment": "string",
  "run_id": "string",
  "run_workspace_id": 0,
  "model_version_dependencies": {
    "dependencies": [
      {}
    ]
  },
  "status": "string",
  "version": 0,
  "storage_location": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "id": "string",
  "aliases": [
    {
      "alias_name": "string",
      "version_num": 0,
      "id": "string",
      "model_name": "string",
      "catalog_name": "string",
      "schema_name": "string"
    }
  ]
}