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