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