[DOCS-36] The documentation of $near seems wrong, or at least confusing Created: 26/Mar/11  Updated: 29/Nov/12  Resolved: 31/Mar/11

Status: Closed
Project: Documentation
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major - P3
Reporter: Knut Forkalsrud Assignee: Greg Studer
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: JPEG File degree-radian.jpg    
Participants:
Days since reply: 12 years, 46 weeks, 6 days ago

 Description   

The second bullet point describing the spherical coordinates states that "All distances use radians", and continues with "... multiply by the radius of the earth (about 6371 km or 3959 miles) to get the distance in your choice of units." Given the circumference of the earth being 2*pi*radius and the entire circle being 2*pi (radians) then one radian at the surface of the earth would be equal to the earth's radius, which is 3959 miles.
http://www.mongodb.org/display/DOCS/Geospatial+Indexing#GeospatialIndexing-NewSphericalModel
On the other hand the last comment in SERVER-813 says that one (radian) corresponds to 69 miles on the surface of the earth. Some empirical testing suggests that this is indeed the accurate measure.
http://jira.mongodb.org/browse/SERVER-813?focusedCommentId=19076&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_19076

However if we assume we're talking about one good old degree (1/360 of a circle) it does make more sense. One degree would measure 1/360 * 2*pi*radius at the surface, which does indeed compute to about 69 miles.

I would therefore propose that the documentation say "All distances use decimal degrees, just like the coordinates themselves". At least among my peers that seems to cause less confusion.



 Comments   
Comment by Greg Studer [ 31/Mar/11 ]

Yep, though again, beware, the two searches are not exactly equivalent over large areas. Picture the circle in the first case bounded by the not-quite-square shape of a grid section on a spherical globe.

Comment by Knut Forkalsrud [ 31/Mar/11 ]

ok, I think I understand this now. When switching from $near to $nearSphere I also need to change $maxDistance from degrees to radians.

> db.points.insert({ pos :

{ long : 1, lat : 0 }

})
> db.points.insert({ pos :

{ long : 2, lat : 0 }

})
> db.points.insert({ pos :

{ long : 3, lat : 0 }

})
> db.points.insert({ pos :

{ long : 4, lat : 0 }

})
> db.points.insert({ pos :

{ long : 5, lat : 0 }

})
> db.points.insert({ pos :

{ long : 6, lat : 0 }

})
> db.points.insert({ pos :

{ long : 7, lat : 0 }

})
> db.points.insert({ pos :

{ long : 8, lat : 0 }

})
> db.points.insert({ pos :

{ long : 9, lat : 0 }

})
> db.points.insert({ pos :

{ long : 10, lat : 0 }

})
> db.points.ensureIndex(

{ pos : "2d" }

)

> db.points.find( { pos :

{ $near : [0,0] , $maxDistance : 5 }

} ).count()
5
> db.points.find( { pos :

{ $nearSphere : [0,0] , $maxDistance : (5 * 2 * 3.1416 / 360) }

} ).count()
5

Comment by Greg Studer [ 28/Mar/11 ]

I believe the comment in SERVER-813 is actually inaccurate, and the distance parameters and results of a $near query where spherical is not set to true will be in terms of decimal degrees long/lat*, as you mentioned. However, when using spherical = true or $nearSphere queries, the units of distance parameters and results are in fact radians - for example, see SERVER-2408 , where the problem was a very large 1-radian-bounded query which was searching in a 3959 mile area.

This seems to be a fairly frequent question, however, I agree the documentation should be clearer (or give an example!).

*The euclidean distance formula used to calculate non-spherical distances is strange in that using degrees long/lat will give you back distance "in degrees long/lat" but converting this into a metric like km or miles is only accurate over small distances, it is not a degree of a great-circle such as you describe above.

Generated at Thu Feb 08 07:37:47 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.