You are currently browsing legacy 3.5 version of documentation. Click here to switch to the newest 6.0 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(
	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.

    see on GitHub

    related articlesRelated Articles

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