Skip to main content

registered-models command group

note

This information applies to Databricks CLI versions 0.205 and above. The Databricks CLI is in Public Preview.

Databricks CLI use is subject to the Databricks License and Databricks Privacy Notice, including any Usage Data provisions.

The registered-models command group within the Databricks CLI contains commands to manage models in the model registry in Unity Catalog. Registered models provide centralized access control, auditing, lineage, and discovery of ML models across Databricks workspaces. See Manage model lifecycle in Unity Catalog.

databricks registered-models create

Create a new registered model in Unity Catalog.

File storage for model versions in the registered model will be located in the default location which is specified by the parent schema, or the parent catalog, or the Metastore.

For registered model creation to succeed, the user must satisfy the following conditions:

  • The caller must be a metastore admin, or be the owner of the parent catalog and schema, or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.
  • The caller must have the CREATE MODEL or CREATE FUNCTION privilege on the parent schema.
databricks registered-models create CATALOG_NAME SCHEMA_NAME NAME [flags]

Arguments

CATALOG_NAME

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

SCHEMA_NAME

    The name of the schema where the registered model resides.

NAME

    The name of the registered model.

Options

--comment string

    The comment attached to the registered model.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--storage-location string

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

Global flags

Examples

The following example creates a registered model in the specified catalog and schema:

Bash
databricks registered-models create main my_schema my_model

The following example creates a registered model with a comment:

Bash
databricks registered-models create main my_schema my_model --comment "My model description"

databricks registered-models delete

Delete a registered model and all its model versions from the specified parent catalog and schema.

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.

databricks registered-models delete FULL_NAME [flags]

Arguments

FULL_NAME

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

Options

Global flags

Examples

The following example deletes a registered model:

Bash
databricks registered-models delete main.my_schema.my_model

databricks registered-models delete-alias

Delete 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.

databricks registered-models delete-alias FULL_NAME ALIAS [flags]

Arguments

FULL_NAME

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

ALIAS

    The name of the alias.

Options

Global flags

Examples

The following example deletes a registered model alias:

Bash
databricks registered-models delete-alias main.my_schema.my_model production

databricks registered-models get

Get a registered model.

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.

databricks registered-models get FULL_NAME [flags]

Arguments

FULL_NAME

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

Options

--include-aliases

    Whether to include registered model aliases in the response.

--include-browse

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

Global flags

Examples

The following example gets information about a registered model:

Bash
databricks registered-models get main.my_schema.my_model

The following example gets information about a registered model including aliases:

Bash
databricks registered-models get main.my_schema.my_model --include-aliases

databricks registered-models list

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 recieve 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.

databricks registered-models list [flags]

Options

--catalog-name string

    The identifier of the catalog under which to list registered models.

--include-browse

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

--max-results int

    Max number of registered models to return.

--page-token string

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

--schema-name string

    The identifier of the schema under which to list registered models.

Global flags

Examples

The following example lists all registered models in the current metastore:

Bash
databricks registered-models list

The following example lists registered models in a specific catalog:

Bash
databricks registered-models list --catalog-name main

The following example lists registered models in a specific schema:

Bash
databricks registered-models list --catalog-name main --schema-name my_schema

databricks registered-models set-alias

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.

databricks registered-models set-alias FULL_NAME ALIAS VERSION_NUM [flags]

Arguments

FULL_NAME

    Full name of the registered model.

ALIAS

    The name of the alias.

VERSION_NUM

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

Options

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

Global flags

Examples

The following example sets an alias on a registered model:

Bash
databricks registered-models set-alias main.my_schema.my_model production 1

databricks registered-models update

Update 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.

Currently only the name, the owner or the comment of the registered model can be updated.

databricks registered-models update FULL_NAME [flags]

Arguments

FULL_NAME

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

Options

--comment string

    The comment attached to the registered model.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

``--new-name string`**

    New name for the registered model.

--owner string

    The identifier of the user who owns the registered model.

Global flags

Examples

The following example updates a registered model's comment:

Bash
databricks registered-models update main.my_schema.my_model --comment "Updated model description"

The following example updates a registered model's name:

Bash
databricks registered-models update main.my_schema.my_model --new-name my_new_model

Global flags

--debug

  Whether to enable debug logging.

-h or --help

    Display help for the Databricks CLI or the related command group or the related command.

--log-file string

    A string representing the file to write output logs to. If this flag is not specified then the default is to write output logs to stderr.

--log-format format

    The log format type, text or json. The default value is text.

--log-level string

    A string representing the log format level. If not specified then the log format level is disabled.

-o, --output type

    The command output type, text or json. The default value is text.

-p, --profile string

    The name of the profile in the ~/.databrickscfg file to use to run the command. If this flag is not specified then if it exists, the profile named DEFAULT is used.

--progress-format format

    The format to display progress logs: default, append, inplace, or json

-t, --target string

    If applicable, the bundle target to use