org.apache.flink.table.catalog

Interface Catalog

All Known Implementing Classes:

AbstractCatalog

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

Method Summary

Modifier and Type	Method and 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.
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) Modify 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.
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.
void	createPartition(ObjectPath tablePath, CatalogPartitionSpec partitionSpec, CatalogPartition partition, boolean ignoreIfExists) Create a partition.
void	createTable(ObjectPath tablePath, CatalogBaseTable table, boolean ignoreIfExists) Create a new table or view.
boolean	databaseExists(String databaseName) Check if a database exists in this catalog.
void	dropDatabase(String name, boolean ignoreIfNotExists) Drop a database.
void	dropFunction(ObjectPath functionPath, boolean ignoreIfNotExists) Drop a function.
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.
CatalogFunction	getFunction(ObjectPath functionPath) Get the function.
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.
CatalogBaseTable	getTable(ObjectPath tablePath) Get a CatalogTable or CatalogView identified by tablePath.
CatalogColumnStatistics	getTableColumnStatistics(ObjectPath tablePath) Get the column statistics of a table.
default Optional<TableFactory>	getTableFactory() Get an optional TableFactory instance that's responsible for generating table-related instances stored in this catalog, instances such as source/sink and function definitions.
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.
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<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.
void	open() Open the catalog.
boolean	partitionExists(ObjectPath tablePath, CatalogPartitionSpec partitionSpec) Check whether a partition exists or not.
void	renameTable(ObjectPath tablePath, String newTableName, boolean ignoreIfNotExists) Rename an existing table or view.
boolean	tableExists(ObjectPath tablePath) Check if a table or view exists in this catalog.

Method Detail

getTableFactory

default Optional<TableFactory> getTableFactory()

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

Returns:

an optional TableFactory 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

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.

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

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

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

Get a CatalogTable or CatalogView identified by tablePath.

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

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

Create a new table or view.

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

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

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

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,
                                          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

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 table with the given name already exists: if set to false, it throws a TableAlreadyExistException, 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 database 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 database 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

getFunction

CatalogFunction getFunction(ObjectPath functionPath)
                     throws FunctionNotExistException,
                            CatalogException

Get the function.

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

functionExists

boolean functionExists(ObjectPath functionPath)
                throws CatalogException

Check whether a function exists or not.

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.

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.

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.

Parameters:

functionPath - path of the function to be dropped

ignoreIfNotExists - plag 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

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

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

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