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 Summary

Modifier and Type	Method and Description
default void	createNamespace(Namespace namespace) Create a namespace in the catalog.
void	createNamespace(Namespace namespace, java.util.Map<java.lang.String,java.lang.String> metadata) Create a namespace in the catalog.
boolean	dropNamespace(Namespace namespace) Drop a namespace.
default java.util.List<Namespace>	listNamespaces() List top-level namespaces from the catalog.
java.util.List<Namespace>	listNamespaces(Namespace namespace) List child namespaces from the namespace.
java.util.Map<java.lang.String,java.lang.String>	loadNamespaceMetadata(Namespace namespace) Load metadata properties for a namespace.
default boolean	namespaceExists(Namespace namespace) Checks whether the Namespace exists.
boolean	removeProperties(Namespace namespace, java.util.Set<java.lang.String> properties) Remove a set of property keys from a namespace in the catalog.
boolean	setProperties(Namespace namespace, java.util.Map<java.lang.String,java.lang.String> properties) Set a collection of properties on a namespace in the catalog.

Method Detail

createNamespace

default void createNamespace(Namespace namespace)

Create a namespace in the catalog.

Parameters:

namespace - a namespace. Namespace.

Throws:

AlreadyExistsException - If the namespace already exists

java.lang.UnsupportedOperationException - If create is not a supported operation

createNamespace

void createNamespace(Namespace namespace,
                     java.util.Map<java.lang.String,java.lang.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

java.lang.UnsupportedOperationException - If create is not a supported operation

listNamespaces

default java.util.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

java.util.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

java.util.Map<java.lang.String,java.lang.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,
                      java.util.Map<java.lang.String,java.lang.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)

java.lang.UnsupportedOperationException - If namespace properties are not supported

removeProperties

boolean removeProperties(Namespace namespace,
                         java.util.Set<java.lang.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)

java.lang.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