---
title: "Make a Spatial Query"
url: "https://docs.ravendb.net/6.2/client-api/session/querying/how-to-make-a-spatial-query"
version: "6.2"
language: "java"
---

# Make a Spatial Query

> Client language: Java. Also available for [C#](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-make-a-spatial-query.md), [Python](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-make-a-spatial-query.python.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-make-a-spatial-query.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

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](#spatial)
- [OrderByDistance](#orderbydistance)
- [OrderByDistanceDescending](#orderbydistancedescending)

## Spatial

```java
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

```java
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

```java
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](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-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 |

> **Info:** Polygons {#polygons}
>
> When using `spatial.wkt()` to define a **polygon**, the vertices (points that form the corners of the polygon) must be listed
> in a counter-clockwise order:
>
> ![NoSQL DB - Query a Spatial Index](https://docs.ravendb.net/assets/images/spatial_1-779c509ab611ef1c93896d4b50a1790d.png)

### Example I

#### Java

```java
// 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();
```

#### RQL

```sql
from Houses
where spatial.within(spatial.point(Latitude, Longitude), spatial.circle(10, 32.1234. 23.4321))
```

### Example II

#### Java

```java
// 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();
```

#### RQL

```sql
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.

```java
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](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-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

#### Java

```java
// 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();
```

#### RQL

```sql
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.

```java
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

#### Java

```java
// 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();
```

#### RQL

```sql
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**.

## See also

- [How to Query](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.md)
- [Querying: Basics](https://docs.ravendb.net/6.2/indexes/querying/query-index.java.md)
- [Indexing Spatial Data](https://docs.ravendb.net/6.2/indexes/indexing-spatial-data.java.md)
- [Query spatial index](https://docs.ravendb.net/6.2/indexes/querying/spatial.java.md)
- [Spatial query view](https://docs.ravendb.net/6.2/studio/database/queries/spatial-queries-map-view.md)
