You are currently browsing legacy 3.0 version of documentation. Click here to switch to the newest 6.2 version.
    We can help you with migration to the latest RavenDB
    Contact Us Now
    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(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.

    related articlesRelated Articles

    Home / Docs / Client Api / Session / Querying / How To Query A Spatial Index