Gitiles
Code Review Sign In
asterix-gerrit.ics.uci.edu / incubator-asterixdb-site / e2b799e7f3e90723f409633464b4bd8f25e72573 / . / docs / 0.8.7-incubating / api.html
blob: 72fd689f9c39018a01b35b128dbd947750036281 [file] [log] [blame]
Ian Maxone2b799e2015-11-24 18:20:03 -0800[diff] [blame^]1<!DOCTYPE html>
2<!--
3 | Generated by Apache Maven Doxia at 2015-11-24
4 | Rendered using Apache Maven Fluido Skin 1.3.0
5-->
6<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 <head>
8 <meta charset="UTF-8" />
9 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
10 <meta name="Date-Revision-yyyymmdd" content="20151124" />
11 <meta http-equiv="Content-Language" content="en" />
12 <title>AsterixDB &#x2013; HTTP API to AsterixDB</title>
13 <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
14 <link rel="stylesheet" href="./css/site.css" />
15 <link rel="stylesheet" href="./css/print.css" media="print" />
16
17
18 <script type="text/javascript" src="./js/apache-maven-fluido-1.3.0.min.js"></script>
19
20
21
22<script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
23 (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
24 m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
25 })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
26
27 ga('create', 'UA-41536543-1', 'uci.edu');
28 ga('send', 'pageview');</script>
29
30 </head>
31 <body class="topBarDisabled">
32
33
34
35
36 <div class="container-fluid">
37 <div id="banner">
38 <div class="pull-left">
39 <a href="http://asterixdb.apache.org/" id="bannerLeft">
40 <img src="images/asterixlogo.png" alt="AsterixDB"/>
41 </a>
42 </div>
43 <div class="pull-right"> </div>
44 <div class="clear"><hr/></div>
45 </div>
46
47 <div id="breadcrumbs">
48 <ul class="breadcrumb">
49
50
51 <li id="publishDate">Last Published: 2015-11-24</li>
52
53
54
55 <li id="projectVersion" class="pull-right">Version: 0.8.7-incubating</li>
56
57 <li class="divider pull-right">|</li>
58
59 <li class="pull-right"> <a href="index.html" title="Documentation Home">
60 Documentation Home</a>
61 </li>
62
63 </ul>
64 </div>
65
66
67 <div class="row-fluid">
68 <div id="leftColumn" class="span3">
69 <div class="well sidebar-nav">
70
71
72 <ul class="nav nav-list">
73 <li class="nav-header">Documentation</li>
74
75 <li>
76
77 <a href="install.html" title="Installing and Managing AsterixDB using Managix">
78 <i class="none"></i>
79 Installing and Managing AsterixDB using Managix</a>
80 </li>
81
82 <li>
83
84 <a href="yarn.html" title="Deploying AsterixDB using YARN">
85 <i class="none"></i>
86 Deploying AsterixDB using YARN</a>
87 </li>
88
89 <li>
90
91 <a href="aql/primer.html" title="AsterixDB 101: An ADM and AQL Primer">
92 <i class="none"></i>
93 AsterixDB 101: An ADM and AQL Primer</a>
94 </li>
95
96 <li>
97
98 <a href="aql/primer-sql-like.html" title="AsterixDB 101: An ADM and AQL Primer (For SQL Fans)">
99 <i class="none"></i>
100 AsterixDB 101: An ADM and AQL Primer (For SQL Fans)</a>
101 </li>
102
103 <li>
104
105 <a href="aql/js-sdk.html" title="AsterixDB Javascript SDK">
106 <i class="none"></i>
107 AsterixDB Javascript SDK</a>
108 </li>
109
110 <li>
111
112 <a href="aql/datamodel.html" title="Asterix Data Model (ADM)">
113 <i class="none"></i>
114 Asterix Data Model (ADM)</a>
115 </li>
116
117 <li>
118
119 <a href="aql/manual.html" title="Asterix Query Language (AQL)">
120 <i class="none"></i>
121 Asterix Query Language (AQL)</a>
122 </li>
123
124 <li>
125
126 <a href="aql/functions.html" title="AQL Functions">
127 <i class="none"></i>
128 AQL Functions</a>
129 </li>
130
131 <li>
132
133 <a href="aql/allens.html" title="AQL Allen's Relations Functions">
134 <i class="none"></i>
135 AQL Allen's Relations Functions</a>
136 </li>
137
138 <li>
139
140 <a href="aql/similarity.html" title="AQL Support of Similarity Queries">
141 <i class="none"></i>
142 AQL Support of Similarity Queries</a>
143 </li>
144
145 <li>
146
147 <a href="aql/externaldata.html" title="Accessing External Data">
148 <i class="none"></i>
149 Accessing External Data</a>
150 </li>
151
152 <li>
153
154 <a href="feeds/tutorial.html" title="Support for Data Ingestion in AsterixDB">
155 <i class="none"></i>
156 Support for Data Ingestion in AsterixDB</a>
157 </li>
158
159 <li>
160
161 <a href="udf.html" title="Support for User Defined Functions in AsterixDB">
162 <i class="none"></i>
163 Support for User Defined Functions in AsterixDB</a>
164 </li>
165
166 <li>
167
168 <a href="aql/filters.html" title="Filter-Based LSM Index Acceleration">
169 <i class="none"></i>
170 Filter-Based LSM Index Acceleration</a>
171 </li>
172
173 <li class="active">
174
175 <a href="#"><i class="none"></i>HTTP API to AsterixDB</a>
176 </li>
177 </ul>
178
179
180
181 <hr class="divider" />
182
183 <div id="poweredBy">
184 <div class="clear"></div>
185 <div class="clear"></div>
186 <div class="clear"></div>
187 <a href="https://code.google.com/p/hyracks/" title="Hyracks" class="builtBy">
188 <img class="builtBy" alt="Hyracks" src="images/hyrax_ts.png" />
189 </a>
190 </div>
191 </div>
192 </div>
193
194
195 <div id="bodyColumn" class="span9" >
196
197 <!-- ! Licensed to the Apache Software Foundation (ASF) under one
198 ! or more contributor license agreements. See the NOTICE file
199 ! distributed with this work for additional information
200 ! regarding copyright ownership. The ASF licenses this file
201 ! to you under the Apache License, Version 2.0 (the
202 ! "License"); you may not use this file except in compliance
203 ! with the License. You may obtain a copy of the License at
204 !
205 ! http://www.apache.org/licenses/LICENSE-2.0
206 !
207 ! Unless required by applicable law or agreed to in writing,
208 ! software distributed under the License is distributed on an
209 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
210 ! KIND, either express or implied. See the License for the
211 ! specific language governing permissions and limitations
212 ! under the License.
213 ! --><h1>HTTP API to AsterixDB</h1>
214<div class="section">
215<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2>
216
217<ul>
218
219<li><a href="#DdlApi">DDL API</a></li>
220
221<li><a href="#UpdateApi">Update API</a></li>
222
223<li><a href="#QueryApi">Query API</a></li>
224
225<li><a href="#AnyApi">Mixed API</a></li>
226
227<li><a href="#AsynchronousResultApi">Asynchronous Result API</a></li>
228
229<li><a href="#QueryStatusApi">Query Status API</a></li>
230
231<li><a href="#ErrorCodes">Error Codes</a></li>
232</ul></div>
233<div class="section">
234<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>
235<p><i>End point for the data definition statements</i></p>
236<p>Endpoint: <i>/ddl</i></p>
237<p>Parameters:</p>
238
239<table border="0" class="table table-striped">
240
241<tr class="a">
242
243<td>Parameter</td>
244
245<td>Description</td>
246
247<td>Required?</td>
248</tr>
249
250<tr class="b">
251
252<td>ddl</td>
253
254<td>String containing DDL statements to modify Metadata</td>
255
256<td>Yes</td>
257</tr>
258</table>
259<p>This call does not return any result. If the operations were successful, HTTP OK status code is returned.</p>
260<div class="section">
261<h3><a name="Example"></a>Example</h3>
262<div class="section">
263<h4><a name="DDL_Statements"></a>DDL Statements</h4>
264
265<div class="source">
266<div class="source">
267<pre> drop dataverse company if exists;
268 create dataverse company;
269 use dataverse company;
270
271 create type Emp as open {
272 id : int32,
273 name : string
274 };
275
276 create dataset Employee(Emp) primary key id;
277</pre></div></div>
278<p>API call for the above DDL statements in the URL-encoded form.</p>
279<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>
280<div class="section">
281<h4><a name="Response"></a>Response</h4>
282<p><i>HTTP OK 200</i><br /><tt>&lt;NO PAYLOAD&gt;</tt></p></div></div></div>
283<div class="section">
284<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>
285<p><i>End point for update statements (INSERT, DELETE and LOAD)</i></p>
286<p>Endpoint: <i>/update</i></p>
287<p>Parameters:</p>
288
289<table border="0" class="table table-striped">
290
291<tr class="a">
292
293<td>Parameter</td>
294
295<td>Description</td>
296
297<td>Required?</td>
298</tr>
299
300<tr class="b">
301
302<td>statements</td>
303
304<td>String containing update (insert/delete) statements to execute</td>
305
306<td>Yes</td>
307</tr>
308</table>
309<p>This call does not return any result. If the operations were successful, HTTP OK status code is returned.</p>
310<div class="section">
311<h3><a name="Example"></a>Example</h3>
312<div class="section">
313<h4><a name="Update_Statements"></a>Update Statements</h4>
314
315<div class="source">
316<div class="source">
317<pre> use dataverse company;
318
319 insert into dataset Employee({ &quot;id&quot;:123,&quot;name&quot;:&quot;John Doe&quot;});
320</pre></div></div>
321<p>API call for the above update statement in the URL-encoded form.</p>
322<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>
323<div class="section">
324<h4><a name="Response"></a>Response</h4>
325<p><i>HTTP OK 200</i><br /><tt>&lt;NO PAYLOAD&gt;</tt></p></div></div></div>
326<div class="section">
327<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>
328<p><i>End point for query statements</i></p>
329<p>Endpoint: <i>/query</i></p>
330<p>Parameters:</p>
331
332<table border="0" class="table table-striped">
333
334<tr class="a">
335
336<td>Parameter</td>
337
338<td>Description</td>
339
340<td>Required?</td>
341</tr>
342
343<tr class="b">
344
345<td>query</td>
346
347<td>Query string to pass to ASTERIX for execution</td>
348
349<td>Yes</td>
350</tr>
351
352<tr class="a">
353
354<td>mode</td>
355
356<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&#x2019;s status and to fetch results when available</td>
357
358<td>No. default mode = synchronous</td>
359</tr>
360</table>
361<p>Result: The result is returned as a JSON object as follows</p>
362
363<div class="source">
364<div class="source">
365<pre> {
366 results: &lt;result as a string, if mode = synchronous&gt;
367 error-code: [&lt;code&gt;, &lt;message&gt;] (if an error occurs)
368 handle: &lt;opaque result handle, if mode = asynchronous&gt;
369 }
370</pre></div></div>
371<div class="section">
372<h3><a name="Example"></a>Example</h3>
373<div class="section">
374<h4><a name="Select_query_with_synchronous_result_delivery"></a>Select query with synchronous result delivery</h4>
375
376<div class="source">
377<div class="source">
378<pre> use dataverse company;
379
380 for $l in dataset('Employee') return $l;
381</pre></div></div>
382<p>API call for the above query statement in the URL-encoded form.</p>
383<p>[http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset(&#x2018;Employee&#x2019;)%20return%20$l;](<a class="externalLink" href="http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset(&apos;Employee&apos;)%20return%20$l;">http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset('Employee')%20return%20$l;</a>)</p></div>
384<div class="section">
385<h4><a name="Response"></a>Response</h4>
386<p><i>HTTP OK 200</i><br />Payload</p>
387
388<div class="source">
389<div class="source">
390<pre> {
391 &quot;results&quot;: [
392 [
393 &quot;{ &quot;id&quot;: 123, &quot;name&quot;: &quot;John Doe&quot; }&quot;
394 ]
395 ]
396 }
397</pre></div></div></div>
398<div class="section">
399<h4><a name="Same_select_query_with_asynchronous_result_delivery"></a>Same select query with asynchronous result delivery</h4>
400<p>API call for the above query statement in the URL-encoded form with mode=asynchronous</p>
401<p>[http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset(&#x2018;Employee&#x2019;)%20return%20$l;&amp;mode=asynchronous](<a class="externalLink" href="http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset(&apos;Employee&apos;)%20return%20$l;&amp;mode=asynchronous">http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset('Employee')%20return%20$l;&amp;mode=asynchronous</a>)</p></div>
402<div class="section">
403<h4><a name="Response"></a>Response</h4>
404<p><i>HTTP OK 200</i><br />Payload</p>
405
406<div class="source">
407<div class="source">
408<pre> {
409 &quot;handle&quot;: [45,0]
410 }
411</pre></div></div></div></div></div>
412<div class="section">
413<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>
414<p><i>End point for any/mixed statement</i></p>
415<p>Endpoint: <i>/aql</i></p>
416<p>Parameters:</p>
417
418<table border="0" class="table table-striped">
419
420<tr class="a">
421
422<td>Parameter</td>
423
424<td>Description</td>
425
426<td>Required?</td>
427</tr>
428
429<tr class="b">
430
431<td>query</td>
432
433<td>Query string to pass to ASTERIX for execution</td>
434
435<td>Yes</td>
436</tr>
437
438<tr class="a">
439
440<td>mode</td>
441
442<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&#x2019;s status and to fetch results when available</td>
443
444<td>No. default mode = synchronous</td>
445</tr>
446</table>
447<p>Similar to <i><i>/update</i></i> but allows any arbitrary AQL statement rather than only modifications.</p></div>
448<div class="section">
449<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>
450<p><i>End point to fetch the results of an asynchronous query</i></p>
451<p>Endpoint: <i>/query/result</i></p>
452<p>Parameters:</p>
453
454<table border="0" class="table table-striped">
455
456<tr class="a">
457
458<td>Parameter</td>
459
460<td>Description</td>
461
462<td>Required?</td>
463</tr>
464
465<tr class="b">
466
467<td>handle</td>
468
469<td>Result handle that was returned by a previous call to a /query call with mode = asynchronous</td>
470
471<td>Yes</td>
472</tr>
473</table>
474<p>Result: The result is returned as a JSON object as follows:</p>
475
476<div class="source">
477<div class="source">
478<pre> {
479 results: &lt;result as a string, if mode = synchronous, or mode = asynchronous and results are available&gt;
480 error-code: [&lt;code&gt;, &lt;message&gt;] (if an error occurs)
481 }
482</pre></div></div>
483<p>If mode = asynchronous and results are not available, the returned JSON object is empty: { }</p>
484<div class="section">
485<h3><a name="Example"></a>Example</h3>
486<div class="section">
487<h4><a name="Fetching_results_for_asynchronous_query"></a>Fetching results for asynchronous query</h4>
488<p>We use the handle returned by the asynchronous query to get the results for the query. The handle returned was:</p>
489
490<div class="source">
491<div class="source">
492<pre> {
493 &quot;handle&quot;: [45,0]
494 }
495</pre></div></div>
496<p>API call for reading results from the previous asynchronous query in the URL-encoded form.</p>
497<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>
498<div class="section">
499<h4><a name="Response"></a>Response</h4>
500<p><i>HTTP OK 200</i><br />Payload</p>
501
502<div class="source">
503<div class="source">
504<pre> {
505 &quot;results&quot;: [
506 [
507 &quot;{ &quot;id&quot;: 123, &quot;name&quot;: &quot;John Doe&quot; }&quot;
508 ]
509 ]
510 }
511</pre></div></div></div></div></div>
512<div class="section">
513<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>
514<p><i>End point to check the status of the query asynchronous</i></p>
515<p>Endpoint: <i>/query/status</i></p>
516<p>Parameters:</p>
517
518<table border="0" class="table table-striped">
519
520<tr class="a">
521
522<td>Parameter</td>
523
524<td>Description</td>
525
526<td>Required?</td>
527</tr>
528
529<tr class="b">
530
531<td>handle</td>
532
533<td>Result handle that was returned by a previous call to a /query call with mode = asynchronous</td>
534
535<td>Yes</td>
536</tr>
537</table>
538<p>Result: The result is returned as a JSON object as follows:</p>
539
540<div class="source">
541<div class="source">
542<pre> {
543 status: (&quot;RUNNING&quot; | &quot;SUCCESS&quot; | &quot;ERROR&quot;)
544 }
545</pre></div></div></div>
546<div class="section">
547<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>
548<p>Table of error codes and their types:</p>
549
550<table border="0" class="table table-striped">
551
552<tr class="a">
553
554<td>Code</td>
555
556<td>Type</td>
557</tr>
558
559<tr class="b">
560
561<td>1</td>
562
563<td>Invalid statement</td>
564</tr>
565
566<tr class="a">
567
568<td>2</td>
569
570<td>Parse failures</td>
571</tr>
572
573<tr class="b">
574
575<td>99</td>
576
577<td>Uncategorized error</td>
578</tr>
579</table></div>
580 </div>
581 </div>
582 </div>
583
584 <hr/>
585
586 <footer>
587 <div class="container-fluid">
588 <div class="row span12">Copyright &copy; 2015
589 <a href="http://www.apache.org/">The Apache Software Foundation</a>.
590 All Rights Reserved.
591
592 </div>
593
594 <?xml version="1.0" encoding="UTF-8"?>
595<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
596 feather logo, and the Apache AsterixDB project logo are either
597 registered trademarks or trademarks of The Apache Software
598 Foundation in the United States and other countries.
599 All other marks mentioned may be trademarks or registered
600 trademarks of their respective owners.</div>
601
602
603 </div>
604 </footer>
605 </body>
606</html>