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