1
0
Fork 0
arangodb/Doxygen/doc/HttpQueries.html

135 lines
6.1 KiB
HTML

<html><head><title>ArangoDB Manual</title> <style media="screen" type="text/css" style="display:none">body{background-color:white;font:13px Helvetica,arial,freesans,clean,sans-serif;line-height:1.4;color:#333;}#access{font-size:16px;margin-left:12px;display:block;margin-left:10px;margin-right:10px;background-color:#F3F1EE!important;}#access a{border-right:1px solid #DBDEDF;color:#A49F96;display:block;line-height:38px;padding:0 10px;text-decoration:none;}#navigation ul{text-transform:uppercase;list-style:none;margin:0;}#navigation li{float:left;position:relative;}#container{width:920px;margin:0 auto;}a{color:#4183C4;text-decoration:none;}.contents h2{font-size:24px;border-bottom:1px solid #CCC;color:black;}.contents h1{font-size:33px;border-bottom:1px solid #CCC;color:black;}.clearfix:after{content:".";display:block;clear:both;font-size:0;height:0;visibility:hidden;}/**/ *:first-child+html .clearfix{min-height:0;}/**/ * html .clearfix{height:1%;}</style></head><body><div id="container"><img src="images/logo_arangodb.png" width="397" height="67" alt="ArangoDB"><div id="access" role="navigation"><div id="navigation"><ul id="menu-ahome" class="menu"><li><a href="Home.html">Table of contents</a></li> <li><a href="http://www.arangodb.org">ArangoDB homepage</a></li></ul></div><div class="clearfix"></div></div><div>
<!-- Generated by Doxygen 1.7.5.1 -->
</div>
<div class="header">
<div class="headertitle">
<h1>HTTP Interface for AQL Queries </h1> </div>
</div>
<div class="contents">
<div class="textblock"><p>ArangoDB has an Http interface to syntactically validate AQL queries. Furthermore, it offers an Http interface to retrieve the execution plan for any valid AQL query.</p>
<p>Both functionalities do not actually execute the supplied AQL query, but only inspect it and return meta information about it.</p>
<p><a class="anchor" id="HttpExplainPost"></a> <hr/>
<em>POST /_api/explain</em> (explains a query)<hr/>
<br/>
<code><b>POST /_api/explain</b></code></p>
<p>To explain how a query would be executed (without actually executing it), the query string can be passed to the server via an HTTP POST request.</p>
<p>These query string needs to be passed in the attribute <code>query</code> of a JSON object as the body of the POST request. If the query references any bind variables, these must also be passed in the attribute <code>bindVars</code>.</p>
<p>If the query is valid, the server will respond with <code>HTTP 200</code> and return a list of the individual query execution steps in the <code>"plan"</code> attribute of the response.</p>
<p>The server will respond with <code>HTTP 400</code> in case of a malformed request, or if the query contains a parse error. The body of the response will contain the error details embedded in a JSON object. Omitting bind variables if the query references any will result also result in an <code>HTTP 400</code> error.</p>
<p><b>Examples</b><br/>
</p>
<p>Valid query:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/explain
{ "query" : "FOR u IN users FILTER u.id == @id LIMIT 2 RETURN u.name", "bindVars": { "id" : 3 } }
HTTP/1.1 200 OK
content-type: application/json
{
"plan": [
{ "id": 1,
"level": 1,
"type": "for",
"resultVariable": "u",
"expression": {
"type": "collection",
"value": "users",
"extra": {
"accessType": "index",
"index": {
"id": "1392880787389/1425650910275",
"type": "hash",
"attributes": "id"
}
}
}
},
{
"id": 2,
"level": 1,
"type": "filter",
"expression": {
"type": "expression",
"value": "u.id == 3"
}
},
{
"id": 3,
"level": 1,
"type": "limit",
"offset": 0,
"count": 2
},
{
"id": 4,
"level": 1,
"type": "limit",
"offset": 0,
"count": 2
},
{
"id": 5,
"level": 1,
"type": "return",
"expression": {
"type": "expression",
"value": "u.name"
}
}
],
"error": false,
"code": 200
}
</pre></div><p>Invalid query:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/explain
{ "query" : "FOR u IN users FILTER u.name == @name LIMIT 2 RETURN u.n" }
HTTP/1.1 400 Bad Request
content-type: application/json
{
"errorNum": 1551,
"errorMessage": "no value specified for declared bind parameter 'name'",
"error": true,
"code": 400
}
</pre></div> <p><a class="anchor" id="HttpQueryPost"></a> <hr/>
<em>POST /_api/query</em> (parses a query)<hr/>
<br/>
<code><b>POST /_api/query</b></code></p>
<p>To validate a query string without executing it, the query string can be passed to the server via an HTTP POST request.</p>
<p>These query string needs to be passed in the attribute <code>query</code> of a JSON object as the body of the POST request.</p>
<p>If the query is valid, the server will respond with <code>HTTP 200</code> and return the names of the bind parameters it found in the query (if any) in the <code>"bindVars"</code> attribute of the response.</p>
<p>The server will respond with <code>HTTP 400</code> in case of a malformed request, or if the query contains a parse error. The body of the response will contain the error details embedded in a JSON object.</p>
<p><b>Examples</b><br/>
</p>
<p>Valid query:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/query
{ "query" : "FOR u IN users FILTER u.name == @name LIMIT 2 RETURN u.n" }
HTTP/1.1 200 OK
content-type: application/json
{
"error": false,
"bindVars": [
"name"
],
"code": 200
}
</pre></div><p>Invalid query:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/query
{ "query" : "FOR u IN users FILTER u.name = @name LIMIT 2 RETURN u.n" }
HTTP/1.1 400 Bad Request
content-type: application/json
{
"errorNum": 1501,
"errorMessage": "parse error: %s: parse error: 1:29 syntax error, unexpected assignment near ' = @name LIMIT 2 RETURN u.n'",
"error": true,
"code": 400
}
</pre></div> </div></div>
</div></body></html>