connector/catalog/TableCatalog.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.connector.expressions.Transform;
0022 import org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException;
0023 import org.apache.spark.sql.catalyst.analysis.NoSuchTableException;
0024 import org.apache.spark.sql.catalyst.analysis.TableAlreadyExistsException;
0025 import org.apache.spark.sql.types.StructType;
0026
0027 import java.util.Map;
0028
0029 /**
0030  * Catalog methods for working with Tables.
0031  * <p>
0032  * TableCatalog implementations may be case sensitive or case insensitive. Spark will pass
0033  * {@link Identifier table identifiers} without modification. Field names passed to
0034  * {@link #alterTable(Identifier, TableChange...)} will be normalized to match the case used in the
0035  * table schema when updating, renaming, or dropping existing columns when catalyst analysis is case
0036  * insensitive.
0037  *
0038  * @since 3.0.0
0039  */
0040 @Evolving
0041 public interface TableCatalog extends CatalogPlugin {
0042
0043   /**
0044    * A reserved property to specify the location of the table. The files of the table
0045    * should be under this location.
0046    */
0047   String PROP_LOCATION = "location";
0048
0049   /**
0050    * A reserved property to specify the description of the table.
0051    */
0052   String PROP_COMMENT = "comment";
0053
0054   /**
0055    * A reserved property to specify the provider of the table.
0056    */
0057   String PROP_PROVIDER = "provider";
0058
0059   /**
0060    * A reserved property to specify the owner of the table.
0061    */
0062   String PROP_OWNER = "owner";
0063
0064   /**
0065    * List the tables in a namespace from the catalog.
0066    * <p>
0067    * If the catalog supports views, this must return identifiers for only tables and not views.
0068    *
0069    * @param namespace a multi-part namespace
0070    * @return an array of Identifiers for tables
0071    * @throws NoSuchNamespaceException If the namespace does not exist (optional).
0072    */
0073   Identifier[] listTables(String[] namespace) throws NoSuchNamespaceException;
0074
0075   /**
0076    * Load table metadata by {@link Identifier identifier} from the catalog.
0077    * <p>
0078    * If the catalog supports views and contains a view for the identifier and not a table, this
0079    * must throw {@link NoSuchTableException}.
0080    *
0081    * @param ident a table identifier
0082    * @return the table's metadata
0083    * @throws NoSuchTableException If the table doesn't exist or is a view
0084    */
0085   Table loadTable(Identifier ident) throws NoSuchTableException;
0086
0087   /**
0088    * Invalidate cached table metadata for an {@link Identifier identifier}.
0089    * <p>
0090    * If the table is already loaded or cached, drop cached data. If the table does not exist or is
0091    * not cached, do nothing. Calling this method should not query remote services.
0092    *
0093    * @param ident a table identifier
0094    */
0095   default void invalidateTable(Identifier ident) {
0096   }
0097
0098   /**
0099    * Test whether a table exists using an {@link Identifier identifier} from the catalog.
0100    * <p>
0101    * If the catalog supports views and contains a view for the identifier and not a table, this
0102    * must return false.
0103    *
0104    * @param ident a table identifier
0105    * @return true if the table exists, false otherwise
0106    */
0107   default boolean tableExists(Identifier ident) {
0108     try {
0109       return loadTable(ident) != null;
0110     } catch (NoSuchTableException e) {
0111       return false;
0112     }
0113   }
0114
0115   /**
0116    * Create a table in the catalog.
0117    *
0118    * @param ident a table identifier
0119    * @param schema the schema of the new table, as a struct type
0120    * @param partitions transforms to use for partitioning data in the table
0121    * @param properties a string map of table properties
0122    * @return metadata for the new table
0123    * @throws TableAlreadyExistsException If a table or view already exists for the identifier
0124    * @throws UnsupportedOperationException If a requested partition transform is not supported
0125    * @throws NoSuchNamespaceException If the identifier namespace does not exist (optional)
0126    */
0127   Table createTable(
0128       Identifier ident,
0129       StructType schema,
0130       Transform[] partitions,
0131       Map<String, String> properties) throws TableAlreadyExistsException, NoSuchNamespaceException;
0132
0133   /**
0134    * Apply a set of {@link TableChange changes} to a table in the catalog.
0135    * <p>
0136    * Implementations may reject the requested changes. If any change is rejected, none of the
0137    * changes should be applied to the table.
0138    * <p>
0139    * The requested changes must be applied in the order given.
0140    * <p>
0141    * If the catalog supports views and contains a view for the identifier and not a table, this
0142    * must throw {@link NoSuchTableException}.
0143    *
0144    * @param ident a table identifier
0145    * @param changes changes to apply to the table
0146    * @return updated metadata for the table
0147    * @throws NoSuchTableException If the table doesn't exist or is a view
0148    * @throws IllegalArgumentException If any change is rejected by the implementation.
0149    */
0150   Table alterTable(
0151       Identifier ident,
0152       TableChange... changes) throws NoSuchTableException;
0153
0154   /**
0155    * Drop a table in the catalog.
0156    * <p>
0157    * If the catalog supports views and contains a view for the identifier and not a table, this
0158    * must not drop the view and must return false.
0159    *
0160    * @param ident a table identifier
0161    * @return true if a table was deleted, false if no table exists for the identifier
0162    */
0163   boolean dropTable(Identifier ident);
0164
0165   /**
0166    * Renames a table in the catalog.
0167    * <p>
0168    * If the catalog supports views and contains a view for the old identifier and not a table, this
0169    * throws {@link NoSuchTableException}. Additionally, if the new identifier is a table or a view,
0170    * this throws {@link TableAlreadyExistsException}.
0171    * <p>
0172    * If the catalog does not support table renames between namespaces, it throws
0173    * {@link UnsupportedOperationException}.
0174    *
0175    * @param oldIdent the table identifier of the existing table to rename
0176    * @param newIdent the new table identifier of the table
0177    * @throws NoSuchTableException If the table to rename doesn't exist or is a view
0178    * @throws TableAlreadyExistsException If the new table name already exists or is a view
0179    * @throws UnsupportedOperationException If the namespaces of old and new identiers do not
0180    *                                       match (optional)
0181    */
0182   void renameTable(Identifier oldIdent, Identifier newIdent)
0183       throws NoSuchTableException, TableAlreadyExistsException;
0184 }