<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">

<document>
  <header>
    <title>Command Line Interface</title>
  </header>
  <body>

<!-- ==================================================================== -->
<section>
	<title>Set Up</title>
<p>The HCatalog command line interface (CLI) can be invoked as
<code>HIVE_HOME=</code><em>hive_home hcat_home</em><code>/bin/hcat</code>
where <em>hive_home</em> is the directory where Hive has been installed and
<em>hcat_home</em> is the directory where HCatalog has been installed.</p>

<p>If you are using BigTop's rpms or debs you can invoke the CLI by doing
<code>/usr/bin/hcat</code>.</p>


</section>

<section>
<title>HCatalog CLI</title>

<p>The HCatalog CLI supports these command line options:</p>

<table>
  <tr>
    <th><p class="center">Option</p></th>
    <th><p class="center">Usage</p></th>
    <th><p class="center">Description</p></th>
  </tr>
  <tr>
    <td><p class="cell"><strong>-g</strong></p></td>
    <td><p class="cell"><code>hcat -g mygroup ...</code></p></td>
    <td><p class="cell">Tells HCatalog that the table which needs to be created must have group "mygroup".</p></td>
  </tr>
  <tr>
    <td><p class="cell"><strong>-p</strong></p></td>
    <td><p class="cell"><code>hcat -p rwxr-xr-x ...</code></p></td>
    <td><p class="cell">Tells HCatalog that the table which needs to be created must have permissions "rwxr-xr-x".</p></td>
  </tr>
  <tr>
    <td><p class="cell"><strong>-f</strong></p></td>
    <td><p class="cell"><code>hcat -f myscript.hcatalog ...</code></p></td>
    <td><p class="cell">Tells HCatalog that myscript.hcatalog is a file containing DDL commands to execute.</p></td>
  </tr>
  <tr>
    <td><p class="cell"><strong>-e</strong></p></td>
    <td><p class="cell"><code>hcat -e 'create table mytable(a int);' ...</code></p></td>
    <td><p class="cell">Tells HCatalog to treat the following string as a DDL command and execute it.</p></td>
  </tr>
  <tr>
    <td><p class="cell"><strong>-D</strong></p></td>
    <td><p class="cell"><code>hcat -D</code><em>key</em>=<em>value</em><code> ...</code></p></td>
    <td><p class="cell">Passes the key-value pair to HCatalog as a Java System Property.</p></td>
  </tr>
  <tr>
    <td></td>
    <td><p class="cell"><code>hcat</code></p></td>
    <td><p class="cell">Prints a usage message.</p></td>
  </tr>
</table>

<p>Note the following:</p>
<ul>
<li>The <strong>-g</strong> and <strong>-p</strong> options are not mandatory. 
</li>
<li>Only one <strong>-e</strong> or <strong>-f</strong> option can be provided, not both. 
</li>
<li>The order of options is immaterial; you can specify the options in any order. 
</li>
</ul>
<p>If no option is provided, then a usage message is printed:</p>
<source>
Usage:  hcat  { -e "&lt;query&gt;" | -f &lt;filepath&gt; }  [-g &lt;group&gt;] [-p &lt;perms&gt;] [-D&lt;name&gt;=&lt;value&gt;]
</source>
<p></p>

<p><strong>Owner Permissions</strong></p>
<p>When using the HCatalog CLI, you cannot specify a permission string without read permissions for owner, such as -wxrwxr-x, because the string begins with "-". 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.</p>
	
</section>

<!-- ==================================================================== -->
<section>
	<title>HCatalog DDL</title>
	
<p>HCatalog supports all <a href="http://wiki.apache.org/hadoop/Hive/LanguageManual/DDL">Hive Data Definition Language</a> except those operations that require running a MapReduce job. For commands that are supported, any variances are noted below.</p>
<p>HCatalog does not support the following Hive DDL commands:</p> 
   <ul>
     <li>IMPORT FROM ...</li>
     <li>EXPORT TABLE</li>
     <li>CREATE TABLE ... AS SELECT</li> 
     <li>ALTER TABLE ... REBUILD</li> 
     <li>ALTER TABLE ... CONCATENATE</li>
     <li>ANALYZE TABLE ... COMPUTE STATISTICS</li>
     <li>ALTER TABLE ARCHIVE/UNARCHIVE PARTITION</li>
   </ul>

<section>
	<title>Create/Drop/Alter Table</title>


<p><strong>CREATE TABLE</strong></p>	

<p>If you create a table with a CLUSTERED BY clause you will not be able to write to it with Pig or MapReduce. This is because they do not understand how to partition the table, so attempting to write to it would cause data corruption.</p>

<p></p>
<p><strong>CREATE TABLE AS SELECT</strong></p>
<p>Not supported. Throws an exception with the message "Operation Not Supported". </p>	
	
<p><strong>DROP TABLE</strong></p>
<p>Supported. Behavior the same as Hive.</p>	


<!-- ==================================================================== -->
<p><strong>ALTER TABLE</strong></p>

<p>Supported except for the REBUILD and CONCATENATE options. Behavior the same as Hive.</p>

<p></p>
	
</section>

<!-- ==================================================================== -->
<section>
	<title>Create/Drop/Alter View</title>
<p>Note: Pig and MapReduce cannot read from or write to views.</p>

<p><strong>CREATE VIEW</strong></p>	
<p>Supported. Behavior same as Hive.</p>		
	
<p><strong>DROP VIEW</strong></p>	
<p>Supported. Behavior same as Hive.</p>		

<p><strong>ALTER VIEW</strong></p>	
<p>Supported. Behavior same as Hive.</p>		

</section>

<!-- ==================================================================== -->
<section>
	<title>Show/Describe </title>
	
<p><strong>SHOW TABLES</strong></p>
<p>Supported. Behavior same as Hive.</p>

<p><strong>SHOW PARTITIONS</strong></p>
<p>Not supported. Throws an exception with message "Operation Not Supported". </p>	

<p><strong>SHOW FUNCTIONS</strong></p>
<p>Supported. Behavior same as Hive.</p>	

<p><strong>DESCRIBE</strong></p>
<p>Supported. Behavior same as Hive.</p>

</section>

	<!-- ==================================================================== -->
<section>
	<title>Create/Drop Index</title>

<p>CREATE and DROP INDEX operations are supported.</p>
<p>Note: Pig and MapReduce cannot write to a table that has auto rebuild on, because Pig and MapReduce do not know how to rebuild the index.</p>
</section>

	<!-- ==================================================================== -->
<section>
	<title>Create/Drop Function</title>

<p>CREATE and DROP FUNCTION operations are supported, but created functions must still be registered in Pig and placed in CLASSPATH for MapReduce.</p>

</section>
	
	<!-- ==================================================================== -->
<section>
	<title>"dfs" Command and "set" Command</title>
	<p>Supported. Behavior same as Hive.</p>
</section>
<section>
	<title>Other Commands</title>
	<p>Any command not listed above is NOT supported and throws an exception with the message "Operation Not Supported". </p>
</section>

</section>

<section>
    <title>CLI Errors</title>
<p><strong>Authentication</strong></p>
<table>
	<tr>
	<td><p>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/&lt;username&gt;/hive.log, then make sure you have run "kinit &lt;username&gt;@FOO.COM" to get a Kerberos ticket and to be able to authenticate to the HCatalog server. </p></td>
	</tr>
</table>

<p><strong>Error Log</strong></p>

<p>If other errors occur while using the HCatalog CLI, more detailed messages are written to /tmp/&lt;username&gt;/hive.log. </p>

</section>

  </body>
</document>
