org.apache.spark.sql.connector.catalog

Interface SupportsNamespaces

All Superinterfaces:

CatalogPlugin

All Known Subinterfaces:

CatalogExtension

All Known Implementing Classes:

DelegatingCatalogExtension

@Evolving
public interface SupportsNamespaces
extends CatalogPlugin

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(String[]).

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.

Since:

3.0.0

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROP_COMMENT A reserved property to specify the description of the namespace.
static String	PROP_LOCATION A reserved property to specify the location of the namespace.
static String	PROP_OWNER A reserved property to specify the owner of the namespace.

Method Summary

Modifier and Type	Method and Description
void	alterNamespace(String[] namespace, NamespaceChange... changes) Apply a set of metadata changes to a namespace in the catalog.
void	createNamespace(String[] namespace, java.util.Map<String,String> metadata) Create a namespace in the catalog.
boolean	dropNamespace(String[] namespace) Drop a namespace from the catalog, recursively dropping all objects within the namespace.
String[][]	listNamespaces() List top-level namespaces from the catalog.
String[][]	listNamespaces(String[] namespace) List namespaces in a namespace.
java.util.Map<String,String>	loadNamespaceMetadata(String[] namespace) Load metadata properties for a namespace.
default boolean	namespaceExists(String[] namespace) Test whether a namespace exists.

Methods inherited from interface org.apache.spark.sql.connector.catalog.CatalogPlugin

defaultNamespace, initialize, name

Field Detail

PROP_LOCATION

static final String PROP_LOCATION

A reserved property to specify the location of the namespace. If the namespace needs to store files, it should be under this location.

See Also:

Constant Field Values

PROP_COMMENT

static final String PROP_COMMENT

A reserved property to specify the description of the namespace. The description will be returned in the result of "DESCRIBE NAMESPACE" command.

See Also:

Constant Field Values

PROP_OWNER

static final String PROP_OWNER

A reserved property to specify the owner of the namespace.

See Also:

Constant Field Values

Method Detail

listNamespaces

String[][] listNamespaces()
                   throws org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException

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:

an array of multi-part namespace names

Throws:

org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException

listNamespaces

String[][] listNamespaces(String[] namespace)
                   throws org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException

List namespaces in a namespace.

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 invoked as listNamespaces(["a"]) must return ["a", "b"] in the result array.

Parameters:

namespace - a multi-part namespace

Returns:

an array of multi-part namespace names

Throws:

org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException - If the namespace does not exist (optional)

namespaceExists

default boolean namespaceExists(String[] namespace)

Test whether a namespace exists.

If an object such as a table, view, or function exists, its parent namespaces must also exist. For example, if table a.b.t exists, this method invoked as namespaceExists(["a"]) or namespaceExists(["a", "b"]) must return true.

Parameters:

namespace - a multi-part namespace

Returns:

true if the namespace exists, false otherwise

loadNamespaceMetadata

java.util.Map<String,String> loadNamespaceMetadata(String[] namespace)
                                            throws org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException

Load metadata properties for a namespace.

Parameters:

namespace - a multi-part namespace

Returns:

a string map of properties for the given namespace

Throws:

org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException - If the namespace does not exist (optional)

UnsupportedOperationException - If namespace properties are not supported

createNamespace

void createNamespace(String[] namespace,
                     java.util.Map<String,String> metadata)
              throws org.apache.spark.sql.catalyst.analysis.NamespaceAlreadyExistsException

Create a namespace in the catalog.

Parameters:

namespace - a multi-part namespace

metadata - a string map of properties for the given namespace

Throws:

org.apache.spark.sql.catalyst.analysis.NamespaceAlreadyExistsException - If the namespace already exists

UnsupportedOperationException - If create is not a supported operation

alterNamespace

void alterNamespace(String[] namespace,
                    NamespaceChange... changes)
             throws org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException

Apply a set of metadata changes to a namespace in the catalog.

Parameters:

namespace - a multi-part namespace

changes - a collection of changes to apply to the namespace

Throws:

org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException - If the namespace does not exist (optional)

UnsupportedOperationException - If namespace properties are not supported

dropNamespace

boolean dropNamespace(String[] namespace)
               throws org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException

Drop a namespace from the catalog, recursively dropping all objects within the namespace.

If the catalog implementation does not support this operation, it may throw UnsupportedOperationException.

Parameters:

namespace - a multi-part namespace

Returns:

true if the namespace was dropped

Throws:

org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException - If the namespace does not exist (optional)

UnsupportedOperationException - If drop is not a supported operation