Overview
The Model Catalog brings machine learning models into the same unified governance framework as tables and volumes. DataBuddy provides a managed MLflow Model Registry in the Catalog, allowing you to centrally register and version models trained from experiments, and quickly reference specific versions by alias for deployment or online inference.
This document describes how to create a Model Catalog, register models, and manage model versions and metadata. For model deployment and online inference, see Model Serving. Prerequisites
You have activated the DataBuddy service and completed workspace initialization.
The current account has permission to create Catalogs in the target workspace, as well as the create model permission on the target Catalog/Schema.
You are familiar with the basic workflow of Experiment Management and have completed at least one experiment run (for UI registration). A model must include a model Signature, which specifies the field names and data types of inputs and outputs. Otherwise, the model cannot be registered.
Use Limits
Limit | Description |
Registration prerequisite | A model must have a Signature to be registered. |
Tag source | Tags for models and versions must be selected from the governance tag policy, and the UI does not support arbitrary free text. |
Alias uniqueness | Aliases under the same model must be unique. |
Tag operations | Model tags can only be added / modified / deleted through the UI. Writing model tags is not currently supported for models created through custom code. |
Creating a Model Catalog
1. Select Data Catalog in the left sidebar.
2. Click + Create Data Catalog at the top of the left directory tree.
3. In the pop-up window, configure the following:
Catalog Name: Required.
Catalog Source: Required. Select TCCatalog.
Catalog Type: Required. Select Native Catalog.
Catalog Purpose: Required. Select Model File Directory.
Description: Optional. Up to 256 characters.
1. Click Confirm to complete the creation.
After successful creation, you will be directed to the Catalog details page, which includes the default Schema, similar to a structured data catalog.
Registering a Model
DataBuddy supports two model registration methods:
Method 1: UI Registration (from an Experiment Run)
2. On the run details page, click Register Model.
3. In the pop-up window:
Registration Method: New model, or a new version of an existing model.
Model Name: Enter a model name. It must be unique within the selected Schema.
1. Click Register Model.
The system calls the Catalog registration API to complete the registration. After successful registration, you can find the model in Catalog by using the <catalog>.<schema>.<model> path. If a model with the same name already exists, the new registration will be added as the next version of that model, with an incremented version number.
Method 2: Notebook/Code Registration
Use the MLflow client to register models in Notebook or Python tasks. The default DataBuddy registration URI is set to the MLflow Model Registry in Catalog:
import mlflow
from mlflow.models import infer_signature
# Train and Package a Model
signature = infer_signature(X_train, model.predict(X_train))
mlflow.sklearn.log_model(
sk_model=model,
artifact_path="model",
signature=signature,
registered_model_name="ml_catalog.recsys.deepfm_model"
)
The registration API reports implementation information, such as evaluation metrics, to the model version properties in Catalog.
Tip
Before registration, use mlflow.models.infer_signature or manually construct a Signature. Models without a signature will be rejected during registration.
Model Details Page
Access the model through the left directory tree or the Schema details page. The details page structure is as follows:
Area | Content. |
Top breadcrumb | Catalog > Schema > Model Name (Copyable) |
Overview Tab | Model description, owner, tag, version list |
Activity Log | Model registration time, version, log |
Permissions Tab | |
Model Description
In Overview, click Add Description or the pencil icon in the description area to open the description input box:
Model descriptions and version descriptions are uniformly limited to a maximum of 256 characters.
Repeated editing is supported.
Version List
The version list below the model Overview is displayed in descending order by version number:
Column | Description |
Version number. | Click to go to the version details page to view detailed information such as model lineage. |
Tags | Governance tag of this version (key:value), used to mark business attributes such as champion version and training dataset. |
Alias | Alias bound to this version (such as champion and production) |
Deployment Status | Deployed / Not deployed |
Deployed services | A version can be deployed to multiple services. If more than one service is deployed, they are collapsed into +N. |
Remarks | Remarks of this version |
Model Owner
On the right, Business Information > Model Owner defaults to the registrant. Click the pencil icon to initiate a transfer:
The transfer entry is visible only to the current owner.
A dialog box appears during the transfer, stating: "After the transfer, you will no longer have management permissions on this model."
Model Version Management
Click the version number to go to the version details page.
Version Details Page Structure
Area | Content. |
Operation area | Model description, alias, tag |
Non-operation area | Metrics, parameters, activity logs, model version signature (input and output field table) |
Model Version Signature
A signature records the input and output specifications of a model and serves as the basis for mandatory input and output validation during deployment:
Column | Description |
Input Field Name | For example, user_id |
Input Data Type | For example, STRING |
Output Field Name | For example, score |
Output Data Type | For example, DOUBLE |
Alias
An alias is a mutable named reference that points to a specific version and is commonly used to deploy production versions:
1. On the version details page, click Edit next to Alias.
2. Enter an alias (up to 50 characters).
3. Click Save.
If the alias is already in use under the same model, a message appears: "The alias <Alias> is already in use. Enter a different one."
Reference example:
models:/ml_catalog.recsys.deepfm_model@champion
Reassigning an alias to a different version allows you to switch production versions without modifying the calling code.
Tag (Version-Level)
Tags for a model version are also selected from the Governance Tag policy, and multiple tags can be added: Limit | Description |
Maximum Number | A single version can have up to 10 tags. |
value length | Reuse the limit of governance tag management (no more than 50 characters) |
Version Source
If this version is copied from another model version, the About This Model Version section displays:
Copied From: The full name of the source version (for example, ml_catalog.recsys.deepfm_model/3).
Version Source: If the version comes from an experiment run, a source link is displayed, which you can click to go to the experiment details.
Copying a Model Version
Copy a version to another model so that an existing version can be used as the initial version of the new model.
1. In the upper-right corner of the version details page, click Copy This Version.
2. In the pop-up window:
Copy to Model: Select the target model from the drop-down list.
You can only select target models for which you have permissions.
3. Click Copy.
Feedback on the copy process:
After the copy is triggered, the dialog box closes and the page displays a message indicating that the model version copy has started and may take some time.
After a successful copy, a green banner appears at the top of the page with the message "Version copied successfully! New version: [full new version name]". To the right of the banner, a Go to New Version button is available for direct navigation.
On failure, a red error message is displayed in the dialog box (for example, no write permission on the target Schema), and the dialog box configuration is retained so that you can modify it and retry.
Rules for the new version:
The new version number is incremented in the target model. For example, if the original maximum version is 5, the copied version will be 6.
The status of the new version defaults to Ready, regardless of the status of the original version.
The About This Model Version section automatically records the Copied From field.
Delete a model version
1. In the upper-right corner of the version details page, click Delete This Version.
2. In the second confirmation dialog, confirm the message: "Are you sure you want to delete <full version name>? This action cannot be undone."
3. Click the **Delete** button to delete it.
Warning
Deleted model versions cannot be recovered. Before deletion, confirm that no online services or downstream inference tasks depend on this version.
Permission Management
The permission model of a model is consistent with that of tables and Volumes. Permissions can be granted independently at the Catalog / Schema / Model level.
Model-Level Permission Points
Permission Point | Description |
create model
| Creating a Model |
read
| Read a model (for inference or invocation) |
write
| Update a model. |
delete
| Delete a model. |
create model version
| Create a new version based on the model. |
use model
| Use the model. |
all
| Grant all permissions listed above. |
grant
| Can grant permissions to others |
Tip
Model permissions have dependencies. When granting read, write, or use model on a model, ensure that the user already has the use catalog permission on the owning Catalog and the use schema permission on the owning Schema. The authorization dialog prompts you to select the dependent permissions before you save.
Configuring Model Permissions
1. Go to the Permissions Tab on the model details page or version details page.
2. Click Add Authorization and select the authorized principal (multiple users can be selected).
3. Select the permission points to grant.
4. Click Confirm to complete the authorization.
Only the root account, model owners, and users with the grant permission can perform authorization. Without the grant permission, the authorization button is disabled.
Relationships with Other Modules
Module | Relationship |
| One of the entry points for model registration; experiment runs can be registered to Catalog with one click through the UI. |
| When deploying an online inference service, select a model version or alias from Catalog. |
| The model list in the data science module shares the same metadata as models in Catalog, and they can be navigated bidirectionally. |
| As a lineage node, a model can be used to track upstream training data and downstream inference assets. |
| Tags for models and versions must be selected from the governance tag policy. |
FAQs
Q: Is MLflow required to register a model to Catalog?
A: Yes. Model registration in DataBuddy Catalog follows the MLflow Model Registry protocol, so models must first be recorded in MLflow format (including model artifacts, signatures, and so on). In Notebook, you can directly use the mlflow.<flavor>.log_model API. Models trained in experiments are automatically packaged in MLflow format by DataBuddy.
Q: What should I do if an error "Model signature is required" occurs during model registration?
A: A model must have input and output signatures before registration. During training, use mlflow.models.infer_signature(input, output) to infer them automatically, or explicitly construct a Signature object and pass it to log_model.
Q: What is the difference between an Alias and a Version?
A:
Version Number: increments automatically with each registration and cannot be modified. A version number uniquely corresponds to a specific model artifact.
Alias: a mutable named reference that can be reassigned to different versions. It is commonly used to label the production version as champion and the canary version as staging, allowing the deployment side to switch versions through the alias without changing code.
Q: What is the impact of deleting a model or a version?
A:
Deleting a version removes only the metadata and artifacts of that version. Other versions are not affected, but if the version is referenced by an online service, calls to that service will fail.
Deleting a model removes all versions and history under that model. Before deletion, confirm that no downstream inference tasks depend on it.
References