Package org.apache.iceberg.catalog

Interface SupportsNamespaces

All Known Implementing Classes:
BaseSessionCatalog.AsCatalog, DynamoDbCatalog, EcsCatalog, GlueCatalog, HadoopCatalog, HiveCatalog, InMemoryCatalog, JdbcCatalog, NessieCatalog, RESTCatalog, SnowflakeCatalog
public interface SupportsNamespaces
Catalog methods for working with namespaces.

If an object such as a table, view, or function exists, its parent namespaces must also exist and must be returned by the discovery methods listNamespaces() and listNamespaces(Namespace namespace).

Catalog implementations are not required to maintain the existence of namespaces independent of objects in a namespace. For example, a function catalog that loads functions using reflection and uses Java packages as namespaces is not required to support the methods to create, alter, or drop a namespace. Implementations are allowed to discover the existence of objects or namespaces without throwing NoSuchNamespaceException when no namespace is found.

  • Method Details

    • createNamespace

      default void createNamespace(Namespace namespace)
      Create a namespace in the catalog.
      Parameters:
      namespace - a namespace. Namespace.
      Throws:
      AlreadyExistsException - If the namespace already exists
      UnsupportedOperationException - If create is not a supported operation

    • createNamespace

      void createNamespace(Namespace namespace, Map<String,String> metadata)
      Create a namespace in the catalog.
      Parameters:
      namespace - a multi-part namespace
      metadata - a string Map of properties for the given namespace
      Throws:
      AlreadyExistsException - If the namespace already exists
      UnsupportedOperationException - If create is not a supported operation

    • listNamespaces

      default List<Namespace> listNamespaces()
      List top-level namespaces from the catalog.

      If an object such as a table, view, or function exists, its parent namespaces must also exist and must be returned by this discovery method. For example, if table a.b.t exists, this method must return ["a"] in the result array.

      Returns:
      a List of namespace Namespace names

    • listNamespaces

      List<Namespace> listNamespaces(Namespace namespace) throws NoSuchNamespaceException
      List child namespaces from the namespace.

      For two existing tables named 'a.b.c.table' and 'a.b.d.table', this method returns:

      • Given: Namespace.empty()
      • Returns: Namespace.of("a")
      • Given: Namespace.of("a")
      • Returns: Namespace.of("a", "b")
      • Given: Namespace.of("a", "b")
      • Returns: Namespace.of("a", "b", "c") and Namespace.of("a", "b", "d")
      • Given: Namespace.of("a", "b", "c")
      • Returns: empty list, because there are no child namespaces
      Returns:
      a List of child Namespace names from the given namespace
      Throws:
      NoSuchNamespaceException - If the namespace does not exist (optional)

    • loadNamespaceMetadata

      Map<String,String> loadNamespaceMetadata(Namespace namespace) throws NoSuchNamespaceException
      Load metadata properties for a namespace.
      Parameters:
      namespace - a namespace. Namespace
      Returns:
      a string map of properties for the given namespace
      Throws:
      NoSuchNamespaceException - If the namespace does not exist (optional)

    • dropNamespace

      boolean dropNamespace(Namespace namespace) throws NamespaceNotEmptyException
      Drop a namespace. If the namespace exists and was dropped, this will return true.
      Parameters:
      namespace - a namespace. Namespace
      Returns:
      true if the namespace was dropped, false otherwise.
      Throws:
      NamespaceNotEmptyException - If the namespace is not empty

    • setProperties

      boolean setProperties(Namespace namespace, Map<String,String> properties) throws NoSuchNamespaceException
      Set a collection of properties on a namespace in the catalog.

      Properties that are not in the given map are not modified or removed by this method.

      Parameters:
      namespace - a namespace. Namespace
      properties - a collection of metadata to apply to the namespace
      Throws:
      NoSuchNamespaceException - If the namespace does not exist (optional)
      UnsupportedOperationException - If namespace properties are not supported

    • removeProperties

      boolean removeProperties(Namespace namespace, Set<String> properties) throws NoSuchNamespaceException
      Remove a set of property keys from a namespace in the catalog.

      Properties that are not in the given set are not modified or removed by this method.

      Parameters:
      namespace - a namespace. Namespace
      properties - a collection of metadata to apply to the namespace
      Throws:
      NoSuchNamespaceException - If the namespace does not exist (optional)
      UnsupportedOperationException - If namespace properties are not supported

    • namespaceExists

      default boolean namespaceExists(Namespace namespace)
      Checks whether the Namespace exists.
      Parameters:
      namespace - a namespace. Namespace
      Returns:
      true if the Namespace exists, false otherwise