Package 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 Details

    • 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:

    • 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:

    • PROP_COLLATION

      static final String PROP_COLLATION
      A reserved property to specify the collation of the namespace. The collation will be returned in the result of "DESCRIBE NAMESPACE" command.
      See Also:

    • PROP_OWNER

      static final String PROP_OWNER
      A reserved property to specify the owner of the namespace.
      See Also:

  • Method Details

    • 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

      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, 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