Azure Cosmos DB 中的地理空间和 GeoJSON 位置数据Geospatial and GeoJSON location data in Azure Cosmos DB

适用于: SQL API

本文介绍 Azure Cosmos DB 中的地理空间功能。This article is an introduction to the geospatial functionality in Azure Cosmos DB. 目前,只有 Azure Cosmos DB SQL API 帐户支持存储和访问地理空间数据。Currently storing and accessing geospatial data is supported by Azure Cosmos DB SQL API accounts only. 阅读有关地理空间索引的文档后,你将能够回答以下问题:After reading our documentation on geospatial indexing you will be able to answer the following questions:

  • 如何在 Azure Cosmos DB 中存储空间数据?How do I store spatial data in Azure Cosmos DB?
  • 如何使用 SQL 和 LINQ 查询 Azure Cosmos DB 中的地理空间数据?How can I query geospatial data in Azure Cosmos DB in SQL and LINQ?
  • 如何在Azure Cosmos DB 中启用或禁用空间索引?How do I enable or disable spatial indexing in Azure Cosmos DB?

空间数据用例Spatial Data Use Cases

地理空间数据通常涉及邻近查询,例如“寻找我目前位置附近的所有咖啡厅”。Geospatial data often involve proximity queries, for example, "find all coffee shops near my current location". 常见用例包括:Common use cases are:

  • 地理位置分析,用于推动特定位置市场营销计划。Geolocation Analytics, driving specific located marketing initiatives.
  • 基于位置的个性化,适用于零售和医疗保健等多个行业。Location based personalization, for multiple industries like Retail and Healthcare.
  • 物流增强,用于优化运输。Logistics enhancement, for transport optimization.
  • 风险分析,特别适用于保险和金融公司。Risk Analysis, especially for insurance and finance companies.
  • 态势感知,用于发出警报和通知。Situational awareness, for alerts and notifications.

空间数据简介Introduction to spatial data

空间数据用于描述空间中对象的位置和形状。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.

Azure Cosmos DB SQL API 支持两种空间数据类型:geometry 数据类型和 geography 数据类型 。Azure Cosmos DB's SQL API supports two spatial data types: the geometry data type and the geography data type.

  • geometry 类型在欧几里得(平面)坐标系统中表示数据The geometry type represents data in a Euclidean (flat) coordinate system
  • Geography 类型表示圆形地球坐标系中的数据。The geography type represents data in a round-earth coordinate system.

支持的数据类型Supported data types

Azure Cosmos DB 支持对使用 GeoJSON 规范表示的地理空间点数据进行索引编制和查询。Azure Cosmos DB supports indexing and querying of geospatial point data that's represented using the GeoJSON specification. GeoJSON 数据结构永远是有效的 JSON 对象,因此可以通过 Azure Cosmos DB 来存储和查询,无需任何专用的工具或库。GeoJSON data structures are always valid JSON objects, so they can be stored and queried using Azure Cosmos DB without any specialized tools or libraries.

Azure Cosmos DB 支持以下空间数据类型:Azure Cosmos DB supports the following spatial data types:

  • PointPoint
  • LineStringLineString
  • PolygonPolygon
  • MultiPolygonMultiPolygon


代表空间中的单一位置。A Point denotes a single position in space. 在地理空间数据中,某个点所代表的确切位置可能是杂货店、电话亭、汽车或城市的街道地址。In geospatial data, a Point represents the exact location, which could be a street address of a grocery store, a kiosk, an automobile, or a city. 点使用其坐标对或经纬度,以 GeoJSON 格式(和 Azure Cosmos DB)表示。A point is represented in GeoJSON (and Azure Cosmos DB) using its coordinate pair or longitude and latitude.

以下是点的 JSON 示例:Here's an example JSON for a point:

Azure Cosmos DB 中的点 Points in Azure Cosmos DB

    "coordinates":[ 31.9, -4.8 ]

如下面包含位置数据的用户配置文件示例所示,空间数据类型可以嵌入在 Azure Cosmos DB 文档中:Spatial data types can be embedded in an Azure Cosmos DB document as shown in this example of a user profile containing location data:

存储在 Azure Cosmos DB 中包含位置的用户配置文件 Use Profile with Location stored in Azure Cosmos DB

    "topics":[ "global", "distributed" ],
        "coordinates":[ 31.9, -4.8 ]

几何坐标系统中的点Points in a geometry coordinate system

对于几何 数据类型,GeoJSON 规范首先指定水平轴,然后指定垂直轴。For the geometry data type, GeoJSON specification specifies the horizontal axis first and the vertical axis second.

地理坐标系统中的点Points in a geography coordinate system

对于 geography 数据类型,GeoJSON 规范先指定经度,再指定纬度。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. 经度值从本初子午线测量,并介于 -180 度和 180.0 度之间;纬度值从赤道测量,并介于 -90.0 度和 90.0 度之间。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.

Azure Cosmos DB 会将坐标解释为按照 WGS-84 参考系统表示。Azure Cosmos DB interprets coordinates as represented per the WGS-84 reference system. 有关坐标参考系统的更多详细信息,请参阅下文。See below for more details about coordinate reference systems.


LineString 表示空间中一连串的点(两个或更多个)以及连接这些点的线段。LineStrings represent a series of two or more points in space and the line segments that connect them. 在地理空间数据中,LineString 通常用来表示高速公路或河流。In geospatial data, LineStrings are commonly used to represent highways or rivers.

GeoJSON 中的 LineStringLineStrings in GeoJSON

    "coordinates":[ [
        [ 31.8, -5 ],
        [ 31.8, -4.7 ]
    ] ]


多边形 是形成闭合的 LineString 的相连接的点的边界。A Polygon is a boundary of connected points that forms a closed LineString. 多边形通常用来表示自然构成物(例如湖泊),或表示政治管辖权(例如省/市/自治区)。Polygons are commonly used to represent natural formations like lakes or political jurisdictions like cities and states. 下面是 Azure Cosmos DB 中的一个多边形示例:Here's an example of a Polygon in Azure Cosmos DB:

GeoJSON 中的多边形 Polygons in GeoJSON

    "coordinates":[ [
        [ 31.8, -5 ],
        [ 31.8, -4.7 ],
        [ 32, -4.7 ],
        [ 32, -5 ],
        [ 31.8, -5 ]
    ] ]


GeoJSON 规范需要此数据才能形成有效的多边形;若要创建一个闭合的形状,最后一个坐标对应该与第一个坐标对相同。The GeoJSON specification requires that for valid Polygons, the last coordinate pair provided should be the same as the first, to create a closed shape.

多边形内的点必须以逆时针顺序指定。Points within a Polygon must be specified in counter-clockwise order. 以顺时针顺序指定的多边形表示其中的区域倒转。A Polygon specified in clockwise order represents the inverse of the region within it.


MultiPolygon 是包含零个或多个多边形的数组。A MultiPolygon is an array of zero or more Polygons. 各个 MultiPolygon 的边不能重叠,也不能具有任何公共区域。MultiPolygons cannot overlap sides or have any common area. 它们的一个或多个点可以接触。They may touch at one or more points.

GeoJSON 中的 MultiPolygonMultiPolygons in GeoJSON

        [52.0, 12.0],
        [53.0, 12.0],
        [53.0, 13.0],
        [52.0, 13.0],
        [52.0, 12.0]
        [50.0, 0.0],
        [51.0, 0.0],
        [51.0, 5.0],
        [50.0, 5.0],
        [50.0, 0.0]

坐标参考系统Coordinate reference systems

由于地球的形状不规则,地理空间数据的坐标可以用许多坐标参考系统 (CRS) 来表示,而这些系统各有自己的参考框架和测量单位。Since the shape of the earth is irregular, coordinates of geography geospatial data are represented in many coordinate reference systems (CRS), each with their own frames of reference and units of measurement. 例如,“英国国家网格”对英国而言是非常精确的参考系统,但对其他地区则不是。For example, the "National Grid of Britain" is a reference system is accurate for the United Kingdom, but not outside it.

现今最常使用的 CRS 是世界测地系统 WGS-84The most popular CRS in use today is the World Geodetic System WGS-84. GPS 设备和许多地图服务(包括谷歌地图和必应地图 API)均使用 WGS-84。GPS devices, and many mapping services including Google Maps and Bing Maps APIs use WGS-84. Azure Cosmos DB 仅支持对使用 WGS-84 CRS 的地理空间数据进行索引编制和查询。Azure Cosmos DB supports indexing and querying of geography geospatial data using the WGS-84 CRS only.

创建包含空间数据的文档Creating documents with spatial data

创建包含 GeoJSON 值的文档时,值会根据容器的索引策略,自动以空间索引进行索引编制。When you create documents that contain GeoJSON values, they are automatically indexed with a spatial index in accordance to the indexing policy of the container. 如果以动态类型化语言(如 Python 或 Node.js)使用 Azure Cosmos DB SDK,则必须创建有效的 GeoJSON。If you're working with an Azure Cosmos DB SDK in a dynamically typed language like Python or Node.js, you must create valid GeoJSON.

在 Node.js 中创建包含地理空间数据的文档Create Document with Geospatial data in Node.js

var userProfileDocument = {
        "coordinates":[ -122.12, 47.66 ]

client.createDocument(`dbs/${databaseName}/colls/${collectionName}`, userProfileDocument, (err, created) => {
    // additional code within the callback

如果使用 SQL API,则可以在 Microsoft.Azure.Cosmos.Spatial 命名空间中使用 PointLineStringPolygonMultiPolygon 类,将位置信息嵌入应用程序对象中。If you're working with the SQL APIs, you can use the Point, LineString, Polygon, and MultiPolygon classes within the Microsoft.Azure.Cosmos.Spatial namespace to embed location information within your application objects. 这些类有助于简化将空间数据序列化和反序列化为 GeoJSON 的过程。These classes help simplify the serialization and deserialization of spatial data into GeoJSON.

在 .NET 中创建包含地理空间数据的文档Create Document with Geospatial data in .NET

using Microsoft.Azure.Cosmos.Spatial;

public class UserProfile
    public string id { get; set; }

    public Point Location { get; set; }

    // More properties

await container.CreateItemAsync( new UserProfile
        id = "cosmosdb",
        Location = new Point (-122.12, 47.66)

如果没有经纬度信息,但有物理地址或位置名称,如城市或国家/地区,则可以使用必应地图 REST 服务等地理编码服务来查找实际的坐标。If you don't have the latitude and longitude information, but have the physical addresses or location name like city or country/region, you can look up the actual coordinates by using a geocoding service like Bing Maps REST Services. 此处详细了解必应地图地理编码。Learn more about Bing Maps geocoding here.

后续步骤Next steps

已经学会如何开始使用 Azure Cosmos DB 中的地理空间支持,下一步现在可以:Now that you have learned how to get started with geospatial support in Azure Cosmos DB, next you can: