| Ian Maxon | 9c40a66 | 2018-02-09 12:42:56 -0800 | [diff] [blame] | 1 | <!DOCTYPE html> |
| 2 | <!-- |
| 3 | | Generated by Apache Maven Doxia at 2018-02-09 |
| 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="20180209" /> |
| 11 | <meta http-equiv="Content-Language" content="en" /> |
| 12 | <title>AsterixDB – 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 Maxon | 9c40a66 | 2018-02-09 12:42:56 -0800 | [diff] [blame] | 22 | |
| Ian Maxon | 9c40a66 | 2018-02-09 12:42:56 -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="./" 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: 2018-02-09</li> |
| 46 | |
| 47 | |
| 48 | |
| 49 | <li id="projectVersion" class="pull-right">Version: 0.9.3</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="#queryservice">Query Service API</a></li> |
| 255 | |
| 256 | <li><a href="#querystatus">Query Status API</a></li> |
| 257 | |
| 258 | <li><a href="#queryresult">Query Result API</a></li> |
| 259 | </ul></div> |
| 260 | <div class="section"> |
| 261 | <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> |
| 262 | <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> |
| 263 | <p><b>Parameters</b></p> |
| 264 | |
| 265 | <ul> |
| 266 | |
| 267 | <li><tt>statement</tt> - Specifies at least one valid SQL++ statement to run. The statements need to be urlencoded. Required.</li> |
| 268 | |
| 269 | <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> |
| 270 | |
| 271 | <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> |
| 272 | |
| 273 | <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’s <a href="#querystatus">status</a>.</li> |
| 274 | </ul> |
| 275 | <p><b>Command (immediate result delivery)</b></p> |
| 276 | |
| 277 | <div class="source"> |
| 278 | <div class="source"> |
| 279 | <pre>$ curl -v --data-urlencode "statement=select 1;" \ |
| 280 | --data pretty=true \ |
| 281 | --data client_context_id=xyz \ |
| 282 | http://localhost:19002/query/service |
| 283 | </pre></div></div> |
| 284 | <p><b>Sample response</b></p> |
| 285 | |
| 286 | <div class="source"> |
| 287 | <div class="source"> |
| 288 | <pre>> POST /query/service HTTP/1.1 |
| 289 | > Host: localhost:19002 |
| 290 | > User-Agent: curl/7.43.0 |
| 291 | > Accept: */* |
| 292 | > Content-Length: 57 |
| 293 | > Content-Type: application/x-www-form-urlencoded |
| 294 | > |
| 295 | < HTTP/1.1 200 OK |
| 296 | < transfer-encoding: chunked |
| 297 | < connection: keep-alive |
| 298 | < content-type: application/json; charset=utf-8 |
| 299 | < |
| 300 | { |
| 301 | "requestID": "5f72e78c-482a-45bf-b174-6443c8273025", |
| 302 | "clientContextID": "xyz", |
| 303 | "signature": "*", |
| 304 | "results": [ { |
| 305 | "$1" : 1 |
| 306 | } ] |
| 307 | , |
| 308 | "status": "success", |
| 309 | "metrics": { |
| 310 | "elapsedTime": "20.263371ms", |
| 311 | "executionTime": "19.889389ms", |
| 312 | "resultCount": 1, |
| 313 | "resultSize": 15 |
| 314 | } |
| 315 | } |
| 316 | </pre></div></div> |
| 317 | <p><b>Command (<a name="deferred" id="deferred">deferred result delivery</a>)</b></p> |
| 318 | |
| 319 | <div class="source"> |
| 320 | <div class="source"> |
| 321 | <pre>$ curl -v --data-urlencode "statement=select 1;" \ |
| 322 | --data mode=deferred \ |
| 323 | http://localhost:19002/query/service |
| 324 | </pre></div></div> |
| 325 | <p><b>Sample response</b></p> |
| 326 | |
| 327 | <div class="source"> |
| 328 | <div class="source"> |
| 329 | <pre>> POST /query/service HTTP/1.1 |
| 330 | > Host: localhost:19002 |
| 331 | > User-Agent: curl/7.43.0 |
| 332 | > Accept: */* |
| 333 | > Content-Length: 37 |
| 334 | > Content-Type: application/x-www-form-urlencoded |
| 335 | > |
| 336 | < HTTP/1.1 200 OK |
| 337 | < transfer-encoding: chunked |
| 338 | < connection: keep-alive |
| 339 | < content-type: application/json; charset=utf-8 |
| 340 | < |
| 341 | { |
| 342 | "requestID": "6df7afb4-5f83-49b6-8c4b-f11ec84c4d7e", |
| 343 | "signature": "*", |
| 344 | "handle": "http://localhost:19002/query/service/result/7-0", |
| 345 | "status": "success", |
| 346 | "metrics": { |
| 347 | "elapsedTime": "12.270570ms", |
| 348 | "executionTime": "11.948343ms", |
| 349 | "resultCount": 0, |
| 350 | "resultSize": 0 |
| 351 | } |
| 352 | } |
| 353 | </pre></div></div> |
| 354 | <p><b>Command (<a name="async" id="async>">async result delivery</a>)</b></p> |
| 355 | |
| 356 | <div class="source"> |
| 357 | <div class="source"> |
| 358 | <pre>$ curl -v --data-urlencode "statement=select 1;" \ |
| 359 | --data mode=async \ |
| 360 | http://localhost:19002/query/service |
| 361 | </pre></div></div> |
| 362 | <p><b>Sample response</b></p> |
| 363 | |
| 364 | <div class="source"> |
| 365 | <div class="source"> |
| 366 | <pre>> POST /query/service HTTP/1.1 |
| 367 | > Host: localhost:19002 |
| 368 | > User-Agent: curl/7.43.0 |
| 369 | > Accept: */* |
| 370 | > Content-Length: 34 |
| 371 | > Content-Type: application/x-www-form-urlencoded |
| 372 | > |
| 373 | < HTTP/1.1 200 OK |
| 374 | < transfer-encoding: chunked |
| 375 | < connection: keep-alive |
| 376 | < content-type: application/json; charset=utf-8 |
| 377 | < |
| 378 | { |
| 379 | "requestID": "c5858420-d821-4c0c-81a4-2364386827c2", |
| 380 | "signature": "*", |
| 381 | "status": "running", |
| 382 | "handle": "http://localhost:19002/query/service/status/9-0", |
| 383 | "metrics": { |
| 384 | "elapsedTime": "9.727006ms", |
| 385 | "executionTime": "9.402282ms", |
| 386 | "resultCount": 0, |
| 387 | "resultSize": 0 |
| 388 | } |
| 389 | } |
| 390 | </pre></div></div></div> |
| 391 | <div class="section"> |
| 392 | <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> |
| 393 | <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> |
| 394 | <p><b>Command</b></p> |
| 395 | <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> |
| 396 | |
| 397 | <div class="source"> |
| 398 | <div class="source"> |
| 399 | <pre>$ curl -v http://localhost:19002/query/service/status/9-0 |
| 400 | </pre></div></div> |
| 401 | <p><b>Sample response</b></p> |
| 402 | |
| 403 | <div class="source"> |
| 404 | <div class="source"> |
| 405 | <pre>> GET /query/service/status/9-0 HTTP/1.1 |
| 406 | > Host: localhost:19002 |
| 407 | > User-Agent: curl/7.43.0 |
| 408 | > Accept: */* |
| 409 | > |
| 410 | < HTTP/1.1 200 OK |
| 411 | < transfer-encoding: chunked |
| 412 | < connection: keep-alive |
| 413 | < content-type: application/json; charset=utf-8 |
| 414 | < |
| 415 | { |
| 416 | "status": "success", |
| 417 | "handle": "http://localhost:19002/query/service/result/9-0" |
| 418 | } |
| 419 | </pre></div></div></div> |
| 420 | <div class="section"> |
| 421 | <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> |
| 422 | <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> |
| 423 | <p><b>Command</b></p> |
| 424 | <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> |
| 425 | |
| 426 | <div class="source"> |
| 427 | <div class="source"> |
| 428 | <pre>$ curl -v http://localhost:19002/query/service/result/7-0 |
| 429 | </pre></div></div> |
| 430 | <p><b>Sample response</b></p> |
| 431 | |
| 432 | <div class="source"> |
| 433 | <div class="source"> |
| 434 | <pre>> GET /query/service/result/7-0 HTTP/1.1 |
| 435 | > Host: localhost:19002 |
| 436 | > User-Agent: curl/7.43.0 |
| 437 | > Accept: */* |
| 438 | > |
| 439 | < HTTP/1.1 200 OK |
| 440 | < transfer-encoding: chunked |
| 441 | < connection: keep-alive |
| 442 | < content-type: application/json |
| 443 | < |
| 444 | [ { "$1": 1 } |
| 445 | ] |
| 446 | </pre></div></div></div> |
| 447 | </div> |
| 448 | </div> |
| 449 | </div> |
| 450 | |
| 451 | <hr/> |
| 452 | |
| 453 | <footer> |
| 454 | <div class="container-fluid"> |
| 455 | <div class="row span12">Copyright © 2018 |
| 456 | <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| 457 | All Rights Reserved. |
| 458 | |
| 459 | </div> |
| 460 | |
| 461 | <?xml version="1.0" encoding="UTF-8"?> |
| 462 | <div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache |
| 463 | feather logo, and the Apache AsterixDB project logo are either |
| 464 | registered trademarks or trademarks of The Apache Software |
| 465 | Foundation in the United States and other countries. |
| 466 | All other marks mentioned may be trademarks or registered |
| 467 | trademarks of their respective owners.</div> |
| 468 | |
| 469 | |
| 470 | </div> |
| 471 | </footer> |
| 472 | </body> |
| 473 | </html> |