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