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