Gitiles
Code Review Sign In
asterix-gerrit.ics.uci.edu / incubator-asterixdb-site / 9c40a66dc27ec7887041773bcc5ccff25e3f70ad / . / docs / 0.9.2 / api.html
blob: 1c87fe8f253fc693ceb62de869ce1d92456ecf7e [file] [log] [blame]
Ian Maxon444ca1b2017-08-25 11:41:41 -0700[diff] [blame]1<!DOCTYPE html>
2<!--
Ian Maxonf9dfc032017-09-14 21:37:24 +0200[diff] [blame]3 | Generated by Apache Maven Doxia at 2017-09-14
Ian Maxon444ca1b2017-08-25 11:41:41 -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" />
Ian Maxonf9dfc032017-09-14 21:37:24 +0200[diff] [blame]10 <meta name="Date-Revision-yyyymmdd" content="20170914" />
Ian Maxon444ca1b2017-08-25 11:41:41 -0700[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
22<script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
23 (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
24 m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
25 })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
26
27 ga('create', 'UA-41536543-1', 'uci.edu');
28 ga('send', 'pageview');</script>
29
30 </head>
31 <body class="topBarDisabled">
32
33
34
35
36 <div class="container-fluid">
37 <div id="banner">
38 <div class="pull-left">
39 <a href="./" id="bannerLeft">
40 <img src="images/asterixlogo.png" alt="AsterixDB"/>
41 </a>
42 </div>
43 <div class="pull-right"> </div>
44 <div class="clear"><hr/></div>
45 </div>
46
47 <div id="breadcrumbs">
48 <ul class="breadcrumb">
49
50
Ian Maxonf9dfc032017-09-14 21:37:24 +0200[diff] [blame]51 <li id="publishDate">Last Published: 2017-09-14</li>
Ian Maxon444ca1b2017-08-25 11:41:41 -0700[diff] [blame]52
53
54
Ian Maxonf9dfc032017-09-14 21:37:24 +0200[diff] [blame]55 <li id="projectVersion" class="pull-right">Version: 0.9.2</li>
Ian Maxon444ca1b2017-08-25 11:41:41 -0700[diff] [blame]56
57 <li class="divider pull-right">|</li>
58
59 <li class="pull-right"> <a href="index.html" title="Documentation Home">
60 Documentation Home</a>
61 </li>
62
63 </ul>
64 </div>
65
66
67 <div class="row-fluid">
68 <div id="leftColumn" class="span3">
69 <div class="well sidebar-nav">
70
71
72 <ul class="nav nav-list">
73 <li class="nav-header">Get Started - Installation</li>
74
75 <li>
76
77 <a href="ncservice.html" title="Option 1: using NCService">
78 <i class="none"></i>
79 Option 1: using NCService</a>
80 </li>
81
82 <li>
83
84 <a href="ansible.html" title="Option 2: using Ansible">
85 <i class="none"></i>
86 Option 2: using Ansible</a>
87 </li>
88
89 <li>
90
91 <a href="aws.html" title="Option 3: using Amazon Web Services">
92 <i class="none"></i>
93 Option 3: using Amazon Web Services</a>
94 </li>
95
96 <li>
97
98 <a href="yarn.html" title="Option 4: using YARN">
99 <i class="none"></i>
100 Option 4: using YARN</a>
101 </li>
102
103 <li>
104
105 <a href="install.html" title="Option 5: using Managix (deprecated)">
106 <i class="none"></i>
107 Option 5: using Managix (deprecated)</a>
108 </li>
109 <li class="nav-header">AsterixDB Primer</li>
110
111 <li>
112
113 <a href="sqlpp/primer-sqlpp.html" title="Option 1: using SQL++">
114 <i class="none"></i>
115 Option 1: using SQL++</a>
116 </li>
117
118 <li>
119
120 <a href="aql/primer.html" title="Option 2: using AQL">
121 <i class="none"></i>
122 Option 2: using AQL</a>
123 </li>
124 <li class="nav-header">Data Model</li>
125
126 <li>
127
128 <a href="datamodel.html" title="The Asterix Data Model">
129 <i class="none"></i>
130 The Asterix Data Model</a>
131 </li>
132 <li class="nav-header">Queries - SQL++</li>
133
134 <li>
135
136 <a href="sqlpp/manual.html" title="The SQL++ Query Language">
137 <i class="none"></i>
138 The SQL++ Query Language</a>
139 </li>
140
141 <li>
142
143 <a href="sqlpp/builtins.html" title="Builtin Functions">
144 <i class="none"></i>
145 Builtin Functions</a>
146 </li>
147 <li class="nav-header">Queries - AQL</li>
148
149 <li>
150
151 <a href="aql/manual.html" title="The Asterix Query Language (AQL)">
152 <i class="none"></i>
153 The Asterix Query Language (AQL)</a>
154 </li>
155
156 <li>
157
158 <a href="aql/builtins.html" title="Builtin Functions">
159 <i class="none"></i>
160 Builtin Functions</a>
161 </li>
162 <li class="nav-header">API/SDK</li>
163
164 <li class="active">
165
166 <a href="#"><i class="none"></i>HTTP API</a>
167 </li>
168
169 <li>
170
171 <a href="csv.html" title="CSV Output">
172 <i class="none"></i>
173 CSV Output</a>
174 </li>
175 <li class="nav-header">Advanced Features</li>
176
177 <li>
178
179 <a href="aql/fulltext.html" title="Support of Full-text Queries">
180 <i class="none"></i>
181 Support of Full-text Queries</a>
182 </li>
183
184 <li>
185
186 <a href="aql/externaldata.html" title="Accessing External Data">
187 <i class="none"></i>
188 Accessing External Data</a>
189 </li>
190
191 <li>
192
193 <a href="feeds/tutorial.html" title="Support for Data Ingestion">
194 <i class="none"></i>
195 Support for Data Ingestion</a>
196 </li>
197
198 <li>
199
200 <a href="udf.html" title="User Defined Functions">
201 <i class="none"></i>
202 User Defined Functions</a>
203 </li>
204
205 <li>
206
207 <a href="aql/filters.html" title="Filter-Based LSM Index Acceleration">
208 <i class="none"></i>
209 Filter-Based LSM Index Acceleration</a>
210 </li>
211
212 <li>
213
214 <a href="aql/similarity.html" title="Support of Similarity Queries">
215 <i class="none"></i>
216 Support of Similarity Queries</a>
217 </li>
218 </ul>
219
220
221
222 <hr class="divider" />
223
224 <div id="poweredBy">
225 <div class="clear"></div>
226 <div class="clear"></div>
227 <div class="clear"></div>
228 <a href="./" title="AsterixDB" class="builtBy">
229 <img class="builtBy" alt="AsterixDB" src="images/asterixlogo.png" />
230 </a>
231 </div>
232 </div>
233 </div>
234
235
236 <div id="bodyColumn" class="span9" >
237
238 <!-- ! Licensed to the Apache Software Foundation (ASF) under one
239 ! or more contributor license agreements. See the NOTICE file
240 ! distributed with this work for additional information
241 ! regarding copyright ownership. The ASF licenses this file
242 ! to you under the Apache License, Version 2.0 (the
243 ! "License"); you may not use this file except in compliance
244 ! with the License. You may obtain a copy of the License at
245 !
246 ! http://www.apache.org/licenses/LICENSE-2.0
247 !
248 ! Unless required by applicable law or agreed to in writing,
249 ! software distributed under the License is distributed on an
250 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
251 ! KIND, either express or implied. See the License for the
252 ! specific language governing permissions and limitations
253 ! under the License.
254 ! --><h1>HTTP API to AsterixDB</h1>
255<div class="section">
256<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2>
257
258<ul>
259
260<li><a href="#queryservice">Query Service API</a></li>
261
262<li><a href="#querystatus">Query Status API</a></li>
263
264<li><a href="#queryresult">Query Result API</a></li>
265</ul></div>
266<div class="section">
267<h2><a name="POST_queryservice_Back_to_TOC"></a><a name="queryservice" id="queryservice">POST /query/service</a><font size="4"> <a href="#toc">[Back to TOC]</a></font></h2>
268<p><b>Description</b> Returns result for query as JSON. The response is a JSON object that contains some result metadata along with either an embedded result or an opaque handle that can be used to navigate to the result (see the decription of the <tt>mode</tt> parameter for more details).</p>
269<p><b>Parameters</b></p>
270
271<ul>
272
273<li><tt>statement</tt> - Specifies at least one valid SQL++ statement to run. The statements need to be urlencoded. Required.</li>
274
275<li><tt>pretty</tt> - If the parameter <tt>pretty</tt> is given with the value <tt>true</tt>, the result will be indented. (Optional)</li>
276
277<li><tt>client_context_id</tt> - A user-defined sequence of characters that the API receives and returns unchanged. This can be used e.g. to match individual requests, jobs, and responses. Another option could be to use it for groups of requests if an application decides to put e.g. an group identifier into that field to route groups of responses to a particular response processor.</li>
278
279<li><tt>mode</tt> - Result delivery mode. Possible values are <tt>immediate</tt>, <tt>deferred</tt>, <tt>async</tt> (default: <tt>immediate</tt>). If the delivery mode is <tt>immediate</tt> the query result is returned with the response. If the delivery mode is <tt>deferred</tt> the response contains a handle to the <a href="#queryresult">result</a>. If the delivery mode is <tt>async</tt> the response contains a handle to the query&#x2019;s <a href="#querystatus">status</a>.</li>
280</ul>
281<p><b>Command (immediate result delivery)</b></p>
282
283<div class="source">
284<div class="source">
285<pre>$ curl -v --data-urlencode &quot;statement=select 1;&quot; \
286 --data pretty=true \
287 --data client_context_id=xyz \
288 http://localhost:19002/query/service
289</pre></div></div>
290<p><b>Sample response</b></p>
291
292<div class="source">
293<div class="source">
294<pre>&gt; POST /query/service HTTP/1.1
295&gt; Host: localhost:19002
296&gt; User-Agent: curl/7.43.0
297&gt; Accept: */*
298&gt; Content-Length: 57
299&gt; Content-Type: application/x-www-form-urlencoded
300&gt;
301&lt; HTTP/1.1 200 OK
302&lt; transfer-encoding: chunked
303&lt; connection: keep-alive
304&lt; content-type: application/json; charset=utf-8
305&lt;
306{
307 &quot;requestID&quot;: &quot;5f72e78c-482a-45bf-b174-6443c8273025&quot;,
308 &quot;clientContextID&quot;: &quot;xyz&quot;,
309 &quot;signature&quot;: &quot;*&quot;,
310 &quot;results&quot;: [ {
311 &quot;$1&quot; : 1
312 } ]
313 ,
314 &quot;status&quot;: &quot;success&quot;,
315 &quot;metrics&quot;: {
316 &quot;elapsedTime&quot;: &quot;20.263371ms&quot;,
317 &quot;executionTime&quot;: &quot;19.889389ms&quot;,
318 &quot;resultCount&quot;: 1,
319 &quot;resultSize&quot;: 15
320 }
321}
322</pre></div></div>
323<p><b>Command (<a name="deferred" id="deferred">deferred result delivery</a>)</b></p>
324
325<div class="source">
326<div class="source">
327<pre>$ curl -v --data-urlencode &quot;statement=select 1;&quot; \
328 --data mode=deferred \
329 http://localhost:19002/query/service
330</pre></div></div>
331<p><b>Sample response</b></p>
332
333<div class="source">
334<div class="source">
335<pre>&gt; POST /query/service HTTP/1.1
336&gt; Host: localhost:19002
337&gt; User-Agent: curl/7.43.0
338&gt; Accept: */*
339&gt; Content-Length: 37
340&gt; Content-Type: application/x-www-form-urlencoded
341&gt;
342&lt; HTTP/1.1 200 OK
343&lt; transfer-encoding: chunked
344&lt; connection: keep-alive
345&lt; content-type: application/json; charset=utf-8
346&lt;
347{
348 &quot;requestID&quot;: &quot;6df7afb4-5f83-49b6-8c4b-f11ec84c4d7e&quot;,
349 &quot;signature&quot;: &quot;*&quot;,
350 &quot;handle&quot;: &quot;http://localhost:19002/query/service/result/7-0&quot;,
351 &quot;status&quot;: &quot;success&quot;,
352 &quot;metrics&quot;: {
353 &quot;elapsedTime&quot;: &quot;12.270570ms&quot;,
354 &quot;executionTime&quot;: &quot;11.948343ms&quot;,
355 &quot;resultCount&quot;: 0,
356 &quot;resultSize&quot;: 0
357 }
358}
359</pre></div></div>
360<p><b>Command (<a name="async" id="async>">async result delivery</a>)</b></p>
361
362<div class="source">
363<div class="source">
364<pre>$ curl -v --data-urlencode &quot;statement=select 1;&quot; \
365 --data mode=async \
366 http://localhost:19002/query/service
367</pre></div></div>
368<p><b>Sample response</b></p>
369
370<div class="source">
371<div class="source">
372<pre>&gt; POST /query/service HTTP/1.1
373&gt; Host: localhost:19002
374&gt; User-Agent: curl/7.43.0
375&gt; Accept: */*
376&gt; Content-Length: 34
377&gt; Content-Type: application/x-www-form-urlencoded
378&gt;
379&lt; HTTP/1.1 200 OK
380&lt; transfer-encoding: chunked
381&lt; connection: keep-alive
382&lt; content-type: application/json; charset=utf-8
383&lt;
384{
385 &quot;requestID&quot;: &quot;c5858420-d821-4c0c-81a4-2364386827c2&quot;,
386 &quot;signature&quot;: &quot;*&quot;,
387 &quot;status&quot;: &quot;running&quot;,
388 &quot;handle&quot;: &quot;http://localhost:19002/query/service/status/9-0&quot;,
389 &quot;metrics&quot;: {
390 &quot;elapsedTime&quot;: &quot;9.727006ms&quot;,
391 &quot;executionTime&quot;: &quot;9.402282ms&quot;,
392 &quot;resultCount&quot;: 0,
393 &quot;resultSize&quot;: 0
394 }
395}
396</pre></div></div></div>
397<div class="section">
398<h2><a name="GET_queryservicestatus_Back_to_TOC"></a><a name="querystatus" id="querystatus">GET /query/service/status</a><font size="4"> <a href="#toc">[Back to TOC]</a></font></h2>
399<p><b>Description</b> Returns status of an <tt>async</tt> query request. The response is a JSON object that has a similar structure to the responses for the <a href="#queryservice">/query/service</a> endpoint. Possible status values for the status are <tt>running</tt>, <tt>success</tt>, <tt>timeout</tt>, <tt>failed</tt>, and <tt>fatal</tt>. If the status value is <tt>success</tt>, the response also contains a handle to the <a href="#queryresult">result</a>. URLs for this endpoint are usually not constructed by the application, they are simply extracted from the <tt>handle</tt> field of the response to a request to the <a href="#queryservice">/query/service</a> endpoint.</p>
400<p><b>Command</b></p>
401<p>This example shows a request/reponse for the (opaque) status handle that was returned by the <a href="#async">async result delivery</a> example.</p>
402
403<div class="source">
404<div class="source">
405<pre>$ curl -v http://localhost:19002/query/service/status/9-0
406</pre></div></div>
407<p><b>Sample response</b></p>
408
409<div class="source">
410<div class="source">
411<pre>&gt; GET /query/service/status/9-0 HTTP/1.1
412&gt; Host: localhost:19002
413&gt; User-Agent: curl/7.43.0
414&gt; Accept: */*
415&gt;
416&lt; HTTP/1.1 200 OK
417&lt; transfer-encoding: chunked
418&lt; connection: keep-alive
419&lt; content-type: application/json; charset=utf-8
420&lt;
421{
422 &quot;status&quot;: &quot;success&quot;,
423 &quot;handle&quot;: &quot;http://localhost:19002/query/service/result/9-0&quot;
424}
425</pre></div></div></div>
426<div class="section">
427<h2><a name="GET_queryserviceresult_Back_to_TOC"></a><a name="queryresult" id="queryresult">GET /query/service/result</a><font size="4"> <a href="#toc">[Back to TOC]</a></font></h2>
428<p><b>Description</b> Returns result set for an <tt>async</tt> or <tt>deferred</tt> query request. The response is a plain result without a wrapping JSON object. URLs for this endpoint are usually not constructed by the application, they are simply extracted from the <tt>handle</tt> field of the response to a request to the <a href="#queryservice">/query/service</a> or the <a href="#querystatus">/query/service/status</a> endpoint.</p>
429<p><b>Command</b></p>
430<p>This example shows a request/reponse for the (opaque) result handle that was returned by the <a href="#deferred">deferred result delivery</a> example.</p>
431
432<div class="source">
433<div class="source">
434<pre>$ curl -v http://localhost:19002/query/service/result/7-0
435</pre></div></div>
436<p><b>Sample response</b></p>
437
438<div class="source">
439<div class="source">
440<pre>&gt; GET /query/service/result/7-0 HTTP/1.1
441&gt; Host: localhost:19002
442&gt; User-Agent: curl/7.43.0
443&gt; Accept: */*
444&gt;
445&lt; HTTP/1.1 200 OK
446&lt; transfer-encoding: chunked
447&lt; connection: keep-alive
448&lt; content-type: application/json
449&lt;
450[ { &quot;$1&quot;: 1 }
451 ]
452</pre></div></div></div>
453 </div>
454 </div>
455 </div>
456
457 <hr/>
458
459 <footer>
460 <div class="container-fluid">
461 <div class="row span12">Copyright &copy; 2017
462 <a href="https://www.apache.org/">The Apache Software Foundation</a>.
463 All Rights Reserved.
464
465 </div>
466
467 <?xml version="1.0" encoding="UTF-8"?>
468<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
469 feather logo, and the Apache AsterixDB project logo are either
470 registered trademarks or trademarks of The Apache Software
471 Foundation in the United States and other countries.
472 All other marks mentioned may be trademarks or registered
473 trademarks of their respective owners.</div>
474
475
476 </div>
477 </footer>
478 </body>
479</html>