Skip to content

Commit 816c327

Browse files
v-albemiv-albemi
authored
Merge pull request #107115 from timsander1/master
update with geospatial geometry
2 parents fc041ec + 37050fb commit 816c327

File tree

2 files changed

+105
-6
lines changed

2 files changed

+105
-6
lines changed

‎articles/cosmos-db/sql-query-geospatial-index.md

Lines changed: 96 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ ms.author: tisande
1010
---
1111
# Index geospatial data with Azure Cosmos DB
1212

13-
We designed Azure Cosmos DB’s database engine to be truly schema agnostic and provide first class support for JSON. The write optimized database engine of Azure Cosmos DB natively understands spatial data represented in the GeoJSON standard.
13+
We designed Azure Cosmos DB's database engine to be truly schema agnostic and provide first class support for JSON. The write optimized database engine of Azure Cosmos DB natively understands spatial data represented in the GeoJSON standard.
1414

1515
In a nutshell, the geometry is projected from geodetic coordinates onto a 2D plane then divided progressively into cells using a **quadtree**. These cells are mapped to 1D based on the location of the cell within a **Hilbert space filling curve**, which preserves locality of points. Additionally when location data is indexed, it goes through a process known as **tessellation**, that is, all the cells that intersect a location are identified and stored as keys in the Azure Cosmos DB index. At query time, arguments like points and Polygons are also tessellated to extract the relevant cell ID ranges, then used to retrieve data from the index.
1616

@@ -21,6 +21,44 @@ If you specify an indexing policy that includes spatial index for /* (all paths)
2121
>
2222
>
2323
24+
## Modifying geospatial data type
25+
26+
In your container, the `geospatialConfig` specifies how the geospatial data will be indexed. You should specify one `geospatialConfig` per container: geography or geometry. If not specified, the `geospatialConfig` will default to the geography data type. When you modify the `geospatialConfig`, all existing geospatial data in the container will be reindexed.
27+
28+
> [!NOTE]
29+
> Azure Cosmos DB currently supports modifications to the geospatialConfig in the .NET SDK only in versions 3.6 and above.
30+
>
31+
32+
Here is an example for modifying the geospatial data type to `geometry` by setting the `geospatialConfig` property and adding a **boundingBox**:
33+
34+
```csharp
35+
//Retrieve the container's details
36+
ContainerResponse containerResponse = await client.GetContainer("db", "spatial").ReadContainerAsync();
37+
//Set GeospatialConfig to Geometry
38+
GeospatialConfig geospatialConfig = new GeospatialConfig(GeospatialType.Geometry);
39+
containerResponse.Resource.GeospatialConfig = geospatialConfig;
40+
// Add a spatial index including the required boundingBox
41+
SpatialPath spatialPath = new SpatialPath
42+
{
43+
Path = "/locations/*",
44+
BoundingBox = new BoundingBoxProperties(){
45+
Xmin = 0,
46+
Ymin = 0,
47+
Xmax = 10,
48+
Ymax = 10
49+
}
50+
};
51+
spatialPath.SpatialTypes.Add(SpatialType.Point);
52+
spatialPath.SpatialTypes.Add(SpatialType.LineString);
53+
spatialPath.SpatialTypes.Add(SpatialType.Polygon);
54+
spatialPath.SpatialTypes.Add(SpatialType.MultiPolygon);
55+
56+
containerResponse.Resource.IndexingPolicy.SpatialIndexes.Add(spatialPath);
57+
58+
// Update container with changes
59+
await client.GetContainer("db", "spatial").ReplaceContainerAsync(containerResponse.Resource);
60+
```
61+
2462
## Geography data indexing examples
2563

2664
The following JSON snippet shows an indexing policy with spatial indexing enabled for the **geography** data type. It is valid for spatial data with the geography data type and will index any GeoJSON Point, Polygon, MultiPolygon, or LineString found within documents for spatial querying. If you are modifying the indexing policy using the Azure portal, you can specify the following JSON for indexing policy to enable spatial indexing on your container:
@@ -53,12 +91,66 @@ The following JSON snippet shows an indexing policy with spatial indexing enable
5391

5492
> [!NOTE]
5593
> If the location GeoJSON value within the document is malformed or invalid, then it will not get indexed for spatial querying. You can validate location values using ST_ISVALID and ST_ISVALIDDETAILED.
56-
>
57-
>
58-
>
5994
6095
You can also [modify indexing policy](how-to-manage-indexing-policy.md) using the Azure CLI, PowerShell, or any SDK.
6196

97+
## Geometry data indexing examples
98+
99+
With the **geometry** data type, similar to the geography data type, you must specify relevant paths and types to index. In addition, you must also specify a `boundingBox` within the indexing policy to indicate the desired area to be indexed for that specific path. Each geospatial path requires its own`boundingBox`.
100+
101+
The bounding box consists of the following properties:
102+
103+
- **xmin**: the minimum indexed x coordinate
104+
- **ymin**: the minimum indexed y coordinate
105+
- **xmax**: the maximum indexed x coordinate
106+
- **ymax**: the maximum indexed y coordinate
107+
108+
A bounding box is required because geometric data occupies a plane that can be infinite. Spatial indexes, however, require a finite space. For the **geography** data type, the Earth is the boundary and you do not need to set a bounding box.
109+
110+
You should create a bounding box that contains all (or most) of your data. Only operations computed on the objects that are entirely inside the bounding box will be able to utilize the spatial index. You should not make the bounding box significantly larger than necessary because this will negatively impact query performance.
111+
112+
Here is an example indexing policy that indexes **geometry** data with **geospatialConfig** set to `geometry`:
113+
114+
```json
115+
{
116+
"indexingMode": "consistent",
117+
"automatic": true,
118+
"includedPaths": [
119+
{
120+
"path": "/*"
121+
}
122+
],
123+
"excludedPaths": [
124+
{
125+
"path": "/\"_etag\"/?"
126+
}
127+
],
128+
"spatialIndexes": [
129+
{
130+
"path": "/locations/*",
131+
"types": [
132+
"Point",
133+
"LineString",
134+
"Polygon",
135+
"MultiPolygon"
136+
],
137+
"boundingBox": {
138+
"xmin": -10,
139+
"ymin": -20,
140+
"xmax": 10,
141+
"ymax": 20
142+
}
143+
}
144+
]
145+
}
146+
```
147+
148+
The above indexing policy has a **boundingBox** of (-10, 10) for x coordinates and (-20, 20) for y coordinates. The container with the above indexing policy will index all Points, Polygons, MultiPolygons, and LineStrings that are entirely within this region.
149+
150+
> [!NOTE]
151+
> If you try to add an indexing policy with a **boundingBox** to a container with `geography` data type, it will fail. You should modify the container's **geospatialConfig** to be `geometry` before adding a **boundingBox**. You can add data and modify the remainder of
152+
> your indexing policy (such as the paths and types) either before or after selecting the geospatial data type for the container.
153+
62154
## Next steps
63155

64156
Now that you have learned how to get started with geospatial support in Azure Cosmos DB, next you can:

‎articles/cosmos-db/sql-query-geospatial-intro.md

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,10 @@ This article is an introduction to the geospatial functionality in Azure Cosmos
2020

2121
Spatial data describes the position and shape of objects in space. In most applications, these correspond to objects on the earth and geospatial data. Spatial data can be used to represent the location of a person, a place of interest, or the boundary of a city, or a lake. Common use cases often involve proximity queries, for example, "find all coffee shops near my current location."
2222

23-
Azure Cosmos DB's SQL API supports the **geography** data type. The **geography** type represents data in a round-earth coordinate system.
23+
Azure Cosmos DB's SQL API supports two spatial data types: the **geometry** data type and the **geography** data type.
24+
25+
- The **geometry** type represents data in a Euclidean (flat) coordinate system
26+
- The **geography** type represents data in a round-earth coordinate system.
2427

2528
## Supported data types
2629

@@ -65,7 +68,11 @@ Spatial data types can be embedded in an Azure Cosmos DB document as shown in th
6568
}
6669
```
6770

68-
### Points in geography coordinate system
71+
### Points in a geometry coordinate system
72+
73+
For the **geometry** data type, GeoJSON specification specifies the horizontal axis first and the vertical axis second.
74+
75+
### Points in a geography coordinate system
6976

7077
For the **geography** data type, GeoJSON specification specifies longitude first and latitude second. Like in other mapping applications, longitude and latitude are angles and represented in terms of degrees. Longitude values are measured from the Prime Meridian and are between -180 degrees and 180.0 degrees, and latitude values are measured from the equator and are between -90.0 degrees and 90.0 degrees.
7178

0 commit comments

Comments
 (0)