<?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>PUT ddl/database/:db/table/:table</title>
  </header>

  <body>
  <section>
   <title>Description</title>
    <p>Create a new HCatalog table. For more information, please refer to the
     <a href="https://cwiki.apache.org/Hive/languagemanual-ddl.html#LanguageManualDDL-CreateTable">Hive documentation.</a></p>
  </section>

  <section>
   <title>URL</title>
    <p><code>http://</code>www.myserver.com<code>/templeton/v1/ddl/database/</code>:db<code>/table/</code>:table</p>
  </section>

  <section>
   <title>Parameters</title>
    <table>
    <tr><th>Name</th><th>Description</th><th>Required?</th><th>Default</th></tr>

    <tr><td><strong>:db</strong></td>
        <td>The database name</td>
        <td>Required</td>
        <td>None</td>
    </tr>

    <tr><td><strong>:table</strong></td>
        <td>The new table name</td>
        <td>Required</td>
        <td>None</td>
    </tr>

    <tr><td><strong>group</strong></td>
        <td>The user group to use when creating a table</td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    <tr><td><strong>permissions</strong></td>
        <td>The permissions string to use when creating a table.</td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    <tr><td><strong>external</strong></td>
        <td>Allows you to specify a location so that Hive does not use the default
            location for this table.</td>
        <td>Optional</td>
        <td>false</td>
    </tr>

    <tr><td><strong>ifNotExists</strong></td>
        <td>If true, you will not receive an error if the table already exists.</td>
        <td>Optional</td>
        <td>false</td>
    </tr>

    <tr><td><strong>comment</strong></td>
        <td>Comment for the table</td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    <tr><td><strong>columns</strong></td>
        <td>A list of column descriptions, including name, type, and an optional comment.</td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    <tr><td><strong>partitionedBy</strong></td>
        <td>A list of column descriptions used to partition the table.  Like the columns
          parameter this is a list of name, type, and comment fields.</td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    <tr><td><strong>clusteredBy</strong></td>
        <td>An object describing how to cluster the table including the parameters
         columnNames, sortedBy, numberOfBuckets.  The sortedBy parameter includes
         the parameters columnName and order.  For further information
         please refer to the examples below or to the
         <a href="https://cwiki.apache.org/Hive/languagemanual-ddl.html#LanguageManualDDL-CreateTable">
         Hive documentation.</a></td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    <tr><td><strong>format</strong></td>
        <td>Storage format description including paraeters for rowFormat, storedAs
         and storedBy.  For further information please refer to the examples below or to the
         <a href="https://cwiki.apache.org/Hive/languagemanual-ddl.html#LanguageManualDDL-CreateTable">
         Hive documentation.</a></td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    <tr><td><strong>location</strong></td>
        <td>The HDFS path</td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    <tr><td><strong>tableProperties</strong></td>
        <td>A list of table property names and values (key/value pairs)</td>
        <td>Optional</td>
        <td>None</td>
    </tr>

    </table>
  </section>

  <section>
   <title>Results</title>
    <table>
    <tr><th>Name</th><th>Description</th></tr>

    <tr><td><strong>table</strong></td>
        <td>The new table name</td>
    </tr>

    <tr><td><strong>database</strong></td>
        <td>The database name</td>
    </tr>

    </table>
 </section>

  <section>
   <title>Example</title>

   <p><strong>Curl Command</strong></p>
<source>
% curl -s -X PUT -HContent-type:application/json -d '{
 "comment": "Best table made today",
 "columns": [
   { "name": "id", "type": "bigint" },
   { "name": "price", "type": "float", "comment": "The unit price" } ],
 "partitionedBy": [
   { "name": "country", "type": "string" } ],
 "format": { "storedAs": "rcfile" } }' \
 'http://localhost:50111/templeton/v1/ddl/database/default/table/test_table?user.name=ctdean'
</source>

   <p><strong>Curl Command (using clusteredBy)</strong></p>
<source>
% curl -s -X PUT -HContent-type:application/json -d '{
  "comment": "Best table made today",
  "columns": [
    { "name": "id", "type": "bigint"},
    { "name": "price", "type": "float", "comment": "The unit price" } ],
  "partitionedBy": [
    { "name": "country", "type": "string" } ],
  "clusteredBy": {
    "columnNames": ["id"],
    "sortedBy": [
      { "columnName": "id", "order": "ASC" } ],
    "numberOfBuckets": 10 },
  "format": {
    "storedAs": "rcfile",
    "rowFormat": {
      "fieldsTerminatedBy": "\u0001",
      "serde": {
        "name": "org.apache.hadoop.hive.serde2.columnar.ColumnarSerDe",
        "properties": {
          "key": "value" } } } }
  } ' \
  'http://localhost:50111/templeton/v1/ddl/database/default/table/test_table_c?user.name=ctdean'
</source>

   <p><strong>JSON Output</strong></p>
<source>
{
 "table": "test_table",
 "database": "default"
}
</source>

   <p><strong>JSON Output (error)</strong></p>
<source>
{
  "statement": "use default; create table test_table_c(id bigint, price float comment ...",
  "error": "unable to create table: test_table_c",
  "exec": {
    "stdout": "",
    "stderr": "WARNING: org.apache.hadoop.metrics.jvm.EventCounter is deprecated...
        Hive history file=/tmp/ctdean/hive_job_log_ctdean_201204051335_2016086186.txt
        SLF4J: Class path contains multiple SLF4J bindings.
        SLF4J: Found binding in ...
        SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
        OK
        Time taken: 0.448 seconds
        FAILED: Error in semantic analysis: Operation not supported. HCatalog doesn't allow Clustered By in create table.
        ",
    "exitcode": 10
  }
}
</source>

  </section>
 </body>
</document>
