Package org.apache.gravitino.model

Interface ModelCatalog

@Evolving
public interface ModelCatalog

The ModelCatalog interface defines the public API for managing model objects in a schema. If the catalog implementation supports model objects, it should implement this interface.

Method Summary

Modifier and Type	Method	Description
Model	alterModel(NameIdentifier ident, ModelChange... changes)	Applies the changes to a model in the catalog.
ModelVersion	alterModelVersion(NameIdentifier ident, int version, ModelVersionChange... changes)	Applies the specified changes to a model version identified by its version number.
ModelVersion	alterModelVersion(NameIdentifier ident, String alias, ModelVersionChange... changes)	Applies the specified changes to a model version identified by its alias.
boolean	deleteModel(NameIdentifier ident)	Delete the model from the catalog.
boolean	deleteModelVersion(NameIdentifier ident, int version)	Delete the model version by the NameIdentifier and version number.
boolean	deleteModelVersion(NameIdentifier ident, String alias)	Delete the model version by the NameIdentifier and version alias.
Model	getModel(NameIdentifier ident)	Get a model metadata by NameIdentifier from the catalog.
ModelVersion	getModelVersion(NameIdentifier ident, int version)	Get a model version by the NameIdentifier and version number from the catalog.
ModelVersion	getModelVersion(NameIdentifier ident, String alias)	Get a model version by the NameIdentifier and version alias from the catalog.
String	getModelVersionUri(NameIdentifier ident, int version, String uriName)	Get the URI of the model artifact with a specified version number and URI name.
String	getModelVersionUri(NameIdentifier ident, String alias, String uriName)	Get the URI of the model artifact with a specified version alias and URI name.
default void	linkModelVersion(NameIdentifier ident, String uri, String[] aliases, String comment, Map<String,String> properties)	Link a new model version to the registered model object.
void	linkModelVersion(NameIdentifier ident, Map<String,String> uris, String[] aliases, String comment, Map<String,String> properties)	Link a new model version to the registered model object.
NameIdentifier[]	listModels(Namespace namespace)	List the models in a schema namespace from the catalog.
ModelVersion[]	listModelVersionInfos(NameIdentifier ident)	List all the versions with their information of the register model by NameIdentifier in the catalog.
int[]	listModelVersions(NameIdentifier ident)	List all the versions of the register model by NameIdentifier in the catalog.
default boolean	modelExists(NameIdentifier ident)	Check if a model exists using an NameIdentifier from the catalog.
default boolean	modelVersionExists(NameIdentifier ident, int version)	Check if the model version exists by the NameIdentifier and version number.
default boolean	modelVersionExists(NameIdentifier ident, String alias)	Check if the model version exists by the NameIdentifier and version alias.
Model	registerModel(NameIdentifier ident, String comment, Map<String,String> properties)	Register a model in the catalog if the model is not existed, otherwise the ModelAlreadyExistsException will be thrown.
default Model	registerModel(NameIdentifier ident, Map<String,String> uris, String[] aliases, String comment, Map<String,String> properties)	Register a model in the catalog if the model is not existed, otherwise the ModelAlreadyExistsException will be thrown.

Method Details

listModels

NameIdentifier[] listModels(Namespace namespace)
                     throws NoSuchSchemaException

List the models in a schema namespace from the catalog.

Parameters:

namespace - A schema namespace.

Returns:

An array of model identifiers in the namespace.

Throws:

NoSuchSchemaException - If the schema does not exist.

getModel

Model getModel(NameIdentifier ident)
        throws NoSuchModelException

Get a model metadata by NameIdentifier from the catalog.

Parameters:

ident - A model identifier.

Returns:

The model metadata.

Throws:

NoSuchModelException - If the model does not exist.

modelExists

default boolean modelExists(NameIdentifier ident)

Check if a model exists using an NameIdentifier from the catalog.

Parameters:

ident - A model identifier.

Returns:

true If the model exists, false if the model does not exist.

registerModel

Model registerModel(NameIdentifier ident,
 String comment,
 Map<String,String> properties)
             throws NoSuchSchemaException,
ModelAlreadyExistsException

Register a model in the catalog if the model is not existed, otherwise the ModelAlreadyExistsException will be thrown. The Model object will be created when the model is registered, users can call linkModelVersion(NameIdentifier, Map, String[], String, Map) to link the model version to the registered Model.

Parameters:

ident - The name identifier of the model.

comment - The comment of the model. The comment is optional and can be null.

properties - The properties of the model. The properties are optional and can be null or empty.

Returns:

The registered model object.

Throws:

NoSuchSchemaException - If the schema does not exist.

ModelAlreadyExistsException - If the model already registered.

registerModel

default Model registerModel(NameIdentifier ident,
 Map<String,String> uris,
 String[] aliases,
 String comment,
 Map<String,String> properties)
                     throws NoSuchSchemaException,
ModelAlreadyExistsException,
ModelVersionAliasesAlreadyExistException

Register a model in the catalog if the model is not existed, otherwise the ModelAlreadyExistsException will be thrown. The Model object will be created when the model is registered, in the meantime, the model version (version 0) will also be created and linked to the registered model.

Parameters:

ident - The name identifier of the model.

uris - The names and URIs of the model version artifact.

aliases - The aliases of the model version. The aliases should be unique in this model, otherwise the ModelVersionAliasesAlreadyExistException will be thrown. The aliases are optional and can be empty. Also, be aware that the alias cannot be a number or a number string.

comment - The comment of the model. The comment is optional and can be null.

properties - The properties of the model. The properties are optional and can be null or empty.

Returns:

The registered model object.

Throws:

NoSuchSchemaException - If the schema does not exist when register a model.

ModelAlreadyExistsException - If the model already registered.

ModelVersionAliasesAlreadyExistException - If the aliases already exist in the model.

deleteModel

boolean deleteModel(NameIdentifier ident)

Delete the model from the catalog. If the model does not exist, return false. Otherwise, return true. The deletion of the model will also delete all the model versions linked to this model.

Parameters:

ident - The name identifier of the model.

Returns:

True if the model is deleted, false if the model does not exist.

listModelVersions

int[] listModelVersions(NameIdentifier ident)
                 throws NoSuchModelException

List all the versions of the register model by NameIdentifier in the catalog.

Parameters:

ident - The name identifier of the model.

Returns:

An array of version numbers of the model.

Throws:

NoSuchModelException - If the model does not exist.

listModelVersionInfos

ModelVersion[] listModelVersionInfos(NameIdentifier ident)
                              throws NoSuchModelException

List all the versions with their information of the register model by NameIdentifier in the catalog.

Parameters:

ident - The name identifier of the model.

Returns:

An array of version information of the model.

Throws:

NoSuchModelException - If the model does not exist.

getModelVersion

ModelVersion getModelVersion(NameIdentifier ident,
 int version)
                      throws NoSuchModelVersionException

Get a model version by the NameIdentifier and version number from the catalog.

Parameters:

ident - The name identifier of the model.

version - The version number of the model.

Returns:

The model version object.

Throws:

NoSuchModelVersionException - If the model version does not exist.

getModelVersion

ModelVersion getModelVersion(NameIdentifier ident,
 String alias)
                      throws NoSuchModelVersionException

Get a model version by the NameIdentifier and version alias from the catalog.

Parameters:

ident - The name identifier of the model.

alias - The version alias of the model.

Returns:

The model version object.

Throws:

NoSuchModelVersionException - If the model version does not exist.

modelVersionExists

default boolean modelVersionExists(NameIdentifier ident,
 int version)

Check if the model version exists by the NameIdentifier and version number. If the model version exists, return true, otherwise return false.

Parameters:

ident - The name identifier of the model.

version - The version number of the model.

Returns:

True if the model version exists, false if the model version does not exist.

modelVersionExists

default boolean modelVersionExists(NameIdentifier ident,
 String alias)

Check if the model version exists by the NameIdentifier and version alias. If the model version exists, return true, otherwise return false.

Parameters:

ident - The name identifier of the model.

alias - The version alias of the model.

Returns:

True if the model version exists, false if the model version does not exist.

linkModelVersion

default void linkModelVersion(NameIdentifier ident,
 String uri,
 String[] aliases,
 String comment,
 Map<String,String> properties)
                       throws NoSuchModelException,
ModelVersionAliasesAlreadyExistException

Link a new model version to the registered model object. The new model version will be added to the model object. If the model object does not exist, it will throw an exception. If the version alias already exists in the model, it will throw an exception.

Parameters:

ident - The name identifier of the model.

uri - The URI of the model version artifact.

aliases - The aliases of the model version. The aliases should be unique in this model, otherwise the ModelVersionAliasesAlreadyExistException will be thrown. The aliases are optional and can be empty. Also, be aware that the alias cannot be a number or a number string.

comment - The comment of the model version. The comment is optional and can be null.

properties - The properties of the model version. The properties are optional and can be null or empty.

Throws:

NoSuchModelException - If the model does not exist.

ModelVersionAliasesAlreadyExistException - If the aliases already exist in the model.

linkModelVersion

void linkModelVersion(NameIdentifier ident,
 Map<String,String> uris,
 String[] aliases,
 String comment,
 Map<String,String> properties)
               throws NoSuchModelException,
ModelVersionAliasesAlreadyExistException

Link a new model version to the registered model object. The new model version will be added to the model object. If the model object does not exist, it will throw an exception. If the version alias already exists in the model, it will throw an exception.

Parameters:

ident - The name identifier of the model.

uris - The names and URIs of the model version artifact.

aliases - The aliases of the model version. The aliases should be unique in this model, otherwise the ModelVersionAliasesAlreadyExistException will be thrown. The aliases are optional and can be empty. Also, be aware that the alias cannot be a number or a number string.

comment - The comment of the model version. The comment is optional and can be null.

properties - The properties of the model version. The properties are optional and can be null or empty.

Throws:

NoSuchModelException - If the model does not exist.

ModelVersionAliasesAlreadyExistException - If the aliases already exist in the model.

getModelVersionUri

String getModelVersionUri(NameIdentifier ident,
 int version,
 String uriName)
                   throws NoSuchModelVersionException,
NoSuchModelVersionURINameException

Get the URI of the model artifact with a specified version number and URI name.

Parameters:

ident - The name identifier of the model.

version - The version number of the model.

uriName - The name of the URI. If null, the default URI will be used.

Returns:

The URI of the model version.

Throws:

NoSuchModelVersionException - If the model version does not exist.

NoSuchModelVersionURINameException

getModelVersionUri

String getModelVersionUri(NameIdentifier ident,
 String alias,
 String uriName)
                   throws NoSuchModelVersionException,
NoSuchModelVersionURINameException

Get the URI of the model artifact with a specified version alias and URI name.

Parameters:

ident - The name identifier of the model.

alias - The version alias of the model.

uriName - The name of the URI. If null, the default URI will be used.

Returns:

The URI of the model version.

Throws:

NoSuchModelVersionException - If the model version does not exist.

NoSuchModelVersionURINameException

deleteModelVersion

boolean deleteModelVersion(NameIdentifier ident,
 int version)

Delete the model version by the NameIdentifier and version number. If the model version does not exist, return false. If the model version is deleted, return true.

Parameters:

ident - The name identifier of the model.

version - The version number of the model.

Returns:

True if the model version is deleted, false if the model version does not exist.

deleteModelVersion

boolean deleteModelVersion(NameIdentifier ident,
 String alias)

Delete the model version by the NameIdentifier and version alias. If the model version does not exist, return false. If the model version is deleted, return true.

Parameters:

ident - The name identifier of the model.

alias - The version alias of the model.

Returns:

True if the model version is deleted, false if the model version does not exist.

alterModel

Model alterModel(NameIdentifier ident,
 ModelChange... changes)
          throws NoSuchModelException,
IllegalArgumentException

Applies the changes to a model in the catalog.

Implementations may reject the changes. If any change is rejected, no changes should be applied to the model.

Parameters:

ident - the NameIdentifier instance of the model to alter

changes - the several ModelChange instances to apply to the model

Returns:

the updated Model instance

Throws:

NoSuchModelException - If the model does not exist

IllegalArgumentException - If the change is rejected by the implementation

alterModelVersion

ModelVersion alterModelVersion(NameIdentifier ident,
 int version,
 ModelVersionChange... changes)
                        throws NoSuchModelException,
NoSuchModelVersionException,
IllegalArgumentException

Applies the specified changes to a model version identified by its version number.

If any change is rejected by the implementation, no changes will be applied.

Parameters:

ident - the NameIdentifier of the model to be altered

version - the version number of the model version to be altered

changes - one or more ModelVersionChange instances to apply

Returns:

the updated ModelVersion instance

Throws:

NoSuchModelVersionException - if the specified model version does not exist

IllegalArgumentException - if any change is rejected by the implementation

NoSuchModelException

alterModelVersion

ModelVersion alterModelVersion(NameIdentifier ident,
 String alias,
 ModelVersionChange... changes)
                        throws NoSuchModelException,
IllegalArgumentException

Applies the specified changes to a model version identified by its alias.

If any change is rejected by the implementation, no changes will be applied.

Parameters:

ident - the NameIdentifier of the model to be altered

alias - the alias of the model version to be altered

changes - one or more ModelVersionChange instances to apply

Returns:

the updated ModelVersion instance

Throws:

NoSuchModelVersionException - if the specified model version does not exist

IllegalArgumentException - if any change is rejected by the implementation

NoSuchModelException