http://git-wip-us.apache.org/repos/asf/hive/blob/ba8a99e1/standalone-metastore/src/main/java/org/apache/hadoop/hive/metastore/IMetaStoreClient.java ---------------------------------------------------------------------- diff --git a/standalone-metastore/src/main/java/org/apache/hadoop/hive/metastore/IMetaStoreClient.java b/standalone-metastore/src/main/java/org/apache/hadoop/hive/metastore/IMetaStoreClient.java index c69192b..2e146f3 100644 --- a/standalone-metastore/src/main/java/org/apache/hadoop/hive/metastore/IMetaStoreClient.java +++ b/standalone-metastore/src/main/java/org/apache/hadoop/hive/metastore/IMetaStoreClient.java @@ -27,6 +27,7 @@ import java.util.Map.Entry; import org.apache.hadoop.classification.InterfaceAudience; import org.apache.hadoop.classification.InterfaceStability; +import org.apache.hadoop.conf.Configurable; import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.hive.common.ValidTxnList; import org.apache.hadoop.hive.common.ValidTxnWriteIdList; @@ -37,6 +38,7 @@ import org.apache.hadoop.hive.metastore.api.AggrStats; import org.apache.hadoop.hive.metastore.api.AlreadyExistsException; import org.apache.hadoop.hive.metastore.api.BasicTxnInfo; import org.apache.hadoop.hive.metastore.api.CheckConstraintsRequest; +import org.apache.hadoop.hive.metastore.api.Catalog; import org.apache.hadoop.hive.metastore.api.CmRecycleRequest; import org.apache.hadoop.hive.metastore.api.CmRecycleResponse; import org.apache.hadoop.hive.metastore.api.ColumnStatistics; @@ -125,6 +127,7 @@ import org.apache.hadoop.hive.metastore.api.WMResourcePlan; import org.apache.hadoop.hive.metastore.api.WMTrigger; import org.apache.hadoop.hive.metastore.api.WMValidateResourcePlanResponse; import org.apache.hadoop.hive.metastore.partition.spec.PartitionSpecProxy; +import org.apache.hadoop.hive.metastore.utils.MetaStoreUtils; import org.apache.hadoop.hive.metastore.utils.ObjectPair; import org.apache.thrift.TException; @@ -176,77 +179,219 @@ public interface IMetaStoreClient { String getMetaConf(String key) throws MetaException, TException; /** - * Get the names of all databases in the MetaStore that match the given pattern. - * @param databasePattern + * Create a new catalog. + * @param catalog catalog object to create. + * @throws AlreadyExistsException A catalog of this name already exists. + * @throws InvalidObjectException There is something wrong with the passed in catalog object. + * @throws MetaException something went wrong, usually either in the database or trying to + * create the directory for the catalog. + * @throws TException general thrift exception. + */ + void createCatalog(Catalog catalog) + throws AlreadyExistsException, InvalidObjectException, MetaException, TException; + + /** + * Get a catalog object. + * @param catName Name of the catalog to fetch. + * @return The catalog. + * @throws NoSuchObjectException no catalog of this name exists. + * @throws MetaException something went wrong, usually in the database. + * @throws TException general thrift exception. + */ + Catalog getCatalog(String catName) throws NoSuchObjectException, MetaException, TException; + + /** + * Get a list of all catalogs known to the system. + * @return list of catalog names + * @throws MetaException something went wrong, usually in the database. + * @throws TException general thrift exception. + */ + List<String> getCatalogs() throws MetaException, TException; + + /** + * Drop a catalog. Catalogs must be empty to be dropped, there is no cascade for dropping a + * catalog. + * @param catName name of the catalog to drop + * @throws NoSuchObjectException no catalog of this name exists. + * @throws InvalidOperationException The catalog is not empty and cannot be dropped. + * @throws MetaException something went wrong, usually in the database. + * @throws TException general thrift exception. + */ + void dropCatalog(String catName) + throws NoSuchObjectException, InvalidOperationException, MetaException, TException; + + /** + * Get the names of all databases in the default catalog that match the given pattern. + * @param databasePattern pattern for the database name to patch * @return List of database names. - * @throws MetaException - * @throws TException + * @throws MetaException error accessing RDBMS. + * @throws TException thrift transport error */ List<String> getDatabases(String databasePattern) throws MetaException, TException; /** + * Get all databases in a catalog whose names match a pattern. + * @param catName catalog name. Can be null, in which case the default catalog is assumed. + * @param databasePattern pattern for the database name to match + * @return list of database names + * @throws MetaException error accessing RDBMS. + * @throws TException thrift transport error + */ + List<String> getDatabases(String catName, String databasePattern) + throws MetaException, TException; + + /** * Get the names of all databases in the MetaStore. - * @return List of database names. - * @throws MetaException - * @throws TException + * @return List of database names in the default catalog. + * @throws MetaException error accessing RDBMS. + * @throws TException thrift transport error */ List<String> getAllDatabases() throws MetaException, TException; /** + * Get all databases in a catalog. + * @param catName catalog name. Can be null, in which case the default catalog is assumed. + * @return list of all database names + * @throws MetaException error accessing RDBMS. + * @throws TException thrift transport error + */ + List<String> getAllDatabases(String catName) throws MetaException, TException; + + /** * Get the names of all tables in the specified database that satisfy the supplied * table name pattern. - * @param dbName - * @param tablePattern + * @param dbName database name. + * @param tablePattern pattern for table name to conform to * @return List of table names. - * @throws MetaException - * @throws TException - * @throws UnknownDBException + * @throws MetaException error fetching information from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException indicated database to search in does not exist. */ List<String> getTables(String dbName, String tablePattern) throws MetaException, TException, UnknownDBException; /** * Get the names of all tables in the specified database that satisfy the supplied + * table name pattern. + * @param catName catalog name. + * @param dbName database name. + * @param tablePattern pattern for table name to conform to + * @return List of table names. + * @throws MetaException error fetching information from the RDBMS + * @throws TException general thrift error + * @throws UnknownDBException indicated database to search in does not exist. + */ + List<String> getTables(String catName, String dbName, String tablePattern) + throws MetaException, TException, UnknownDBException; + + + /** + * Get the names of all tables in the specified database that satisfy the supplied * table name pattern and table type (MANAGED_TABLE || EXTERNAL_TABLE || VIRTUAL_VIEW) * @param dbName Name of the database to fetch tables in. * @param tablePattern pattern to match for table names. * @param tableType Type of the table in the HMS store. VIRTUAL_VIEW is for views. * @return List of table names. - * @throws MetaException - * @throws TException - * @throws UnknownDBException + * @throws MetaException error fetching information from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException indicated database does not exist. */ List<String> getTables(String dbName, String tablePattern, TableType tableType) throws MetaException, TException, UnknownDBException; /** - * Get materialized views that have rewriting enabled. + * Get the names of all tables in the specified database that satisfy the supplied + * table name pattern and table type (MANAGED_TABLE || EXTERNAL_TABLE || VIRTUAL_VIEW) + * @param catName catalog name. + * @param dbName Name of the database to fetch tables in. + * @param tablePattern pattern to match for table names. + * @param tableType Type of the table in the HMS store. VIRTUAL_VIEW is for views. + * @return List of table names. + * @throws MetaException error fetching information from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException indicated database does not exist. + */ + List<String> getTables(String catName, String dbName, String tablePattern, TableType tableType) + throws MetaException, TException, UnknownDBException; + + /** + * Get materialized views that have rewriting enabled. This will use the default catalog. * @param dbName Name of the database to fetch materialized views from. * @return List of materialized view names. - * @throws MetaException - * @throws TException - * @throws UnknownDBException + * @throws MetaException error fetching from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException no such database */ List<String> getMaterializedViewsForRewriting(String dbName) throws MetaException, TException, UnknownDBException; /** - * For quick GetTablesOperation + * Get materialized views that have rewriting enabled. + * @param catName catalog name. + * @param dbName Name of the database to fetch materialized views from. + * @return List of materialized view names. + * @throws MetaException error fetching from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException no such database + */ + List<String> getMaterializedViewsForRewriting(String catName, String dbName) + throws MetaException, TException, UnknownDBException; + + /** + * Fetches just table name and comments. Useful when you need full table name + * (catalog.database.table) but don't need extra information like partition columns that + * require additional fetches from the database. + * @param dbPatterns database pattern to match, or null for all databases + * @param tablePatterns table pattern to match. + * @param tableTypes list of table types to fetch. + * @return list of TableMeta objects with information on matching tables + * @throws MetaException something went wrong with the fetch from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException No databases match the provided pattern. */ List<TableMeta> getTableMeta(String dbPatterns, String tablePatterns, List<String> tableTypes) throws MetaException, TException, UnknownDBException; /** + * Fetches just table name and comments. Useful when you need full table name + * (catalog.database.table) but don't need extra information like partition columns that + * require additional fetches from the database. + * @param catName catalog to search in. Search cannot cross catalogs. + * @param dbPatterns database pattern to match, or null for all databases + * @param tablePatterns table pattern to match. + * @param tableTypes list of table types to fetch. + * @return list of TableMeta objects with information on matching tables + * @throws MetaException something went wrong with the fetch from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException No databases match the provided pattern. + */ + List<TableMeta> getTableMeta(String catName, String dbPatterns, String tablePatterns, + List<String> tableTypes) + throws MetaException, TException, UnknownDBException; + + /** * Get the names of all tables in the specified database. - * @param dbName + * @param dbName database name * @return List of table names. - * @throws MetaException - * @throws TException - * @throws UnknownDBException + * @throws MetaException something went wrong with the fetch from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException No databases match the provided pattern. */ List<String> getAllTables(String dbName) throws MetaException, TException, UnknownDBException; /** + * Get the names of all tables in the specified database. + * @param catName catalog name + * @param dbName database name + * @return List of table names. + * @throws MetaException something went wrong with the fetch from the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException No databases match the provided pattern. + */ + List<String> getAllTables(String catName, String dbName) + throws MetaException, TException, UnknownDBException; + + /** * Get a list of table names that match a filter. * The filter operators are LIKE, <, <=, >, >=, =, <> * @@ -281,10 +426,55 @@ public interface IMetaStoreClient { * @param maxTables * The maximum number of tables returned * @return A list of table names that match the desired filter + * @throws InvalidOperationException invalid filter + * @throws UnknownDBException no such database + * @throws TException thrift transport error */ List<String> listTableNamesByFilter(String dbName, String filter, short maxTables) - throws MetaException, TException, InvalidOperationException, UnknownDBException; + throws TException, InvalidOperationException, UnknownDBException; + /** + * Get a list of table names that match a filter. + * The filter operators are LIKE, <, <=, >, >=, =, <> + * + * In the filter statement, values interpreted as strings must be enclosed in quotes, + * while values interpreted as integers should not be. Strings and integers are the only + * supported value types. + * + * The currently supported key names in the filter are: + * Constants.HIVE_FILTER_FIELD_OWNER, which filters on the tables' owner's name + * and supports all filter operators + * Constants.HIVE_FILTER_FIELD_LAST_ACCESS, which filters on the last access times + * and supports all filter operators except LIKE + * Constants.HIVE_FILTER_FIELD_PARAMS, which filters on the tables' parameter keys and values + * and only supports the filter operators = and <>. + * Append the parameter key name to HIVE_FILTER_FIELD_PARAMS in the filter statement. + * For example, to filter on parameter keys called "retention", the key name in the filter + * statement should be Constants.HIVE_FILTER_FIELD_PARAMS + "retention" + * Also, = and <> only work for keys that exist in the tables. + * E.g., filtering on tables where key1 <> value will only + * return tables that have a value for the parameter key1. + * Some example filter statements include: + * filter = Constants.HIVE_FILTER_FIELD_OWNER + " like \".*test.*\" and " + + * Constants.HIVE_FILTER_FIELD_LAST_ACCESS + " = 0"; + * filter = Constants.HIVE_FILTER_FIELD_OWNER + " = \"test_user\" and (" + + * Constants.HIVE_FILTER_FIELD_PARAMS + "retention = \"30\" or " + + * Constants.HIVE_FILTER_FIELD_PARAMS + "retention = \"90\")" + * + * @param catName catalog name + * @param dbName + * The name of the database from which you will retrieve the table names + * @param filter + * The filter string + * @param maxTables + * The maximum number of tables returned + * @return A list of table names that match the desired filter + * @throws InvalidOperationException invalid filter + * @throws UnknownDBException no such database + * @throws TException thrift transport error + */ + List<String> listTableNamesByFilter(String catName, String dbName, String filter, int maxTables) + throws TException, InvalidOperationException, UnknownDBException; /** * Drop the table. @@ -303,50 +493,109 @@ public interface IMetaStoreClient { * The table wasn't found. * @throws TException * A thrift communication error occurred + * */ void dropTable(String dbname, String tableName, boolean deleteData, boolean ignoreUnknownTab) throws MetaException, TException, NoSuchObjectException; /** + * Drop the table. + * + * @param dbname + * The database for this table + * @param tableName + * The table to drop + * @param deleteData + * Should we delete the underlying data + * @param ignoreUnknownTab + * don't throw if the requested table doesn't exist * @param ifPurge * completely purge the table (skipping trash) while removing data from warehouse - * @see #dropTable(String, String, boolean, boolean) + * @throws MetaException + * Could not drop table properly. + * @throws NoSuchObjectException + * The table wasn't found. + * @throws TException + * A thrift communication error occurred */ - public void dropTable(String dbname, String tableName, boolean deleteData, + void dropTable(String dbname, String tableName, boolean deleteData, boolean ignoreUnknownTab, boolean ifPurge) throws MetaException, TException, NoSuchObjectException; /** - * Drop the table in the DEFAULT database. + * Drop the table. * + * @param dbname + * The database for this table * @param tableName * The table to drop - * @param deleteData - * Should we delete the underlying data * @throws MetaException * Could not drop table properly. - * @throws UnknownTableException + * @throws NoSuchObjectException * The table wasn't found. * @throws TException * A thrift communication error occurred - * @throws NoSuchObjectException - * The table wasn't found. - * - * @deprecated As of release 0.6.0 replaced by {@link #dropTable(String, String, boolean, boolean)}. - * This method will be removed in release 0.7.0. - */ - @Deprecated - void dropTable(String tableName, boolean deleteData) - throws MetaException, UnknownTableException, TException, NoSuchObjectException; - - /** - * @see #dropTable(String, String, boolean, boolean) */ void dropTable(String dbname, String tableName) throws MetaException, TException, NoSuchObjectException; /** + * Drop a table. + * @param catName catalog the table is in. + * @param dbName database the table is in. + * @param tableName table name. + * @param deleteData whether associated data should be deleted. + * @param ignoreUnknownTable whether a non-existent table name should be ignored + * @param ifPurge whether dropped data should be immediately removed rather than placed in HDFS + * trash. + * @throws MetaException something went wrong, usually in the RDBMS or storage. + * @throws NoSuchObjectException No table of this name exists, only thrown if + * ignoreUnknownTable is false. + * @throws TException general thrift error. + */ + void dropTable(String catName, String dbName, String tableName, boolean deleteData, + boolean ignoreUnknownTable, boolean ifPurge) + throws MetaException, NoSuchObjectException, TException; + + /** + * Drop a table. Equivalent to + * {@link #dropTable(String, String, String, boolean, boolean, boolean)} with ifPurge set to + * false. + * @param catName catalog the table is in. + * @param dbName database the table is in. + * @param tableName table name. + * @param deleteData whether associated data should be deleted. + * @param ignoreUnknownTable whether a non-existent table name should be ignored + * @throws MetaException something went wrong, usually in the RDBMS or storage. + * @throws NoSuchObjectException No table of this name exists, only thrown if + * ignoreUnknownTable is false. + * @throws TException general thrift error. + */ + default void dropTable(String catName, String dbName, String tableName, boolean deleteData, + boolean ignoreUnknownTable) + throws MetaException, NoSuchObjectException, TException { + dropTable(catName, dbName, tableName, deleteData, ignoreUnknownTable, false); + } + + /** + * Drop a table. Equivalent to + * {@link #dropTable(String, String, String, boolean, boolean, boolean)} with deleteData + * set and ignoreUnknownTable set to true and ifPurge set to false. + * @param catName catalog the table is in. + * @param dbName database the table is in. + * @param tableName table name. + * @throws MetaException something went wrong, usually in the RDBMS or storage. + * @throws NoSuchObjectException No table of this name exists, only thrown if + * ignoreUnknownTable is false. + * @throws TException general thrift error. + */ + default void dropTable(String catName, String dbName, String tableName) + throws MetaException, NoSuchObjectException, TException { + dropTable(catName, dbName, tableName, true, true, false); + } + + /** * Truncate the table/partitions in the DEFAULT database. * @param dbName * The db to which the table to be truncate belongs to @@ -354,13 +603,27 @@ public interface IMetaStoreClient { * The table to truncate * @param partNames * List of partitions to truncate. NULL will truncate the whole table/all partitions - * @throws MetaException - * @throws TException - * Could not truncate table properly. + * @throws MetaException Failure in the RDBMS or storage + * @throws TException Thrift transport exception */ void truncateTable(String dbName, String tableName, List<String> partNames) throws MetaException, TException; /** + * Truncate the table/partitions in the DEFAULT database. + * @param catName catalog name + * @param dbName + * The db to which the table to be truncate belongs to + * @param tableName + * The table to truncate + * @param partNames + * List of partitions to truncate. NULL will truncate the whole table/all partitions + * @throws MetaException Failure in the RDBMS or storage + * @throws TException Thrift transport exception + */ + void truncateTable(String catName, String dbName, String tableName, List<String> partNames) + throws MetaException, TException; + + /** * Recycles the files recursively from the input path to the cmroot directory either by copying or moving it. * * @param request Inputs for path of the data files to be recycled to cmroot and @@ -369,43 +632,33 @@ public interface IMetaStoreClient { */ CmRecycleResponse recycleDirToCmPath(CmRecycleRequest request) throws MetaException, TException; - boolean tableExists(String databaseName, String tableName) throws MetaException, - TException, UnknownDBException; - /** - * Check to see if the specified table exists in the DEFAULT database. - * @param tableName - * @return TRUE if DEFAULT.tableName exists, FALSE otherwise. - * @throws MetaException - * @throws TException - * @throws UnknownDBException - * @deprecated As of release 0.6.0 replaced by {@link #tableExists(String, String)}. - * This method will be removed in release 0.7.0. + * Check whether a table exists in the default catalog. + * @param databaseName database name + * @param tableName table name + * @return true if the indicated table exists, false if not + * @throws MetaException error fetching form the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException the indicated database does not exist. */ - @Deprecated - boolean tableExists(String tableName) throws MetaException, - TException, UnknownDBException; + boolean tableExists(String databaseName, String tableName) + throws MetaException, TException, UnknownDBException; /** - * Get a table object from the DEFAULT database. - * - * @param tableName - * Name of the table to fetch. - * @return An object representing the table. - * @throws MetaException - * Could not fetch the table - * @throws TException - * A thrift communication error occurred - * @throws NoSuchObjectException - * In case the table wasn't found. - * @deprecated As of release 0.6.0 replaced by {@link #getTable(String, String)}. - * This method will be removed in release 0.7.0. + * Check whether a table exists. + * @param catName catalog name + * @param dbName database name + * @param tableName table name + * @return true if the indicated table exists, false if not + * @throws MetaException error fetching form the RDBMS + * @throws TException thrift transport error + * @throws UnknownDBException the indicated database does not exist. */ - @Deprecated - Table getTable(String tableName) throws MetaException, TException, NoSuchObjectException; + boolean tableExists(String catName, String dbName, String tableName) + throws MetaException, TException, UnknownDBException; /** - * Get a Database Object + * Get a Database Object in the default catalog * @param databaseName name of the database to fetch * @return the database * @throws NoSuchObjectException The database does not exist @@ -415,9 +668,21 @@ public interface IMetaStoreClient { Database getDatabase(String databaseName) throws NoSuchObjectException, MetaException, TException; + /** + * Get a database. + * @param catalogName catalog name. Can be null, in which case + * {@link Warehouse#DEFAULT_CATALOG_NAME} will be assumed. + * @param databaseName database name + * @return the database object + * @throws NoSuchObjectException No database with this name exists in the specified catalog + * @throws MetaException something went wrong, usually in the RDBMS + * @throws TException general thrift error + */ + Database getDatabase(String catalogName, String databaseName) + throws NoSuchObjectException, MetaException, TException; /** - * Get a table object. + * Get a table object in the default catalog. * * @param dbName * The database the table is located in. @@ -435,7 +700,19 @@ public interface IMetaStoreClient { TException, NoSuchObjectException; /** - * + * Get a table object. + * @param catName catalog the table is in. + * @param dbName database the table is in. + * @param tableName table name. + * @return table object. + * @throws MetaException Something went wrong, usually in the RDBMS. + * @throws TException general thrift error. + */ + Table getTable(String catName, String dbName, String tableName) throws MetaException, TException; + + /** + * Get tables as objects (rather than just fetching their names). This is more expensive and + * should only be used if you actually need all the information about the tables. * @param dbName * The database the tables are located in. * @param tableNames @@ -457,6 +734,30 @@ public interface IMetaStoreClient { throws MetaException, InvalidOperationException, UnknownDBException, TException; /** + * Get tables as objects (rather than just fetching their names). This is more expensive and + * should only be used if you actually need all the information about the tables. + * @param catName catalog name + * @param dbName + * The database the tables are located in. + * @param tableNames + * The names of the tables to fetch + * @return A list of objects representing the tables. + * Only the tables that can be retrieved from the database are returned. For example, + * if none of the requested tables could be retrieved, an empty list is returned. + * There is no guarantee of ordering of the returned tables. + * @throws InvalidOperationException + * The input to this operation is invalid (e.g., the list of tables names is null) + * @throws UnknownDBException + * The requested database could not be fetched. + * @throws TException + * A thrift communication error occurred + * @throws MetaException + * Any other errors + */ + List<Table> getTableObjectsByName(String catName, String dbName, List<String> tableNames) + throws MetaException, InvalidOperationException, UnknownDBException, TException; + + /** * Returns the invalidation information for the materialized views given as input. */ Map<String, Materialization> getMaterializationsInvalidationInfo(String dbName, List<String> viewNames) @@ -469,22 +770,72 @@ public interface IMetaStoreClient { throws MetaException, TException; /** - * @param tableName - * @param dbName - * @param partVals + * Updates the creation metadata for the materialized view. + */ + void updateCreationMetadata(String catName, String dbName, String tableName, CreationMetadata cm) + throws MetaException, TException; + + /** + /** + * Add a partition to a table and get back the resulting Partition object. This creates an + * empty default partition with just the partition values set. + * @param dbName database name + * @param tableName table name + * @param partVals partition values * @return the partition object - * @throws InvalidObjectException - * @throws AlreadyExistsException - * @throws MetaException - * @throws TException - * @see org.apache.hadoop.hive.metastore.api.ThriftHiveMetastore.Iface#append_partition(java.lang.String, - * java.lang.String, java.util.List) + * @throws InvalidObjectException no such table + * @throws AlreadyExistsException a partition with these values already exists + * @throws MetaException error accessing the RDBMS + * @throws TException thrift transport error */ - Partition appendPartition(String tableName, String dbName, - List<String> partVals) throws InvalidObjectException, - AlreadyExistsException, MetaException, TException; + Partition appendPartition(String dbName, String tableName, List<String> partVals) + throws InvalidObjectException, AlreadyExistsException, MetaException, TException; - Partition appendPartition(String tableName, String dbName, String name) + /** + * Add a partition to a table and get back the resulting Partition object. This creates an + * empty default partition with just the partition values set. + * @param catName catalog name + * @param dbName database name + * @param tableName table name + * @param partVals partition values + * @return the partition object + * @throws InvalidObjectException no such table + * @throws AlreadyExistsException a partition with these values already exists + * @throws MetaException error accessing the RDBMS + * @throws TException thrift transport error + */ + Partition appendPartition(String catName, String dbName, String tableName, List<String> partVals) + throws InvalidObjectException, AlreadyExistsException, MetaException, TException; + + /** + * Add a partition to a table and get back the resulting Partition object. This creates an + * empty default partition with just the partition value set. + * @param dbName database name. + * @param tableName table name. + * @param name name of the partition, should be in the form partkey=partval. + * @return new partition object. + * @throws InvalidObjectException No such table. + * @throws AlreadyExistsException Partition of this name already exists. + * @throws MetaException error accessing the RDBMS + * @throws TException thrift transport error + */ + Partition appendPartition(String dbName, String tableName, String name) + throws InvalidObjectException, AlreadyExistsException, MetaException, TException; + + /** + * Add a partition to a table and get back the resulting Partition object. This creates an + * empty default partition with just the partition value set. + * @param catName catalog name. + * @param dbName database name. + * @param tableName table name. + * @param name name of the partition, should be in the form partkey=partval. + * @return new partition object. + * @throws InvalidObjectException No such table. + * @throws AlreadyExistsException Partition of this name already exists. + * @throws MetaException error accessing the RDBMS + * @throws TException thrift transport error + */ + Partition appendPartition(String catName, String dbName, String tableName, String name) throws InvalidObjectException, AlreadyExistsException, MetaException, TException; /** @@ -522,6 +873,15 @@ public interface IMetaStoreClient { int add_partitions(List<Partition> partitions) throws InvalidObjectException, AlreadyExistsException, MetaException, TException; + /** + * Add a partitions using a spec proxy. + * @param partitionSpec partition spec proxy + * @return number of partitions that were added + * @throws InvalidObjectException the partitionSpec is malformed. + * @throws AlreadyExistsException one or more of the partitions already exist. + * @throws MetaException error accessing the RDBMS or storage. + * @throws TException thrift transport error + */ int add_partitions_pspec(PartitionSpecProxy partitionSpec) throws InvalidObjectException, AlreadyExistsException, MetaException, TException; @@ -538,25 +898,46 @@ public interface IMetaStoreClient { throws InvalidObjectException, AlreadyExistsException, MetaException, TException; /** - * @param dbName - * @param tblName - * @param partVals + * Get a partition. + * @param dbName database name + * @param tblName table name + * @param partVals partition values for this partition, must be in the same order as the + * partition keys of the table. * @return the partition object - * @throws MetaException - * @throws TException - * @see org.apache.hadoop.hive.metastore.api.ThriftHiveMetastore.Iface#get_partition(java.lang.String, - * java.lang.String, java.util.List) + * @throws NoSuchObjectException no such partition + * @throws MetaException error access the RDBMS. + * @throws TException thrift transport error + */ + Partition getPartition(String dbName, String tblName, List<String> partVals) + throws NoSuchObjectException, MetaException, TException; + + /** + * Get a partition. + * @param catName catalog name + * @param dbName database name + * @param tblName table name + * @param partVals partition values for this partition, must be in the same order as the + * partition keys of the table. + * @return the partition object + * @throws NoSuchObjectException no such partition + * @throws MetaException error access the RDBMS. + * @throws TException thrift transport error */ - Partition getPartition(String dbName, String tblName, - List<String> partVals) throws NoSuchObjectException, MetaException, TException; + Partition getPartition(String catName, String dbName, String tblName, List<String> partVals) + throws NoSuchObjectException, MetaException, TException; /** - * @param partitionSpecs - * @param sourceDb - * @param sourceTable - * @param destdb - * @param destTableName + * Move a partition from one table to another + * @param partitionSpecs key value pairs that describe the partition to be moved. + * @param sourceDb database of the source table + * @param sourceTable name of the source table + * @param destdb database of the destination table + * @param destTableName name of the destination table * @return partition object + * @throws MetaException error accessing the RDBMS or storage + * @throws NoSuchObjectException no such table, for either source or destination table + * @throws InvalidObjectException error in partition specifications + * @throws TException thrift transport error */ Partition exchange_partition(Map<String, String> partitionSpecs, String sourceDb, String sourceTable, String destdb, @@ -564,14 +945,38 @@ public interface IMetaStoreClient { InvalidObjectException, TException; /** + * Move a partition from one table to another + * @param partitionSpecs key value pairs that describe the partition to be moved. + * @param sourceCat catalog of the source table + * @param sourceDb database of the source table + * @param sourceTable name of the source table + * @param destCat catalog of the destination table, for now must the same as sourceCat + * @param destdb database of the destination table + * @param destTableName name of the destination table + * @return partition object + * @throws MetaException error accessing the RDBMS or storage + * @throws NoSuchObjectException no such table, for either source or destination table + * @throws InvalidObjectException error in partition specifications + * @throws TException thrift transport error + */ + Partition exchange_partition(Map<String, String> partitionSpecs, String sourceCat, + String sourceDb, String sourceTable, String destCat, String destdb, + String destTableName) throws MetaException, NoSuchObjectException, + InvalidObjectException, TException; + + /** * With the one partitionSpecs to exchange, multiple partitions could be exchanged. * e.g., year=2015/month/day, exchanging partition year=2015 results to all the partitions * belonging to it exchanged. This function returns the list of affected partitions. - * @param partitionSpecs - * @param sourceDb - * @param sourceTable - * @param destdb - * @param destTableName + * @param partitionSpecs key value pairs that describe the partition(s) to be moved. + * @param sourceDb database of the source table + * @param sourceTable name of the source table + * @param destdb database of the destination table + * @param destTableName name of the destination table + * @throws MetaException error accessing the RDBMS or storage + * @throws NoSuchObjectException no such table, for either source or destination table + * @throws InvalidObjectException error in partition specifications + * @throws TException thrift transport error * @return the list of the new partitions */ List<Partition> exchange_partitions(Map<String, String> partitionSpecs, @@ -580,60 +985,243 @@ public interface IMetaStoreClient { InvalidObjectException, TException; /** - * @param dbName - * @param tblName + * With the one partitionSpecs to exchange, multiple partitions could be exchanged. + * e.g., year=2015/month/day, exchanging partition year=2015 results to all the partitions + * belonging to it exchanged. This function returns the list of affected partitions. + * @param partitionSpecs key value pairs that describe the partition(s) to be moved. + * @param sourceCat catalog of the source table + * @param sourceDb database of the source table + * @param sourceTable name of the source table + * @param destCat catalog of the destination table, for now must the same as sourceCat + * @param destdb database of the destination table + * @param destTableName name of the destination table + * @throws MetaException error accessing the RDBMS or storage + * @throws NoSuchObjectException no such table, for either source or destination table + * @throws InvalidObjectException error in partition specifications + * @throws TException thrift transport error + * @return the list of the new partitions + */ + List<Partition> exchange_partitions(Map<String, String> partitionSpecs, String sourceCat, + String sourceDb, String sourceTable, String destCat, + String destdb, String destTableName) + throws MetaException, NoSuchObjectException, InvalidObjectException, TException; + + /** + * Get a Partition by name. + * @param dbName database name. + * @param tblName table name. * @param name - partition name i.e. 'ds=2010-02-03/ts=2010-02-03 18%3A16%3A01' * @return the partition object - * @throws MetaException - * @throws TException - * @see org.apache.hadoop.hive.metastore.api.ThriftHiveMetastore.Iface#get_partition(java.lang.String, - * java.lang.String, java.util.List) + * @throws MetaException error access the RDBMS. + * @throws TException thrift transport error + */ + Partition getPartition(String dbName, String tblName, String name) + throws MetaException, UnknownTableException, NoSuchObjectException, TException; + + /** + * Get a Partition by name. + * @param catName catalog name. + * @param dbName database name. + * @param tblName table name. + * @param name - partition name i.e. 'ds=2010-02-03/ts=2010-02-03 18%3A16%3A01' + * @return the partition object + * @throws MetaException error access the RDBMS. + * @throws TException thrift transport error */ - Partition getPartition(String dbName, String tblName, - String name) throws MetaException, UnknownTableException, NoSuchObjectException, TException; + Partition getPartition(String catName, String dbName, String tblName, String name) + throws MetaException, UnknownTableException, NoSuchObjectException, TException; /** - * @param dbName - * @param tableName - * @param pvals - * @param userName - * @param groupNames + * Get a Partition along with authorization information. + * @param dbName database name + * @param tableName table name + * @param pvals partition values, must be in the same order as the tables partition keys + * @param userName name of the calling user + * @param groupNames groups the call * @return the partition - * @throws MetaException - * @throws UnknownTableException - * @throws NoSuchObjectException - * @throws TException + * @throws MetaException error accessing the RDBMS + * @throws UnknownTableException no such table + * @throws NoSuchObjectException no such partition + * @throws TException thrift transport error */ Partition getPartitionWithAuthInfo(String dbName, String tableName, List<String> pvals, String userName, List<String> groupNames) throws MetaException, UnknownTableException, NoSuchObjectException, TException; /** - * @param tbl_name - * @param db_name - * @param max_parts + * Get a Partition along with authorization information. + * @param catName catalog name + * @param dbName database name + * @param tableName table name + * @param pvals partition values, must be in the same order as the tables partition keys + * @param userName name of the calling user + * @param groupNames groups the call + * @return the partition + * @throws MetaException error accessing the RDBMS + * @throws UnknownTableException no such table + * @throws NoSuchObjectException no such partition + * @throws TException thrift transport error + */ + Partition getPartitionWithAuthInfo(String catName, String dbName, String tableName, + List<String> pvals, String userName, List<String> groupNames) + throws MetaException, UnknownTableException, NoSuchObjectException, TException; + + /** + * Get a list of partittions for a table. + * @param db_name database name + * @param tbl_name table name + * @param max_parts maximum number of parts to return, -1 for all * @return the list of partitions - * @throws NoSuchObjectException - * @throws MetaException - * @throws TException + * @throws NoSuchObjectException No such table. + * @throws MetaException error accessing RDBMS. + * @throws TException thrift transport error */ - List<Partition> listPartitions(String db_name, String tbl_name, - short max_parts) throws NoSuchObjectException, MetaException, TException; + List<Partition> listPartitions(String db_name, String tbl_name, short max_parts) + throws NoSuchObjectException, MetaException, TException; + + /** + * Get a list of partittions for a table. + * @param catName catalog name + * @param db_name database name + * @param tbl_name table name + * @param max_parts maximum number of parts to return, -1 for all + * @return the list of partitions + * @throws NoSuchObjectException No such table. + * @throws MetaException error accessing RDBMS. + * @throws TException thrift transport error + */ + List<Partition> listPartitions(String catName, String db_name, String tbl_name, int max_parts) + throws NoSuchObjectException, MetaException, TException; - public PartitionSpecProxy listPartitionSpecs(String dbName, String tableName, int maxParts) + /** + * Get a list of partitions from a table, returned in the form of PartitionSpecProxy + * @param dbName database name. + * @param tableName table name. + * @param maxParts maximum number of partitions to return, or -1 for all + * @return a PartitionSpecProxy + * @throws TException thrift transport error + */ + PartitionSpecProxy listPartitionSpecs(String dbName, String tableName, int maxParts) throws TException; + + /** + * Get a list of partitions from a table, returned in the form of PartitionSpecProxy + * @param catName catalog name. + * @param dbName database name. + * @param tableName table name. + * @param maxParts maximum number of partitions to return, or -1 for all + * @return a PartitionSpecProxy + * @throws TException thrift transport error + */ + PartitionSpecProxy listPartitionSpecs(String catName, String dbName, String tableName, + int maxParts) throws TException; + + /** + * Get a list of partitions based on a (possibly partial) list of partition values. + * @param db_name database name. + * @param tbl_name table name. + * @param part_vals partition values, in order of the table partition keys. These can be + * partial, or .* to match all values for a particular key. + * @param max_parts maximum number of partitions to return, or -1 for all. + * @return list of partitions + * @throws NoSuchObjectException no such table. + * @throws MetaException error accessing the database or processing the partition values. + * @throws TException thrift transport error. + */ List<Partition> listPartitions(String db_name, String tbl_name, List<String> part_vals, short max_parts) throws NoSuchObjectException, MetaException, TException; + /** + * Get a list of partitions based on a (possibly partial) list of partition values. + * @param catName catalog name. + * @param db_name database name. + * @param tbl_name table name. + * @param part_vals partition values, in order of the table partition keys. These can be + * partial, or .* to match all values for a particular key. + * @param max_parts maximum number of partitions to return, or -1 for all. + * @return list of partitions + * @throws NoSuchObjectException no such table. + * @throws MetaException error accessing the database or processing the partition values. + * @throws TException thrift transport error. + */ + List<Partition> listPartitions(String catName, String db_name, String tbl_name, + List<String> part_vals, int max_parts) + throws NoSuchObjectException, MetaException, TException; + + /** + * List Names of partitions in a table. + * @param db_name database name. + * @param tbl_name table name. + * @param max_parts maximum number of parts of fetch, or -1 to fetch them all. + * @return list of partition names. + * @throws NoSuchObjectException No such table. + * @throws MetaException Error accessing the RDBMS. + * @throws TException thrift transport error + */ List<String> listPartitionNames(String db_name, String tbl_name, short max_parts) throws NoSuchObjectException, MetaException, TException; + /** + * List Names of partitions in a table. + * @param catName catalog name. + * @param db_name database name. + * @param tbl_name table name. + * @param max_parts maximum number of parts of fetch, or -1 to fetch them all. + * @return list of partition names. + * @throws NoSuchObjectException No such table. + * @throws MetaException Error accessing the RDBMS. + * @throws TException thrift transport error + */ + List<String> listPartitionNames(String catName, String db_name, String tbl_name, + int max_parts) throws NoSuchObjectException, MetaException, TException; + + /** + * Get a list of partition names matching a partial specification of the partition values. + * @param db_name database name. + * @param tbl_name table name. + * @param part_vals partial list of partition values. These must be given in the order of the + * partition keys. If you wish to accept any value for a particular key you + * can pass ".*" for that value in this list. + * @param max_parts maximum number of partition names to return, or -1 to return all that are + * found. + * @return list of matching partition names. + * @throws MetaException error accessing the RDBMS. + * @throws TException thrift transport error. + * @throws NoSuchObjectException no such table. + */ List<String> listPartitionNames(String db_name, String tbl_name, List<String> part_vals, short max_parts) throws MetaException, TException, NoSuchObjectException; - public PartitionValuesResponse listPartitionValues(PartitionValuesRequest request) + /** + * Get a list of partition names matching a partial specification of the partition values. + * @param catName catalog name. + * @param db_name database name. + * @param tbl_name table name. + * @param part_vals partial list of partition values. These must be given in the order of the + * partition keys. If you wish to accept any value for a particular key you + * can pass ".*" for that value in this list. + * @param max_parts maximum number of partition names to return, or -1 to return all that are + * found. + * @return list of matching partition names. + * @throws MetaException error accessing the RDBMS. + * @throws TException thrift transport error. + * @throws NoSuchObjectException no such table. + */ + List<String> listPartitionNames(String catName, String db_name, String tbl_name, + List<String> part_vals, int max_parts) + throws MetaException, TException, NoSuchObjectException; + + /** + * Get a list of partition values + * @param request request + * @return reponse + * @throws MetaException error accessing RDBMS + * @throws TException thrift transport error + * @throws NoSuchObjectException no such table + */ + PartitionValuesResponse listPartitionValues(PartitionValuesRequest request) throws MetaException, TException, NoSuchObjectException; /** @@ -644,15 +1232,31 @@ public interface IMetaStoreClient { * for example "part1 = \"p1_abc\" and part2 <= "\p2_test\"". Filtering can * be done only on string partition keys. * @return number of partitions - * @throws MetaException - * @throws NoSuchObjectException - * @throws TException + * @throws MetaException error accessing RDBMS or processing the filter + * @throws NoSuchObjectException no such table + * @throws TException thrift transport error + */ + int getNumPartitionsByFilter(String dbName, String tableName, + String filter) throws MetaException, NoSuchObjectException, TException; + + /** + * Get number of partitions matching specified filter + * @param catName catalog name + * @param dbName the database name + * @param tableName the table name + * @param filter the filter string, + * for example "part1 = \"p1_abc\" and part2 <= "\p2_test\"". Filtering can + * be done only on string partition keys. + * @return number of partitions + * @throws MetaException error accessing RDBMS or processing the filter + * @throws NoSuchObjectException no such table + * @throws TException thrift transport error */ - public int getNumPartitionsByFilter(String dbName, String tableName, - String filter) throws MetaException, NoSuchObjectException, TException; + int getNumPartitionsByFilter(String catName, String dbName, String tableName, + String filter) throws MetaException, NoSuchObjectException, TException; - /** + /** * Get list of partitions matching specified filter * @param db_name the database name * @param tbl_name the table name @@ -662,17 +1266,64 @@ public interface IMetaStoreClient { * @param max_parts the maximum number of partitions to return, * all partitions are returned if -1 is passed * @return list of partitions - * @throws MetaException - * @throws NoSuchObjectException - * @throws TException + * @throws MetaException Error accessing the RDBMS or processing the filter. + * @throws NoSuchObjectException No such table. + * @throws TException thrift transport error */ List<Partition> listPartitionsByFilter(String db_name, String tbl_name, - String filter, short max_parts) throws MetaException, - NoSuchObjectException, TException; + String filter, short max_parts) throws MetaException, NoSuchObjectException, TException; + + /** + * Get list of partitions matching specified filter + * @param catName catalog name. + * @param db_name the database name + * @param tbl_name the table name + * @param filter the filter string, + * for example "part1 = \"p1_abc\" and part2 <= "\p2_test\"". Filtering can + * be done only on string partition keys. + * @param max_parts the maximum number of partitions to return, + * all partitions are returned if -1 is passed + * @return list of partitions + * @throws MetaException Error accessing the RDBMS or processing the filter. + * @throws NoSuchObjectException No such table. + * @throws TException thrift transport error + */ + List<Partition> listPartitionsByFilter(String catName, String db_name, String tbl_name, + String filter, int max_parts) + throws MetaException, NoSuchObjectException, TException; + /** + * Get a list of partitions in a PartitionSpec, using a filter to select which partitions to + * fetch. + * @param db_name database name + * @param tbl_name table name + * @param filter SQL where clause filter + * @param max_parts maximum number of partitions to fetch, or -1 for all + * @return PartitionSpec + * @throws MetaException error accessing RDBMS or processing the filter + * @throws NoSuchObjectException No table matches the request + * @throws TException thrift transport error + */ PartitionSpecProxy listPartitionSpecsByFilter(String db_name, String tbl_name, - String filter, int max_parts) throws MetaException, - NoSuchObjectException, TException; + String filter, int max_parts) + throws MetaException, NoSuchObjectException, TException; + + /** + * Get a list of partitions in a PartitionSpec, using a filter to select which partitions to + * fetch. + * @param catName catalog name + * @param db_name database name + * @param tbl_name table name + * @param filter SQL where clause filter + * @param max_parts maximum number of partitions to fetch, or -1 for all + * @return PartitionSpec + * @throws MetaException error accessing RDBMS or processing the filter + * @throws NoSuchObjectException No table matches the request + * @throws TException thrift transport error + */ + PartitionSpecProxy listPartitionSpecsByFilter(String catName, String db_name, String tbl_name, + String filter, int max_parts) + throws MetaException, NoSuchObjectException, TException; /** * Get list of partitions matching specified serialized expression @@ -685,22 +1336,61 @@ public interface IMetaStoreClient { * metastore server-side configuration is used. * @param result the resulting list of partitions * @return whether the resulting list contains partitions which may or may not match the expr + * @throws TException thrift transport error or error executing the filter. */ boolean listPartitionsByExpr(String db_name, String tbl_name, byte[] expr, String default_partition_name, short max_parts, List<Partition> result) throws TException; /** - * @param dbName - * @param tableName - * @param s - * @param userName - * @param groupNames + * Get list of partitions matching specified serialized expression + * @param catName catalog name + * @param db_name the database name + * @param tbl_name the table name + * @param expr expression, serialized from ExprNodeDesc + * @param max_parts the maximum number of partitions to return, + * all partitions are returned if -1 is passed + * @param default_partition_name Default partition name from configuration. If blank, the + * metastore server-side configuration is used. + * @param result the resulting list of partitions + * @return whether the resulting list contains partitions which may or may not match the expr + * @throws TException thrift transport error or error executing the filter. + */ + boolean listPartitionsByExpr(String catName, String db_name, String tbl_name, byte[] expr, + String default_partition_name, int max_parts, List<Partition> result) + throws TException; + + /** + * List partitions, fetching the authorization information along with the partitions. + * @param dbName database name + * @param tableName table name + * @param maxParts maximum number of partitions to fetch, or -1 for all + * @param userName user to fetch privileges for + * @param groupNames groups to fetch privileges for * @return the list of partitions - * @throws NoSuchObjectException + * @throws NoSuchObjectException no partitions matching the criteria were found + * @throws MetaException error accessing the RDBMS + * @throws TException thrift transport error */ List<Partition> listPartitionsWithAuthInfo(String dbName, - String tableName, short s, String userName, List<String> groupNames) + String tableName, short maxParts, String userName, List<String> groupNames) + throws MetaException, TException, NoSuchObjectException; + + /** + * List partitions, fetching the authorization information along with the partitions. + * @param catName catalog name + * @param dbName database name + * @param tableName table name + * @param maxParts maximum number of partitions to fetch, or -1 for all + * @param userName user to fetch privileges for + * @param groupNames groups to fetch privileges for + * @return the list of partitions + * @throws NoSuchObjectException no partitions matching the criteria were found + * @throws MetaException error accessing the RDBMS + * @throws TException thrift transport error + */ + List<Partition> listPartitionsWithAuthInfo(String catName, String dbName, String tableName, + int maxParts, String userName, List<String> groupNames) throws MetaException, TException, NoSuchObjectException; /** @@ -709,62 +1399,138 @@ public interface IMetaStoreClient { * @param tbl_name table name * @param part_names list of partition names * @return list of Partition objects - * @throws NoSuchObjectException - * @throws MetaException - * @throws TException + * @throws NoSuchObjectException No such partitions + * @throws MetaException error accessing the RDBMS. + * @throws TException thrift transport error */ List<Partition> getPartitionsByNames(String db_name, String tbl_name, List<String> part_names) throws NoSuchObjectException, MetaException, TException; /** - * @param dbName - * @param tableName - * @param partialPvals - * @param s - * @param userName - * @param groupNames - * @return the list of paritions - * @throws NoSuchObjectException + * Get partitions by a list of partition names. + * @param catName catalog name + * @param db_name database name + * @param tbl_name table name + * @param part_names list of partition names + * @return list of Partition objects + * @throws NoSuchObjectException No such partitions + * @throws MetaException error accessing the RDBMS. + * @throws TException thrift transport error + */ + List<Partition> getPartitionsByNames(String catName, String db_name, String tbl_name, + List<String> part_names) + throws NoSuchObjectException, MetaException, TException; + + /** + * List partitions along with privilege information for a user or groups + * @param dbName database name + * @param tableName table name + * @param partialPvals partition values, can be partial + * @param maxParts maximum number of partitions to fetch, or -1 for all + * @param userName user to fetch privilege information for + * @param groupNames group to fetch privilege information for + * @return the list of partitions + * @throws NoSuchObjectException no partitions matching the criteria were found + * @throws MetaException error accessing the RDBMS + * @throws TException thrift transport error */ List<Partition> listPartitionsWithAuthInfo(String dbName, - String tableName, List<String> partialPvals, short s, String userName, + String tableName, List<String> partialPvals, short maxParts, String userName, List<String> groupNames) throws MetaException, TException, NoSuchObjectException; /** - * @param db_name - * @param tbl_name - * @param partKVs - * @param eventType - * @throws MetaException - * @throws NoSuchObjectException - * @throws TException - * @throws UnknownTableException - * @throws UnknownDBException - * @throws UnknownPartitionException - * @throws InvalidPartitionException + * List partitions along with privilege information for a user or groups + * @param dbName database name + * @param tableName table name + * @param partialPvals partition values, can be partial + * @param maxParts maximum number of partitions to fetch, or -1 for all + * @param userName user to fetch privilege information for + * @param groupNames group to fetch privilege information for + * @return the list of partitions + * @throws NoSuchObjectException no partitions matching the criteria were found + * @throws MetaException error accessing the RDBMS + * @throws TException thrift transport error + */ + List<Partition> listPartitionsWithAuthInfo(String catName, String dbName, String tableName, + List<String> partialPvals, int maxParts, String userName, + List<String> groupNames) + throws MetaException, TException, NoSuchObjectException; + + /** + * Mark an event as having occurred on a partition. + * @param db_name database name + * @param tbl_name table name + * @param partKVs key value pairs that describe the partition + * @param eventType type of the event + * @throws MetaException error access the RDBMS + * @throws NoSuchObjectException never throws this AFAICT + * @throws TException thrift transport error + * @throws UnknownTableException no such table + * @throws UnknownDBException no such database + * @throws UnknownPartitionException no such partition + * @throws InvalidPartitionException partition partKVs is invalid */ void markPartitionForEvent(String db_name, String tbl_name, Map<String,String> partKVs, PartitionEventType eventType) throws MetaException, NoSuchObjectException, TException, UnknownTableException, UnknownDBException, UnknownPartitionException, InvalidPartitionException; /** - * @param db_name - * @param tbl_name - * @param partKVs - * @param eventType - * @throws MetaException - * @throws NoSuchObjectException - * @throws TException - * @throws UnknownTableException - * @throws UnknownDBException - * @throws UnknownPartitionException - * @throws InvalidPartitionException + * Mark an event as having occurred on a partition. + * @param catName catalog name + * @param db_name database name + * @param tbl_name table name + * @param partKVs key value pairs that describe the partition + * @param eventType type of the event + * @throws MetaException error access the RDBMS + * @throws NoSuchObjectException never throws this AFAICT + * @throws TException thrift transport error + * @throws UnknownTableException no such table + * @throws UnknownDBException no such database + * @throws UnknownPartitionException no such partition + * @throws InvalidPartitionException partition partKVs is invalid + */ + void markPartitionForEvent(String catName, String db_name, String tbl_name, Map<String,String> partKVs, + PartitionEventType eventType) throws MetaException, NoSuchObjectException, TException, + UnknownTableException, UnknownDBException, UnknownPartitionException, InvalidPartitionException; + + /** + * Determine whether a partition has been marked with a particular event type. + * @param db_name database name + * @param tbl_name table name. + * @param partKVs key value pairs that describe the partition. + * @param eventType event type + * @throws MetaException error access the RDBMS + * @throws NoSuchObjectException never throws this AFAICT + * @throws TException thrift transport error + * @throws UnknownTableException no such table + * @throws UnknownDBException no such database + * @throws UnknownPartitionException no such partition + * @throws InvalidPartitionException partition partKVs is invalid */ boolean isPartitionMarkedForEvent(String db_name, String tbl_name, Map<String,String> partKVs, PartitionEventType eventType) throws MetaException, NoSuchObjectException, TException, UnknownTableException, UnknownDBException, UnknownPartitionException, InvalidPartitionException; /** + * Determine whether a partition has been marked with a particular event type. + * @param catName catalog name + * @param db_name database name + * @param tbl_name table name. + * @param partKVs key value pairs that describe the partition. + * @param eventType event type + * @throws MetaException error access the RDBMS + * @throws NoSuchObjectException never throws this AFAICT + * @throws TException thrift transport error + * @throws UnknownTableException no such table + * @throws UnknownDBException no such database + * @throws UnknownPartitionException no such partition + * @throws InvalidPartitionException partition partKVs is invalid + */ + boolean isPartitionMarkedForEvent(String catName, String db_name, String tbl_name, Map<String,String> partKVs, + PartitionEventType eventType) throws MetaException, NoSuchObjectException, TException, + UnknownTableException, UnknownDBException, UnknownPartitionException, InvalidPartitionException; + + /** * @param partVals * @throws TException * @throws MetaException @@ -784,92 +1550,449 @@ public interface IMetaStoreClient { void createTable(Table tbl) throws AlreadyExistsException, InvalidObjectException, MetaException, NoSuchObjectException, TException; - void alter_table(String defaultDatabaseName, String tblName, - Table table) throws InvalidOperationException, MetaException, TException; + /** + * Alter a table + * @param databaseName database name + * @param tblName table name + * @param table new table object, should be complete representation of the table, not just the + * things you want to change. + * @throws InvalidOperationException something is wrong with the new table object or an + * operation was attempted that is not allowed (such as changing partition columns). + * @throws MetaException something went wrong, usually in the RDBMS + * @throws TException general thrift exception + */ + void alter_table(String databaseName, String tblName, Table table) + throws InvalidOperationException, MetaException, TException; + + /** + * Alter a table. Equivalent to + * {@link #alter_table(String, String, String, Table, EnvironmentContext)} with + * EnvironmentContext set to null. + * @param catName catalog name. + * @param dbName database name. + * @param tblName table name. + * @param newTable new table object, should be complete representation of the table, not just the + * things you want to change. + * @throws InvalidOperationException something is wrong with the new table object or an + * operation was attempted that is not allowed (such as changing partition columns). + * @throws MetaException something went wrong, usually in the RDBMS + * @throws TException general thrift exception + */ + default void alter_table(String catName, String dbName, String tblName, Table newTable) + throws InvalidOperationException, MetaException, TException { + alter_table(catName, dbName, tblName, newTable, null); + } + + /** + * Alter a table. + * @param catName catalog name. + * @param dbName database name. + * @param tblName table name. + * @param newTable new table object, should be complete representation of the table, not just the + * things you want to change. + * @param envContext options for the alter. + * @throws InvalidOperationException something is wrong with the new table object or an + * operation was attempted that is not allowed (such as changing partition columns). + * @throws MetaException something went wrong, usually in the RDBMS + * @throws TException general thrift exception + */ + void alter_table(String catName, String dbName, String tblName, Table newTable, + EnvironmentContext envContext) + throws InvalidOperationException, MetaException, TException; /** - * Use alter_table_with_environmentContext instead of alter_table with cascade option + * @deprecated Use alter_table_with_environmentContext instead of alter_table with cascade option * passed in EnvironmentContext using {@code StatsSetupConst.CASCADE} */ @Deprecated void alter_table(String defaultDatabaseName, String tblName, Table table, boolean cascade) throws InvalidOperationException, MetaException, TException; - //wrapper of alter_table_with_cascade - void alter_table_with_environmentContext(String defaultDatabaseName, String tblName, Table table, + /** + * Alter a table. + * @param databaseName database name + * @param tblName table name + * @param table new table object, should be complete representation of the table, not just the + * things you want to change. + * @param environmentContext options for the alter. + * @throws InvalidOperationException something is wrong with the new table object or an + * operation was attempted that is not allowed (such as changing partition columns). + * @throws MetaException something went wrong, usually in the RDBMS + * @throws TException general thrift exception + */ + void alter_table_with_environmentContext(String databaseName, String tblName, Table table, EnvironmentContext environmentContext) throws InvalidOperationException, MetaException, TException; + /** + * Create a new database. + * @param db database object. If the catalog name is null it will be assumed to be + * {@link Warehouse#DEFAULT_CATALOG_NAME}. + * @throws InvalidObjectException There is something wrong with the database object. + * @throws AlreadyExistsException There is already a database of this name in the specified + * catalog. + * @throws MetaException something went wrong, usually in the RDBMS + * @throws TException general thrift error + */ void createDatabase(Database db) throws InvalidObjectException, AlreadyExistsException, MetaException, TException; + /** + * Drop a database. + * @param name name of the database to drop. + * @throws NoSuchObjectException No such database exists. + * @throws InvalidOperationException The database cannot be dropped because it is not empty. + * @throws MetaException something went wrong, usually either in the RDMBS or in storage. + * @throws TException general thrift error. + */ void dropDatabase(String name) throws NoSuchObjectException, InvalidOperationException, MetaException, TException; + /** + * + * Drop a database. + * @param name name of the database to drop. + * @param deleteData whether to drop the underlying HDFS directory. + * @param ignoreUnknownDb whether to ignore an attempt to drop a non-existant database + * @throws NoSuchObjectException No database of this name exists in the specified catalog and + * ignoreUnknownDb is false. + * @throws InvalidOperationException The database cannot be dropped because it is not empty. + * @throws MetaException something went wrong, usually either in the RDMBS or in storage. + * @throws TException general thrift error. + */ void dropDatabase(String name, boolean deleteData, boolean ignoreUnknownDb) throws NoSuchObjectException, InvalidOperationException, MetaException, TException; + /** + * + * Drop a database. + * @param name database name. + * @param deleteData whether to drop the underlying HDFS directory. + * @param ignoreUnknownDb whether to ignore an attempt to drop a non-existant database + * @param cascade whether to drop contained tables, etc. If this is false and there are + * objects still in the database the drop will fail. + * @throws NoSuchObjectException No database of this name exists in the specified catalog and + * ignoreUnknownDb is false. + * @throws InvalidOperationException The database contains objects and cascade is false. + * @throws MetaException something went wrong, usually either in the RDBMS or storage. + * @throws TException general thrift error. + */ void dropDatabase(String name, boolean deleteData, boolean ignoreUnknownDb, boolean cascade) throws NoSuchObjectException, InvalidOperationException, MetaException, TException; + /** + * Drop a database. + * @param catName Catalog name. This can be null, in which case + * {@link Warehouse#DEFAULT_CATALOG_NAME} will be assumed. + * @param dbName database name. + * @param deleteData whether to drop the underlying HDFS directory. + * @param ignoreUnknownDb whether to ignore an attempt to drop a non-existant database + * @param cascade whether to drop contained tables, etc. If this is false and there are + * objects still in the database the drop will fail. + * @throws NoSuchObjectException No database of this name exists in the specified catalog and + * ignoreUnknownDb is false. + * @throws InvalidOperationException The database contains objects and cascade is false. + * @throws MetaException something went wrong, usually either in the RDBMS or storage. + * @throws TException general thrift error. + */ + void dropDatabase(String catName, String dbName, boolean deleteData, boolean ignoreUnknownDb, + boolean cascade) + throws NoSuchObjectException, InvalidOperationException, MetaException, TException; + + /** + * Drop a database. Equivalent to + * {@link #dropDatabase(String, String, boolean, boolean, boolean)} with cascade = false. + * @param catName Catalog name. This can be null, in which case + * {@link Warehouse#DEFAULT_CATALOG_NAME} will be assumed. + * @param dbName database name. + * @param deleteData whether to drop the underlying HDFS directory. + * @param ignoreUnknownDb whether to ignore an attempt to drop a non-existant database + * @throws NoSuchObjectException No database of this name exists in the specified catalog and + * ignoreUnknownDb is false. + * @throws InvalidOperationException The database contains objects and cascade is false. + * @throws MetaException something went wrong, usually either in the RDBMS or storage. + * @throws TException general thrift error. + */ + default void dropDatabase(String catName, String dbName, boolean deleteData, + boolean ignoreUnknownDb) + throws NoSuchObjectException, InvalidOperationException, MetaException, TException { + dropDatabase(catName, dbName, deleteData, ignoreUnknownDb, false); + } + + /** + * Drop a database. Equivalent to + * {@link #dropDatabase(String, String, boolean, boolean, boolean)} with deleteData = + * true, ignoreUnknownDb = false, cascade = false. + * @param catName Catalog name. This can be null, in which case + * {@link Warehouse#DEFAULT_CATALOG_NAME} will be assumed. + * @param dbName database name. + * @throws NoSuchObjectException No database of this name exists in the specified catalog and + * ignoreUnknownDb is false. + * @throws InvalidOperationException The database contains objects and cascade is false. + * @throws MetaException something went wrong, usually either in the RDBMS or storage. + * @throws TException general thrift error. + */ + default void dropDatabase(String catName, String dbName) + throws NoSuchObjectException, InvalidOperationException, MetaException, TException { + dropDatabase(catName, dbName, true, false, false); + } + + + /** + * Alter a database. + * @param name database name. + * @param db new database object. + * @throws NoSuchObjectException No database of this name exists in the specified catalog. + * @throws MetaException something went wrong, usually in the RDBMS. + * @throws TException general thrift error. + */ void alterDatabase(String name, Database db) throws NoSuchObjectException, MetaException, TException; /** - * @param db_name - * @param tbl_name - * @param part_vals + * Alter a database. + * @param catName Catalog name. This can be null, in which case + * {@link Warehouse#DEFAULT_CATALOG_NAME} will be assumed. + * @param dbName database name. + * @param newDb new database object. + * @throws NoSuchObjectException No database of this name exists in the specified catalog. + * @throws MetaException something went wrong, usually in the RDBMS. + * @throws TException general thrift error. + */ + void alterDatabase(String catName, String dbName, Database newDb) + throws NoSuchObjectException, MetaException, TException; + + /** + * Drop a partition. + * @param db_name database name + * @param tbl_name table name + * @param part_vals partition values, in the same order as the partition keys * @param deleteData - * delete the underlying data or just delete the table in metadata + * delete the underlying data or just delete the partition in metadata * @return true or false - * @throws NoSuchObjectException - * @throws MetaException - * @throws TException - * @see org.apache.hadoop.hive.metastore.api.ThriftHiveMetastore.Iface#drop_partition(java.lang.String, - * java.lang.String, java.util.List, boolean) + * @throws NoSuchObjectException partition does not exist + * @throws MetaException error accessing the RDBMS or the storage. + * @throws TException thrift transport error + */ + boolean dropPartition(String db_name, String tbl_name, + List<String> part_vals, boolean deleteData) throws NoSuchObjectException, + MetaException, TException; + + /** + * Drop a partition. + * @param catName catalog name. + * @param db_name database name + * @param tbl_name table name + * @param part_vals partition values, in the same order as the partition keys + * @param deleteData + * delete the underlying data or just delete the partition in metadata + * @return true or false + * @throws NoSuchObjectException partition does not exist + * @throws MetaException error accessing the RDBMS or the storage. + * @throws TException thrift transport error + */ + boolean dropPartition(String catName, String db_name, String tbl_name, + List<String> part_vals, boolean deleteData) throws NoSuchObjectException, + MetaException, TException; + + /** + * Drop a partition with the option to purge the partition data directly, + * rather than to move data to trash. + * @param db_name Name of the database. + * @param tbl_name Name of the table. + * @param part_vals Specification of the partitions being dropped. + * @param options PartitionDropOptions for the operation. + * @return True (if partitions are dropped), else false. + * @throws NoSuchObjectException partition does not exist + * @throws MetaException error accessing the RDBMS or the storage. + * @throws TException thrift transport error. */ - boolean dropPartition(String db_name, String tbl_name, - List<String> part_vals, boolean deleteData) throws NoSuchObjectException, - MetaException, TException; + boolean dropPartition(String db_name, String tbl_name, List<String> part_vals, + PartitionDropOptions options) + throws NoSuchObjectException, MetaException, TException; /** - * Method to dropPartitions() with the option to purge the partition data directly, + * Drop a partition with the option to purge the partition data directly, * rather than to move data to trash. + * @param catName catalog name. * @param db_name Name of the database. * @param tbl_name Name of the table. * @param part_vals Specification of the partitions being dropped. * @param options PartitionDropOptions for the operation. * @return True (if partitions are dropped), else false. - * @throws TException + * @throws NoSuchObjectException partition does not exist + * @throws MetaException error accessing the RDBMS or the storage. + * @throws TException thrift transport error. */ - boolean dropPartition(String db_name, String tbl_name, List<String> part_vals, - PartitionDropOptions options) throws TException; + boolean dropPartition(String catName, String db_name, String tbl_name, List<String> part_vals, + PartitionDropOptions options) + throws NoSuchObjectException, MetaException, TException; + /** + * Drop partitions based on an expression. + * @param dbName database name. + * @param tblName table name. + * @param partExprs I don't understand this fully, so can't completely explain it. The second + * half of the object pair is an expression used to determine which partitions + * to drop. The first half has something to do with archive level, but I + * don't understand what. I'm also not sure what happens if you pass multiple + * expressions. + * @param deleteData whether to delete the data as well as the metadata. + * @param ifExists if true, it is not an error if no partitions match the expression(s). + * @return list of deleted partitions. + * @throws NoSuchObjectException No partition matches the expression(s), and ifExists was false. + * @throws MetaException error access the RDBMS or storage. + * @throws TException Thrift transport error. + */ List<Partition> dropPartitions(String dbName, String tblName, List<ObjectPair<Integer, byte[]>> partExprs, boolean deleteData, boolean ifExists) throws NoSuchObjectException, MetaException, TException; + /** + * Drop partitions based on an expression. + * @param catName catalog name. + * @param dbName database name. + * @param tblName table name. + * @param partExprs I don't understand this fully, so can't completely explain it. The second + * half of the object pair is an expression used to determine which partitions + * to drop. The first half has something to do with archive level, but I + * don't understand what. I'm also not sure what happens if you pass multiple + * expressions. + * @param deleteData whether to delete the data as well as the metadata. + * @param ifExists if true, it is not an error if no partitions match the expression(s). + * @return list of deleted partitions. + * @throws NoSuchObjectException No partition matches the expression(s), and ifExists was false. + * @throws MetaException error access the RDBMS or storage. + * @throws TException Thrift transport error. + */ + default List<Partition> dropPartitions(String catName, String dbName, String tblName, + List<ObjectPair<Integer, byte[]>> partExprs, + boolean deleteData, boolean ifExists) + throws NoSuchObjectException, MetaException, TException { + return dropPartitions(catName, dbName, tblName, partExprs, + PartitionDropOptions.instance() + .deleteData(deleteData) + .ifExists(ifExists)); + } + + /** + * Drop partitions based on an expression. + * @param dbName database name. + * @param tblName table name. + * @param partExprs I don't understand this fully, so can't completely explain it. The second + * half of the object pair is an expression used to determine which partitions + * to drop. The first half has something to do with archive level, but I + * don't understand what. I'm also not sure what happens if you pass multiple + * expressions. + * @param deleteData whether to delete the data as well as the metadata. + * @param ifExists if true, it is not an error if no partitions match the expression(s). + * @param needResults if true, the list of deleted partitions will be returned, if not, null + * will be returned. + * @return list of deleted partitions. + * @throws NoSuchObjectException No partition matches the expression(s), and ifExists was false. + * @throws MetaException error access the RDBMS or storage. + * @throws TException Thrift transport error. + * @deprecated Use {@link #dropPartitions(String, String, String, List, boolean, boolean, boolean)} + */ List<Partition> dropPartitions(String dbName, String tblName, List<ObjectPair<Integer, byte[]>> partExprs, boolean deleteData, boolean ifExists, boolean needResults) throws NoSuchObjectException, MetaException, TException; /** + * Drop partitions based on an expression. + * @param catName catalog name. + * @param dbName database name. + * @param tblName table name. + * @param partExprs I don't understand this fully, so can't completely explain it. The second + * half of the object pair is an expression used to determine which partitions + * to drop. The first half has something to do with archive level, but I + * don't understand what. I'm also not sure what happens if you pass multiple + * expressions. + * @param deleteData whether to delete the data as well as the metadata. + * @param ifExists if true, it is not an error if no partitions match the expression(s). + * @param needResults if true, the list of deleted partitions will be returned, if not, null + * will be returned. + * @return list of deleted partitions, if needResults is true + * @throws NoSuchObjectException No partition matches the expression(s), and ifExists was false. + * @throws MetaException error access the RDBMS or storage. + * @throws TException Thrift transport error. + */ + default List<Partition> dropPartitions(String catName, String dbName, String tblName, + List<ObjectPair<Integer, byte[]>> partExprs, boolean deleteData, + boolean ifExists, boolean needResults) + throws NoSuchObjectException, MetaException, TException { + return dropPartitions(catName, dbName, tblName, partExprs, + PartitionDropOptions.instance() + .deleteData(deleteData) + .ifExists(ifExists) + .returnResults(needResults)); + } + + /** * Generalization of dropPartitions(), * @param dbName Name of the database * @param tblName Name of the table * @param partExprs Partition-specification * @param options Boolean options for dropping partitions * @return List of Partitions dropped + *
<TRUNCATED>
