Blame - docs/0.9.6/api.html - incubator-asterixdb-site

Ian Maxon

49d15b2

2020-12-06 16:23:00 -0800

[diff] [blame^]

1

<!DOCTYPE html>

2

<!--

3

| Generated by Apache Maven Doxia Site Renderer 1.8.1 from src/site/markdown/api.md at 2020-12-06

4

| Rendered using Apache Maven Fluido Skin 1.7

-->

<head>

<title>AsterixDB – HTTP API to AsterixDB</title>

</head>

</div>

<li id="publishDate">Last Published: 2020-12-06</li>

30

<li id="projectVersion" class="pull-right">Version: 0.9.6-SNAPSHOT</li>

31

<li class="pull-right"><a href="index.html" title="Documentation Home">Documentation Home</a></li>

</ul>

</div>

<li class="nav-header">Get Started - Installation</li>

39

<li><a href="ncservice.html" title="Option 1: using NCService"><span class="none"></span>Option 1: using NCService</a></li>

40

<li><a href="ansible.html" title="Option 2: using Ansible"><span class="none"></span>Option 2: using Ansible</a></li>

41

<li><a href="aws.html" title="Option 3: using Amazon Web Services"><span class="none"></span>Option 3: using Amazon Web Services</a></li>

42

<li class="nav-header">AsterixDB Primer</li>

43

<li><a href="sqlpp/primer-sqlpp.html" title="Using SQL++"><span class="none"></span>Using SQL++</a></li>

44

<li class="nav-header">Data Model</li>

45

<li><a href="datamodel.html" title="The Asterix Data Model"><span class="none"></span>The Asterix Data Model</a></li>

46

<li class="nav-header">Queries</li>

47

<li><a href="sqlpp/manual.html" title="The SQL++ Query Language"><span class="none"></span>The SQL++ Query Language</a></li>

48

<li><a href="SQLPP.html" title="Raw SQL++ Grammar"><span class="none"></span>Raw SQL++ Grammar</a></li>

49

<li><a href="sqlpp/builtins.html" title="Builtin Functions"><span class="none"></span>Builtin Functions</a></li>

50

51

52

<li><a href="csv.html" title="CSV Output"><span class="none"></span>CSV Output</a></li>

53

<li class="nav-header">Advanced Features</li>

54

<li><a href="aql/externaldata.html" title="Accessing External Data"><span class="none"></span>Accessing External Data</a></li>

55

<li><a href="feeds.html" title="Data Ingestion with Feeds"><span class="none"></span>Data Ingestion with Feeds</a></li>

56

<li><a href="udf.html" title="User Defined Functions"><span class="none"></span>User Defined Functions</a></li>

57

<li><a href="sqlpp/filters.html" title="Filter-Based LSM Index Acceleration"><span class="none"></span>Filter-Based LSM Index Acceleration</a></li>

58

<li><a href="sqlpp/fulltext.html" title="Support of Full-text Queries"><span class="none"></span>Support of Full-text Queries</a></li>

59

<li><a href="sqlpp/similarity.html" title="Support of Similarity Queries"><span class="none"></span>Support of Similarity Queries</a></li>

60

<li><a href="interval_join.html" title="Support of Interval Joins"><span class="none"></span>Support of Interval Joins</a></li>

61

<li class="nav-header">Deprecated</li>

62

<li><a href="aql/primer.html" title="AsterixDB Primer: Using AQL"><span class="none"></span>AsterixDB Primer: Using AQL</a></li>

63

<li><a href="aql/manual.html" title="Queries: The Asterix Query Language (AQL)"><span class="none"></span>Queries: The Asterix Query Language (AQL)</a></li>

64

<li><a href="aql/builtins.html" title="Queries: Builtin Functions (AQL)"><span class="none"></span>Queries: Builtin Functions (AQL)</a></li>

</ul>

<hr />

</div>

</div>

</div>

<!--

! Licensed to the Apache Software Foundation (ASF) under one

79

! or more contributor license agreements. See the NOTICE file

80

! distributed with this work for additional information

81

! regarding copyright ownership. The ASF licenses this file

82

! to you under the Apache License, Version 2.0 (the

83

! "License"); you may not use this file except in compliance

84

! with the License. You may obtain a copy of the License at

85

!

86

! http://www.apache.org/licenses/LICENSE-2.0

87

!

88

! Unless required by applicable law or agreed to in writing,

89

! software distributed under the License is distributed on an

90

! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

91

! KIND, either express or implied. See the License for the

92

! specific language governing permissions and limitations

93

! under the License.

94

!-->

95

<h1>HTTP API to AsterixDB</h1>

96

97

<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2>

98

<ul>

99

100

<li><a href="#queryservice">Query Service API</a></li>

101

<li><a href="#querystatus">Query Status API</a></li>

102

<li><a href="#queryresult">Query Result API</a></li>

103

</ul></div>

104

105

<h2><a name="POST_.2Fquery.2Fservice_.5BBack_to_TOC.5D"></a><a name="queryservice" id="queryservice">POST /query/service</a><font size="4"> <a href="#toc">[Back to TOC]</a></font></h2>

106

<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>

107

<p><b>Parameters</b></p>

108

<ul>

109

110

<li><tt>statement</tt> - Specifies at least one valid SQL++ statement to run. The statements need to be urlencoded. Required.</li>

111

<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>

112

<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>

113

<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>

114

<li><tt>readonly</tt> - Reject DDL and DML statements, only accept the following kinds: <a href="sqlpp/manual.html#SELECT_statements">SELECT</a>, <a href="sqlpp/manual.html#Declarations">USE</a>, <a href="sqlpp/manual.html#Declarations">DECLARE FUNCTION</a>, and <a href="sqlpp/manual.html#Performance_tuning">SET</a></li>

115

<li><tt>args</tt> - (SQL++ only) A JSON array where each item is a value of a <a href="sqlpp/manual.html#Parameter_references">positional query parameter</a></li>

116

<li><tt>$parameter_name</tt> - (SQL++ only) a JSON value of a <a href="sqlpp/manual.html#Parameter_references">named query parameter</a>.</li>

117

</ul>

118

<p><b>Command (immediate result delivery)</b></p>

<div>

<div>

<pre class="source">$ curl -v --data-urlencode "statement=select 1;" \

123

--data pretty=true \

124

--data client_context_id=xyz \

125

http://localhost:19002/query/service

126

</pre></div></div>

127

128

<p><b>Sample response</b></p>

<div>

<div>

<pre class="source">> POST /query/service HTTP/1.1

133

> Host: localhost:19002

134

> User-Agent: curl/7.43.0

135

> Accept: */*

136

> Content-Length: 57

137

> Content-Type: application/x-www-form-urlencoded

138

>

139

< HTTP/1.1 200 OK

140

< transfer-encoding: chunked

141

< connection: keep-alive

142

< content-type: application/json; charset=utf-8

143

<

144

{

145

"requestID": "5f72e78c-482a-45bf-b174-6443c8273025",

146

"clientContextID": "xyz",

"signature": "*",

"results": [ {

"$1" : 1

} ]

,

"status": "success",

"metrics": {

"elapsedTime": "20.263371ms",

155

"executionTime": "19.889389ms",

"resultCount": 1,

"resultSize": 15

}

}

</pre></div></div>

<p><b>Command (<a name="deferred" id="deferred">deferred result delivery</a>)</b></p>

<div>

<div>

<pre class="source">$ curl -v --data-urlencode "statement=select 1;" \

167

--data mode=deferred \

168

http://localhost:19002/query/service

169

</pre></div></div>

170

171

<p><b>Sample response</b></p>

<div>

<div>

<pre class="source">> POST /query/service HTTP/1.1

176

> Host: localhost:19002

177

> User-Agent: curl/7.43.0

178

> Accept: */*

179

> Content-Length: 37

180

> Content-Type: application/x-www-form-urlencoded

181

>

182

< HTTP/1.1 200 OK

183

< transfer-encoding: chunked

184

< connection: keep-alive

185

< content-type: application/json; charset=utf-8

186

<

187

{

188

"requestID": "6df7afb4-5f83-49b6-8c4b-f11ec84c4d7e",

189

"signature": "*",

190

"handle": "http://localhost:19002/query/service/result/7-0",

191

"status": "success",

192

"metrics": {

193

"elapsedTime": "12.270570ms",

194

"executionTime": "11.948343ms",

"resultCount": 0,

"resultSize": 0

}

}

</pre></div></div>

<p><b>Command (<a name="async" id="async>">async result delivery</a>)</b></p>

<div>

<div>

<pre class="source">$ curl -v --data-urlencode "statement=select 1;" \

206

--data mode=async \

207

http://localhost:19002/query/service

208

</pre></div></div>

209

210

<p><b>Sample response</b></p>

<div>

<div>

<pre class="source">> POST /query/service HTTP/1.1

215

> Host: localhost:19002

216

> User-Agent: curl/7.43.0

217

> Accept: */*

218

> Content-Length: 34

219

> Content-Type: application/x-www-form-urlencoded

220

>

221

< HTTP/1.1 200 OK

222

< transfer-encoding: chunked

223

< connection: keep-alive

224

< content-type: application/json; charset=utf-8

225

<

226

{

227

"requestID": "c5858420-d821-4c0c-81a4-2364386827c2",

228

"signature": "*",

229

"status": "running",

230

"handle": "http://localhost:19002/query/service/status/9-0",

231

"metrics": {

232

"elapsedTime": "9.727006ms",

233

"executionTime": "9.402282ms",

"resultCount": 0,

"resultSize": 0

}

}

</pre></div></div>

</div>

<h2><a name="GET_.2Fquery.2Fservice.2Fstatus_.5BBack_to_TOC.5D"></a><a name="querystatus" id="querystatus">GET /query/service/status</a><font size="4"> <a href="#toc">[Back to TOC]</a></font></h2>

242

<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>

243

<p><b>Command</b></p>

244

<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>

<div>

<div>

<pre class="source">$ curl -v http://localhost:19002/query/service/status/9-0

249

</pre></div></div>

250

251

<p><b>Sample response</b></p>

<div>

<div>

<pre class="source">> GET /query/service/status/9-0 HTTP/1.1

256

> Host: localhost:19002

257

> User-Agent: curl/7.43.0

> Accept: */*

>

< HTTP/1.1 200 OK

< transfer-encoding: chunked

262

< connection: keep-alive

263

< content-type: application/json; charset=utf-8

<

{

"status": "success",

"handle": "http://localhost:19002/query/service/result/9-0"

}

</pre></div></div>

</div>

<h2><a name="GET_.2Fquery.2Fservice.2Fresult_.5BBack_to_TOC.5D"></a><a name="queryresult" id="queryresult">GET /query/service/result</a><font size="4"> <a href="#toc">[Back to TOC]</a></font></h2>

273

<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>

274

<p><b>Command</b></p>

275

<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>

<div>

<div>

<pre class="source">$ curl -v http://localhost:19002/query/service/result/7-0

280

</pre></div></div>

281

282

<p><b>Sample response</b></p>