Package org.apache.flink.table.catalog

Class CatalogManager

    • Method Detail

      • close

        public void close()
           throws CatalogException
        Closes the catalog manager and releases its resources.

        This method closes all initialized catalogs and the catalog store.

        Specified by:
        close in interface AutoCloseable
        Throws:
        CatalogException - if an error occurs while closing the catalogs or the catalog store

      • getDataTypeFactory

        public DataTypeFactory getDataTypeFactory()
        Returns a factory for creating fully resolved data types that can be used for planning.

      • createCatalog

        public void createCatalog​(String catalogName,
                          CatalogDescriptor catalogDescriptor,
                          boolean ignoreIfExists)
                   throws CatalogException
        Creates a catalog under the given name. The catalog name must be unique.
        Parameters:
        catalogName - the given catalog name under which to create the given catalog
        catalogDescriptor - catalog descriptor for creating catalog
        ignoreIfExists - if false exception will be thrown if a catalog exists.
        Throws:
        CatalogException - If the catalog already exists in the catalog store or initialized catalogs, or if an error occurs while creating the catalog or storing the CatalogDescriptor

      • alterCatalog

        public void alterCatalog​(String catalogName,
                         CatalogChange catalogChange)
                  throws CatalogException
        Alters a catalog under the given name. The catalog name must be unique.
        Parameters:
        catalogName - the given catalog name under which to alter the given catalog
        catalogChange - catalog change to update the underlying catalog descriptor
        Throws:
        CatalogException - If the catalog neither exists in the catalog store nor in the initialized catalogs, or if an error occurs while creating the catalog or storing the CatalogDescriptor

      • registerCatalog

        @Deprecated
public void registerCatalog​(String catalogName,
                            Catalog catalog)
        Deprecated.
        This method is deprecated and will be removed in a future release. Use createCatalog instead to create a catalog using CatalogDescriptor and store it in the CatalogStore.
        Registers a catalog under the given name. The catalog name must be unique.
        Parameters:
        catalogName - name under which to register the given catalog
        catalog - catalog to register
        Throws:
        CatalogException - if the registration of the catalog under the given name failed

      • unregisterCatalog

        public void unregisterCatalog​(String catalogName,
                              boolean ignoreIfNotExists)
        Unregisters a catalog under the given name. The catalog name must be existed.

        If the catalog is in the initialized catalogs, it will be removed from the initialized catalogs. If the catalog is stored in the CatalogStore, it will be removed from the CatalogStore.

        Parameters:
        catalogName - name under which to unregister the given catalog.
        ignoreIfNotExists - If false exception will be thrown if the table or database or catalog to be altered does not exist.
        Throws:
        CatalogException - If the catalog does not exist in the initialized catalogs and not in the CatalogStore, or if the remove operation failed.

      • getCatalog

        public Optional<Catalog> getCatalog​(String catalogName)
        Gets a Catalog instance by name.

        If the catalog has already been initialized, the initialized instance will be returned directly. Otherwise, the CatalogDescriptor will be obtained from the CatalogStore, and the catalog instance will be initialized.

        Parameters:
        catalogName - name of the catalog to retrieve
        Returns:
        the requested catalog or empty if it does not exist

      • getCatalogOrThrowException

        public Catalog getCatalogOrThrowException​(String catalogName)

      • setCurrentDatabase

        public void setCurrentDatabase​(@Nullable
                               String databaseName)
        Sets the current database name that will be used when resolving a table path. The database has to exist in the current catalog.
        Parameters:
        databaseName - database name to set as current database name
        Throws:
        CatalogException - thrown if the database doesn't exist in the current catalog
        See Also:
        qualifyIdentifier(UnresolvedIdentifier), setCurrentCatalog(String)

      • getBuiltInCatalogName

        public String getBuiltInCatalogName()
        Gets the built-in catalog name. The built-in catalog is used for storing all non-serializable transient meta-objects.
        Returns:
        the built-in catalog name

      • getBuiltInDatabaseName

        public String getBuiltInDatabaseName()
        Gets the built-in database name in the built-in catalog. The built-in database is used for storing all non-serializable transient meta-objects.
        Returns:
        the built-in database name

      • getTable

        public Optional<ContextResolvedTable> getTable​(ObjectIdentifier objectIdentifier,
                                               long timestamp)
        Retrieves a fully qualified table with a specific time. If the path is not yet fully qualified, use qualifyIdentifier(UnresolvedIdentifier) first.
        Parameters:
        objectIdentifier - full path of the table to retrieve
        timestamp - Timestamp of the table snapshot, which is milliseconds since 1970-01-01 00:00:00 UTC
        Returns:
        table at a specific time that the path points to.

      • isTemporaryTable

        public boolean isTemporaryTable​(ObjectIdentifier objectIdentifier)
        Return whether the table with a fully qualified table path is temporary or not.
        Specified by:
        isTemporaryTable in interface CatalogRegistry
        Parameters:
        objectIdentifier - full path of the table
        Returns:
        the table is temporary or not.

      • listCatalogs

        public Set<String> listCatalogs()
        Retrieves the set of names of all registered catalogs, including all initialized catalogs and all catalogs stored in the CatalogStore.
        Returns:
        a set of names of registered catalogs

      • listTables

        public Set<String> listTables()
        Returns an array of names of all tables (tables and views, both temporary and permanent) registered in the namespace of the current catalog and database.
        Returns:
        names of all registered tables

      • listTables

        public Set<String> listTables​(String catalogName,
                              String databaseName)
        Returns an array of names of all tables (tables and views, both temporary and permanent) registered in the namespace of the given catalog and database.
        Returns:
        names of all registered tables

      • listTemporaryTables

        public Set<String> listTemporaryTables()
        Returns an array of names of temporary tables registered in the namespace of the current catalog and database.
        Returns:
        names of registered temporary tables

      • listTemporaryViews

        public Set<String> listTemporaryViews()
        Returns an array of names of temporary views registered in the namespace of the current catalog and database.
        Returns:
        names of registered temporary views

      • listViews

        public Set<String> listViews()
        Returns an array of names of all views(both temporary and permanent) registered in the namespace of the current catalog and database.
        Returns:
        names of all registered views

      • listViews

        public Set<String> listViews​(String catalogName,
                             String databaseName)
        Returns an array of names of all views(both temporary and permanent) registered in the namespace of the given catalog and database.
        Returns:
        names of registered views

      • listSchemas

        public Set<String> listSchemas()
        Lists all available schemas in the root of the catalog manager. It is not equivalent to listing all catalogs as it includes also different catalog parts of the temporary objects.

        NOTE:It is primarily used for interacting with Calcite's schema.

        Returns:
        set of schemas in the root of catalog manager

      • listSchemas

        public Set<String> listSchemas​(String catalogName)
        Lists all available schemas in the given catalog. It is not equivalent to listing databases within the given catalog as it includes also different database parts of the temporary objects identifiers.

        NOTE:It is primarily used for interacting with Calcite's schema.

        Parameters:
        catalogName - filter for the catalog part of the schema
        Returns:
        set of schemas with the given prefix

      • schemaExists

        public boolean schemaExists​(String catalogName)
        Checks if there is a catalog with given name or is there a temporary object registered within a given catalog.

        NOTE:It is primarily used for interacting with Calcite's schema.

        Parameters:
        catalogName - filter for the catalog part of the schema
        Returns:
        true if a subschema exists

      • schemaExists

        public boolean schemaExists​(String catalogName,
                            String databaseName)
        Checks if there is a database with given name in a given catalog or is there a temporary object registered within a given catalog and database.

        NOTE:It is primarily used for interacting with Calcite's schema.

        Parameters:
        catalogName - filter for the catalog part of the schema
        databaseName - filter for the database part of the schema
        Returns:
        true if a subschema exists

      • qualifyIdentifier

        public ObjectIdentifier qualifyIdentifier​(UnresolvedIdentifier identifier)
        Returns the full name of the given table path, this name may be padded with current catalog/database name based on the identifier's length.
        Specified by:
        qualifyIdentifier in interface CatalogRegistry
        Parameters:
        identifier - an unresolved identifier
        Returns:
        a fully qualified object identifier

      • createTable

        public void createTable​(CatalogBaseTable table,
                        ObjectIdentifier objectIdentifier,
                        boolean ignoreIfExists)
        Creates a table in a given fully qualified path.
        Parameters:
        table - The table to put in the given path.
        objectIdentifier - The fully qualified path where to put the table.
        ignoreIfExists - If false exception will be thrown if a table exists in the given path.

      • createTemporaryTable

        public void createTemporaryTable​(CatalogBaseTable table,
                                 ObjectIdentifier objectIdentifier,
                                 boolean ignoreIfExists)
        Creates a temporary table in a given fully qualified path.
        Parameters:
        table - The table to put in the given path.
        objectIdentifier - The fully qualified path where to put the table.
        ignoreIfExists - if false exception will be thrown if a table exists in the given path.

      • resolveCompactManagedTableOptions

        public Map<String,​String> resolveCompactManagedTableOptions​(ResolvedCatalogTable origin,
                                                                  ObjectIdentifier tableIdentifier,
                                                                  CatalogPartitionSpec partitionSpec)
        Resolve dynamic options for compact operation on a Flink's managed table.
        Parameters:
        origin - The resolved managed table with enriched options.
        tableIdentifier - The fully qualified path of the managed table.
        partitionSpec - User-specified unresolved partition spec.
        Returns:
        dynamic options which describe the metadata of compaction

      • dropTemporaryTable

        public void dropTemporaryTable​(ObjectIdentifier objectIdentifier,
                               boolean ignoreIfNotExists)
        Drop a temporary table in a given fully qualified path.
        Parameters:
        objectIdentifier - The fully qualified path of the table to drop.
        ignoreIfNotExists - If false exception will be thrown if the table to be dropped does not exist.

      • dropTemporaryView

        public void dropTemporaryView​(ObjectIdentifier objectIdentifier,
                              boolean ignoreIfNotExists)
        Drop a temporary view in a given fully qualified path.
        Parameters:
        objectIdentifier - The fully qualified path of the view to drop.
        ignoreIfNotExists - If false exception will be thrown if the view to be dropped does not exist.

      • alterTable

        public void alterTable​(CatalogBaseTable table,
                       ObjectIdentifier objectIdentifier,
                       boolean ignoreIfNotExists)
        Alters a table in a given fully qualified path.
        Parameters:
        table - The table to put in the given path
        objectIdentifier - The fully qualified path where to alter the table.
        ignoreIfNotExists - If false exception will be thrown if the table or database or catalog to be altered does not exist.

      • alterTable

        public void alterTable​(CatalogBaseTable table,
                       List<TableChange> changes,
                       ObjectIdentifier objectIdentifier,
                       boolean ignoreIfNotExists)
        Alters a table in a given fully qualified path with table changes.
        Parameters:
        table - The table to put in the given path
        changes - The table changes from the original table to the new table.
        objectIdentifier - The fully qualified path where to alter the table.
        ignoreIfNotExists - If false exception will be thrown if the table or database or catalog to be altered does not exist.

      • dropTable

        public void dropTable​(ObjectIdentifier objectIdentifier,
                      boolean ignoreIfNotExists)
        Drops a table in a given fully qualified path.
        Parameters:
        objectIdentifier - The fully qualified path of the table to drop.
        ignoreIfNotExists - If false exception will be thrown if the table to drop does not exist.

      • dropMaterializedTable

        public void dropMaterializedTable​(ObjectIdentifier objectIdentifier,
                                  boolean ignoreIfNotExists)
        Drops a materialized table in a given fully qualified path.
        Parameters:
        objectIdentifier - The fully qualified path of the materialized table to drop.
        ignoreIfNotExists - If false exception will be thrown if the table to drop does not exist.

      • dropView

        public void dropView​(ObjectIdentifier objectIdentifier,
                     boolean ignoreIfNotExists)
        Drops a view in a given fully qualified path.
        Parameters:
        objectIdentifier - The fully qualified path of the view to drop.
        ignoreIfNotExists - If false exception will be thrown if the view to drop does not exist.

      • isTemporaryModel

        public boolean isTemporaryModel​(ObjectIdentifier objectIdentifier)
        Return whether the model with a fully qualified table path is temporary or not.
        Parameters:
        objectIdentifier - full path of the table
        Returns:
        the model is temporary or not.

      • listModels

        public Set<String> listModels()
        Returns an array of names of all models registered in the namespace of the current catalog and database.
        Returns:
        names of all registered models

      • listModels

        public Set<String> listModels​(String catalogName,
                              String databaseName)
        Returns an array of names of all models registered in the namespace of the given catalog and database.
        Returns:
        names of all registered models

      • createModel

        public void createModel​(CatalogModel model,
                        ObjectIdentifier objectIdentifier,
                        boolean ignoreIfExists)
        Creates a model in a given fully qualified path.
        Parameters:
        model - The resolved model to put in the given path.
        objectIdentifier - The fully qualified path where to put the model.
        ignoreIfExists - If false exception will be thrown if a model exists in the given path.

      • createTemporaryModel

        public void createTemporaryModel​(CatalogModel model,
                                 ObjectIdentifier objectIdentifier,
                                 boolean ignoreIfExists)
        Creates a temporary model in a given fully qualified path.
        Parameters:
        model - The resolved model to put in the given path.
        objectIdentifier - The fully qualified path where to put the model.
        ignoreIfExists - if false exception will be thrown if a model exists in the given path.

      • alterModel

        public void alterModel​(CatalogModel modelChange,
                       ObjectIdentifier objectIdentifier,
                       boolean ignoreIfNotExists)
        Alters a model in a given fully qualified path.
        Parameters:
        modelChange - The model containing only changes
        objectIdentifier - The fully qualified path where to alter the model.
        ignoreIfNotExists - If false exception will be thrown if the model to be altered does not exist.

      • dropModel

        public void dropModel​(ObjectIdentifier objectIdentifier,
                      boolean ignoreIfNotExists)
        Drops a model in a given fully qualified path.
        Parameters:
        objectIdentifier - The fully qualified path of the model to drop.
        ignoreIfNotExists - If false exception will be thrown if the model to drop does not exist.

      • dropTemporaryModel

        public void dropTemporaryModel​(ObjectIdentifier objectIdentifier,
                               boolean ignoreIfNotExists)
        Drop a temporary model in a given fully qualified path.
        Parameters:
        objectIdentifier - The fully qualified path of the model to drop.
        ignoreIfNotExists - If false exception will be thrown if the model to be dropped does not exist.

      • createDatabase

        public void createDatabase​(String catalogName,
                           String databaseName,
                           CatalogDatabase database,
                           boolean ignoreIfExists)
                    throws DatabaseAlreadyExistException,
                           CatalogException
        Create a database.
        Parameters:
        catalogName - Name of the catalog for database
        databaseName - 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

        public void dropDatabase​(String catalogName,
                         String databaseName,
                         boolean ignoreIfNotExists,
                         boolean cascade)
                  throws DatabaseNotExistException,
                         DatabaseNotEmptyException,
                         CatalogException
        Drop a database.
        Parameters:
        catalogName - Name of the catalog for database.
        databaseName - 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

        public void alterDatabase​(String catalogName,
                          String databaseName,
                          CatalogDatabase newDatabase,
                          boolean ignoreIfNotExists)
                   throws DatabaseNotExistException,
                          CatalogException
        Modify an existing database.
        Parameters:
        catalogName - Name of the catalog for database
        databaseName - Name of the database to be dropped
        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