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<T> Spatial<T>(
  Expression<Func<T, object>> path,
  Func<SpatialCriteriaFactory, SpatialCriteria> clause);

IRavenQueryable<T> Spatial<T>(
  string fieldName,
  Func<SpatialCriteriaFactory, SpatialCriteria> clause);

IRavenQueryable<T> Spatial<T>(
  Func<DynamicSpatialFieldFactory<T>, DynamicSpatialField> field,
  Func<SpatialCriteriaFactory, SpatialCriteria> clause);

IRavenQueryable<T> Spatial<T>(
  DynamicSpatialField field,
  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

PointField Point(
  Expression<Func<T, object>> latitudePath,
  Expression<Func<T, object>> longitudePath);

WktField Wkt(Expression<Func<T, object>> wktPath);

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.

SpatialCriteria RelatesToShape(
  string shapeWkt,
  SpatialRelation relation,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria RelatesToShape(
  string shapeWkt,
  SpatialRelation relation,
  SpatialUnits units,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria Intersects(
  string shapeWkt,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria Intersects(
  string shapeWkt,
  SpatialUnits units,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria Contains(
  string shapeWkt,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria Contains(
  string shapeWkt,
  SpatialUnits units,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria Disjoint(
  string shapeWkt,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria Disjoint(
  string shapeWkt,
  SpatialUnits units,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria Within(
  string shapeWkt,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria Within(
  string shapeWkt,
  SpatialUnits units,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

SpatialCriteria WithinRadius(
  double radius,
  double latitude,
  double longitude,
  SpatialUnits? radiusUnits = null,
  double distErrorPercent = Constants.Documents.Indexing.Spatial.DefaultDistanceErrorPct);

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
// within 10 kilometers radius
// from 32.1234 latitude and 23.4321 longitude coordinates
List<House> results = session
  .Query<House>()
  .Spatial(
      factory => factory.Point(x => x.Latitude, x => x.Longitude),
      criteria => criteria.WithinRadius(10, 32.1234, 23.4321))
  .ToList();

SortByDistance

To sort by distance from origin point use SortByDistance method.

// return all matching entities
// within 10 miles radius
// from 32.1234 latitude and 23.4321 longitude coordinates
// this equals to WithinRadius(10, 32.1234, 23.4321)
List<House> results = session
  .Query<House>()
  .Spatial(
      factory => factory.Point(x => x.Latitude, x => x.Longitude),
      criteria => criteria.RelatesToShape(
          "Circle(32.1234 23.4321 d=10.0000)",
          SpatialRelation.Within,
          SpatialUnits.Miles))
  .ToList();

Return Value
IDocumentQueryCustomization	Returns self for easier method chaining.

Example

// From point
IOrderedQueryable<T> OrderByDistance<T>(
  Func<DynamicSpatialFieldFactory<T>, DynamicSpatialField> field,
  double latitude,
  double longitude);

IOrderedQueryable<T> OrderByDistance<T>(
  DynamicSpatialField field,
  double latitude,
  double longitude);

IOrderedQueryable<T> OrderByDistance<T>(
  Expression<Func<T, object>> path,
  double latitude,
  double longitude);

IOrderedQueryable<T> OrderByDistance<T>(
  string fieldName,
  double latitude,
  double longitude);

// From center of WKT shape
IOrderedQueryable<T> OrderByDistance<T>(
  Func<DynamicSpatialFieldFactory<T>, DynamicSpatialField> field,
  string shapeWkt);

IOrderedQueryable<T> OrderByDistance<T>(
  DynamicSpatialField field,
  string shapeWkt);

IOrderedQueryable<T> OrderByDistance<T>(
  Expression<Func<T, object>> path,
  string shapeWkt);

IOrderedQueryable<T> OrderByDistance<T>(
  string fieldName,
  string shapeWkt);

// Rounding
IOrderedQueryable<T> OrderByDistance<T>(
  Expression<Func<T, object>> path,
  double latitude,
  double longitude,
  double roundFactor);

IOrderedQueryable<T> OrderByDistance<T>(
  string fieldName,
  double latitude,
  double longitude,
  double roundFactor);

IOrderedQueryable<T> OrderByDistance<T>(
  Expression<Func<T, object>> path,
  string shapeWkt,
  double roundFactor);

IOrderedQueryable<T> OrderByDistance<T>(
  string fieldName,
  string shapeWkt,
  double roundFactor);

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.

// return all matching entities
// within 10 kilometers radius
// from 32.1234 latitude and 23.4321 longitude coordinates
// sort results by distance from 32.1234 latitude and 23.4321 longitude point
List<House> results = session
  .Query<House>()
  .Spatial(
      factory => factory.Point(x => x.Latitude, x => x.Longitude),
      criteria => criteria.WithinRadius(10, 32.1234, 23.4321))
  .OrderByDistance(
      factory => factory.Point(x => x.Latitude, x => x.Longitude), 32.1234, 23.4321)
  .ToList();

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

// From point
IOrderedQueryable<T> OrderByDistanceDescending<T>(
  Func<DynamicSpatialFieldFactory<T>, DynamicSpatialField> field,
  double latitude,
  double longitude);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  DynamicSpatialField field,
  double latitude,
  double longitude);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  Expression<Func<T, object>> path,
  double latitude,
  double longitude);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  string fieldName,
  double latitude,
  double longitude);

// From center of WKT shape
IOrderedQueryable<T> OrderByDistanceDescending<T>(
  Func<DynamicSpatialFieldFactory<T>, DynamicSpatialField> field,
  string shapeWkt);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  DynamicSpatialField field,
  string shapeWkt);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  Expression<Func<T, object>> path,
  string shapeWkt);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  string fieldName,
  string shapeWkt);

// Rounding
IOrderedQueryable<T> OrderByDistanceDescending<T>(
  Expression<Func<T, object>> path,
  double latitude,
  double longitude,
  double roundFactor);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  string fieldName,
  double latitude,
  double longitude,
  double roundFactor);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  Expression<Func<T, object>> path,
  string shapeWkt,
  double roundFactor);

IOrderedQueryable<T> OrderByDistanceDescending<T>(
  string fieldName,
  string shapeWkt,
  double roundFactor);

Remarks

By default, distances are measured in kilometers.

Spatial​

Example​

RelatesToShape​

Example​

SortByDistance​

Example​

WithinRadiusOf​

Example​

Remarks​

Spatial

Example

RelatesToShape

Example

SortByDistance

Example

WithinRadiusOf

Example

Remarks