Session: Querying: How to Query a Spatial Index

Spatial indexes can be queried using the spatial method which contains a full spectrum of spatial methods. The following article will cover these methods:

Spatial

IDocumentQuery<T> spatial(String fieldName, Function<SpatialCriteriaFactory, SpatialCriteria> clause);

IDocumentQuery<T> spatial(DynamicSpatialField field, Function<SpatialCriteriaFactory, SpatialCriteria> clause);
Parameters
fieldName String Path to spatial field in an index
field DynamicSpatialField Field that points to a dynamic field (used with auto-indexes). Either PointField or WktField
clause Function<SpatialCriteriaFactory, SpatialCriteria> Spatial criteria

DynamicSpatialField

public PointField(String latitude, String longitude)

public WktField(String wkt)
Parameters
latitude or longitude or wkt String Path to the field in a document containing either longitude, latitude or WKT

SpatialCriteriaFactory

SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation);

SpatialCriteria relatesToShape(String shapeWkt, SpatialRelation relation, double distErrorPercent);

SpatialCriteria intersects(String shapeWkt);

SpatialCriteria intersects(String shapeWkt, double distErrorPercent) ;

SpatialCriteria contains(String shapeWkt);

SpatialCriteria contains(String shapeWkt, double distErrorPercent);

SpatialCriteria disjoint(String shapeWkt);

SpatialCriteria disjoint(String shapeWkt, double distErrorPercent);

SpatialCriteria within(String shapeWkt);

SpatialCriteria within(String shapeWkt, double distErrorPercent);

SpatialCriteria withinRadius(double radius, double latitude, double longitude);

SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits);

SpatialCriteria withinRadius(double radius, double latitude, double longitude, SpatialUnits radiusUnits, double distErrorPercent);
Parameters
shapeWkt String WKT-based shape to be used in operation
relation SpatialRelation Shape relation. Can be WITHIN, CONTAINS, DISJOINT, INTERSECTS
distErrorPercent double Maximum distance error tolerance in percents. Default: 0.025
radius or latitude or longitude double Used to define a radius circle
radiusUnits SpatialUnits Determines if circle should be calculated in KILOMETERS or MILES units

Example I

// return all matching entities
// within 10 kilometers radius
// from 32.1234 latitude and 23.4321 longitude coordinates
List<House> results = session
    .query(House.class)
    .spatial(
        new PointField("latitude", "longitude"),
        f -> f.withinRadius(10, 32.1234, 23.4321))
    .toList();
from Houses
where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321))

Example II

// return all matching entities
// within 10 kilometers 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.class)
    .spatial(
        new PointField("latitude", "longitude"),
        f -> f.relatesToShape("Circle(32.1234 23.4321 d=10.0000)", SpatialRelation.WITHIN)
    )
    .toList();
from Houses
where spatial.within(spatial.point(Latitude, Longitude), spatial.wkt('Circle(32.1234 23.4321 d=10.0000)'))

OrderByDistance

To sort by distance from given point use the orderByDistance method. The closest results will come first.

IDocumentQuery<T> orderByDistance(DynamicSpatialField field, double latitude, double longitude);

IDocumentQuery<T> orderByDistance(DynamicSpatialField field, String shapeWkt);

IDocumentQuery<T> orderByDistance(String fieldName, double latitude, double longitude);

IDocumentQuery<T> orderByDistance(String fieldName, String shapeWkt);
Parameters
fieldName String Path to spatial field in index
field DynamicSpatialField Field that points to a dynamic field (used with auto-indexes). Either PointField or WktField
shapeWkt String WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference.
latitude or longitude double Used to define a point from which distance will be measured

Example

// 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.class)
    .spatial(
        new PointField("latitude", "longitude"),
        f -> f.withinRadius(10, 32.1234, 23.4321)
    )
    .orderByDistance(
        new PointField("latitude", "longtude"),
        32.12324, 23.4321)
    .toList();
from Houses
where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321))
order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321))

OrderByDistanceDescending

To sort by distance from given point use the OrderByDistanceDescending method. The farthest results will come first.

IDocumentQuery<T> orderByDistanceDescending(DynamicSpatialField field, double latitude, double longitude);

IDocumentQuery<T> orderByDistanceDescending(DynamicSpatialField field, String shapeWkt);

IDocumentQuery<T> orderByDistanceDescending(String fieldName, double latitude, double longitude);

IDocumentQuery<T> orderByDistanceDescending(String fieldName, String shapeWkt);
Parameters
fieldName String Path to spatial field in index
field DynamicSpatialField Field that points to a dynamic field (used with auto-indexes). Either PointField or WktField
shapeWkt String WKT-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference.
latitude or longitude double Used to define a point from which distance will be measured

Example

// 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.class)
    .spatial(
        new PointField("latitude", "longitude"),
        f -> f.withinRadius(10, 32.1234, 23.4321)
    )
    .orderByDistanceDescending(
        new PointField("latitude", "longtude"),
        32.12324, 23.4321)
    .toList();
from Houses
where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321))
order by spatial.distance(spatial.point(Latitude, Longitude), spatial.point(32.1234, 23.4321)) desc

Remarks

Note

By default, distances are measured in kilometers.