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