From 1f0ecf9462fb442e6cd9acfcdc156b573bc7bf46 Mon Sep 17 00:00:00 2001 From: Simran Brucherseifer Date: Tue, 27 Sep 2016 18:24:18 +0200 Subject: [PATCH] fix sortedness documentation (additional clarification) --- Documentation/Books/AQL/Functions/Geo.mdpp | 30 +++++++++++++--------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/Documentation/Books/AQL/Functions/Geo.mdpp b/Documentation/Books/AQL/Functions/Geo.mdpp index fdba957f49..f00cb5e003 100644 --- a/Documentation/Books/AQL/Functions/Geo.mdpp +++ b/Documentation/Books/AQL/Functions/Geo.mdpp @@ -14,11 +14,12 @@ with an error. Return at most *limit* documents from collection *coll* that are near *latitude* and *longitude*. The result contains at most *limit* documents, returned sorted by distance, with closest distances being returned first. If more than *limit* documents -qualify, it is undefined which of the qualifying documents are returned. Optionally, -the distances between the specified coordinate (*latitude* and *longitude*) and the -document coordinates can be returned as well. To make use of that, the desired attribute -name for the distance result has to be specified in the *distanceName* argument. The -result documents will contain the distance value in an attribute of that name. +qualify, with the distance being exactly the same among multiple documents around the +limit, it is undefined which of the qualifying documents are returned. Optionally, +the distances in meters between the specified coordinate (*latitude* and *longitude*) +and the document coordinates can be returned as well. To make use of that, the desired +attribute name for the distance result has to be specified in the *distanceName* argument. +The result documents will contain the distance value in an attribute of that name. - **coll** (collection): a collection - **latitude** (number): the latitude portion of the search coordinate @@ -28,7 +29,8 @@ result documents will contain the distance value in an attribute of that name. ones will be returned. - **distanceName** (string, *optional*): include the distance to the search coordinate in each document in the result (in meters), using the attribute name *distanceName* -- returns **docArray** (array): an array of documents, in random order +- returns **docArray** (array): an array of documents, sorted by distance (shortest + distance first) !SUBSECTION WITHIN() @@ -37,10 +39,10 @@ result documents will contain the distance value in an attribute of that name. Return all documents from collection *coll* that are within a radius of *radius* around the specified coordinate (*latitude* and *longitude*). The documents returned are sorted by distance to the search coordinate, with the closest distances being -returned first. Optionally, the distance between the search coordinate and the document -coordinates can be returned as well. To make use of that, an attribute name for the distance -result has to be specified in the *distanceName* argument. The result documents will contain -the distance value in an attribute of that name. +returned first. Optionally, the distance in meters between the search coordinate and +the document coordinates can be returned as well. To make use of that, an attribute +name for the distance result has to be specified in the *distanceName* argument. +The result documents will contain the distance value in an attribute of that name. - **coll** (collection): a collection - **latitude** (number): the latitude portion of the search coordinate @@ -48,7 +50,8 @@ the distance value in an attribute of that name. - **radius** (number): radius in meters - **distanceName** (string, *optional*): include the distance to the search coordinate in each document in the result (in meters), using the attribute name *distanceName* -- returns **docArray** (array): an array of documents, in random order +- returns **docArray** (array): an array of documents, sorted by distance (shortest + distance first) !SUBSECTION WITHIN_RECTANGLE() @@ -56,6 +59,7 @@ the distance value in an attribute of that name. Return all documents from collection *coll* that are positioned inside the bounding rectangle with the points (*latitude1*, *longitude1*) and (*latitude2*, *longitude2*). +There is no guaranteed order in which the documents are returned. - **coll** (collection): a collection - **latitude1** (number): the bottom-left latitude portion of the search coordinate @@ -66,7 +70,9 @@ rectangle with the points (*latitude1*, *longitude1*) and (*latitude2*, *longitu !SECTION Geo utility functions -The following helper functions do not use any geo index. +The following helper functions do **not use any geo index**. It is advisable to use +them in combination with index-accelerated geo functions to limit the number of +calls to the non-accelerated functions because of their computational costs. !SUBSECTION IS_IN_POLYGON()