Package org.apache.flink.table.catalog

Interface Catalog

All Known Implementing Classes:

AbstractCatalog, GenericInMemoryCatalog, TestFileSystemCatalog

@PublicEvolving
public interface Catalog

This interface is responsible for reading and writing metadata such as database/table/views/UDFs from a registered catalog. It connects a registered catalog and Flink's Table API. This interface only processes permanent metadata objects. In order to process temporary objects, a catalog can also implement the TemporaryOperationListener interface.

Method Summary

Modifier and Type	Method	Description
void	alterDatabase(String name, CatalogDatabase newDatabase, boolean ignoreIfNotExists)	Modify an existing database.
void	alterFunction(ObjectPath functionPath, CatalogFunction newFunction, boolean ignoreIfNotExists)	Modify an existing function.
default void	alterModel(ObjectPath modelPath, CatalogModel newModel, boolean ignoreIfNotExists)	Modifies an existing model.
void	alterPartition(ObjectPath tablePath, CatalogPartitionSpec partitionSpec, CatalogPartition newPartition, boolean ignoreIfNotExists)	Alter a partition.
void	alterPartitionColumnStatistics(ObjectPath tablePath, CatalogPartitionSpec partitionSpec, CatalogColumnStatistics columnStatistics, boolean ignoreIfNotExists)	Update the column statistics of a table partition.
void	alterPartitionStatistics(ObjectPath tablePath, CatalogPartitionSpec partitionSpec, CatalogTableStatistics partitionStatistics, boolean ignoreIfNotExists)	Update the statistics of a table partition.
void	alterTable(ObjectPath tablePath, CatalogBaseTable newTable, boolean ignoreIfNotExists)	Modifies an existing table or view.
default void	alterTable(ObjectPath tablePath, CatalogBaseTable newTable, List<TableChange> tableChanges, boolean ignoreIfNotExists)	Modifies an existing table or view.
void	alterTableColumnStatistics(ObjectPath tablePath, CatalogColumnStatistics columnStatistics, boolean ignoreIfNotExists)	Update the column statistics of a table.
void	alterTableStatistics(ObjectPath tablePath, CatalogTableStatistics tableStatistics, boolean ignoreIfNotExists)	Update the statistics of a table.
default List<CatalogColumnStatistics>	bulkGetPartitionColumnStatistics(ObjectPath tablePath, List<CatalogPartitionSpec> partitionSpecs)	Get a list of column statistics for given partitions.
default List<CatalogTableStatistics>	bulkGetPartitionStatistics(ObjectPath tablePath, List<CatalogPartitionSpec> partitionSpecs)	Get a list of statistics of given partitions.
void	close()	Close the catalog when it is no longer needed and release any resource that it might be holding.
void	createDatabase(String name, CatalogDatabase database, boolean ignoreIfExists)	Create a database.
void	createFunction(ObjectPath functionPath, CatalogFunction function, boolean ignoreIfExists)	Create a function.
default void	createModel(ObjectPath modelPath, CatalogModel model, boolean ignoreIfExists)	Creates a new model.
void	createPartition(ObjectPath tablePath, CatalogPartitionSpec partitionSpec, CatalogPartition partition, boolean ignoreIfExists)	Create a partition.
void	createTable(ObjectPath tablePath, CatalogBaseTable table, boolean ignoreIfExists)	Creates a new table or view.
boolean	databaseExists(String databaseName)	Check if a database exists in this catalog.
default void	dropDatabase(String name, boolean ignoreIfNotExists)	Drop a database.
void	dropDatabase(String name, boolean ignoreIfNotExists, boolean cascade)	Drop a database.
void	dropFunction(ObjectPath functionPath, boolean ignoreIfNotExists)	Drop a function.
default void	dropModel(ObjectPath modelPath, boolean ignoreIfNotExists)	Drop a model.
void	dropPartition(ObjectPath tablePath, CatalogPartitionSpec partitionSpec, boolean ignoreIfNotExists)	Drop a partition.
void	dropTable(ObjectPath tablePath, boolean ignoreIfNotExists)	Drop a table or view.
boolean	functionExists(ObjectPath functionPath)	Check whether a function exists or not.
CatalogDatabase	getDatabase(String databaseName)	Get a database from this catalog.
String	getDefaultDatabase()	Get the name of the default database for this catalog.
default Optional<Factory>	getFactory()	Returns a factory for creating instances from catalog objects.
CatalogFunction	getFunction(ObjectPath functionPath)	Get the function.
default Optional<FunctionDefinitionFactory>	getFunctionDefinitionFactory()	Get an optional FunctionDefinitionFactory instance that's responsible for instantiating function definitions.
default CatalogModel	getModel(ObjectPath modelPath)	Returns a CatalogModel identified by the given ObjectPath.
CatalogPartition	getPartition(ObjectPath tablePath, CatalogPartitionSpec partitionSpec)	Get a partition of the given table.
CatalogColumnStatistics	getPartitionColumnStatistics(ObjectPath tablePath, CatalogPartitionSpec partitionSpec)	Get the column statistics of a partition.
CatalogTableStatistics	getPartitionStatistics(ObjectPath tablePath, CatalogPartitionSpec partitionSpec)	Get the statistics of a partition.
default Procedure	getProcedure(ObjectPath procedurePath)	Get the procedure.
CatalogBaseTable	getTable(ObjectPath tablePath)	Returns a CatalogTable or CatalogView identified by the given ObjectPath.
default CatalogBaseTable	getTable(ObjectPath tablePath, long timestamp)	Returns a CatalogTable or CatalogView at a specific time identified by the given ObjectPath.
CatalogColumnStatistics	getTableColumnStatistics(ObjectPath tablePath)	Get the column statistics of a table.
default Optional<TableFactory>	getTableFactory()	Deprecated. Use getFactory() for the new factory stack.
CatalogTableStatistics	getTableStatistics(ObjectPath tablePath)	Get the statistics of a table.
List<String>	listDatabases()	Get the names of all databases in this catalog.
List<String>	listFunctions(String dbName)	List the names of all functions in the given database.
default List<String>	listModels(String databaseName)	Get names of all models under this database.
List<CatalogPartitionSpec>	listPartitions(ObjectPath tablePath)	Get CatalogPartitionSpec of all partitions of the table.
List<CatalogPartitionSpec>	listPartitions(ObjectPath tablePath, CatalogPartitionSpec partitionSpec)	Get CatalogPartitionSpec of all partitions that is under the given CatalogPartitionSpec in the table.
List<CatalogPartitionSpec>	listPartitionsByFilter(ObjectPath tablePath, List<Expression> filters)	Get CatalogPartitionSpec of partitions by expression filters in the table.
default List<String>	listProcedures(String dbName)	List the names of all procedures in the given database.
List<String>	listTables(String databaseName)	Get names of all tables and views under this database.
List<String>	listViews(String databaseName)	Get names of all views under this database.
default boolean	modelExists(ObjectPath modelPath)	Check if a model exists in this catalog.
void	open()	Open the catalog.
boolean	partitionExists(ObjectPath tablePath, CatalogPartitionSpec partitionSpec)	Check whether a partition exists or not.
default void	renameModel(ObjectPath modelPath, String newModelName, boolean ignoreIfNotExists)	Rename an existing model.
void	renameTable(ObjectPath tablePath, String newTableName, boolean ignoreIfNotExists)	Rename an existing table or view.
default boolean	supportsManagedTable()	Deprecated. This method will be removed soon.
boolean	tableExists(ObjectPath tablePath)	Check if a table or view exists in this catalog.

Method Detail

getFactory

default Optional<Factory> getFactory()

Returns a factory for creating instances from catalog objects.

This method enables bypassing the discovery process. Implementers can directly pass internal catalog-specific objects to their own factory. For example, a custom CatalogTable can be processed by a custom DynamicTableFactory.

If this catalog support to create materialized table, you should also override this method to provide DynamicTableFactory which help planner to find DynamicTableSource and DynamicTableSink correctly during compile optimization phase. If you don't override this method, you must specify the physical connector identifier that this catalog represents storage when create materialized table. Otherwise, the planner can't find the DynamicTableFactory.

Because all factories are interfaces, the returned Factory instance can implement multiple supported extension points. An instanceof check is performed by the caller that checks whether a required factory is implemented; otherwise the discovery process is used.

getTableFactory

@Deprecated
default Optional<TableFactory> getTableFactory()

Deprecated.

Use getFactory() for the new factory stack. The new factory stack uses the new table sources and sinks defined in FLIP-95 and a slightly different discovery mechanism.

Get an optional TableFactory instance that's responsible for generating table-related instances stored in this catalog, instances such as source/sink.

Returns:

an optional TableFactory instance

getFunctionDefinitionFactory

default Optional<FunctionDefinitionFactory> getFunctionDefinitionFactory()

Get an optional FunctionDefinitionFactory instance that's responsible for instantiating function definitions.

Returns:

an optional FunctionDefinitionFactory instance

open

void open()
   throws CatalogException

Open the catalog. Used for any required preparation in initialization phase.

Throws:

CatalogException - in case of any runtime exception

close

void close()
    throws CatalogException

Close the catalog when it is no longer needed and release any resource that it might be holding.

Throws:

CatalogException - in case of any runtime exception

getDefaultDatabase

@Nullable
String getDefaultDatabase()
                   throws CatalogException

Get the name of the default database for this catalog. The default database will be the current database for the catalog when user's session doesn't specify a current database. The value probably comes from configuration, will not change for the life time of the catalog instance.

If the default database is null, users will need to set a current database themselves or qualify identifiers at least with the database name when using the catalog.

Returns:

the name of the current database

Throws:

CatalogException - in case of any runtime exception

listDatabases

List<String> listDatabases()
                    throws CatalogException

Get the names of all databases in this catalog.

Returns:

a list of the names of all databases

Throws:

CatalogException - in case of any runtime exception

getDatabase

CatalogDatabase getDatabase(String databaseName)
                     throws DatabaseNotExistException,
                            CatalogException

Get a database from this catalog.

Parameters:

databaseName - Name of the database

Returns:

The requested database

Throws:

DatabaseNotExistException - if the database does not exist

CatalogException - in case of any runtime exception

databaseExists

boolean databaseExists(String databaseName)
                throws CatalogException

Check if a database exists in this catalog.

Parameters:

databaseName - Name of the database

Returns:

true if the given database exists in the catalog false otherwise

Throws:

CatalogException - in case of any runtime exception

createDatabase

void createDatabase(String name,
                    CatalogDatabase database,
                    boolean ignoreIfExists)
             throws DatabaseAlreadyExistException,
                    CatalogException

Create a database.

Parameters:

name - Name of the database to be created

database - The database definition

ignoreIfExists - Flag to specify behavior when a database with the given name already exists: if set to false, throw a DatabaseAlreadyExistException, if set to true, do nothing.

Throws:

DatabaseAlreadyExistException - if the given database already exists and ignoreIfExists is false

CatalogException - in case of any runtime exception

dropDatabase

default void dropDatabase(String name,
                          boolean ignoreIfNotExists)
                   throws DatabaseNotExistException,
                          DatabaseNotEmptyException,
                          CatalogException

Drop a database.

Parameters:

name - Name of the database to be dropped.

ignoreIfNotExists - Flag to specify behavior when the database does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

DatabaseNotExistException - if the given database does not exist

CatalogException - in case of any runtime exception

DatabaseNotEmptyException

dropDatabase

void dropDatabase(String name,
                  boolean ignoreIfNotExists,
                  boolean cascade)
           throws DatabaseNotExistException,
                  DatabaseNotEmptyException,
                  CatalogException

Drop a database.

Parameters:

name - Name of the database to be dropped.

ignoreIfNotExists - Flag to specify behavior when the database does not exist: if set to false, throw an exception, if set to true, do nothing.

cascade - Flag to specify behavior when the database contains table or function: if set to true, delete all tables and functions in the database and then delete the database, if set to false, throw an exception.

Throws:

DatabaseNotExistException - if the given database does not exist

DatabaseNotEmptyException - if the given database is not empty and isRestrict is true

CatalogException - in case of any runtime exception

alterDatabase

void alterDatabase(String name,
                   CatalogDatabase newDatabase,
                   boolean ignoreIfNotExists)
            throws DatabaseNotExistException,
                   CatalogException

Modify an existing database.

Parameters:

name - Name of the database to be modified

newDatabase - The new database definition

ignoreIfNotExists - Flag to specify behavior when the given database does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

DatabaseNotExistException - if the given database does not exist

CatalogException - in case of any runtime exception

listTables

List<String> listTables(String databaseName)
                 throws DatabaseNotExistException,
                        CatalogException

Get names of all tables and views under this database. An empty list is returned if none exists.

Returns:

a list of the names of all tables and views in this database

Throws:

DatabaseNotExistException - if the database does not exist

CatalogException - in case of any runtime exception

listViews

List<String> listViews(String databaseName)
                throws DatabaseNotExistException,
                       CatalogException

Get names of all views under this database. An empty list is returned if none exists.

Parameters:

databaseName - the name of the given database

Returns:

a list of the names of all views in the given database

Throws:

DatabaseNotExistException - if the database does not exist

CatalogException - in case of any runtime exception

getTable

CatalogBaseTable getTable(ObjectPath tablePath)
                   throws TableNotExistException,
                          CatalogException

Returns a CatalogTable or CatalogView identified by the given ObjectPath. The framework will resolve the metadata objects when necessary.

Parameters:

tablePath - Path of the table or view

Returns:

The requested table or view

Throws:

TableNotExistException - if the target does not exist

CatalogException - in case of any runtime exception

getTable

default CatalogBaseTable getTable(ObjectPath tablePath,
                                  long timestamp)
                           throws TableNotExistException,
                                  CatalogException

Returns a CatalogTable or CatalogView at a specific time identified by the given ObjectPath. The framework will resolve the metadata objects when necessary.

Parameters:

tablePath - Path of the table or view

timestamp - Timestamp of the table snapshot, which is milliseconds since 1970-01-01 00:00:00 UTC

Returns:

The requested table or view

Throws:

TableNotExistException - if the target does not exist

CatalogException - in case of any runtime exception

tableExists

boolean tableExists(ObjectPath tablePath)
             throws CatalogException

Check if a table or view exists in this catalog.

Parameters:

tablePath - Path of the table or view

Returns:

true if the given table exists in the catalog false otherwise

Throws:

CatalogException - in case of any runtime exception

dropTable

void dropTable(ObjectPath tablePath,
               boolean ignoreIfNotExists)
        throws TableNotExistException,
               CatalogException

Drop a table or view.

Parameters:

tablePath - Path of the table or view to be dropped

ignoreIfNotExists - Flag to specify behavior when the table or view does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

TableNotExistException - if the table or view does not exist

CatalogException - in case of any runtime exception

renameTable

void renameTable(ObjectPath tablePath,
                 String newTableName,
                 boolean ignoreIfNotExists)
          throws TableNotExistException,
                 TableAlreadyExistException,
                 CatalogException

Rename an existing table or view.

Parameters:

tablePath - Path of the table or view to be renamed

newTableName - the new name of the table or view

ignoreIfNotExists - Flag to specify behavior when the table or view does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

TableNotExistException - if the table does not exist

CatalogException - in case of any runtime exception

TableAlreadyExistException

createTable

void createTable(ObjectPath tablePath,
                 CatalogBaseTable table,
                 boolean ignoreIfExists)
          throws TableAlreadyExistException,
                 DatabaseNotExistException,
                 CatalogException

Creates a new table or view.

The framework will make sure to call this method with fully validated ResolvedCatalogTable or ResolvedCatalogView. Those instances are easy to serialize for a durable catalog implementation.

Parameters:

tablePath - path of the table or view to be created

table - the table definition

ignoreIfExists - flag to specify behavior when a table or view already exists at the given path: if set to false, it throws a TableAlreadyExistException, if set to true, do nothing.

Throws:

TableAlreadyExistException - if table already exists and ignoreIfExists is false

DatabaseNotExistException - if the database in tablePath doesn't exist

CatalogException - in case of any runtime exception

alterTable

void alterTable(ObjectPath tablePath,
                CatalogBaseTable newTable,
                boolean ignoreIfNotExists)
         throws TableNotExistException,
                CatalogException

Modifies an existing table or view. Note that the new and old CatalogBaseTable must be of the same kind. For example, this doesn't allow altering a regular table to partitioned table, or altering a view to a table, and vice versa.

The framework will make sure to call this method with fully validated ResolvedCatalogTable or ResolvedCatalogView. Those instances are easy to serialize for a durable catalog implementation.

Parameters:

tablePath - path of the table or view to be modified

newTable - the new table definition

ignoreIfNotExists - flag to specify behavior when the table or view does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

TableNotExistException - if the table does not exist

CatalogException - in case of any runtime exception

alterTable

default void alterTable(ObjectPath tablePath,
                        CatalogBaseTable newTable,
                        List<TableChange> tableChanges,
                        boolean ignoreIfNotExists)
                 throws TableNotExistException,
                        CatalogException

Modifies an existing table or view. Note that the new and old CatalogBaseTable must be of the same kind. For example, this doesn't allow altering a regular table to partitioned table, or altering a view to a table, and vice versa.

The framework will make sure to call this method with fully validated ResolvedCatalogTable or ResolvedCatalogView. Those instances are easy to serialize for a durable catalog implementation.

Parameters:

tablePath - path of the table or view to be modified

newTable - the new table definition

tableChanges - change to describe the modification between the newTable and the original table.

ignoreIfNotExists - flag to specify behavior when the table or view does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

TableNotExistException - if the table does not exist

CatalogException - in case of any runtime exception

supportsManagedTable

@Deprecated
default boolean supportsManagedTable()

Deprecated.

This method will be removed soon. Please see FLIP-346 for more details.

If true, tables which do not specify a connector will be translated to managed tables.

listPartitions

List<CatalogPartitionSpec> listPartitions(ObjectPath tablePath)
                                   throws TableNotExistException,
                                          TableNotPartitionedException,
                                          CatalogException

Get CatalogPartitionSpec of all partitions of the table.

Parameters:

tablePath - path of the table

Returns:

a list of CatalogPartitionSpec of the table

Throws:

TableNotExistException - thrown if the table does not exist in the catalog

TableNotPartitionedException - thrown if the table is not partitioned

CatalogException - in case of any runtime exception

listPartitions

List<CatalogPartitionSpec> listPartitions(ObjectPath tablePath,
                                          CatalogPartitionSpec partitionSpec)
                                   throws TableNotExistException,
                                          TableNotPartitionedException,
                                          PartitionSpecInvalidException,
                                          CatalogException

Get CatalogPartitionSpec of all partitions that is under the given CatalogPartitionSpec in the table.

Parameters:

tablePath - path of the table

partitionSpec - the partition spec to list

Returns:

a list of CatalogPartitionSpec that is under the given CatalogPartitionSpec in the table

Throws:

TableNotExistException - thrown if the table does not exist in the catalog

TableNotPartitionedException - thrown if the table is not partitioned

CatalogException - in case of any runtime exception

PartitionSpecInvalidException

listPartitionsByFilter

List<CatalogPartitionSpec> listPartitionsByFilter(ObjectPath tablePath,
                                                  List<Expression> filters)
                                           throws TableNotExistException,
                                                  TableNotPartitionedException,
                                                  CatalogException

Get CatalogPartitionSpec of partitions by expression filters in the table.

NOTE: For FieldReferenceExpression, the field index is based on schema of this table instead of partition columns only.

The passed in predicates have been translated in conjunctive form.

If catalog does not support this interface at present, throw an UnsupportedOperationException directly. If the catalog does not have a valid filter, throw the UnsupportedOperationException directly. Planner will fallback to get all partitions and filter by itself.

Parameters:

tablePath - path of the table

filters - filters to push down filter to catalog

Returns:

a list of CatalogPartitionSpec that is under the given CatalogPartitionSpec in the table

Throws:

TableNotExistException - thrown if the table does not exist in the catalog

TableNotPartitionedException - thrown if the table is not partitioned

CatalogException - in case of any runtime exception

getPartition

CatalogPartition getPartition(ObjectPath tablePath,
                              CatalogPartitionSpec partitionSpec)
                       throws PartitionNotExistException,
                              CatalogException

Get a partition of the given table. The given partition spec keys and values need to be matched exactly for a result.

Parameters:

tablePath - path of the table

partitionSpec - partition spec of partition to get

Returns:

the requested partition

Throws:

PartitionNotExistException - thrown if the partition doesn't exist

CatalogException - in case of any runtime exception

partitionExists

boolean partitionExists(ObjectPath tablePath,
                        CatalogPartitionSpec partitionSpec)
                 throws CatalogException

Check whether a partition exists or not.

Parameters:

tablePath - path of the table

partitionSpec - partition spec of the partition to check

Throws:

CatalogException - in case of any runtime exception

createPartition

void createPartition(ObjectPath tablePath,
                     CatalogPartitionSpec partitionSpec,
                     CatalogPartition partition,
                     boolean ignoreIfExists)
              throws TableNotExistException,
                     TableNotPartitionedException,
                     PartitionSpecInvalidException,
                     PartitionAlreadyExistsException,
                     CatalogException

Create a partition.

Parameters:

tablePath - path of the table.

partitionSpec - partition spec of the partition

partition - the partition to add.

ignoreIfExists - flag to specify behavior if a partition with the given name already exists: if set to false, it throws a PartitionAlreadyExistsException, if set to true, nothing happens.

Throws:

TableNotExistException - thrown if the target table does not exist

TableNotPartitionedException - thrown if the target table is not partitioned

PartitionSpecInvalidException - thrown if the given partition spec is invalid

PartitionAlreadyExistsException - thrown if the target partition already exists

CatalogException - in case of any runtime exception

dropPartition

void dropPartition(ObjectPath tablePath,
                   CatalogPartitionSpec partitionSpec,
                   boolean ignoreIfNotExists)
            throws PartitionNotExistException,
                   CatalogException

Drop a partition.

Parameters:

tablePath - path of the table.

partitionSpec - partition spec of the partition to drop

ignoreIfNotExists - flag to specify behavior if the partition does not exist: if set to false, throw an exception, if set to true, nothing happens.

Throws:

PartitionNotExistException - thrown if the target partition does not exist

CatalogException - in case of any runtime exception

alterPartition

void alterPartition(ObjectPath tablePath,
                    CatalogPartitionSpec partitionSpec,
                    CatalogPartition newPartition,
                    boolean ignoreIfNotExists)
             throws PartitionNotExistException,
                    CatalogException

Alter a partition.

Parameters:

tablePath - path of the table

partitionSpec - partition spec of the partition

newPartition - new partition to replace the old one

ignoreIfNotExists - flag to specify behavior if the partition does not exist: if set to false, throw an exception, if set to true, nothing happens.

Throws:

PartitionNotExistException - thrown if the target partition does not exist

CatalogException - in case of any runtime exception

listFunctions

List<String> listFunctions(String dbName)
                    throws DatabaseNotExistException,
                           CatalogException

List the names of all functions in the given database. An empty list is returned if none is registered.

Parameters:

dbName - name of the database.

Returns:

a list of the names of the functions in this database

Throws:

DatabaseNotExistException - if the database does not exist

CatalogException - in case of any runtime exception

listProcedures

default List<String> listProcedures(String dbName)
                             throws DatabaseNotExistException,
                                    CatalogException

List the names of all procedures in the given database. An empty list is returned if no procedure.

Parameters:

dbName - name of the database.

Returns:

a list of the names of the procedures in this database

Throws:

DatabaseNotExistException - if the database does not exist

CatalogException - in case of any runtime exception

getFunction

CatalogFunction getFunction(ObjectPath functionPath)
                     throws FunctionNotExistException,
                            CatalogException

Get the function. Function name should be handled in a case insensitive way.

Parameters:

functionPath - path of the function

Returns:

the requested function

Throws:

FunctionNotExistException - if the function does not exist in the catalog

CatalogException - in case of any runtime exception

getProcedure

default Procedure getProcedure(ObjectPath procedurePath)
                        throws ProcedureNotExistException,
                               CatalogException

Get the procedure. The procedure name should be handled in a case-insensitive way.

Parameters:

procedurePath - path of the procedure

Returns:

the requested procedure

Throws:

ProcedureNotExistException - if the procedure does not exist in the catalog

CatalogException - in case of any runtime exception

functionExists

boolean functionExists(ObjectPath functionPath)
                throws CatalogException

Check whether a function exists or not. Function name should be handled in a case insensitive way.

Parameters:

functionPath - path of the function

Returns:

true if the function exists in the catalog false otherwise

Throws:

CatalogException - in case of any runtime exception

createFunction

void createFunction(ObjectPath functionPath,
                    CatalogFunction function,
                    boolean ignoreIfExists)
             throws FunctionAlreadyExistException,
                    DatabaseNotExistException,
                    CatalogException

Create a function. Function name should be handled in a case insensitive way.

Parameters:

functionPath - path of the function

function - the function to be created

ignoreIfExists - flag to specify behavior if a function with the given name already exists: if set to false, it throws a FunctionAlreadyExistException, if set to true, nothing happens.

Throws:

FunctionAlreadyExistException - if the function already exist

DatabaseNotExistException - if the given database does not exist

CatalogException - in case of any runtime exception

alterFunction

void alterFunction(ObjectPath functionPath,
                   CatalogFunction newFunction,
                   boolean ignoreIfNotExists)
            throws FunctionNotExistException,
                   CatalogException

Modify an existing function. Function name should be handled in a case insensitive way.

Parameters:

functionPath - path of the function

newFunction - the function to be modified

ignoreIfNotExists - flag to specify behavior if the function does not exist: if set to false, throw an exception if set to true, nothing happens

Throws:

FunctionNotExistException - if the function does not exist

CatalogException - in case of any runtime exception

dropFunction

void dropFunction(ObjectPath functionPath,
                  boolean ignoreIfNotExists)
           throws FunctionNotExistException,
                  CatalogException

Drop a function. Function name should be handled in a case insensitive way.

Parameters:

functionPath - path of the function to be dropped

ignoreIfNotExists - flag to specify behavior if the function does not exist: if set to false, throw an exception if set to true, nothing happens

Throws:

FunctionNotExistException - if the function does not exist

CatalogException - in case of any runtime exception

getTableStatistics

CatalogTableStatistics getTableStatistics(ObjectPath tablePath)
                                   throws TableNotExistException,
                                          CatalogException

Get the statistics of a table.

Parameters:

tablePath - path of the table

Returns:

statistics of the given table

Throws:

TableNotExistException - if the table does not exist in the catalog

CatalogException - in case of any runtime exception

getTableColumnStatistics

CatalogColumnStatistics getTableColumnStatistics(ObjectPath tablePath)
                                          throws TableNotExistException,
                                                 CatalogException

Get the column statistics of a table.

Parameters:

tablePath - path of the table

Returns:

column statistics of the given table

Throws:

TableNotExistException - if the table does not exist in the catalog

CatalogException - in case of any runtime exception

getPartitionStatistics

CatalogTableStatistics getPartitionStatistics(ObjectPath tablePath,
                                              CatalogPartitionSpec partitionSpec)
                                       throws PartitionNotExistException,
                                              CatalogException

Get the statistics of a partition.

Parameters:

tablePath - path of the table

partitionSpec - partition spec of the partition

Returns:

statistics of the given partition

Throws:

PartitionNotExistException - if the partition does not exist

CatalogException - in case of any runtime exception

bulkGetPartitionStatistics

default List<CatalogTableStatistics> bulkGetPartitionStatistics(ObjectPath tablePath,
                                                                List<CatalogPartitionSpec> partitionSpecs)
                                                         throws PartitionNotExistException,
                                                                CatalogException

Get a list of statistics of given partitions.

Parameters:

tablePath - path of the table

partitionSpecs - partition specs of partitions that will be used to filter out all other unrelated statistics, i.e. the statistics fetch will be limited within the given partitions

Returns:

list of statistics of given partitions

Throws:

PartitionNotExistException - if one partition does not exist

CatalogException - in case of any runtime exception

getPartitionColumnStatistics

CatalogColumnStatistics getPartitionColumnStatistics(ObjectPath tablePath,
                                                     CatalogPartitionSpec partitionSpec)
                                              throws PartitionNotExistException,
                                                     CatalogException

Get the column statistics of a partition.

Parameters:

tablePath - path of the table

partitionSpec - partition spec of the partition

Returns:

column statistics of the given partition

Throws:

PartitionNotExistException - if the partition does not exist

CatalogException - in case of any runtime exception

bulkGetPartitionColumnStatistics

default List<CatalogColumnStatistics> bulkGetPartitionColumnStatistics(ObjectPath tablePath,
                                                                       List<CatalogPartitionSpec> partitionSpecs)
                                                                throws PartitionNotExistException,
                                                                       CatalogException

Get a list of column statistics for given partitions.

Parameters:

tablePath - path of the table

partitionSpecs - partition specs of partitions that will be used to filter out all other unrelated statistics, i.e. the statistics fetch will be limited within the given partitions

Returns:

list of column statistics for given partitions

Throws:

PartitionNotExistException - if one partition does not exist

CatalogException - in case of any runtime exception

alterTableStatistics

void alterTableStatistics(ObjectPath tablePath,
                          CatalogTableStatistics tableStatistics,
                          boolean ignoreIfNotExists)
                   throws TableNotExistException,
                          CatalogException

Update the statistics of a table.

Parameters:

tablePath - path of the table

tableStatistics - new statistics to update

ignoreIfNotExists - flag to specify behavior if the table does not exist: if set to false, throw an exception, if set to true, nothing happens.

Throws:

TableNotExistException - if the table does not exist in the catalog

CatalogException - in case of any runtime exception

alterTableColumnStatistics

void alterTableColumnStatistics(ObjectPath tablePath,
                                CatalogColumnStatistics columnStatistics,
                                boolean ignoreIfNotExists)
                         throws TableNotExistException,
                                CatalogException,
                                TablePartitionedException

Update the column statistics of a table.

Parameters:

tablePath - path of the table

columnStatistics - new column statistics to update

ignoreIfNotExists - flag to specify behavior if the table does not exist: if set to false, throw an exception, if set to true, nothing happens.

Throws:

TableNotExistException - if the table does not exist in the catalog

CatalogException - in case of any runtime exception

TablePartitionedException

alterPartitionStatistics

void alterPartitionStatistics(ObjectPath tablePath,
                              CatalogPartitionSpec partitionSpec,
                              CatalogTableStatistics partitionStatistics,
                              boolean ignoreIfNotExists)
                       throws PartitionNotExistException,
                              CatalogException

Update the statistics of a table partition.

Parameters:

tablePath - path of the table

partitionSpec - partition spec of the partition

partitionStatistics - new statistics to update

ignoreIfNotExists - flag to specify behavior if the partition does not exist: if set to false, throw an exception, if set to true, nothing happens.

Throws:

PartitionNotExistException - if the partition does not exist

CatalogException - in case of any runtime exception

alterPartitionColumnStatistics

void alterPartitionColumnStatistics(ObjectPath tablePath,
                                    CatalogPartitionSpec partitionSpec,
                                    CatalogColumnStatistics columnStatistics,
                                    boolean ignoreIfNotExists)
                             throws PartitionNotExistException,
                                    CatalogException

Update the column statistics of a table partition.

Parameters:

tablePath - path of the table

partitionSpec - partition spec of the partition @@param columnStatistics new column statistics to update

ignoreIfNotExists - flag to specify behavior if the partition does not exist: if set to false, throw an exception, if set to true, nothing happens.

Throws:

PartitionNotExistException - if the partition does not exist

CatalogException - in case of any runtime exception

listModels

default List<String> listModels(String databaseName)
                         throws DatabaseNotExistException,
                                CatalogException

Get names of all models under this database. An empty list is returned if none exists.

Returns:

a list of the names of all models in this database

Throws:

DatabaseNotExistException - if the database does not exist

CatalogException - in case of any runtime exception

getModel

default CatalogModel getModel(ObjectPath modelPath)
                       throws ModelNotExistException,
                              CatalogException

Returns a CatalogModel identified by the given ObjectPath.

Parameters:

modelPath - Path of the model

Returns:

The requested model

Throws:

ModelNotExistException - if the target does not exist

CatalogException - in case of any runtime exception

modelExists

default boolean modelExists(ObjectPath modelPath)
                     throws CatalogException

Check if a model exists in this catalog.

Parameters:

modelPath - Path of the model

Returns:

true if the given model exists in the catalog false otherwise

Throws:

CatalogException - in case of any runtime exception

dropModel

default void dropModel(ObjectPath modelPath,
                       boolean ignoreIfNotExists)
                throws ModelNotExistException,
                       CatalogException

Drop a model.

Parameters:

modelPath - Path of the model to be dropped

ignoreIfNotExists - Flag to specify behavior when the model does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

ModelNotExistException - if the model does not exist

CatalogException - in case of any runtime exception

renameModel

default void renameModel(ObjectPath modelPath,
                         String newModelName,
                         boolean ignoreIfNotExists)
                  throws ModelNotExistException,
                         ModelAlreadyExistException,
                         CatalogException

Rename an existing model.

Parameters:

modelPath - Path of the model to be renamed

newModelName - the new name of the model

ignoreIfNotExists - Flag to specify behavior when the model does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

ModelNotExistException - if the model does not exist

CatalogException - in case of any runtime exception

ModelAlreadyExistException

createModel

default void createModel(ObjectPath modelPath,
                         CatalogModel model,
                         boolean ignoreIfExists)
                  throws ModelAlreadyExistException,
                         DatabaseNotExistException,
                         CatalogException

Creates a new model.

The framework will make sure to call this method with fully validated ResolvedCatalogModel. Those instances are easy to serialize for a durable catalog implementation.

Parameters:

modelPath - path of the model to be created

model - the CatalogModel definition

ignoreIfExists - flag to specify behavior when a model already exists at the given path: if set to false, it throws a ModelAlreadyExistException, if set to true, do nothing.

Throws:

ModelAlreadyExistException - if model already exists and ignoreIfExists is false

DatabaseNotExistException - if the database in tablePath doesn't exist

CatalogException - in case of any runtime exception

alterModel

default void alterModel(ObjectPath modelPath,
                        CatalogModel newModel,
                        boolean ignoreIfNotExists)
                 throws ModelNotExistException,
                        CatalogException

Modifies an existing model.

The framework will make sure to call this method with fully validated ResolvedCatalogModel. Those instances are easy to serialize for a durable catalog implementation.

Parameters:

modelPath - path of the model to be modified

newModel - the new model definition

ignoreIfNotExists - flag to specify behavior when the model does not exist: if set to false, throw an exception, if set to true, do nothing.

Throws:

ModelNotExistException - if the model does not exist

CatalogException - in case of any runtime exception