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, boolean cascade) Drop a namespace from the catalog with cascade mode, recursively dropping all objects within the namespace if cascade is true.
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,
                      boolean cascade)
               throws org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException,
                      org.apache.spark.sql.catalyst.analysis.NonEmptyNamespaceException

Drop a namespace from the catalog with cascade mode, recursively dropping all objects within the namespace if cascade is true.

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

Parameters:

namespace - a multi-part namespace

cascade - When true, deletes all objects under the namespace

Returns:

true if the namespace was dropped

Throws:

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

org.apache.spark.sql.catalyst.analysis.NonEmptyNamespaceException - If the namespace is non-empty and cascade is false

UnsupportedOperationException - If drop is not a supported operation