Command Line Interface

The HCatalog command line interface (CLI) can be invoked as hcat.

Authentication

If a failure results in a message like "2010-11-03 16:17:28,225 WARN hive.metastore ... - Unable to connect metastore with URI thrift://..." in /tmp/<username>/hive.log, then make sure you have run "kinit <username>@FOO.COM" to get a kerberos ticket and to be able to authenticate to the HCatalog server.

If other errors occur while using the HCatalog CLI, more detailed messages (if any) are written to /tmp/<username>/hive.log.

The HCatalog CLI supports these command line options:

• -g: Usage is -g mygroup .... This indicates to HCatalog that table that needs to be created must have group as "mygroup"
• -p: Usage is -p rwxr-xr-x .... This indicates to HCatalog that table that needs to be created must have permissions as "rwxr-xr-x"
• -f: Usage is -f myscript.hcatalog .... This indicates to hcatalog that myscript.hcatalog is a file which contains DDL commands it needs to execute.
• -e: Usage is -e 'create table mytable(a int);' .... This indicates to HCatalog to treat the following string as DDL command and execute it.

Note the following:

• The -g and -p options are not mandatory.
• Only one of the -e or -f option can be provided, not both.
• The order of options is immaterial; you can specify the options in any order.
• If no option is provided, then a usage message is printed:

  Usage: hcat  { -e "<query>" | -f "<filepath>" } [-g "<group>" ] [-p "<perms>"]
  

Assumptions

When using the HCatalog CLI, you cannot specify a permission string without read permissions for owner, such as -wxrwxr-x. If such a permission setting is desired, you can use the octal version instead, which in this case would be 375. Also, any other kind of permission string where the owner has read permissions (for example r-x------ or r--r--r--) will work fine.

HCatalog supports a subset of the Hive Data Definition Language. For those commands that are supported, any variances are noted below.

Create/Drop/Alter Table

CREATE TABLE

The STORED AS clause in Hive is:

[STORED AS file_format]
file_format:
  : SEQUENCEFILE
  | TEXTFILE
  | RCFILE     
  | INPUTFORMAT input_format_classname OUTPUTFORMAT output_format_classname

The STORED AS clause in HCatalog is:

[STORED AS file_format]
file_format:
  : RCFILE     
  | INPUTFORMAT input_format_classname OUTPUTFORMAT output_format_classname 
                   INPUTDRIVER input_driver_classname OUTPUTDRIVER output_driver_classname

Note the following:

• CREATE TABLE command must contain a "STORED AS" clause; if it doesn't it will result in an exception containing message "STORED AS specification is either incomplete or incorrect."
  
  

  In this release, HCatalog supports only reading PigStorage formated text files and only writing RCFile formatted files. Therefore, for this release, the command must contain a "STORED AS" clause and either use RCFILE as the file format or specify org.apache.hadoop.hive.ql.io.RCFileInputFormat and org.apache.hadoop.hive.ql.io.RCFileOutputFormat as INPUTFORMAT and OUTPUTFORMAT respectively.

  
  
• For partitioned tables, partition columns can only be of type String.
• CLUSTERED BY clause is not supported. If provided error message will contain "Operation not supported. HCatalog doesn't allow Clustered By in create table."

CREATE TABLE AS SELECT

Not supported. Throws an exception with message "Operation Not Supported".

CREATE TABLE LIKE

Not supported. Throws an exception with message "Operation Not Supported".

DROP TABLE

Supported. Behavior the same as Hive.

ALTER TABLE

ALTER TABLE table_name ADD partition_spec [ LOCATION 'location1' ] partition_spec [ LOCATION 'location2' ] ...
 partition_spec:
  : PARTITION (partition_col = partition_col_value, partition_col = partiton_col_value, ...)

Note the following:

• Allowed only if TABLE table_name was created using HCatalog. Else, throws an exception containing error message "Operation not supported. Partitions can be added only in a table created through HCatalog. It seems table tablename was not created through HCatalog"

ALTER TABLE FILE FORMAT

ALTER TABLE table_name SET FILEFORMAT file_format 

Note the following:

• Here file_format must be same as the one described above in CREATE TABLE. Else, throw an exception "Operation not supported. Not a valid file format."
• CLUSTERED BY clause is not supported. If provided will result in an exception "Operation not supported."

ALTER TABLE Change Column Name/Type/Position/Comment

ALTER TABLE table_name CHANGE [COLUMN] col_old_name col_new_name column_type [COMMENT col_comment] [FIRST|AFTER column_name]

Not supported. Throws an exception with message "Operation Not Supported".

ALTER TABLE Add/Replace Columns

ALTER TABLE table_name ADD|REPLACE COLUMNS (col_name data_type [COMMENT col_comment], ...)

Note the following:

• ADD Columns is allowed. Behavior same as of Hive.
• Replace column is not supported. Throws an exception with message "Operation Not Supported".

ALTER TABLE TOUCH

ALTER TABLE table_name TOUCH;
ALTER TABLE table_name TOUCH PARTITION partition_spec;

Not supported. Throws an exception with message "Operation Not Supported".

Create/Drop/Alter View

CREATE VIEW

Not supported. Throws an exception with message "Operation Not Supported".

DROP VIEW

Not supported. Throws an exception with message "Operation Not Supported".

ALTER VIEW

Not supported. Throws an exception with message "Operation Not Supported".

Show/Describe

SHOW TABLES

Supported. Behavior same as Hive.

SHOW PARTITIONS

Not supported. Throws an exception with message "Operation Not Supported".

SHOW FUNCTIONS

Supported. Behavior same as Hive.

DESCRIBE

Supported. Behavior same as Hive.

Other Commands

Any command not listed above is NOT supported and throws an exception with message "Operation Not Supported".