connector/catalog/SupportsNamespaces.java

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *    http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 package org.apache.spark.sql.connector.catalog;
0019
0020 import org.apache.spark.annotation.Evolving;
0021 import org.apache.spark.sql.catalyst.analysis.NamespaceAlreadyExistsException;
0022 import org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException;
0023
0024 import java.util.Map;
0025
0026 /**
0027  * Catalog methods for working with namespaces.
0028  * <p>
0029  * If an object such as a table, view, or function exists, its parent namespaces must also exist
0030  * and must be returned by the discovery methods {@link #listNamespaces()} and
0031  * {@link #listNamespaces(String[])}.
0032  * <p>
0033  * Catalog implementations are not required to maintain the existence of namespaces independent of
0034  * objects in a namespace. For example, a function catalog that loads functions using reflection
0035  * and uses Java packages as namespaces is not required to support the methods to create, alter, or
0036  * drop a namespace. Implementations are allowed to discover the existence of objects or namespaces
0037  * without throwing {@link NoSuchNamespaceException} when no namespace is found.
0038  *
0039  * @since 3.0.0
0040  */
0041 @Evolving
0042 public interface SupportsNamespaces extends CatalogPlugin {
0043
0044   /**
0045    * A reserved property to specify the location of the namespace. If the namespace
0046    * needs to store files, it should be under this location.
0047    */
0048   String PROP_LOCATION = "location";
0049
0050   /**
0051    * A reserved property to specify the description of the namespace. The description
0052    * will be returned in the result of "DESCRIBE NAMESPACE" command.
0053    */
0054   String PROP_COMMENT = "comment";
0055
0056   /**
0057    * A reserved property to specify the owner of the namespace.
0058    */
0059   String PROP_OWNER = "owner";
0060
0061   /**
0062    * List top-level namespaces from the catalog.
0063    * <p>
0064    * If an object such as a table, view, or function exists, its parent namespaces must also exist
0065    * and must be returned by this discovery method. For example, if table a.b.t exists, this method
0066    * must return ["a"] in the result array.
0067    *
0068    * @return an array of multi-part namespace names
0069    */
0070   String[][] listNamespaces() throws NoSuchNamespaceException;
0071
0072   /**
0073    * List namespaces in a namespace.
0074    * <p>
0075    * If an object such as a table, view, or function exists, its parent namespaces must also exist
0076    * and must be returned by this discovery method. For example, if table a.b.t exists, this method
0077    * invoked as listNamespaces(["a"]) must return ["a", "b"] in the result array.
0078    *
0079    * @param namespace a multi-part namespace
0080    * @return an array of multi-part namespace names
0081    * @throws NoSuchNamespaceException If the namespace does not exist (optional)
0082    */
0083   String[][] listNamespaces(String[] namespace) throws NoSuchNamespaceException;
0084
0085   /**
0086    * Test whether a namespace exists.
0087    * <p>
0088    * If an object such as a table, view, or function exists, its parent namespaces must also exist.
0089    * For example, if table a.b.t exists, this method invoked as namespaceExists(["a"]) or
0090    * namespaceExists(["a", "b"]) must return true.
0091    *
0092    * @param namespace a multi-part namespace
0093    * @return true if the namespace exists, false otherwise
0094    */
0095   default boolean namespaceExists(String[] namespace) {
0096     try {
0097       loadNamespaceMetadata(namespace);
0098       return true;
0099     } catch (NoSuchNamespaceException e) {
0100       return false;
0101     }
0102   }
0103
0104   /**
0105    * Load metadata properties for a namespace.
0106    *
0107    * @param namespace a multi-part namespace
0108    * @return a string map of properties for the given namespace
0109    * @throws NoSuchNamespaceException If the namespace does not exist (optional)
0110    * @throws UnsupportedOperationException If namespace properties are not supported
0111    */
0112   Map<String, String> loadNamespaceMetadata(String[] namespace) throws NoSuchNamespaceException;
0113
0114   /**
0115    * Create a namespace in the catalog.
0116    *
0117    * @param namespace a multi-part namespace
0118    * @param metadata a string map of properties for the given namespace
0119    * @throws NamespaceAlreadyExistsException If the namespace already exists
0120    * @throws UnsupportedOperationException If create is not a supported operation
0121    */
0122   void createNamespace(
0123       String[] namespace,
0124       Map<String, String> metadata) throws NamespaceAlreadyExistsException;
0125
0126   /**
0127    * Apply a set of metadata changes to a namespace in the catalog.
0128    *
0129    * @param namespace a multi-part namespace
0130    * @param changes a collection of changes to apply to the namespace
0131    * @throws NoSuchNamespaceException If the namespace does not exist (optional)
0132    * @throws UnsupportedOperationException If namespace properties are not supported
0133    */
0134   void alterNamespace(
0135       String[] namespace,
0136       NamespaceChange... changes) throws NoSuchNamespaceException;
0137
0138   /**
0139    * Drop a namespace from the catalog, recursively dropping all objects within the namespace.
0140    * <p>
0141    * If the catalog implementation does not support this operation, it may throw
0142    * {@link UnsupportedOperationException}.
0143    *
0144    * @param namespace a multi-part namespace
0145    * @return true if the namespace was dropped
0146    * @throws NoSuchNamespaceException If the namespace does not exist (optional)
0147    * @throws UnsupportedOperationException If drop is not a supported operation
0148    */
0149   boolean dropNamespace(String[] namespace) throws NoSuchNamespaceException;
0150 }