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(Path<?> path, SpatialCriteria criteria);
Parameters
path Path<?> Path to spatial field.
clause 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
QSpatialDoc s = QSpatialDoc.spatialDoc;
List<SpatialDoc> results = session
  .query(SpatialDoc.class, SpatialDoc_ByShapeAndPoint.class)
  .spatial(s.shape, new SpatialCriteriaFactory().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.

public 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.class, SpatialDoc_ByShapeAndPoint.class)
  .customize(new DocumentQueryCustomizationFactory()
    .relatesToShape("Shape", "Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN))
  .toList();

SortByDistance

To sort by distance from origin point use sortByDistance method.

public 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
QSpatialDoc s = QSpatialDoc.spatialDoc;
List<SpatialDoc> results = session
  .query(SpatialDoc.class, SpatialDoc_ByShapeAndPoint.class)
  .customize(new DocumentQueryCustomizationFactory().sortByDistance())
  .spatial(s.shape, new SpatialCriteriaFactory().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.

public IDocumentQueryCustomization withinRadiusOf(double radius, double latitude, double longitude);

public IDocumentQueryCustomization withinRadiusOf(double radius, double latitude, double longitude, SpatialUnits radiusUnits);

public IDocumentQueryCustomization withinRadiusOf(String fieldName, double radius, double latitude, double longitude);

public 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
QSpatialDoc s = QSpatialDoc.spatialDoc;
List<SpatialDoc> results = session
  .query(SpatialDoc.class, SpatialDoc_ByShapeAndPoint.class)
  .customize(new DocumentQueryCustomizationFactory().withinRadiusOf("Shape", 10, 32.1234, 23.4321))
  .toList();

Remarks

Note

By default, distances are measured in kilometers.