Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
arangodb/Doxygen/doc/HttpSimple.html

469 lines
18 KiB
HTML
Raw Blame History

<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 Simple Queries </h1> </div>
</div>
<div class="contents">
<div class="textblock"><p>This is an introduction to ArangoDB's Http interface for simple queries.</p>
<hr/>
<ul>
<li>
<a class="el" href="HttpSimple.html">HTTP Interface for Simple Queries</a> <ul>
<li>
<a class="el" href="HttpSimple.html#HttpSimpleIntro">Simple Queries</a> </li>
<li>
<a class="el" href="HttpSimple.html#HttpSimpleHttp">Working with Simples Queries using HTTP</a> <ul>
<li>
<a class="el" href="HttpSimple.html#HttpSimpleAll">POST /_api/simple/all</a> </li>
<li>
<a class="el" href="HttpSimple.html#HttpSimpleByExample">POST /_api/simple/by-example</a> </li>
<li>
<a class="el" href="HttpSimple.html#HttpSimpleFirstExample">POST /_api/simple/first-example</a> </li>
<li>
<a class="el" href="HttpSimple.html#HttpSimpleRange">POST /_api/simple/range</a> </li>
<li>
<a class="el" href="HttpSimple.html#HttpSimpleNear">POST /_api/simple/near</a> </li>
<li>
<a class="el" href="HttpSimple.html#HttpSimpleWithin">POST /_api/simple/within</a> </li>
</ul>
</li>
</ul>
</li>
</ul>
<hr/>
<h2><a class="anchor" id="HttpSimpleIntro"></a>
Simple Queries</h2>
<p>Simple queries can be used if the query condition is straight forward simple, i.e., a document reference, all documents, a query-by-example, or a simple geo query. In a simple query you can specify exactly one collection and one condition. The result can then be sorted and can be split into pages.</p>
<h2><a class="anchor" id="HttpSimpleHttp"></a>
Working with Simples Queries using HTTP</h2>
<p>To limit the amount of results to be transferred in one batch, simple queries support a <code>batchSize</code> parameter that can optionally be used to tell the server to limit the number of results to be transferred in one batch to a certain value. If the query has more results than were transferred in one go, more results are waiting on the server so they can be fetched subsequently. If no value for the <code>batchSize</code> parameter is specified, the server will use a reasonable default value.</p>
<p>If the server has more documents than should be returned in a single batch, the server will set the <code>hasMore</code> attribute in the result. It will also return the id of the server-side cursor in the <code>id</code> attribute in the result. This id can be used with the cursor API to fetch any outstanding results from the server and dispose the server-side cursor afterwards.</p>
<p><a class="anchor" id="HttpSimpleAll"></a> <hr/>
<em>PUT /_api/simple/all</em> (executes simple query "all")<hr/>
<br/>
<code><b>PUT /_api/simple/all</b></code></p>
<p>Returns all documents of a collections. The call expects a JSON object as body with the following attributes:</p>
<ul>
<li><code>collection</code>: The identifier or name of the collection to query.</li>
</ul>
<ul>
<li><code>skip</code>: The number of documents to skip in the query (optional).</li>
</ul>
<ul>
<li><code>limit</code>: The maximal amount of documents to return. The <code>skip</code> is applied before the <code>limit</code> restriction. (optional)</li>
</ul>
<p>Returns a cursor containing the result, see <a class="el" href="HttpCursor.html">HTTP Interface for AQL Query Cursors</a> for details.</p>
<p><b>Examples</b><br/>
</p>
<p>Limit the amount of documents using <code>limit</code></p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/all
{ "collection" : "4421689145", "skip" : 2900, "limit" : 2 }
HTTP/1.1 201 Created
content-type: application/json
{
"code": 201,
"hasMore": false,
"result": [
{
"n": 1679,
"_rev": 4533165881,
"_id": "4421689145/4533165881"
},
{
"n": 679,
"_rev": 4467629881,
"_id": "4421689145/4467629881"
}
],
"count": 2,
"error": false
}
</pre></div><p>Using a <code>batchSize</code> value</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/all
{ "collection" : "4421689145", "batchSize" : 2 }
HTTP/1.1 201 Created
content-type: application/json
{
"code": 201,
"hasMore": true,
"result": [
{
"n": 1679,
"_rev": 4533165881,
"_id": "4421689145/4533165881"
},
{
"n": 679,
"_rev": 4467629881,
"_id": "4421689145/4467629881"
}
],
"id":142116766,
"count": 3000,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpSimpleByExample"></a> <hr/>
<em>PUT /_api/simple/by-example</em> (executes simple query "by-example")<hr/>
<br/>
<code><b>PUT /_api/simple/by-example</b></code></p>
<p>This will find all documents matching a given example.</p>
<p>The call expects a JSON hash array as body with the following attributes:</p>
<ul>
<li><code>collection</code>: The identifier or name of the collection to query.</li>
</ul>
<ul>
<li><code>example</code>: The example.</li>
</ul>
<ul>
<li><code>skip</code>: The documents to skip in the query. (optional)</li>
</ul>
<ul>
<li><code>limit</code>: The maximal amount of documents to return. (optional)</li>
</ul>
<p>Returns a cursor containing the result, see <a class="el" href="HttpCursor.html">HTTP Interface for AQL Query Cursors</a> for details.</p>
<p><b>Examples</b><br/>
</p>
<p>Matching an attribute:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/by-example
{ "collection" : "3179705695", "example" : [ { "i" : 1 } ] }
HTTP/1.1 201 Created
content-type: application/json
{
"result": [
{ "a": { "k": 2, "j": 2 }, "i": 1, "_rev": 3181802847, "_id": "3179705695/3181802847" },
{ "a": { "j": 1 }, "i": 1, "_rev": 3181475167, "_id": "3179705695/3181475167" },
{ "a": { "k": 1, "j": 1 }, "i": 1, "_rev": 3181737311, "_id": "3179705695/3181737311" },
{ "i": 1, "_rev": 3181147487, "_id": "3179705695/3181147487" }
],
"count": 4,
"error": false,
"hasMore": false,
"code": 201
}
</pre></div><p>Matching an attribute which is a sub-document:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/by-example
{ "collection" : "3179705695", "example" : [ { "a" : { "j" : 1 } } ] }
HTTP/1.1 201 Created
content-type: application/json
{
"result": [
{ "a": { "j": 1 }, "i": 1, "_rev": 3181475167, "_id": "3179705695/3181475167" }
],
"count": 1,
"error": false,
"hasMore": false,
"code": 201
}
</pre></div><p>Matching an attribute within a sub-document:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/by-example
{ "collection" : "3179705695", "example" : [ "a.j", 1 ] }
HTTP/1.1 201 Created
content-type: application/json
{
"result": [
{ "a": { "j": 1 }, "i": 1, "_rev": 3181475167, "_id": "3179705695/3181475167" },
{ "a": { "k": 1, "j": 1 }, "i": 1, "_rev": 3181737311, "_id": "3179705695/3181737311" }
],
"count": 2,
"error": false,
"hasMore": false,
"code": 201
}
</pre></div> <p><a class="anchor" id="HttpSimpleFirstExample"></a> <hr/>
<em>PUT /_api/simple/first-example</em> (executes simple query "first-example")<hr/>
<br/>
<code><b>PUT /_api/simple/first-example</b></code></p>
<p>This will return the first document matching a given example.</p>
<p>The call expects a JSON hash array as body with the following attributes:</p>
<ul>
<li><code>collection</code>: The identifier or name of the collection to query.</li>
</ul>
<ul>
<li><code>example</code>: The example.</li>
</ul>
<p>Returns a result containing the document or <code>HTTP 404</code> if no document matched the example.</p>
<p><b>Examples</b><br/>
</p>
<p>If a matching document was found:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/first-example
{ "collection" : "666351134", "example" : [ "a.j", 1, "a.k", 1 ] }
HTTP/1.1 200 OK
content-type: application/json
{
"error": false,
"code": 200,
"document": { "_rev": 668382750, "_id": "666351134/668382750", "a": { "k": 1, "j": 1, "l" : 10 }, "i": 1 }
}
</pre></div><p>If no document was found:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/first-example
{ "collection" : "666351134", "example" : [ "a.j", 1, "a.k", 2 ] }
HTTP/1.1 404 Not Found
content-type: application/json
{
"errorMessage": "no match",
"error": true,
"code": 404,
"errorNum": 404
}
</pre></div> <p><a class="anchor" id="HttpSimpleRange"></a> <hr/>
<em>PUT /_api/simple/range</em> (executes simple range query)<hr/>
<br/>
<code><b>PUT /_api/simple/range</b></code></p>
<p>This will find all documents within a given range. You must declare a skip-list index on the attribute in order to be able to use a range query.</p>
<p>The call expects a JSON hash array as body with the following attributes:</p>
<ul>
<li><code>collection</code>: The identifier or name of the collection to query.</li>
</ul>
<ul>
<li><code>attribute</code>: The attribute path to check.</li>
</ul>
<ul>
<li><code>left</code>: The lower bound.</li>
</ul>
<ul>
<li><code>right</code>: The upper bound.</li>
</ul>
<ul>
<li><code>closed</code>: If true, use intervall including <code>left</code> and <code>right</code>, otherwise exclude <code>right</code>, but include <code>left</code>.</li>
</ul>
<ul>
<li><code>skip</code>: The documents to skip in the query. (optional)</li>
</ul>
<ul>
<li><code>limit</code>: The maximal amount of documents to return. (optional)</li>
</ul>
<p>Returns a cursor containing the result, see <a class="el" href="HttpCursor.html">HTTP Interface for AQL Query Cursors</a> for details.</p>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/range
{ "collection" : "6328369086", "attribute" : "i", "left" : 2, "right" : 4 }
HTTP/1.1 201 Created
content-type: application/json
{
"code": 201,
"result": [
{ "_id": "6328369086/6329876414", "i": 2, "_rev": 6329876414 },
{ "_id": "6328369086/6329941950", "i": 3, "_rev": 6329941950 }
],
"count": 2,
"hasMore": false,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpSimpleNear"></a> <hr/>
<em>PUT /_api/simple/near</em> (executes simple query "near")<hr/>
<br/>
<code><b>PUT /_api/simple/near</b></code></p>
<p>The default will find at most 100 documents near a given coordinate. The returned list is sorted according to the distance, with the nearest document coming first. If there are near documents of equal distance, documents are chosen randomly from this set until the limit is reached.</p>
<p>In order to use the <code>near</code> operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the <code>geo</code> field to select a particular index.</p>
<p>The call expects a JSON hash array as body with the following attributes:</p>
<ul>
<li><code>collection</code>: The identifier or name of the collection to query.</li>
</ul>
<ul>
<li><code>latitude</code>: The latitude of the coordinate.</li>
</ul>
<ul>
<li><code>longitude</code>: The longitude of the coordinate.</li>
</ul>
<ul>
<li><code>distance</code>: If given, the attribute key used to store the distance. (optional)</li>
</ul>
<ul>
<li><code>skip</code>: The number of documents to skip in the query. (optional)</li>
</ul>
<ul>
<li><code>limit</code>: The maximal amount of documents to return. The <code>skip</code> is applied before the <code>limit</code> restriction. The default is 100. (optional)</li>
</ul>
<ul>
<li><code>geo</code>: If given, the identifier of the geo-index to use. (optional)</li>
</ul>
<p>Returns a cursor containing the result, see <a class="el" href="HttpCursor.html">HTTP Interface for AQL Query Cursors</a> for details.</p>
<p><b>Examples</b><br/>
</p>
<p>Without distance:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/near
{ "collection" : "11172897562", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 2 }
HTTP/1.1 201 Created
content-type: application/json
{
"hasMore": false,
"count": 5,
"result": [
{
"_id": "11172897562/11178271514",
"loc": [ 0, -10 ],
"_rev": 11178271514
},
{
"_id": "11172897562/11177616154",
"loc": [ -10, 0 ],
"_rev": 11177616154
}
],
"code": 201,
"error": false
}
</pre></div><p>With distance:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/near
{ "collection" : "11182465818", "latitude" : 0, "longitude" : 0, "limit" : 2, "distance" : "distance" }
HTTP/1.1 201 Created
content-type: application/json
{
"hasMore": false,
"count": 5,
"result": [
{
"distance": 0,
"_id": "11182465818/11187905306",
"loc": [ 0, 0 ],
"_rev": 11187905306
},
{
"distance": 1111949.26644559,
"_id": "11182465818/11187839770",
"loc": [ 0, -10 ],
"_rev": 11187839770
}
],
"code": 201,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpSimpleWithin"></a> <hr/>
<em>PUT /_api/simple/within</em> (executes simple query "within")<hr/>
<br/>
<code><b>PUT /_api/simple/within</b></code></p>
<p>This will find all documents with in a given radius around the coordinate (<em>latitude</em>, <em>longitude</em>). The returned list is sorted by distance.</p>
<p>In order to use the <code>within</code> operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the <code>geo</code> field to select a particular index.</p>
<p>The call expects a JSON hash array as body with the following attributes:</p>
<ul>
<li><code>collection</code>: The identifier or name of the collection to query.</li>
</ul>
<ul>
<li><code>latitude</code>: The latitude of the coordinate.</li>
</ul>
<ul>
<li><code>longitude</code>: The longitude of the coordinate.</li>
</ul>
<ul>
<li><code>radius</code>: The maximal radius (in meters).</li>
</ul>
<ul>
<li><code>distance</code>: If given, the result attribute key used to store the distance values (optional). If specified, distances are returned in meters.</li>
</ul>
<ul>
<li><code>skip</code>: The documents to skip in the query. (optional)</li>
</ul>
<ul>
<li><code>limit</code>: The maximal amount of documents to return. (optional)</li>
</ul>
<ul>
<li><code>geo</code>: If given, the identifier of the geo-index to use. (optional)</li>
</ul>
<p>Returns a cursor containing the result, see <a class="el" href="HttpCursor.html">HTTP Interface for AQL Query Cursors</a> for details.</p>
<p><b>Examples</b><br/>
</p>
<p>Without distance:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/within
{ "collection" : "2076584128", "latitude" : 0, "longitude" : 0, "skip" : 1, "radius" : 1111950 }
HTTP/1.1 201 Created
content-type: application/json
{
"result": [
{
"_id": "2076584128/2082744512",
"loc": [ 10, 0 ],
"_rev": 2082744512
},
{
"_id": "2076584128/2082089152",
"loc": [ 0, 10 ],
"_rev": 2082089152
},
{
"_id": "2076584128/2081302720",
"loc": [ -10, 0 ],
"_rev": 2081302720
},
{
"_id": "2076584128/2081958080",
"loc": [ 0, -10 ],
"_rev": 2081958080
}
],
"code": 201,
"hasMore": false,
"count": 4,
"error": false
}
</pre></div><p>With distance:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/within
{ "collection" : "2086152384", "latitude" : 0, "longitude" : 0, "distance" : "distance", "radius" : 1111950 }
HTTP/1.1 201 Created
content-type: application/json
{
"result": [
{
"distance": 0,
"_id": "2086152384/2091591872",
"loc": [ 0, 0 ],
"_rev": 2091591872
},
{
"distance": 1111949.26644559,
"_id": "2086152384/2090870976",
"loc": [ -10, 0 ],
"_rev": 2090870976
},
{
"distance": 1111949.26644559,
"_id": "2086152384/2091657408",
"loc": [ 0, 10 ],
"_rev": 2091657408
},
{
"distance": 1111949.26644559,
"_id": "2086152384/2092312768",
"loc": [ 10, 0 ],
"_rev": 2092312768
},
{
"distance": 1111949.26644559,
"_id": "2086152384/2091526336",
"loc": [ 0, -10 ],
"_rev": 2091526336
}
],
"code": 201,
"hasMore": false,
"count": 5,
"error": false
}
</pre></div> </div></div>
</div></body></html>
Reference in New Issue View Git Blame Copy Permalink