Geospatial Haystack Indexing

In addition to ordinary 2d geospatial indices, mongodb supports the use of bucket-based geospatial indexes. Called "Haystack indexing", these indices can accelerate small-region type longitude / latitude queries when additional criteria is also required. For example, "find all restaurants within 25 miles with name 'foo'".  Haystack indices allow you to tune your bucket size to the distribution of your data, so that in general you search only very small regions of 2d space for a particular kind of document.  They are not suited for finding the closest documents to a particular location, when the closest documents are far away compared to bucket size.

For now, only a single coordinate field and optional single additional field can be used in a haystack index.

To use haystack indexing, documents with a (longitude, latitude) position stored as a sub-document or array are required, with an optional additional field to be indexed. For example:

> db.foo.insert({ pos : { long : 34.2, lat : 33.3 }, type : "restaurant" })
> db.foo.insert({ pos : { long : 34.2, lat : 37.3 }, type : "restaurant" })
> db.foo.insert({ pos : { long : 59.1, lat : 87.2 }, type : "office" })
...
> db.foo.ensureIndex({ pos : "geoHaystack", type : 1 }, { bucketSize : 1 })

The bucketSize parameter is required, and determines the granularity of the bucket index - our value of 1 above creates an index where keys within 1 unit of longitude or latitude are stored in the same bucket.

The haystack index can only be used by a database command, it is not at present chosen by the query optimizer. As an example of finding all restaurants in a particular area with a given maximum distance of 6 degrees longitude / latitude, with a maximum of 30 results returned (by default, there is a 50 document result limit):

> db.runCommand({ geoSearch : "foo", near : [33, 33], maxDistance : 6, search : { type : "restaurant" }, limit : 30 })
{
	"results" : [
		{
			"_id" : ObjectId("4d948a7db1670124ce358fb7"),
			"pos" : {
				"long" : 34.2,
				"lat" : 33.3
			},
			"type" : "restaurant"
		},
		{
			"_id" : ObjectId("4d948a84b1670124ce358fb8"),
			"pos" : {
				"long" : 34.2,
				"lat" : 37.3
			},
			"type" : "restaurant"
		}
	],
	"stats" : {
		"time" : 0,
		"btreeMatches" : 2,
		"n" : 2
	},
	"ok" : 1
}

Spherical queries are not currently supported by haystack indices.