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