---
title: "Spatial Queries Map View"
description: "* Spatial queries retrieve documents using geographical criteria,"
url: "https://docs.ravendb.net/6.2/studio/database/queries/spatial-queries-map-view"
version: "6.2"
---

# Spatial Queries Map View

> 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 Queries Map View

> **Note**
>
> - [Spatial queries](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-make-a-spatial-query.md) retrieve documents using geographical criteria,  
>   provided that the documents contain spatial data.
>
> - The spatial query defines geographic regions (circles or polygons)  
>   and queries for documents that have some relation to those regions.
>
> - When executing a dynamic spatial query in the Studio, in addition to the regular document results,  
>   a **Spatial Map** view will be displayed, showing the search results on a global map.
>
>   > **Info**
>   >
>   > The spatial map view is added only for a [dynamic](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.md#dynamicquery) spatial query.  
>   > It is not added when querying a spatial index.
>
> - In this page:
>   - [Spatial data in documents](#spatial-data-in-documents)
>   - [Running a dynamic spatial query](#running-a-dynamic-spatial-query)
>   - [Spatial map view](#spatial-map-view)
>   - [Examples](#examples)
>     - [Circular region example](#circular-region-example)
>     - [Polygonal region example](#polygonal-region-example)
>     - [Mixed shapes intersection example](#mixed-shapes-intersection-example)

## Spatial data in documents

- Documents that contain geographic data can be queried for using a spatial query.  
  The spatial data in a document can be in the form of:
  - Latitude & Longitude
  - [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) string

- For example, the following Employee document contains fields:  
  `Address.Location.Latitude` & `Address.Location.Longitude` and can be searched for by this spatial data.

- Note:  
  Using "Latitude" and "Longitude" as the document fields' names is Not mandatory.  
  Any custom name can be assigned to those coordinate fields.

![Figure 1. Spatial Data](https://docs.ravendb.net/assets/images/spatial-map-view-query-1-c210e7b0f62c2301ff4d15e9a8805224.png)

## Running a dynamic spatial query

![Figure 2. The Query Section](https://docs.ravendb.net/assets/images/spatial-map-view-query-2-302220e8821810be6d8f86e3e8b56c5e.png)

- **1**. **Indexes**  
  Open the **Indexes** section.

- **2**. **Query**  
  Choose **Query**.  
  ![Figure 3. Running a Query](https://docs.ravendb.net/assets/images/spatial-map-view-query-3-d9ddd4878dca9a8df506a33ea231b3c2.png)

- **1**. **Query box**  
  Type your query in this area. The query is written in [RQL](https://docs.ravendb.net/6.2/client-api/session/querying/what-is-rql.md).

```csharp
// Specify the collection queried
from Employees

// Make a spatial query
where spatial.within(

  // Use 'spatial.point' to specify the document field names containing the spatial data.
  // The latitude field is always passed as the first param.
  // (Note: 'spatial.wkt' is used when the document contains a WKT string.)
  spatial.point(Address.Location.Latitude, Address.Location.Longitude),

  // Specify a geographical area.
  // This query will search for documents whose latitude & longitude are within this circle.
  spatial.circle(20,47.623473, -122.3060097, 'miles')
)
```

- **2**. **Run query**  
  Click this button to execute the query.  
  The query results will include two tabs:
  - Results tab - listing all resulting documents in textual form
  - Spatial map tab - showing results on the global map  
    ![Figure 4. Textual Results View](https://docs.ravendb.net/assets/images/spatial-map-view-query-4-f0ebaccc5c27c7926228482778f2d2a0.png)

## Spatial map view

![Figure 5. Spatial Map View](https://docs.ravendb.net/assets/images/spatial-map-view-query-5-a419250ba34cc248e29b419ab5cdf50f.png)

- **1**. **Spatial map**  
  If there are any resulting documents that match the spatial query, a **Spatial Map tab** is added to the results view.  
  Click the tab to view the resulting documents in their geographical locations on the map.

- **2**. **Expand results**  
  Click to expand the spatial map.  
  ![Figure 6. Zoom and Drag](https://docs.ravendb.net/assets/images/spatial-map-view-query-6-0db2956fc06ac29f32634c96bbaee76a.png)

- **1**. **Zoom control**  
  Click **+**/**-** or roll your mouse wheel to zoom in and out.

- **2**. **Map**  
  Click anywhere in the map area and drag to move the map.  
  ![Figure 7. Region and Points](https://docs.ravendb.net/assets/images/spatial-map-view-query-7-73ccc6786c8f6b72d4b23368cc3fc5e8.png)

![Figure 8. Same Points, Zoomed In](https://docs.ravendb.net/assets/images/spatial-map-view-query-8-4584bb3e2df6bbd610cbc9d5a574058b.png)

- **1**. **Region**  
  The region (a circle in this case) that was defined in the query.

- **2**. **Location markers**

  - **Red markers**  
    A red marker locates a single document result.  
    Hovering over the marker pops up the document's name.  
    ![Figure 9. Hovering over a Red Point](https://docs.ravendb.net/assets/images/spatial-map-view-query-9-82917e880563fcc5cf4d08c46066fd7e.png)  
    Clicking the marker pops up the document's contents.  
    ![Figure 10. Clicking a Red Point](https://docs.ravendb.net/assets/images/spatial-map-view-query-10-7ca6157786914f675ee578a00d88fba2.png)

  - **Green markers**  
    A green marker gathers two or more neighboring red markers (documents).  
    Zooming in will reveal the individual locations.  
    The number on the green marker represents the number of documents gathered by this marker.
    - If a green marker gathers at least three document locations,  
      hovering over it would display a crude scheme of these locations on the map.  
      ![Figure 11. Hovering over a Green Point](https://docs.ravendb.net/assets/images/spatial-map-view-query-11-c120720d440d9f8ea7bf7081ab8403e2.png)
    - Clicking a green marker zooms in to reveal the locations it gathers.  
      ![Figure 12. Viewing-Options Tooltip](https://docs.ravendb.net/assets/images/spatial-map-view-query-12-c9a04921fe98384ef430513fa6e50472.png)

- **1**. **Viewing-options toggler**  
  Hovering over the toggler will open the viewing options.

- **2**. **Viewing Options**  
  The map view options.

- **3**. **Map view**  
  Select **Streets** or **Topography** map.

- **4**. **Point fields**  
  When checked, the documents that contain these fields will be visible as marker points on the map.

- **5**. **Regions**  
  Show or hide circular/polygonal search regions.

## Examples

> **Note**
>
> ### Circular region example
>
> The following query locates companies within **two separate circular regions**.
>
> ```csharp
> from Companies 
> where 
> spatial.within(
>   spatial.point(Address.Location.Latitude, Address.Location.Longitude),
>   spatial.circle(200, 45.5137863, -122.675375, 'miles')
>   )
> or
> spatial.within(
>   spatial.point(Address.Location.Latitude, Address.Location.Longitude),
>   spatial.circle(200, 37.7774357, -122.418, 'miles')
>   )
> ```
>
> ![Figure 13. Multiple Regions](https://docs.ravendb.net/assets/images/spatial-map-view-query-13-7a6058a014d5278a816ff6a4d3f923ca.png)
>
> > **Info**
> >
> > - **Circular region syntax**  
> >   A circular region can be defined using two different syntaxes,
> >   `spatial.circle` and `spatial.wkt`.
> >
> > #### spatial.circle
> >
> > ```csharp
> > from Employees
> > where spatial.within(
> >   spatial.point(Address.Location.Latitude, Address.Location.Longitude),
> >   spatial.circle(20, 47.623473, -122.3060097, 'miles')
> >   )
> > ```
> >
> > #### spatial.wkt
> >
> > ```csharp
> > from Employees
> > where spatial.within(
> >   spatial.point(Address.Location.Latitude, Address.Location.Longitude),
> >   spatial.wkt('CIRCLE(-122.3060097 47.623473 d=20)')
> >   )
> > ```
> >
> > The **search coordinates** are provided in **a different order** for the two syntaxes.  
> > For `spatial.circle`, provide the Latitude first and the Longitude second.  
> > For `spatial.wkt`, provide the Longitude first and the Latitude second.
> >
> > - **Region color**  
> >   When multiple regions are defined, they are given different colors in the spatial map view.

> **Note**
>
> ### Polygonal region example
>
> The following query searches for companies within the boundaries of a **polygonal** region.
>
> - The polygon's coordinates must be provided in counterclockwise order.
> - The first and last coordinates must mark the same location to form a closed region.
> - You can use [tools like this one](https://www.keene.edu/campus/maps/tool/)
>   to draw a polygon on the world map and copy the coordinates to your query.
>
> ```csharp
> from companies 
> where 
> spatial.within(
>   spatial.point(Address.Location.Latitude, Address.Location.Longitude), 
>   spatial.wkt('POLYGON ((
>       -118.6527948 32.7114894, 
>       -95.8040242 37.5929338, 
>       -102.8344151 53.3349629, 
>       -127.5286633 48.3485664, 
>       -129.4620208 38.0786067, 
>       -118.7406746 32.7853769, 
>       -118.6527948 32.7114894))')
> )
> ```
>
> ![Figure 14. Polygon](https://docs.ravendb.net/assets/images/spatial-map-view-query-14-ffb9b6cf0361ef37c770c3aef4ecf478.png)

> **Note**
>
> ### Mixed shapes intersection example
>
> This query searches for companies at the intersection of a **circular region** and a **polygonal region**.  
> Though additional companies are located in each region, only companies located in both regions are retrieved.
>
> ```csharp
> from Companies 
> where 
> spatial.within(
>   spatial.point(Address.Location.Latitude, Address.Location.Longitude),
>   spatial.wkt('CIRCLE(-119.5 45.5137863 d=400)')
> )
> and 
> spatial.within(
>   spatial.point(Address.Location.Latitude, Address.Location.Longitude), 
>   spatial.wkt('POLYGON ((
>       -119.7105226 47.1000662,
>       -117.0712682 40.3896178,
>       -110.7439164 34.3929116,
>       -97.9134529 38.0071749,
>       -98.1770925 45.2197803,
>       -119.7105226 47.1000662))')
> )
> ```
>
> ![Figure 15. Multiple Shapes Intersection](https://docs.ravendb.net/assets/images/spatial-map-view-query-15-e110fbeb59778207c0eee2284fee3e68.png)
