see on GitHub

Session : Querying : How to query a spatial index?

Spatial indexes can be queried using Spatial method which contains full spectrum of spatial methods, certain shortcuts have been created for easier access and are available in Customize as a part of query customizations. Following article will cover those methods:

Spatial

IRavenQueryable<TResult> Spatial(
	Expression<Func<TResult, object>> path,
	Func<SpatialCriteriaFactory, SpatialCriteria> clause);

Parameters
path Expression<Func<TResult, object>> Path to spatial field.
clause Func<SpatialCriteriaFactory, SpatialCriteria> Spatial criteria that will be executed on given spatial field from path parameter.
Return Value
IRavenQueryable Object instance implementing IRavenQueryable interface containing additional query methods and extensions.

Example

// return all matching entities
// where 'Shape' (spatial field) is within 10 kilometers radius
// from 32.1234 latitude and 23.4321 longitude coordinates
List<SpatialDoc> results = session
	.Query<SpatialDoc, SpatialDoc_ByShapeAndPoint>()
	.Spatial(x => x.Shape, criteria => criteria.WithinRadiusOf(10, 32.1234, 23.4321))
	.ToList();

RelatesToShape

RelatesToShape is low-level method available for spatial searches. You can pass any valid WKT shape with any relation. All other methods sooner or later are using it to define a shape.

IDocumentQueryCustomization RelatesToShape(
	string fieldName,
	string shapeWKT,
	SpatialRelation rel);

Parameters
fieldName string Spatial field name.
shapeWKT string WKT formatted shape.
rel SpatialRelation Spatial relation to check.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

// return all matching entities
// where 'Shape' (spatial field) is within 10 kilometers radius
// from 32.1234 latitude and 23.4321 longitude coordinates
// this equals to WithinRadiusOf(10, 32.1234, 23.4321)
List<SpatialDoc> results = session
	.Query<SpatialDoc, SpatialDoc_ByShapeAndPoint>()
	.Customize(x => x.RelatesToShape("Shape", "Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.Within))
	.ToList();

SortByDistance

To sort by distance from origin point use SortByDistance method.

IDocumentQueryCustomization SortByDistance();

Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

// return all matching entities
// where 'Shape' (spatial field) is within 10 kilometers radius
// from 32.1234 latitude and 23.4321 longitude coordinates
// sort results by distance from origin point
List<SpatialDoc> results = session
	.Query<SpatialDoc, SpatialDoc_ByShapeAndPoint>()
	.Customize(x => x.SortByDistance())
	.Spatial(x => x.Shape, criteria => criteria.WithinRadiusOf(10, 32.1234, 23.4321))
	.ToList();

WithinRadiusOf

WithinRadiusOf filter matches to be inside specified radius. Internally it creates a circle with passed latitude and longitude as a center point with given distance (radius) and SpatialRelation set to Within.

IDocumentQueryCustomization WithinRadiusOf(
	double radius,
	double latitude,
	double longitude);

IDocumentQueryCustomization WithinRadiusOf(
	double radius,
	double latitude,
	double longitude,
	SpatialUnits radiusUnits);

IDocumentQueryCustomization WithinRadiusOf(
	string fieldName,
	double radius,
	double latitude,
	double longitude);

IDocumentQueryCustomization WithinRadiusOf(
	string fieldName,
	double radius,
	double latitude,
	double longitude,
	SpatialUnits radiusUnits);

Parameters
fieldName string Spatial field name. In overloads without this parameter default field name is assumed (__spatial).
radius double Circle radius.
latitude double Latitude pointing to circle center.
longitude double Longitude pointing to circle center.
spatialUnits SpatialUnits Units that will be used to measure distance (Kilometers or Miles).
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

// return all matching entities
// where 'Shape' (spatial field) is within 10 kilometers radius
// from 32.1234 latitude and 23.4321 longitude coordinates
List<SpatialDoc> results = session
	.Query<SpatialDoc, SpatialDoc_ByShapeAndPoint>()
	.Customize(x => x.WithinRadiusOf("Shape", 10, 32.1234, 23.4321))
	.ToList();

Remarks

Note

By default, distances are measured in kilometers.