Gitiles
Code Review Sign In
asterix-gerrit.ics.uci.edu / incubator-asterixdb-site / 0817a3ff0fd5a3e470499eb96e9bc528cb35be79 / . / api.html
blob: f614dc3d2a2351da8b9552c464747bce5484c80d [file] [log] [blame]
Ian Maxoned124d82015-05-29 18:44:11 -0700[diff] [blame]1<!DOCTYPE html>
2<!--
Till Westmann0817a3f2015-06-03 21:08:18 -0700[diff] [blame^]3 | Generated by Apache Maven Doxia at 2015-05-31
Ian Maxoned124d82015-05-29 18:44:11 -0700[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" />
Till Westmann0817a3f2015-06-03 21:08:18 -0700[diff] [blame^]10 <meta name="Date-Revision-yyyymmdd" content="20150531" />
Ian Maxoned124d82015-05-29 18:44:11 -0700[diff] [blame]11 <meta http-equiv="Content-Language" content="en" />
12 <title>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 </head>
22 <body class="topBarDisabled">
23
24
25
26
27 <div class="container-fluid">
28 <div id="banner">
29 <div class="pull-left">
30 <a href="./" id="bannerLeft">
31 <img src="images/asterixlogo.png" alt="AsterixDB"/>
32 </a>
33 </div>
34 <div class="pull-right"> <a href="http://incubator.apache.org/" id="bannerRight">
35 <img src="images/egg-logo.png" alt="Apache Software Foundation Incubator"/>
36 </a>
37 </div>
38 <div class="clear"><hr/></div>
39 </div>
40
41 <div id="breadcrumbs">
42 <ul class="breadcrumb">
43
44
Till Westmann0817a3f2015-06-03 21:08:18 -0700[diff] [blame^]45 <li id="publishDate">Last Published: 2015-05-31</li>
Ian Maxoned124d82015-05-29 18:44:11 -0700[diff] [blame]46
47
48
49 <li id="projectVersion" class="pull-right">Version: 0.8.7-SNAPSHOT</li>
50
51 <li class="divider pull-right">|</li>
52
53 <li class="pull-right"> <a href="index.html" title="Home">
54 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">Apache Software Foundation</li>
68
69 <li>
70
71 <a href="http://www.apache.org/" class="externalLink" title="Home">
72 <i class="none"></i>
73 Home</a>
74 </li>
75
76 <li>
77
78 <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Donate">
79 <i class="none"></i>
80 Donate</a>
81 </li>
82
83 <li>
84
85 <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">
86 <i class="none"></i>
87 Thanks</a>
88 </li>
89
90 <li>
91
92 <a href="http://www.apache.org/security/" class="externalLink" title="Security">
93 <i class="none"></i>
94 Security</a>
95 </li>
96 <li class="nav-header">User Documentation</li>
97
98 <li>
99
100 <a href="install.html" title="Installing and Managing AsterixDB using Managix">
101 <i class="none"></i>
102 Installing and Managing AsterixDB using Managix</a>
103 </li>
104
105 <li>
106
107 <a href="aql/primer.html" title="AsterixDB 101: An ADM and AQL Primer">
108 <i class="none"></i>
109 AsterixDB 101: An ADM and AQL Primer</a>
110 </li>
111
112 <li>
113
114 <a href="aql/primer-sql-like.html" title="AsterixDB 101: An ADM and AQL Primer (For SQL Fans)">
115 <i class="none"></i>
116 AsterixDB 101: An ADM and AQL Primer (For SQL Fans)</a>
117 </li>
118
119 <li>
120
121 <a href="aql/js-sdk.html" title="AsterixDB Javascript SDK">
122 <i class="none"></i>
123 AsterixDB Javascript SDK</a>
124 </li>
125
126 <li>
127
128 <a href="aql/datamodel.html" title="Asterix Data Model (ADM)">
129 <i class="none"></i>
130 Asterix Data Model (ADM)</a>
131 </li>
132
133 <li>
134
135 <a href="aql/manual.html" title="Asterix Query Language (AQL)">
136 <i class="none"></i>
137 Asterix Query Language (AQL)</a>
138 </li>
139
140 <li>
141
142 <a href="aql/functions.html" title="AQL Functions">
143 <i class="none"></i>
144 AQL Functions</a>
145 </li>
146
147 <li>
148
149 <a href="aql/allens.html" title="AQL Allen's Relations Functions">
150 <i class="none"></i>
151 AQL Allen's Relations Functions</a>
152 </li>
153
154 <li>
155
156 <a href="aql/similarity.html" title="AQL Support of Similarity Queries">
157 <i class="none"></i>
158 AQL Support of Similarity Queries</a>
159 </li>
160
161 <li>
162
163 <a href="aql/externaldata.html" title="Accessing External Data">
164 <i class="none"></i>
165 Accessing External Data</a>
166 </li>
167
168 <li>
169
170 <a href="aql/filters.html" title="Filter-Based LSM Index Acceleration">
171 <i class="none"></i>
172 Filter-Based LSM Index Acceleration</a>
173 </li>
174
175 <li class="active">
176
177 <a href="#"><i class="none"></i>REST API to AsterixDB</a>
178 </li>
179 </ul>
180
181
182
183 <hr class="divider" />
184
185 <div id="poweredBy">
186 <div class="clear"></div>
187 <div class="clear"></div>
188 <div class="clear"></div>
189 <a href="./" title="Hyracks" class="builtBy">
190 <img class="builtBy" alt="Hyracks" src="images/hyrax_ts.png" />
191 </a>
192 </div>
193 </div>
194 </div>
195
196
197 <div id="bodyColumn" class="span9" >
198
199 <h1>REST API to AsterixDB</h1>
200<div class="section">
201<h2><a name="toc" id="toc">Table of Contents</a><a name="Table_of_Contents"></a></h2>
202
203<ul>
204
205<li><a href="#DdlApi">DDL API</a></li>
206
207<li><a href="#UpdateApi">Update API</a></li>
208
209<li><a href="#QueryApi">Query API</a></li>
210
211<li><a href="#AsynchronousResultApi">Asynchronous Result API</a></li>
212
213<li><a href="#QueryStatusApi">Query Status API</a></li>
214
215<li><a href="#ErrorCodes">Error Codes</a></li>
216</ul></div>
217<div class="section">
218<h2><a name="DdlApi" id="DdlApi">DDL API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="DDL_API_Back_to_TOC"></a></h2>
219<p><i>End point for the data definition statements</i></p>
220<p>Endpoint: <i>/ddl</i></p>
221<p>Parameters:</p>
222
223<table border="0" class="table table-striped">
224
225<tr class="a">
226
227<td>Parameter</td>
228
229<td>Description</td>
230
231<td>Required?</td>
232</tr>
233
234<tr class="b">
235
236<td>ddl</td>
237
238<td>String containing DDL statements to modify Metadata</td>
239
240<td>Yes</td>
241</tr>
242</table>
243<p>This call does not return any result. If the operations were successful, HTTP OK status code is returned.</p>
244<div class="section">
245<h3>Example<a name="Example"></a></h3>
246<div class="section">
247<h4>DDL Statements<a name="DDL_Statements"></a></h4>
248
249<div class="source">
250<pre> drop dataverse company if exists;
251 create dataverse company;
252 use dataverse company;
253
254 create type Emp as open {
255 id : int32,
256 name : string
257 };
258
259 create dataset Employee(Emp) primary key id;
260</pre></div>
261<p>API call for the above DDL statements in the URL-encoded form.</p>
262<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>
263<div class="section">
264<h4>Response<a name="Response"></a></h4>
265<p><i>HTTP OK 200</i><br /><tt>&lt;NO PAYLOAD&gt;</tt></p></div></div></div>
266<div class="section">
267<h2><a name="UpdateApi" id="UpdateApi">Update API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Update_API_Back_to_TOC"></a></h2>
268<p><i>End point for update statements (INSERT, DELETE and LOAD)</i></p>
269<p>Endpoint: <i>/update</i></p>
270<p>Parameters:</p>
271
272<table border="0" class="table table-striped">
273
274<tr class="a">
275
276<td>Parameter</td>
277
278<td>Description</td>
279
280<td>Required?</td>
281</tr>
282
283<tr class="b">
284
285<td>statements</td>
286
287<td>String containing update (insert/delete) statements to execute</td>
288
289<td>Yes</td>
290</tr>
291</table>
292<p>This call does not return any result. If the operations were successful, HTTP OK status code is returned.</p>
293<div class="section">
294<h3>Example<a name="Example"></a></h3>
295<div class="section">
296<h4>Update Statements<a name="Update_Statements"></a></h4>
297
298<div class="source">
299<pre> use dataverse company;
300
301 insert into dataset Employee({ &quot;id&quot;:123,&quot;name&quot;:&quot;John Doe&quot;});
302</pre></div>
303<p>API call for the above update statement in the URL-encoded form.</p>
304<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>
305<div class="section">
306<h4>Response<a name="Response"></a></h4>
307<p><i>HTTP OK 200</i><br /><tt>&lt;NO PAYLOAD&gt;</tt></p></div></div></div>
308<div class="section">
309<h2><a name="QueryApi" id="QueryApi">Query API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Query_API_Back_to_TOC"></a></h2>
310<p><i>End point for query statements</i></p>
311<p>Endpoint: <i>/query</i></p>
312<p>Parameters:</p>
313
314<table border="0" class="table table-striped">
315
316<tr class="a">
317
318<td>Parameter</td>
319
320<td>Description</td>
321
322<td>Required?</td>
323</tr>
324
325<tr class="b">
326
327<td>query</td>
328
329<td>Query string to pass to ASTERIX for execution</td>
330
331<td>Yes</td>
332</tr>
333
334<tr class="a">
335
336<td>mode</td>
337
338<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>
339
340<td>No. default mode = synchronous</td>
341</tr>
342</table>
343<p>Result: The result is returned as a JSON object as follows</p>
344
345<div class="source">
346<pre> {
347 results: &lt;result as a string, if mode = synchronous&gt;
348 error-code: [&lt;code&gt;, &lt;message&gt;] (if an error occurs)
349 handle: &lt;opaque result handle, if mode = asynchronous&gt;
350 }
351</pre></div>
352<div class="section">
353<h3>Example<a name="Example"></a></h3>
354<div class="section">
355<h4>Select query with synchronous result delivery<a name="Select_query_with_synchronous_result_delivery"></a></h4>
356
357<div class="source">
358<pre> use dataverse company;
359
360 for $l in dataset('Employee') return $l;
361</pre></div>
362<p>API call for the above query statement in the URL-encoded form.</p>
363<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>
364<div class="section">
365<h4>Response<a name="Response"></a></h4>
366<p><i>HTTP OK 200</i><br />Payload</p>
367
368<div class="source">
369<pre> {
370 &quot;results&quot;: [
371 [
372 &quot;{ &quot;id&quot;: 123, &quot;name&quot;: &quot;John Doe&quot; }&quot;
373 ]
374 ]
375 }
376</pre></div></div>
377<div class="section">
378<h4>Same select query with asynchronous result delivery<a name="Same_select_query_with_asynchronous_result_delivery"></a></h4>
379<p>API call for the above query statement in the URL-encoded form with mode=asynchronous</p>
380<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>
381<div class="section">
382<h4>Response<a name="Response"></a></h4>
383<p><i>HTTP OK 200</i><br />Payload</p>
384
385<div class="source">
386<pre> {
387 &quot;handle&quot;: [45,0]
388 }
389</pre></div></div></div></div>
390<div class="section">
391<h2><a name="AsynchronousResultApi" id="AsynchronousResultApi">Asynchronous Result API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Asynchronous_Result_API_Back_to_TOC"></a></h2>
392<p><i>End point to fetch the results of an asynchronous query</i></p>
393<p>Endpoint: <i>/query/result</i></p>
394<p>Parameters:</p>
395
396<table border="0" class="table table-striped">
397
398<tr class="a">
399
400<td>Parameter</td>
401
402<td>Description</td>
403
404<td>Required?</td>
405</tr>
406
407<tr class="b">
408
409<td>handle</td>
410
411<td>Result handle that was returned by a previous call to a /query call with mode = asynchronous</td>
412
413<td>Yes</td>
414</tr>
415</table>
416<p>Result: The result is returned as a JSON object as follows:</p>
417
418<div class="source">
419<pre> {
420 results: &lt;result as a string, if mode = synchronous, or mode = asynchronous and results are available&gt;
421 error-code: [&lt;code&gt;, &lt;message&gt;] (if an error occurs)
422 }
423</pre></div>
424<p>If mode = asynchronous and results are not available, the returned JSON object is empty: { }</p>
425<div class="section">
426<h3>Example<a name="Example"></a></h3>
427<div class="section">
428<h4>Fetching results for asynchronous query<a name="Fetching_results_for_asynchronous_query"></a></h4>
429<p>We use the handle returned by the asynchronous query to get the results for the query. The handle returned was:</p>
430
431<div class="source">
432<pre> {
433 &quot;handle&quot;: [45,0]
434 }
435</pre></div>
436<p>API call for reading results from the previous asynchronous query in the URL-encoded form.</p>
437<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>
438<div class="section">
439<h4>Response<a name="Response"></a></h4>
440<p><i>HTTP OK 200</i><br />Payload</p>
441
442<div class="source">
443<pre> {
444 &quot;results&quot;: [
445 [
446 &quot;{ &quot;id&quot;: 123, &quot;name&quot;: &quot;John Doe&quot; }&quot;
447 ]
448 ]
449 }
450</pre></div></div></div></div>
451<div class="section">
452<h2><a name="QueryStatusApi" id="QueryStatusApi">Query Status API</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Query_Status_API_Back_to_TOC"></a></h2>
453<p><i>End point to check the status of the query asynchronous</i></p>
454<p>Endpoint: <i>/query/status</i></p>
455<p>Parameters:</p>
456
457<table border="0" class="table table-striped">
458
459<tr class="a">
460
461<td>Parameter</td>
462
463<td>Description</td>
464
465<td>Required?</td>
466</tr>
467
468<tr class="b">
469
470<td>handle</td>
471
472<td>Result handle that was returned by a previous call to a /query call with mode = asynchronous</td>
473
474<td>Yes</td>
475</tr>
476</table>
477<p>Result: The result is returned as a JSON object as follows:</p>
478
479<div class="source">
480<pre> {
481 status: (&quot;RUNNING&quot; | &quot;SUCCESS&quot; | &quot;ERROR&quot;)
482 }
483</pre></div></div>
484<div class="section">
485<h2><a name="ErrorCodes" id="ErrorCodes">Error Codes</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Error_Codes_Back_to_TOC"></a></h2>
486<p>Table of error codes and their types:</p>
487
488<table border="0" class="table table-striped">
489
490<tr class="a">
491
492<td>Code</td>
493
494<td>Type</td>
495</tr>
496
497<tr class="b">
498
499<td>1</td>
500
501<td>Invalid statement</td>
502</tr>
503
504<tr class="a">
505
506<td>2</td>
507
508<td>Parse failures</td>
509</tr>
510
511<tr class="b">
512
513<td>99</td>
514
515<td>Uncategorized error</td>
516</tr>
517</table></div>
518 </div>
519 </div>
520 </div>
521
522 <hr/>
523
524 <footer>
525 <div class="container-fluid">
526 <div class="row span12">Copyright &copy; 2015.
527 All Rights Reserved.
528
529 </div>
530
531 <?xml version="1.0" encoding="UTF-8"?>
532<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
533 feather logo, and the Apache AsterixDB project logo are either
534 registered trademarks or trademarks of The Apache Software
535 Foundation in the United States and other countries.
536 All other marks mentioned may be trademarks or registered
537 trademarks of their respective owners.</div>
538
539
540 </div>
541 </footer>
542 </body>
543</html>