Package org.apache.gravitino

Interface SupportsCatalogs

All Known Implementing Classes:
GravitinoClient, GravitinoMetalake
@Evolving public interface SupportsCatalogs
Client interface for supporting catalogs. It includes methods for listing, loading, creating, altering and dropping catalogs.

  • Method Details

    • listCatalogs

      String[] listCatalogs() throws NoSuchMetalakeException
      List the name of all catalogs in the metalake.
      Returns:
      The list of catalog's names.
      Throws:
      NoSuchMetalakeException - If the metalake does not exist.

    • listCatalogsInfo

      Catalog[] listCatalogsInfo() throws NoSuchMetalakeException
      List all catalogs with their information in the metalake.
      Returns:
      The list of catalog's information.
      Throws:
      NoSuchMetalakeException - If the metalake with namespace does not exist.

    • loadCatalog

      Catalog loadCatalog(String catalogName) throws NoSuchCatalogException
      Load a catalog by its name.
      Parameters:
      catalogName - the name of the catalog.
      Returns:
      The catalog.
      Throws:
      NoSuchCatalogException - If the catalog does not exist.

    • catalogExists

      default boolean catalogExists(String catalogName)
      Check if a catalog exists.
      Parameters:
      catalogName - The name of the catalog.
      Returns:
      True if the catalog exists, false otherwise.

    • createCatalog

      Catalog createCatalog(String catalogName, Catalog.Type type, String provider, String comment, Map<String,String> properties) throws NoSuchMetalakeException, CatalogAlreadyExistsException
      Create a catalog with specified catalog name, type, provider, comment, and properties.

      The parameter "provider" is a short name of the catalog, used to tell Gravitino which catalog should be created. The short name:

      1) should be the same as the CatalogProvider interface provided. 2) can be "null" if the created catalog is the managed catalog, like model, fileset catalog. For the details of the provider definition, see CatalogProvider.

      Parameters:
      catalogName - the name of the catalog.
      type - the type of the catalog.
      provider - the provider of the catalog, or null if the catalog is a managed catalog.
      comment - the comment of the catalog.
      properties - the properties of the catalog.
      Returns:
      The created catalog.
      Throws:
      NoSuchMetalakeException - If the metalake does not exist.
      CatalogAlreadyExistsException - If the catalog already exists.

    • createCatalog

      default Catalog createCatalog(String catalogName, Catalog.Type type, String comment, Map<String,String> properties) throws NoSuchMetalakeException, CatalogAlreadyExistsException
      Create a managed catalog with specified catalog name, type, comment, and properties.
      Parameters:
      catalogName - the name of the catalog.
      type - the type of the catalog.
      comment - the comment of the catalog.
      properties - the properties of the catalog.
      Returns:
      The created catalog.
      Throws:
      NoSuchMetalakeException - If the metalake does not exist.
      CatalogAlreadyExistsException - If the catalog already exists.

    • alterCatalog

      Catalog alterCatalog(String catalogName, CatalogChange... changes) throws NoSuchCatalogException, IllegalArgumentException
      Alter a catalog with specified catalog name and changes.
      Parameters:
      catalogName - the name of the catalog.
      changes - the changes to apply to the catalog.
      Returns:
      The altered catalog.
      Throws:
      NoSuchCatalogException - If the catalog does not exist.
      IllegalArgumentException - If the changes cannot be applied to the catalog.

    • dropCatalog

      default boolean dropCatalog(String catalogName) throws NonEmptyEntityException, CatalogInUseException
      Drop a catalog with specified name. Please make sure: It is equivalent to calling dropCatalog(ident, false).
      Parameters:
      catalogName - the name of the catalog.
      Returns:
      True if the catalog was dropped, false if the catalog does not exist.
      Throws:
      NonEmptyEntityException - If the catalog is not empty.
      CatalogInUseException - If the catalog is in use.

    • dropCatalog

      boolean dropCatalog(String catalogName, boolean force) throws NonEmptyEntityException, CatalogInUseException
      Drop a catalog with specified name. If the force flag is true, it will:
      • Cascade drop all sub-entities (schemas, tables, etc.) of the catalog in Gravitino store.
      • Drop the catalog even if it is in use.
      • External resources (e.g. database, table, etc.) associated with sub-entities will not be dropped unless it is managed (such as managed fileset).
      If the force flag is false, it is equivalent to calling dropCatalog(String).
      Parameters:
      catalogName - The identifier of the catalog.
      force - Whether to force the drop.
      Returns:
      True if the catalog was dropped, false if the catalog does not exist.
      Throws:
      NonEmptyEntityException - If the catalog is not empty and force is false.
      CatalogInUseException - If the catalog is in use and force is false.

    • enableCatalog

      void enableCatalog(String catalogName) throws NoSuchCatalogException
      Enable a catalog. If the catalog is already enabled, this method does nothing.
      Parameters:
      catalogName - The identifier of the catalog.
      Throws:
      NoSuchCatalogException - If the catalog does not exist.

    • disableCatalog

      void disableCatalog(String catalogName) throws NoSuchCatalogException
      Disable a catalog. If the catalog is already disabled, this method does nothing. Once a catalog is disabled:
      Parameters:
      catalogName - The identifier of the catalog.
      Throws:
      NoSuchCatalogException - If the catalog does not exist.

    • testConnection

      void testConnection(String catalogName, Catalog.Type type, String provider, String comment, Map<String,String> properties) throws Exception
      Test whether the catalog with specified parameters can be connected to before creating it.
      Parameters:
      catalogName - the name of the catalog.
      type - the type of the catalog.
      provider - the provider of the catalog.
      comment - the comment of the catalog.
      properties - the properties of the catalog.
      Throws:
      Exception - if the test failed.