<?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>POST ddl </title>
  </header>

  <body>
  <section>
   <title>Description</title>
    <p>Performs an <a href="http://incubator.apache.org/hcatalog/docs/r0.2.0/cli.html">
        HCatalog DDL</a> command.  The command is executed immediately upon request.
        Responses are limited to 1MB.  For requests which may return longer results
        consider using the <a href="hive.html">Hive resource</a> as an alternative.</p>
  </section>

  <section>
   <title>URL</title>
    <p><code>http://</code>www.myserver.com<code>/templeton/v1/ddl</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>exec</strong></td>
        <td>The HCatalog ddl string to execute</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.  The format is
          "<code>rwxrw-r-x</code>".</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>stdout</strong></td>
      <td>A string containing the result HCatalog sent to standard out (possibly empty).</td>
      </tr>

      <tr><td><strong>stderr</strong></td>
        <td>A string containing the result HCatalog sent to standard error
        (possibly empty).</td>
      </tr>

      <tr><td><strong>exitcode</strong></td>
        <td>The exitcode HCatalog returned.</td>
      </tr>
     </table>
 </section>

 <section>
   <title>Example</title>

   <p><strong>Curl Command</strong></p>
<source>
% curl -s -d user.name=ctdean \
       -d 'exec=show tables;' \
       'http://localhost:50111/templeton/v1/ddl'
</source>

   <p><strong>JSON Output</strong></p>
<source>
{
 "stdout": "important_table
            my_other_table
            my_table
            my_table_2
            pokes
            ",
 "stderr": "WARNING: org.apache.hadoop.metrics.jvm.EventCounter is deprecated...
            Hive history file=/tmp/ctdean/hive_job_log_ctdean_201111111258_2117356679.txt
            OK
            Time taken: 1.202 seconds
            ",
 "exitcode": 0
}
</source>

   <p><strong>JSON Output (error)</strong></p>
<source>
{
  "stdout": "",
  "stderr": "WARNING: org.apache.hadoop.metrics.jvm.EventCounter is deprecated...
            Hive history file=/tmp/ctdean/hive_job_log_ctdean_201204051246_689834593.txt
            FAILED: Parse Error: line 1:5 Failed to recognize predicate 'tab'...

            ",
  "exitcode": 11
}
</source>

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