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

  <body>
  <section>
   <title>Description</title>
    <p>Describe an HCatalog table.  Normally returns a simple list of columns
     (using "desc table"), but the extended format will show more information (using
     "show table extended like").</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>
    <p><code>http://</code>www.myserver.com<code>/templeton/v1/ddl/database/</code>:db<code>/table/</code>:table<code>?format=extended</code></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 table name</td>
        <td>Required</td>
        <td>None</td>
    </tr>

    <tr><td><strong>format</strong></td>
        <td>Set "format=extended" to see additional information (using "show table
            extended like")</td>
        <td>Optional</td>
        <td>Not extended</td>
    </tr>
    </table>
  </section>

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

    <tr><td><strong>columns</strong></td>
        <td>A list of column names and types</td>
    </tr>

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

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

    <tr><td><strong>partitioned</strong> (extended only)</td>
        <td>True if the table is partitioned</td>
    </tr>

    <tr><td><strong>location</strong> (extended only)</td>
        <td>Location of table</td>
    </tr>

    <tr><td><strong>outputFormat</strong> (extended only)</td>
        <td>Output format</td>
    </tr>

    <tr><td><strong>owner</strong> (extended only)</td>
        <td>The owner's user name</td>
    </tr>

    <tr><td><strong>partitionColumns</strong> (extended only)</td>
        <td>List of the partition columns</td>
    </tr>

    <tr><td><strong>inputFormat</strong> (extended only)</td>
        <td>Input format</td>
    </tr>

    </table>
 </section>

  <section>
   <title>Example</title>

   <p><strong>Curl Command (simple)</strong></p>
<source>
% curl -s 'http://localhost:50111/templeton/v1/ddl/database/default/table/my_table?user.name=ctdean'
</source>

   <p><strong>JSON Output (simple)</strong></p>
<source>
{
 "columns": [
   {
     "name": "id",
     "type": "bigint"
   },
   {
     "name": "user",
     "comment": "The user name",
     "type": "string"
   },
   {
     "name": "my_p",
     "type": "string"
   },
   {
     "name": "my_q",
     "type": "string"
   }
 ],
 "database": "default",
 "table": "my_table"
}
</source>

   <p><strong>Curl Command (extended)</strong></p>
<source>
% curl -s 'http://localhost:50111/templeton/v1/ddl/database/default/table/test_table?user.name=ctdean&amp;format=extended'
</source>

   <p><strong>JSON Output (extended)</strong></p>
<source>
{
  "partitioned": true,
  "location": "hdfs://ip-10-77-6-151.ec2.internal:8020/apps/hive/warehouse/test_table",
  "outputFormat": "org.apache.hadoop.hive.ql.io.RCFileOutputFormat",
  "columns": [
    {
      "name": "id",
      "type": "bigint"
    },
    {
      "name": "price",
      "comment": "The unit price",
      "type": "float"
    }
  ],
  "owner": "ctdean",
  "partitionColumns": [
    {
      "name": "country",
      "type": "string"
    }
  ],
  "inputFormat": "org.apache.hadoop.hive.ql.io.RCFileInputFormat",
  "database": "default",
  "table": "test_table"
}
</source>

   <p><strong>JSON Output (error)</strong></p>
<source>
{
  "error": "Table xtest_table does not exist",
  "errorCode": 404,
  "database": "default",
  "table": "xtest_table"
}
</source>

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