| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia at 2017-01-25 |
| | Rendered using Apache Maven Fluido Skin 1.3.0 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="Date-Revision-yyyymmdd" content="20170125" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>AsterixDB – HTTP API to AsterixDB</title> |
| <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" /> |
| <link rel="stylesheet" href="./css/site.css" /> |
| <link rel="stylesheet" href="./css/print.css" media="print" /> |
| |
| |
| <script type="text/javascript" src="./js/apache-maven-fluido-1.3.0.min.js"></script> |
| |
| |
| |
| <script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-41536543-1', 'uci.edu'); |
| ga('send', 'pageview');</script> |
| |
| </head> |
| <body class="topBarDisabled"> |
| |
| |
| |
| |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"> |
| <a href="./" id="bannerLeft"> |
| <img src="images/asterixlogo.png" alt="AsterixDB"/> |
| </a> |
| </div> |
| <div class="pull-right"> </div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| |
| |
| <li id="publishDate">Last Published: 2017-01-25</li> |
| |
| |
| |
| <li id="projectVersion" class="pull-right">Version: 0.9.0</li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="index.html" title="Documentation Home"> |
| Documentation Home</a> |
| </li> |
| |
| </ul> |
| </div> |
| |
| |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span3"> |
| <div class="well sidebar-nav"> |
| |
| |
| <ul class="nav nav-list"> |
| <li class="nav-header">Get Started - Installation</li> |
| |
| <li> |
| |
| <a href="ncservice.html" title="Option 1: using NCService"> |
| <i class="none"></i> |
| Option 1: using NCService</a> |
| </li> |
| |
| <li> |
| |
| <a href="install.html" title="Option 2: using Managix"> |
| <i class="none"></i> |
| Option 2: using Managix</a> |
| </li> |
| |
| <li> |
| |
| <a href="yarn.html" title="Option 3: using YARN"> |
| <i class="none"></i> |
| Option 3: using YARN</a> |
| </li> |
| <li class="nav-header">AsterixDB Primer</li> |
| |
| <li> |
| |
| <a href="sqlpp/primer-sqlpp.html" title="Option 1: using SQL++"> |
| <i class="none"></i> |
| Option 1: using SQL++</a> |
| </li> |
| |
| <li> |
| |
| <a href="aql/primer.html" title="Option 2: using AQL"> |
| <i class="none"></i> |
| Option 2: using AQL</a> |
| </li> |
| <li class="nav-header">Data Model</li> |
| |
| <li> |
| |
| <a href="datamodel.html" title="The Asterix Data Model"> |
| <i class="none"></i> |
| The Asterix Data Model</a> |
| </li> |
| <li class="nav-header">Queries - SQL++</li> |
| |
| <li> |
| |
| <a href="sqlpp/manual.html" title="The SQL++ Query Language"> |
| <i class="none"></i> |
| The SQL++ Query Language</a> |
| </li> |
| |
| <li> |
| |
| <a href="sqlpp/builtins.html" title="Builtin Functions"> |
| <i class="none"></i> |
| Builtin Functions</a> |
| </li> |
| <li class="nav-header">Queries - AQL</li> |
| |
| <li> |
| |
| <a href="aql/manual.html" title="The Asterix Query Language (AQL)"> |
| <i class="none"></i> |
| The Asterix Query Language (AQL)</a> |
| </li> |
| |
| <li> |
| |
| <a href="aql/builtins.html" title="Builtin Functions"> |
| <i class="none"></i> |
| Builtin Functions</a> |
| </li> |
| <li class="nav-header">Advanced Features</li> |
| |
| <li> |
| |
| <a href="aql/similarity.html" title="Support of Similarity Queries"> |
| <i class="none"></i> |
| Support of Similarity Queries</a> |
| </li> |
| |
| <li> |
| |
| <a href="aql/fulltext.html" title="Support of Full-text Queries"> |
| <i class="none"></i> |
| Support of Full-text Queries</a> |
| </li> |
| |
| <li> |
| |
| <a href="aql/externaldata.html" title="Accessing External Data"> |
| <i class="none"></i> |
| Accessing External Data</a> |
| </li> |
| |
| <li> |
| |
| <a href="feeds/tutorial.html" title="Support for Data Ingestion"> |
| <i class="none"></i> |
| Support for Data Ingestion</a> |
| </li> |
| |
| <li> |
| |
| <a href="udf.html" title="User Defined Functions"> |
| <i class="none"></i> |
| User Defined Functions</a> |
| </li> |
| |
| <li> |
| |
| <a href="aql/filters.html" title="Filter-Based LSM Index Acceleration"> |
| <i class="none"></i> |
| Filter-Based LSM Index Acceleration</a> |
| </li> |
| <li class="nav-header">API/SDK</li> |
| |
| <li class="active"> |
| |
| <a href="#"><i class="none"></i>HTTP API</a> |
| </li> |
| </ul> |
| |
| |
| |
| <hr class="divider" /> |
| |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="./" title="AsterixDB" class="builtBy"> |
| <img class="builtBy" alt="AsterixDB" src="images/asterixlogo.png" /> |
| </a> |
| </div> |
| </div> |
| </div> |
| |
| |
| <div id="bodyColumn" class="span9" > |
| |
| <!-- ! 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. |
| ! --><h1>HTTP API to AsterixDB</h1> |
| <div class="section"> |
| <h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2> |
| |
| <ul> |
| |
| <li><a href="#DdlApi">DDL API</a></li> |
| |
| <li><a href="#UpdateApi">Update API</a></li> |
| |
| <li><a href="#QueryApi">Query API</a></li> |
| |
| <li><a href="#AnyApi">Mixed API</a></li> |
| |
| <li><a href="#AsynchronousResultApi">Asynchronous Result API</a></li> |
| |
| <li><a href="#QueryStatusApi">Query Status API</a></li> |
| |
| <li><a href="#ErrorCodes">Error Codes</a></li> |
| </ul></div> |
| <div class="section"> |
| <h2><a name="DDL_API_Back_to_TOC"></a><a name="DdlApi" id="DdlApi">DDL API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2> |
| <p><i>End point for the data definition statements</i></p> |
| <p>Endpoint: <i>/ddl</i></p> |
| <p>Parameters:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <td>Parameter</td> |
| |
| <td>Description</td> |
| |
| <td>Required?</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ddl</td> |
| |
| <td>String containing DDL statements to modify Metadata</td> |
| |
| <td>Yes</td> |
| </tr> |
| </table> |
| <p>This call does not return any result. If the operations were successful, HTTP OK status code is returned.</p> |
| <div class="section"> |
| <h3><a name="Example"></a>Example</h3> |
| <div class="section"> |
| <h4><a name="DDL_Statements"></a>DDL Statements</h4> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> drop dataverse company if exists; |
| create dataverse company; |
| use dataverse company; |
| |
| create type Emp as open { |
| id : int32, |
| name : string |
| }; |
| |
| create dataset Employee(Emp) primary key id; |
| </pre></div></div> |
| <p>API call for the above DDL statements in the URL-encoded form.</p> |
| <p>[http://localhost:19002/ddl?ddl=drop%20dataverse%20company%20if%20exists;create%20dataverse%20company;use%20dataverse%20company;create%20type%20Emp%20as%20open%20{id%20:%20int32,name%20:%20string};create%20dataset%20Employee(Emp)%20primary%20key%20id;](<a class="externalLink" href="http://localhost:19002/ddl?ddl=drop%20dataverse%20company%20if%20exists;create%20dataverse%20company;use%20dataverse%20company;create%20type%20Emp%20as%20open%20{id%20:%20int32,name%20:%20string};create%20dataset%20Employee(Emp)%20primary%20key%20id;">http://localhost:19002/ddl?ddl=drop%20dataverse%20company%20if%20exists;create%20dataverse%20company;use%20dataverse%20company;create%20type%20Emp%20as%20open%20{id%20:%20int32,name%20:%20string};create%20dataset%20Employee(Emp)%20primary%20key%20id;</a>)</p></div> |
| <div class="section"> |
| <h4><a name="Response"></a>Response</h4> |
| <p><i>HTTP OK 200</i><br /><tt><NO PAYLOAD></tt></p></div></div></div> |
| <div class="section"> |
| <h2><a name="Update_API_Back_to_TOC"></a><a name="UpdateApi" id="UpdateApi">Update API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2> |
| <p><i>End point for update statements (INSERT, DELETE and LOAD)</i></p> |
| <p>Endpoint: <i>/update</i></p> |
| <p>Parameters:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <td>Parameter</td> |
| |
| <td>Description</td> |
| |
| <td>Required?</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>statements</td> |
| |
| <td>String containing update (insert/delete) statements to execute</td> |
| |
| <td>Yes</td> |
| </tr> |
| </table> |
| <p>This call does not return any result. If the operations were successful, HTTP OK status code is returned.</p> |
| <div class="section"> |
| <h3><a name="Example"></a>Example</h3> |
| <div class="section"> |
| <h4><a name="Update_Statements"></a>Update Statements</h4> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> use dataverse company; |
| |
| insert into dataset Employee({ "id":123,"name":"John Doe"}); |
| </pre></div></div> |
| <p>API call for the above update statement in the URL-encoded form.</p> |
| <p>[http://localhost:19002/update?statements=use%20dataverse%20company;insert%20into%20dataset%20Employee({%20%22id%22:123,%22name%22:%22John%20Doe%22});](<a class="externalLink" href="http://localhost:19002/update?statements=use%20dataverse%20company;insert%20into%20dataset%20Employee({%20%22id%22:123,%22name%22:%22John%20Doe%22});">http://localhost:19002/update?statements=use%20dataverse%20company;insert%20into%20dataset%20Employee({%20%22id%22:123,%22name%22:%22John%20Doe%22});</a>)</p></div> |
| <div class="section"> |
| <h4><a name="Response"></a>Response</h4> |
| <p><i>HTTP OK 200</i><br /><tt><NO PAYLOAD></tt></p></div></div></div> |
| <div class="section"> |
| <h2><a name="Query_API_Back_to_TOC"></a><a name="QueryApi" id="QueryApi">Query API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2> |
| <p><i>End point for query statements</i></p> |
| <p>Endpoint: <i>/query</i></p> |
| <p>Parameters:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <td>Parameter</td> |
| |
| <td>Description</td> |
| |
| <td>Required?</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>query</td> |
| |
| <td>Query string to pass to ASTERIX for execution</td> |
| |
| <td>Yes</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>mode</td> |
| |
| <td>Indicate if call should be synchronous or asynchronous. mode = synchronous blocks the call until results are available; mode = asynchronous returns immediately with a handle that can be used later to check the query’s status and to fetch results when available</td> |
| |
| <td>No. default mode = synchronous</td> |
| </tr> |
| </table> |
| <p>Result: The result is returned as a JSON object as follows</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> { |
| results: <result as a string, if mode = synchronous> |
| error-code: [<code>, <message>] (if an error occurs) |
| handle: <opaque result handle, if mode = asynchronous> |
| } |
| </pre></div></div> |
| <div class="section"> |
| <h3><a name="Example"></a>Example</h3> |
| <div class="section"> |
| <h4><a name="Select_query_with_synchronous_result_delivery"></a>Select query with synchronous result delivery</h4> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> use dataverse company; |
| |
| for $l in dataset('Employee') return $l; |
| </pre></div></div> |
| <p>API call for the above query statement in the URL-encoded form.</p> |
| <p>[http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset(‘Employee’)%20return%20$l;](<a class="externalLink" href="http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset('Employee')%20return%20$l;">http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset('Employee')%20return%20$l;</a>)</p></div> |
| <div class="section"> |
| <h4><a name="Response"></a>Response</h4> |
| <p><i>HTTP OK 200</i><br />Payload</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> { |
| "results": [ |
| [ |
| "{ "id": 123, "name": "John Doe" }" |
| ] |
| ] |
| } |
| </pre></div></div></div> |
| <div class="section"> |
| <h4><a name="Same_select_query_with_asynchronous_result_delivery"></a>Same select query with asynchronous result delivery</h4> |
| <p>API call for the above query statement in the URL-encoded form with mode=asynchronous</p> |
| <p>[http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset(‘Employee’)%20return%20$l;&mode=asynchronous](<a class="externalLink" href="http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset('Employee')%20return%20$l;&mode=asynchronous">http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset('Employee')%20return%20$l;&mode=asynchronous</a>)</p></div> |
| <div class="section"> |
| <h4><a name="Response"></a>Response</h4> |
| <p><i>HTTP OK 200</i><br />Payload</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> { |
| "handle": [45,0] |
| } |
| </pre></div></div></div></div></div> |
| <div class="section"> |
| <h2><a name="Mixed_API_Back_to_TOC"></a><a name="AnyApi" id="AnyApi">Mixed API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2> |
| <p><i>End point for any/mixed statement</i></p> |
| <p>Endpoint: <i>/aql</i></p> |
| <p>Parameters:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <td>Parameter</td> |
| |
| <td>Description</td> |
| |
| <td>Required?</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>query</td> |
| |
| <td>Query string to pass to ASTERIX for execution</td> |
| |
| <td>Yes</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>mode</td> |
| |
| <td>Indicate if call should be synchronous or asynchronous. mode = synchronous blocks the call until results are available; mode = asynchronous returns immediately with a handle that can be used later to check the query’s status and to fetch results when available</td> |
| |
| <td>No. default mode = synchronous</td> |
| </tr> |
| </table> |
| <p>Similar to <i><i>/update</i></i> but allows any arbitrary AQL statement rather than only modifications.</p></div> |
| <div class="section"> |
| <h2><a name="Asynchronous_Result_API_Back_to_TOC"></a><a name="AsynchronousResultApi" id="AsynchronousResultApi">Asynchronous Result API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2> |
| <p><i>End point to fetch the results of an asynchronous query</i></p> |
| <p>Endpoint: <i>/query/result</i></p> |
| <p>Parameters:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <td>Parameter</td> |
| |
| <td>Description</td> |
| |
| <td>Required?</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>handle</td> |
| |
| <td>Result handle that was returned by a previous call to a /query call with mode = asynchronous</td> |
| |
| <td>Yes</td> |
| </tr> |
| </table> |
| <p>Result: The result is returned as a JSON object as follows:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> { |
| results: <result as a string, if mode = synchronous, or mode = asynchronous and results are available> |
| error-code: [<code>, <message>] (if an error occurs) |
| } |
| </pre></div></div> |
| <p>If mode = asynchronous and results are not available, the returned JSON object is empty: { }</p> |
| <div class="section"> |
| <h3><a name="Example"></a>Example</h3> |
| <div class="section"> |
| <h4><a name="Fetching_results_for_asynchronous_query"></a>Fetching results for asynchronous query</h4> |
| <p>We use the handle returned by the asynchronous query to get the results for the query. The handle returned was:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> { |
| "handle": [45,0] |
| } |
| </pre></div></div> |
| <p>API call for reading results from the previous asynchronous query in the URL-encoded form.</p> |
| <p><a class="externalLink" href="http://localhost:19002/query/result?handle=%7B%22handle%22%3A+%5B45%2C+0%5D%7D">http://localhost:19002/query/result?handle=%7B%22handle%22%3A+%5B45%2C+0%5D%7D</a></p></div> |
| <div class="section"> |
| <h4><a name="Response"></a>Response</h4> |
| <p><i>HTTP OK 200</i><br />Payload</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> { |
| "results": [ |
| [ |
| "{ "id": 123, "name": "John Doe" }" |
| ] |
| ] |
| } |
| </pre></div></div></div></div></div> |
| <div class="section"> |
| <h2><a name="Query_Status_API_Back_to_TOC"></a><a name="QueryStatusApi" id="QueryStatusApi">Query Status API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2> |
| <p><i>End point to check the status of the query asynchronous</i></p> |
| <p>Endpoint: <i>/query/status</i></p> |
| <p>Parameters:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <td>Parameter</td> |
| |
| <td>Description</td> |
| |
| <td>Required?</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>handle</td> |
| |
| <td>Result handle that was returned by a previous call to a /query call with mode = asynchronous</td> |
| |
| <td>Yes</td> |
| </tr> |
| </table> |
| <p>Result: The result is returned as a JSON object as follows:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre> { |
| status: ("RUNNING" | "SUCCESS" | "ERROR") |
| } |
| </pre></div></div></div> |
| <div class="section"> |
| <h2><a name="Error_Codes_Back_to_TOC"></a><a name="ErrorCodes" id="ErrorCodes">Error Codes</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2> |
| <p>Table of error codes and their types:</p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <td>Code</td> |
| |
| <td>Type</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>1</td> |
| |
| <td>Invalid statement</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>2</td> |
| |
| <td>Parse failures</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>99</td> |
| |
| <td>Uncategorized error</td> |
| </tr> |
| </table></div> |
| </div> |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <footer> |
| <div class="container-fluid"> |
| <div class="row span12">Copyright © 2017 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All Rights Reserved. |
| |
| </div> |
| |
| <?xml version="1.0" encoding="UTF-8"?> |
| <div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache |
| feather logo, and the Apache AsterixDB project logo are either |
| registered trademarks or trademarks of The Apache Software |
| Foundation in the United States and other countries. |
| All other marks mentioned may be trademarks or registered |
| trademarks of their respective owners.</div> |
| |
| |
| </div> |
| </footer> |
| </body> |
| </html> |
