Overview
There are presently three ways to issue HCatalog DDL commands:
- Command line interface
- REST APIs (upcoming)
- HiveMetaStore Client
Presently, java developers go through the Hive meta store (HMS) client interface to issue HCatalog DDl commands. Though the HMS client interface is public, it is not intended for public users. According to the hive user mailing list, the HMS client is not a public API and is subject to change in the future. So, it will be a good idea to have a java APIs in HCatalog which will provide a protect users from the changes made to the hive meta store client. Also, the under the covers either the Rest APIS or the hive metastore client can be used to provide end users with the required data.
Design
New Classes
HCatClient
The HCatClient is an abstract class containing all the APIs permitted HCatalog DDL commands. The implementation class will be provided as a configuration property, which will be used by the
"create" method. In this way, the implementation details will be masked to the users.
Code Block |
---|
public abstract class HCatClient { |
– This document is a work in progress.
Overview
Templeton provides a REST-like web API for HCatalog and related Hadoop components. Developers can make HTTP requests to the Templeton web server to execute HCatalog DDL commands. With the REST APIs in place for HCatalog DDL commands, it is desirable to have a JAVA APIs in HCAT which can help end users to execute DDL commands without using CLI.
Design
New Classes
HCatClient
The HCatClient is an abstract class containing all the APIs permitted HCatalog DDL commands. The implementation class will be provided as a configuration property, which will be used by the
"create" method. In this way, the implementation details will be masked to the users.
Code Block |
---|
/** * The abstract class HCatClient containing APIs for HCatalog DDL commands. */ public abstract class HCatClient { /** * Creates an instance of HCatClient. * * @param conf An instance of configuration. * @return An instance of HCatClient. */ public HCatClient create(Configuration conf){ // Obtain details of implementation class and return an instance. } /** * Gets the database like. * * @param regex The regular expression. Providing "*" would retrieve all the names * of the databases. * @return The list of all the database names. * @throws HCatException */ public abstract List<String> getDatabaseLike(String regex) throws HCatException; /** * Gets the database. * * @param dbName The name of the database. * @return An instance of HCatDatabaseInfo. * @throws HCatException */ public abstract HCatDatabase getDatabase(String dbName) throws HCatException; /** * Creates an instance theof databaseHCatClient. * * @param dbInfoconf An instance of HCatCreateDBDescconfiguration. * @return An true,instance ifof successfulHCatClient. * @throws HCatExceptionIOException */ public abstractstatic booleanHCatClient createDatabase(HCatCreateDBDesc dbInfo)create(Configuration conf) throws IOException{ HCatClient client = HCatUtil.getHCatClient(conf); if(client throws HCatException; != null){ /** * Deletes a databaseclient.initialize(conf); * } * @param dbName The name of the database to delete.return client; } * @param ifExists Hiveabstract returns an error if the database specified does not exist,void initialize(Configuration conf) throws HCatException; /** * Get all existing databases that match the given * pattern. The matching unlessoccurs ifExistsas isper setJava toregular true.expressions * @param mode This is set to either "restrict" or "cascade". Restrict will * @param databasePattern * java re pattern remove the schema if all* the@return tableslist areof empty. Cascade removesdatabase names * @throws HCatException */ public everything including data and definitions.abstract List<String> listDatabaseNamesByPattern(String pattern) throws HCatException; /** * Gets @paramthe userGroupdatabase. The user group to use* * @param permissionsdbName The permissionsname stringof tothe use. The format is "rwxrw-r-x".database. * @return An true,instance ifof successfulHCatDatabaseInfo. * @throws HCatException */ public abstract booleanHCatDatabase deleteDatabasegetDatabase(String dbName, boolean ifExists, String mode,) throws HCatException; /** * Creates the database. * * @param StringdbInfo userGroup,An Stringinstance permissions) throws HCatException; of HCatCreateDBDesc. /** @throws HCatException */ Gets the tablespublic likeabstract avoid pattern specified.createDatabase(HCatCreateDBDesc dbInfo) * * @param dbName The name of the database.throws HCatException; /** * @paramDrops regex The regular expression. Providing "*" would retrieve all the namesa database. * * @param dbName The name of the database to delete. of* @param theifExists table. Hive returns an error if *the @returndatabase Aspecified list ofdoes allnot tableexist, names matching the specified pattern. * * @throws HCatException */ public abstractunless List<String>ifExists getTablesLike(String dbName, String regex)is set to true. * @param mode This is set to throws HCatException; /**either "restrict" or "cascade". Restrict will * Gets the table. * * @paramremove dbNamethe Theschema nameif ofall the tables database.are empty. Cascade removes * @param tableName The name of the table. * @returneverything Anincluding instancedata ofand HCatTableInfodefinitions. * @throws HCatException */ public abstract HCatTable getTable(String dbName, String tableName) abstract void dropDatabase(String dbName, boolean ifExists, String mode) throws HCatException; /** * Creates Returns all existing tables from the specified database which match the table.given * pattern. The matching occurs as per Java regular expressions. * @param dbName createTableDesc An instance of* HCatCreateTableDesc@param class.tablePattern * @return true, if successful.list of table names * @throws HCatException the h cat exception */ public abstract booleanList<String> createTable(HCatCreateTableDesc createTableDesclistTableNamesByPattern(String dbName, String tablePattern) throws HCatException; /** * CreatesGets the table like an existing table. * * @param dbName The name of the database. * @param existingTblName The name of the existing table. * @param newTableNametableName The name of the new table. * @param@return ifExistsAn theinstance ifof existsHCatTableInfo. * @param@throws isExternalHCatException Set to "true", if table has be created at a different */ public *abstract HCatTable getTable(String dbName, String tableName) location other than default.throws HCatException; /** * @param location The location* forCreates the table. * @return true, if successful * @throws@param HCatException createTableDesc An instance of HCatCreateTableDesc */class. public * abstract@throws booleanHCatException createTableLike(String dbName, String existingTblName,the h cat exception String newTableName, boolean ifExists, boolean isExternal, */ public abstract void createTable(HCatCreateTableDesc createTableDesc) String location) throws HCatException; /** * Delete aCreates the table like an existing table. * * @param dbName The name of the database. * @param tableNameexistingTblName The name of the existing table. * @param ifExists Hive returns an error if the database specified does not exist, * newTableName The name of the new table. * @param ifNotExists If true, then error related to already table existing is skipped. * @param isExternal Set to "true", if table unlesshas ifExistsbe iscreated setat toa true.different * @param userGroup The user group to use. * @param permissions The permissions string to use.location Theother format is "rwxrw-r-x"than default. * @return true, if successful@param location The location for the table. * @throws HCatException */ public abstract booleanvoid deleteTablecreateTableLike(String dbName, String tableNameexistingTblName, String newTableName, boolean ifExistsifNotExists, Stringboolean userGroupisExternal, String permissions) String location) throws HCatException; /** * Renames aDrop table. * * @param dbName The name of the database. * @param oldName The name of the table to be renameddatabase. * @param newNametableName The new name of the table. * @param userGroup The user group to use. ifExists Hive returns an error if the database specified does not exist, * @param permissions The permissions string to use. The format is "rwxrw-r-x". unless ifExists is *set @returnto true, if successful. * @throws HCatException */ public abstract booleanvoid renameTabledropTable(String dbName, String oldName, String newNametableName, String userGroup, String permissionsboolean ifExists) throws HCatException; /** * GetsRenames alla the partitionstable. * * @param dbName The name of the database. * @param tblNameoldName The name of the table to be renamed. * @param newName @returnThe Anew listname of partitionthe namestable. * @throws HCatException the h* cat@throws exceptionHCatException */ public abstract List<HCatPartition>void getPartitionsrenameTable(String dbName, String oldName, String tblNamenewName) throws HCatException; /** * Gets all throwsthe HCatException;partitions. /** * Gets @param dbName The name of the partitiondatabase. * @param tblName The name of the table. * @return @paramA dbNamelist Theof databasepartition namenames. * @throws @paramHCatException tableNamethe Theh tablecat name.exception */ @param partitionName The partitionpublic name,abstract CommaList<HCatPartition> separated list of col_name='value'. * @return An instance of HCatPartitionInfo. getPartitions(String dbName, String tblName) * @throwsthrows HCatException; /**/ * Gets publicthe abstractpartition. HCatPartition getPartition(String dbName, String tableName,* * @param dbName The database name. String partitionName) throws HCatException; * @param tableName /**The table name. * @param AddspartitionName theThe partition. name, Comma separated list *of col_name='value'. * @param partInfo@return An instance of HCatAddPartitionDescHCatPartitionInfo. * @return true, if successful@throws HCatException */ public *abstract @throwsHCatPartition HCatException the h cat exceptiongetPartition(String dbName, String tableName, */ public abstract boolean addPartition(HCatAddPartitionDescString partInfopartitionName) throws HCatException; /** * Adds Deletesthe partition. * * @param dbNamepartInfo An Theinstance databaseof nameHCatAddPartitionDesc. * @throws @paramHCatException tableNamethe Theh tablecat name.exception */ @param partitionName The partitionpublic name,abstract Commavoid separated list of col_name='value'. addPartition(HCatAddPartitionDesc partInfo) throws HCatException; /** * @param ifExists* HiveDrops returnspartition. an error if the partition* specified does not exist, unless* ifExists@param isdbName setThe todatabase truename. * @param userGrouptableName The user group to usetable name. * @param permissionspartitionName The permissionspartition stringname, toComma use.separated Thelist format is "rwxrw-r-x"of col_name='value'. * @return@param true,ifExists ifHive successful returns an error if the *partition @throwsspecified HCatException does not exist, unless ifExists */ is set to true. public abstract boolean deletePartition(String dbName,* String@throws tableName,HCatException */ public abstract void dropPartition(String partitionName, boolean ifExistsdbName, String userGrouptableName, String permissionspartitionName, boolean ifExists) throws HCatException; /** * List partitions by filter. * * @param dbName The database name. * @param tblName 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 list of partitions * @throws HCatException the h cat exception */ public abstract List<HCatPartition> listPartitionsByFilter(String dbName, String tblName, String filter) throws HCatException; /** * Mark partition for event. * * @param dbName The database name. * @param tblName The table name. * @param partKVs the part k vs * @param eventType the event type * @throws HCatException the h cat exception */ public abstract void markPartitionForEvent(String dbName, String tblName, Map<String, String> partKVs, PartitionEventType eventType) throws HCatException; /** * Checks if is partition marked for event. * * @param dbName the db name * @param tblName the tbl name * @param partKVs the part k vs * @param eventType the event type * @return true, if is partition marked for event * @throws HCatException the h cat exception */ public abstract boolean isPartitionMarkedForEvent(String dbName, String tblName, Map<String, String> partKVs, PartitionEventType eventType) throws HCatException; /** * Gets the delegation token. * * @param owner the owner * @param renewerKerberosPrincipalName the renewer kerberos principal name * @return the delegation token * @throws HCatException the h cat exception */ public abstract String getDelegationToken(String owner, String renewerKerberosPrincipalName) throws HCatException; /** * Renew delegation token. * * @param tokenStrForm the token str form * @return the long * @throws HCatException the h cat exception */ public abstract long renewDelegationToken(String tokenStrForm) throws HCatException; /** * Cancel delegation token. * * @param tokenStrForm the token str form * @throws HCatException the h cat exception */ public abstract void cancelDelegationToken(String tokenStrForm) throws HCatException; } |
HCatCommandDesc
This is an abstract class that helps in validating user input, building valid command descriptors and queries.
Code Block |
---|
/** * The Class HCatCommandDesc contains methods which help in validating, * building command descriptors and queries. */ public abstract class HCatCommandDesc{ /** * Close the hcatalog client. * * @throws HCatException the h cat exception */ public abstract void validateCommandDescclose() throws HCatException; abstract String buildQuery() throws HCatException; abstract boolean isValidationComplete(); } |
HCatCreateTableDesc
This class is a sub class of HCatCommandDesc and will be used by the users to create descriptor and validate it for the "create table" command.
HCatCreateDBDesc
This class is a sub class of HCatCommandDesc and will be used by the users to create descriptors and validate it for the "create database" command.
!createdb.png|
HCatAddPartitionDesc
This class is a sub class of HCatCommandDesc and will be used by the users to create descriptos descriptors and validate it for the "add partition" command.
HCatTable
This class encapsulates the table information returned the HCatClient implementation class and provides a uniform view to the user.
HCatDatabase
This class encapsulates the database information returned the HCatClient implementation class and provides a uniform view to the user.
HCatPartition
This class encapsulates the partition information returned the HCatClient implementation class and provides a uniform view to the user.
Usage
Code Block |
---|
Configuration config = new Configuration(); config.add("hive-site.xml"); HCatClient client = HCatClient.create(config); HCatCreateTableDesc desc = new HCatCreateTableDesc(); desc.setTableName("demo_table"); desc.setDatabaseName("db1"); desc.setFileFormat("rcfile".create(config); ArrayList<HCatFieldSchema> cols = new ArrayList<HCatFieldSchema>(); cols.add(new HCatFieldSchema("col1id", Type.INT, "comment1id columns")); cols.add(new HCatFieldSchema("col2value", Type.STRING, "comment2id columns")); desc.setCols(cols); //Validate desc.validateCommandDescHCatCreateTableDesc tableDesc = HCatCreateTableDesc.create(db, "testtable", cols).fileFormat("rcfile").build(); boolean success = client.createTable(desctableDesc); |