mirror of https://gitee.com/bigwinds/arangodb
209 lines
15 KiB
HTML
209 lines
15 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>Geo Indexes </h1> </div>
|
|
</div>
|
|
<div class="contents">
|
|
<div class="textblock"><p>This is an introduction to ArangoDB's geo indexes.</p>
|
|
<hr/>
|
|
<ul>
|
|
<li>
|
|
<a class="el" href="IndexGeo.html">Geo Indexes</a> <ul>
|
|
<li>
|
|
<a class="el" href="IndexGeo.html#IndexGeoIntro">Geo Indexes</a> </li>
|
|
<li>
|
|
<a class="el" href="IndexGeo.html#IndexGeoShell">Accessing Geo Indexes from the Shell</a> <ul>
|
|
<li>
|
|
<a class="el" href="IndexGeo.html#IndexGeoShellEnsureGeoIndex">collection.ensureGeoIndex</a> </li>
|
|
<li>
|
|
<a class="el" href="IndexGeo.html#IndexGeoShellEnsureGeoConstraint">collection.ensureGeoConstraint</a> </li>
|
|
<li>
|
|
<a class="el" href="IndexGeo.html#IndexGeoShellGeo">collection.geo</a> </li>
|
|
<li>
|
|
<a class="el" href="IndexGeo.html#IndexGeoShellNear">collection.near</a> </li>
|
|
<li>
|
|
<a class="el" href="IndexGeo.html#IndexGeoShellWithin">collection.within</a> </li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
<h2><a class="anchor" id="IndexGeoIntro"></a>
|
|
Geo Indexes</h2>
|
|
<p>ArangoDB uses Hilbert curves to implement geo-spatial indexes. See this <a href="http://www.arangodb.org/2012/03/31/using-hilbert-curves-and-polyhedrons-for-geo-indexing">blog</a> for details.</p>
|
|
<p>A geo-spatial index assumes that the latitude is between -90 and 90 degree and the longitude is between -180 and 180 degree. A geo index will ignore all documents which do not fulfill these requirements.</p>
|
|
<p>A geo-spatial constraint makes the same assumptions, but documents not fulfilling these requirements are rejected.</p>
|
|
<h2><a class="anchor" id="IndexGeoShell"></a>
|
|
Accessing Geo Indexes from the Shell</h2>
|
|
<p><a class="anchor" id="IndexGeoShellEnsureGeoIndex"></a> <hr/>
|
|
<code><b><em>collection</em>.ensureGeoIndex(<em>location</em>)</b></code><hr/>
|
|
Creates a geo-spatial index on all documents using <em>location</em> as path to the coordinates. The value of the attribute must be a list with at least two double values. The list must contain the latitude (first value) and the longitude (second value). All documents, which do not have the attribute path or with value that are not suitable, are ignored.</p>
|
|
<p>In case that the index was successfully created, the index identifier is returned.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.ensureGeoIndex(<em>location</em>, <code>true</code>)</b></code><hr/>
|
|
As above which the exception, that the order within the list is longitude followed by latitude. This corresponds to the format described in</p>
|
|
<p><a href="http://geojson.org/geojson-spec.html#positions">http://geojson.org/geojson-spec.html#positions</a></p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.ensureGeoIndex(<em>latitude</em>, <em>longitude</em>)</b></code><hr/>
|
|
Creates a geo-spatial index on all documents using <em>latitude</em> and <em>longitude</em> as paths the latitude and the longitude. The value of the attribute <em>latitude</em> and of the attribute <em>longitude</em> must a double. All documents, which do not have the attribute paths or which values are not suitable, are ignored.</p>
|
|
<p>In case that the index was successfully created, the index identifier is returned.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>Create an geo index for a list attribute:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db.geo.ensureGeoIndex("loc");
|
|
{ "id" : "127629/47772301", "type" : "geo1", "geoJson" : false, "fields" : ["loc"], "isNewlyCreated" : true }
|
|
|
|
arango> for (i = -90; i <= 90; i += 10) {
|
|
.......> for (j = -180; j <= 180; j += 10) {
|
|
.......> db.geo.save({ name : "Name/" + i + "/" + j,
|
|
.......> loc: [ i, j ] });
|
|
.......> }
|
|
.......> }
|
|
|
|
arango> db.geo.count();
|
|
703
|
|
|
|
arango> db.geo.near(0,0).limit(3).toArray();
|
|
[ { "_id" : "154092:24861164", "_rev" : 24861164, "name" : "Name/0/0", "loc" : [0, 0]},
|
|
{ "_id" : "154092:24926700", "_rev" : 24926700, "name" : "Name/0/10", "loc" : [0, 10]},
|
|
{ "_id" : "154092:22436332", "_rev" : 22436332, "name" : "Name/-10/0", "loc" : [-10, 0]}]
|
|
|
|
arango> db.geo.near(0,0).count();
|
|
100
|
|
</pre></div><p>Create an geo index for a hash array attribute:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db.geo2.ensureGeoIndex("location.latitude", "location.longitude");
|
|
{ "id" : "87612/1070652", "type" : "geo2", "fields" : ["location.latitude", "location.longitude"], "isNewlyCreated" : true }
|
|
|
|
arango> for (i = -90; i <= 90; i += 10) {
|
|
.......> for (j = -180; j <= 180; j += 10) {
|
|
.......> db.geo2.save({ name : "Name/" + i + "/" + j,
|
|
.......> location: { latitude : i,
|
|
.......> longitude : j } });
|
|
.......> }
|
|
.......> }
|
|
|
|
arango> db.geo2.near(0,0).limit(3).toArray();
|
|
[{
|
|
"_id" : "48126444:72964588",
|
|
"_rev" : 72964588,
|
|
"location" : { "latitude" : 0, "longitude" : 0},
|
|
"name" : "Name/0/0"
|
|
},
|
|
{
|
|
"_id" : "48126444:73030124",
|
|
"_rev" : 73030124,
|
|
"location" : { "latitude" : 0, "longitude" : 10},
|
|
"name" : "Name/0/10"
|
|
},
|
|
{
|
|
"_id" : "48126444:70539756",
|
|
"_rev" : 70539756,
|
|
"location" : { "latitude" : -10, "longitude" : 0},
|
|
"name" : "Name/-10/0"
|
|
}]
|
|
</pre></div> <hr/>
|
|
<p><a class="anchor" id="IndexGeoShellEnsureGeoConstraint"></a> <hr/>
|
|
<code><b><em>collection</em>.ensureGeoConstraint(<em>location</em>, <em>ignore-null</em>)</b></code><hr/>
|
|
<hr/>
|
|
<code><b><em>collection</em>.ensureGeoConstraint(<em>location</em>, <code>true</code>, <em>ignore-null</em>)</b></code><hr/>
|
|
<hr/>
|
|
<code><b><em>collection</em>.ensureGeoConstraint(<em>latitude</em>, <em>longitude</em>, <em>ignore-null</em>)</b></code><hr/>
|
|
Works like <code>ensureGeoIndex</code> but requires that the documents contain a valid geo definition. If <em>ignore-null</em> is true, then documents with a null in <em>location</em> or at least one null in <em>latitude</em> or <em>longitude</em> are ignored. </p>
|
|
<hr/>
|
|
<p><a class="anchor" id="IndexGeoShellGeo"></a> <hr/>
|
|
<code><b><em>collection</em>.geo(<em>location</em>)</b></code><hr/>
|
|
<p>The next <code>near</code> or <code>within</code> operator will use the specific geo-spatial index.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.geo(<em>location</em>, <code>true</code>)</b></code><hr/>
|
|
<p>The next <code>near</code> or <code>within</code> operator will use the specific geo-spatial index.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.geo(<em>latitude</em>, <em>longitude</em>)</b></code><hr/>
|
|
<p>The next <code>near</code> or <code>within</code> operator will use the specific geo-spatial index.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>Assume you have a location stored as list in the attribute <code>home</code> and a destination stored in the attribute <code>work</code>. Than you can use the <code>geo</code> operator to select, which coordinates to use in a near query.</p>
|
|
<div class="fragment"><pre class="fragment">arango> for (i = -90; i <= 90; i += 10) {
|
|
.......> for (j = -180; j <= 180; j += 10) {
|
|
.......> db.complex.save({ name : "Name/" + i + "/" + j,
|
|
.......> home : [ i, j ],
|
|
.......> work : [ -i, -j ] });
|
|
.......> }
|
|
.......> }
|
|
|
|
arango> db.complex.near(0, 170).limit(5);
|
|
exception in file '/simple-query' at 1018,5: an geo-index must be known
|
|
|
|
arango> db.complex.ensureGeoIndex("home");
|
|
arango> db.complex.near(0, 170).limit(5).toArray();
|
|
[ { _id : 48834092:74655276, _rev : 74655276, name : Name/0/170, home : [ 0, 170 ], work : [ 0, -170 ] },
|
|
{ _id : 48834092:74720812, _rev : 74720812, name : Name/0/180, home : [ 0, 180 ], work : [ 0, -180 ] },
|
|
{ _id : 48834092:77080108, _rev : 77080108, name : Name/10/170, home : [ 10, 170 ], work : [ -10, -170 ] },
|
|
{ _id : 48834092:72230444, _rev : 72230444, name : Name/-10/170, home : [ -10, 170 ], work : [ 10, -170 ] },
|
|
{ _id : 48834092:72361516, _rev : 72361516, name : Name/0/-180, home : [ 0, -180 ], work : [ 0, 180 ] } ]
|
|
|
|
arango> db.complex.geo("work").near(0, 170).limit(5);
|
|
exception in file '/simple-query' at 1018,5: an geo-index must be known
|
|
|
|
arango> db.complex.ensureGeoIndex("work");
|
|
arango> db.complex.geo("work").near(0, 170).limit(5).toArray();
|
|
[ { _id : 48834092:72427052, _rev : 72427052, name : Name/0/-170, home : [ 0, -170 ], work : [ 0, 170 ] },
|
|
{ _id : 48834092:72361516, _rev : 72361516, name : Name/0/-180, home : [ 0, -180 ], work : [ 0, 180 ] },
|
|
{ _id : 48834092:70002220, _rev : 70002220, name : Name/-10/-170, home : [ -10, -170 ], work : [ 10, 170 ] },
|
|
{ _id : 48834092:74851884, _rev : 74851884, name : Name/10/-170, home : [ 10, -170 ], work : [ -10, 170 ] },
|
|
{ _id : 48834092:74720812, _rev : 74720812, name : Name/0/180, home : [ 0, 180 ], work : [ 0, -180 ] } ]
|
|
</pre></div> <hr/>
|
|
<p><a class="anchor" id="IndexGeoShellNear"></a> <hr/>
|
|
<code><b><em>collection</em>.near(<em>latitude</em>, <em>longitude</em>)</b></code><hr/>
|
|
<p>The default will find at most 100 documents near the coordinate (<em>latitude</em>, <em>longitude</em>). 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. It is possible to change the limit using the <em>limit</em> operator.</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> operator to select a particular index.</p>
|
|
<dl class="note"><dt><b>Note:</b></dt><dd><code>near</code> does not support negative skips. However, you can still use <code>limit</code> followed to <code>skip</code>.</dd></dl>
|
|
<hr/>
|
|
<code><b><em>collection</em>.near(<em>latitude</em>, <em>longitude</em>).limit(<em>limit</em>)</b></code><hr/>
|
|
<p>Limits the result to <em>limit</em> documents instead of the default 100.</p>
|
|
<dl class="note"><dt><b>Note:</b></dt><dd>Unlike with multiple explicit limits, <em>limit</em> will raise the implicit default limit imposed by <code>within</code>.</dd></dl>
|
|
<hr/>
|
|
<code><b><em>collection</em>.near(<em>latitude</em>, <em>longitude</em>).distance()</b></code><hr/>
|
|
<p>This will add an attribute <code>distance</code> to all documents returned, which contains the distance between the given point and the document in meter.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.near(<em>latitude</em>, <em>longitude</em>).distance(<em>name</em>)</b></code><hr/>
|
|
<p>This will add an attribute <em>name</em> to all documents returned, which contains the distance between the given point and the document in meter.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>To get the nearst two locations:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db.geo.near(0,0).limit(2).toArray();
|
|
[ { _id : 131840:24773376, _rev : 24773376, name : Name/0/0, loc : [ 0, 0 ] },
|
|
{ _id : 131840:22348544, _rev : 22348544, name : Name/-10/0, loc : [ -10, 0 ] } ]
|
|
</pre></div> <p>If you need the distance as well, then you can use the <code>distance</code> operator:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db.geo.near(0,0).distance().limit(2).toArray();
|
|
[ { _id : 131840:24773376, _rev : 24773376, distance : 0, name : Name/0/0, loc : [ 0, 0 ] },
|
|
{ _id : 131840:22348544, _rev : 22348544, distance : 1111949.3, name : Name/-10/0, loc : [ -10, 0 ] } ]
|
|
</pre></div> <hr/>
|
|
<p><a class="anchor" id="IndexGeoShellWithin"></a> <hr/>
|
|
<code><b><em>collection</em>.within(<em>latitude</em>, <em>longitude</em>, <em>radius</em>)</b></code><hr/>
|
|
<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> operator to select a particular index.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.within(<em>latitude</em>, <em>longitude</em>, <em>radius</em>) .distance()</b></code><hr/>
|
|
<p>This will add an attribute <code>_distance</code> to all documents returned, which contains the distance between the given point and the document in meter.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.within(<em>latitude</em>, <em>longitude</em>, <em>radius</em>) .distance(<em>name</em>)</b></code><hr/>
|
|
<p>This will add an attribute <em>name</em> to all documents returned, which contains the distance between the given point and the document in meter.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>To find all documents within a radius of 2000 km use:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db.geo.within(0, 0, 2000 * 1000).distance().toArray();
|
|
[ { _id : 131840:24773376, _rev : 24773376, distance : 0, name : Name/0/0, loc : [ 0, 0 ] },
|
|
{ _id : 131840:24707840, _rev : 24707840, distance : 1111949.3, name : Name/0/-10, loc : [ 0, -10 ] },
|
|
{ _id : 131840:24838912, _rev : 24838912, distance : 1111949.3, name : Name/0/10, loc : [ 0, 10 ] },
|
|
{ _id : 131840:22348544, _rev : 22348544, distance : 1111949.3, name : Name/-10/0, loc : [ -10, 0 ] },
|
|
{ _id : 131840:27198208, _rev : 27198208, distance : 1111949.3, name : Name/10/0, loc : [ 10, 0 ] },
|
|
{ _id : 131840:22414080, _rev : 22414080, distance : 1568520.6, name : Name/-10/10, loc : [ -10, 10 ] },
|
|
{ _id : 131840:27263744, _rev : 27263744, distance : 1568520.6, name : Name/10/10, loc : [ 10, 10 ] },
|
|
{ _id : 131840:22283008, _rev : 22283008, distance : 1568520.6, name : Name/-10/-10, loc : [ -10, -10 ] },
|
|
{ _id : 131840:27132672, _rev : 27132672, distance : 1568520.6, name : Name/10/-10, loc : [ 10, -10 ] } ]
|
|
</pre></div> </div></div>
|
|
</div></body></html>
|