Uso dei dati geospaziali e dei dati località GeoJSON in Azure Cosmos DBWorking with geospatial and GeoJSON location data in Azure Cosmos DB

Questo articolo offre un'introduzione alla funzionalità geospaziale in Azure Cosmos DB.This article is an introduction to the geospatial functionality in Azure Cosmos DB. Dopo la lettura di questo articolo, si potrà rispondere alle domande seguenti:After reading this, you will be able to answer the following questions:

  • Come si archiviano i dati spaziali in Azure Cosmos DB?How do I store spatial data in Azure Cosmos DB?
  • Come si eseguono query su dati geospaziali in Azure Cosmos DB in SQL e LINQ?How can I query geospatial data in Azure Cosmos DB in SQL and LINQ?
  • Come si abilita o disabilita l'indicizzazione spaziale in Azure Cosmos DB?How do I enable or disable spatial indexing in Azure Cosmos DB?

Questo articolo illustra come usare i dati spaziali con l'API di DocumentDB.This article shows how to work with spatial data with the DocumentDB API. Consultare il progetto GitHub per esempi di codice.Please see this GitHub project for code samples.

Introduzione ai dati spazialiIntroduction to spatial data

I dati spaziali descrivono la posizione e la forma degli oggetti nello spazio.Spatial data describes the position and shape of objects in space. Nella maggior parte delle applicazioni, questi corrispondono a oggetti sulla terra, vale a dire dati geospaziali.In most applications, these correspond to objects on the earth, i.e. geospatial data. I dati spaziali possono essere utilizzati per rappresentare la posizione di una persona, un luogo di interesse o i confini di una città o di un lago.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. Casi di utilizzo comuni includono spesso query di prossimità, ad esempio, "trova tutti i negozi vicino alla mia posizione attuale".Common use cases often involve proximity queries, for e.g., "find all coffee shops near my current location".

GeoJSONGeoJSON

Azure Cosmos DB supporta l'indicizzazione e le query dei dati di punti geospaziali rappresentati tramite la specifica GeoJSON.Azure Cosmos DB supports indexing and querying of geospatial point data that's represented using the GeoJSON specification. Le strutture di dati GeoJSON sono sempre oggetti JSON validi, quindi possono essere archiviate e sottoposte a query usando Azure Cosmos DB senza librerie o strumenti specializzati.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. Gli SDK di Azure Cosmos DB forniscono classi helper e metodi che semplificano il lavoro con i dati spaziali.The Azure Cosmos DB SDKs provide helper classes and methods that make it easy to work with spatial data.

Punti, oggetti linestring e poligoniPoints, LineStrings and Polygons

Un punto indica una posizione singola nello spazio.A Point denotes a single position in space. Nei dati geospaziali, un punto rappresenta la posizione esatta, che può essere un indirizzo di un negozio, un chiosco, un'automobile o una città.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. Un punto viene rappresentato in GeoJSON (e Azure Cosmos DB) tramite la sua coppia di coordinate o longitudine e latitudine.A point is represented in GeoJSON (and Azure Cosmos DB) using its coordinate pair or longitude and latitude. Di seguito è riportato un esempio JSON per un punto.Here's an example JSON for a point.

Punti in Azure Cosmos DBPoints in Azure Cosmos DB

{
    "type":"Point",
    "coordinates":[ 31.9, -4.8 ]
}

Nota

GeoJSON specifica la longitudine prima e la latitudine dopo.The GeoJSON specification specifies longitude first and latitude second. Come in altre applicazioni di mapping, longitudine e latitudine sono angoli e sono espresse in gradi.Like in other mapping applications, longitude and latitude are angles and represented in terms of degrees. I valori della longitudine vengono misurati dal meridiano principale e sono compresi tra -180° e 180,0° gradi, mentre i valori della latitudine sono misurati dall'equatore e sono compresi tra -90,0° e 90,0°.Longitude values are measured from the Prime Meridian and are between -180 and 180.0 degrees, and latitude values are measured from the equator and are between -90.0 and 90.0 degrees.

Azure Cosmos DB interpreta le coordinate come rappresentate secondo il sistema di riferimento WGS-84.Azure Cosmos DB interprets coordinates as represented per the WGS-84 reference system. Per ulteriori informazioni sui sistemi di coordinate di riferimento, vedere di seguito.Please see below for more details about coordinate reference systems.

I punti possono essere incorporati in un documento di Azure Cosmos DB come illustrato in questo esempio di profilo utente contenente dati di località:This can be embedded in an Azure Cosmos DB document as shown in this example of a user profile containing location data:

Usare un profilo con località archiviata in Azure Cosmos DBUse Profile with Location stored in Azure Cosmos DB

{
    "id":"documentdb-profile",
    "screen_name":"@CosmosDB",
    "city":"Redmond",
    "topics":[ "global", "distributed" ],
    "location":{
        "type":"Point",
        "coordinates":[ 31.9, -4.8 ]
    }
}

Oltre ai punti, GeoJSON supporta oggetti linestring e poligoni.In addition to points, GeoJSON also supports LineStrings and Polygons. LineStrings rappresentano una serie di due o più punti nello spazio e i segmenti lineari che li connettono.LineStrings represent a series of two or more points in space and the line segments that connect them. Nei dati geospaziali, gli oggetti linestring di solito vengono usati per rappresentare autostrade o fiumi.In geospatial data, LineStrings are commonly used to represent highways or rivers. Un oggetto poligono è un perimetro costituito da punti connessi che forma un elemento LineString chiuso.A Polygon is a boundary of connected points that forms a closed LineString. I poligoni vengono comunemente utilizzati per rappresentare formazioni naturali come laghi o giurisdizioni politiche come città e stati.Polygons are commonly used to represent natural formations like lakes or political jurisdictions like cities and states. Di seguito è riportato un esempio di poligono in Azure Cosmos DB.Here's an example of a Polygon in Azure Cosmos DB.

Poligoni in GeoJSONPolygons in GeoJSON

{
    "type":"Polygon",
    "coordinates":[ [
        [ 31.8, -5 ],
        [ 31.8, -4.7 ],
        [ 32, -4.7 ],
        [ 32, -5 ],
        [ 31.8, -5 ]
    ] ]
}

Nota

La specifica GeoJSON richiede che per i poligoni validi l'ultima coppia di coordinate indicata corrisponda alla prima, in modo da creare una forma chiusa.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.

I punti all'interno di un poligono devono essere specificati in senso antiorario.Points within a Polygon must be specified in counter-clockwise order. Un poligono specificato in senso orario rappresenta l'inverso dell'area al suo interno.A Polygon specified in clockwise order represents the inverse of the region within it.

Oltre a punto, LineString e poligono, GeoJSON specifica inoltre la rappresentazione della modalità di raggruppamento di più posizioni geospaziali, nonché come associare proprietà arbitrarie alla georilevazione come Caratteristica.In addition to Point, LineString and Polygon, GeoJSON also specifies the representation for how to group multiple geospatial locations, as well as how to associate arbitrary properties with geolocation as a Feature. Trattandosi di oggetti JSON validi, essi possono essere archiviati ed elaborati tutti in Azure Cosmos DB.Since these objects are valid JSON, they can all be stored and processed in Azure Cosmos DB. Azure Cosmos DB supporta tuttavia solo l'indicizzazione automatica dei punti.However Azure Cosmos DB only supports automatic indexing of points.

Sistemi di riferimento delle coordinateCoordinate reference systems

Poiché la forma della terra è irregolare, le coordinate dei dati geospaziali sono rappresentate in molti sistemi di coordinate di riferimento (CRS), ognuno con la propria struttura di riferimento e le proprie unità di misura.Since the shape of the earth is irregular, coordinates of geospatial data is represented in many coordinate reference systems (CRS), each with their own frames of reference and units of measurement. Ad esempio, il "National Grid of Britain" è un sistema di riferimento molto accurato per il Regno Unito, ma non al suo esterno.For example, the "National Grid of Britain" is a reference system is very accurate for the United Kingdom, but not outside it.

Il più diffuso CRS attualmente in uso è il World Geodetic System WGS-84.The most popular CRS in use today is the World Geodetic System WGS-84. Dispositivi GPS e molti servizi di mapping, tra cui Google Maps e le API di Bing Maps, utilizzano WGS-84.GPS devices, and many mapping services including Google Maps and Bing Maps APIs use WGS-84. Azure Cosmos DB supporta l'indicizzazione e l'esecuzione di query di dati geospaziali usando solo il CRS WGS-84.Azure Cosmos DB supports indexing and querying of geospatial data using the WGS-84 CRS only.

Creazione di documenti con dati spazialiCreating documents with spatial data

Quando si creano documenti che contengono valori GeoJSON, essi vengono indicizzati automaticamente con un indice spaziale in base al criterio di indicizzazione della raccolta.When you create documents that contain GeoJSON values, they are automatically indexed with a spatial index in accordance to the indexing policy of the collection. Se si usa un SDK di Azure Cosmos DB in un linguaggio tipizzato in modo dinamico come Python o Node.js, è necessario creare un GeoJSON valido.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.

Creare documenti con i dati geospaziali in Node.jsCreate Document with Geospatial data in Node.js

var userProfileDocument = {
    "name":"documentdb",
    "location":{
        "type":"Point",
        "coordinates":[ -122.12, 47.66 ]
    }
};

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

Se si lavora con le API di DocumentDB, è possibile usare le classi Point e Polygon all'interno dello spazio dei nomi Microsoft.Azure.Documents.Spatial per incorporare le informazioni sulla località all'interno di oggetti dell'applicazione.If you're working with the DocumentDB APIs, you can use the Point and Polygon classes within the Microsoft.Azure.Documents.Spatial namespace to embed location information within your application objects. Queste classi consentono di semplificare la serializzazione e la deserializzazione dei dati spaziali in GeoJSON.These classes help simplify the serialization and deserialization of spatial data into GeoJSON.

Creare documenti con i dati geospaziali in .NETCreate Document with Geospatial data in .NET

using Microsoft.Azure.Documents.Spatial;

public class UserProfile
{
    [JsonProperty("name")]
    public string Name { get; set; }

    [JsonProperty("location")]
    public Point Location { get; set; }

    // More properties
}

await client.CreateDocumentAsync(
    UriFactory.CreateDocumentCollectionUri("db", "profiles"), 
    new UserProfile 
    { 
        Name = "documentdb", 
        Location = new Point (-122.12, 47.66) 
    });

Se non si dispone delle informazioni di latitudine e longitudine, ma si dispone di indirizzi fisici o del nome della posizione come la città o il paese, è possibile cercare le coordinate effettive tramite un servizio di geocodifica come i servizi REST di Bing Maps.If you don't have the latitude and longitude information, but have the physical addresses or location name like city or country, you can look up the actual coordinates by using a geocoding service like Bing Maps REST Services. Ulteriori informazioni sulla geocodifica di Bing Maps sono disponibili qui.Learn more about Bing Maps geocoding here.

Query sui tipi spazialiQuerying spatial types

Dopo aver compreso come inserire i dati geospaziali, è ora possibile esaminare come eseguire query sui dati usando Azure Cosmos DB e LINQ.Now that we've taken a look at how to insert geospatial data, let's take a look at how to query this data using Azure Cosmos DB using SQL and LINQ.

Funzioni predefinite spaziali di SQLSpatial SQL built-in functions

Azure Cosmos DB supporta le seguenti funzioni predefinite di Open Geospatial Consortium (OGC) per l'esecuzione di query geospaziali.Azure Cosmos DB supports the following Open Geospatial Consortium (OGC) built-in functions for geospatial querying. Per altre informazioni sul set completo di funzioni predefinite del linguaggio SQL, vedere Query di Azure Cosmos DB.For more details on the complete set of built-in functions in the SQL language, please refer to Query Azure Cosmos DB.

UtilizzoUsage DescrizioneDescription
ST_DISTANCE (spatial_expr, spatial_expr)ST_DISTANCE (spatial_expr, spatial_expr) Restituisce la distanza tra le due espressioni GeoJSON punto, poligono o LineString.Returns the distance between the two GeoJSON Point, Polygon, or LineString expressions.
ST_WITHIN (spatial_expr, spatial_expr)ST_WITHIN (spatial_expr, spatial_expr) Restituisce un'espressione booleana che indica se il primo oggetto GeoJSON (punto, poligono o LineString) è all'interno del secondo oggetto GeoJSON (punto, poligono o LineString).Returns a Boolean expression indicating whether the first GeoJSON object (Point, Polygon, or LineString) is within the second GeoJSON object (Point, Polygon, or LineString).
ST_INTERSECTS (spatial_expr, spatial_expr)ST_INTERSECTS (spatial_expr, spatial_expr) Restituisce un'espressione booleana che indica se i due oggetti GeoJSON specificati (punto, poligono o LineString) si intersecano.Returns a Boolean expression indicating whether the two specified GeoJSON objects (Point, Polygon, or LineString) intersect.
ST_ISVALIDST_ISVALID Restituisce un valore booleano che indica se l'espressione GeoJSON punto, poligono o LineString specificata è valida.Returns a Boolean value indicating whether the specified GeoJSON Point, Polygon, or LineString expression is valid.
ST_ISVALIDDETAILEDST_ISVALIDDETAILED Restituisce un valore JSON che contiene un valore booleano valore se l'espressione GeoJSON punto, poligono o LineString specificata è valida e, se non valida, anche il motivo come valore stringa.Returns a JSON value containing a Boolean value if the specified GeoJSON Point, Polygon, or LineString expression is valid, and if invalid, additionally the reason as a string value.

Le funzioni spaziali possono essere utilizzate per eseguire query di prossimità rispetto ai dati spaziali.Spatial functions can be used to perform proximity queries against spatial data. Ad esempio, di seguito è riportata una query che restituisce tutti i documenti della famiglia entro 30 km della posizione specificata utilizzando la funzione predefinita ST_DISTANCE.For example, here's a query that returns all family documents that are within 30 km of the specified location using the ST_DISTANCE built-in function.

QueryQuery

SELECT f.id 
FROM Families f 
WHERE ST_DISTANCE(f.location, {'type': 'Point', 'coordinates':[31.9, -4.8]}) < 30000

RisultatiResults

[{
  "id": "WakefieldFamily"
}]

Se si include l'indicizzazione spaziale nel criterio di indicizzazione, le "query distance" verranno servite in modo efficiente tramite l'indice.If you include spatial indexing in your indexing policy, then "distance queries" will be served efficiently through the index. Per altre informazioni sull'indicizzazione spaziale, vedere la sezione seguente.For more details on spatial indexing, please see the section below. Se non si dispone di un indice spaziale per i percorsi specificati, è comunque possibile eseguire query spaziali specificando x-ms-documentdb-query-enable-scan intestazione della richiesta con il valore impostato su "true".If you don't have a spatial index for the specified paths, you can still perform spatial queries by specifying x-ms-documentdb-query-enable-scan request header with the value set to "true". In .NET, questa operazione può essere eseguita passando l’argomento facoltativo FeedOptions alle query con EnableScanInQuery impostato su true.In .NET, this can be done by passing the optional FeedOptions argument to queries with EnableScanInQuery set to true.

Usare ST_WITHIN per verificare se un punto si trova all'interno di un poligono.ST_WITHIN can be used to check if a point lies within a Polygon. I poligoni vengono comunemente usati per rappresentare limiti come codici postali, confini di stato o formazioni naturali.Commonly Polygons are used to represent boundaries like zip codes, state boundaries, or natural formations. Ancora una volta, se si include l'indicizzazione spaziale nel criterio di indicizzazione, le query "within" verranno servite in modo efficiente tramite l'indice.Again if you include spatial indexing in your indexing policy, then "within" queries will be served efficiently through the index.

Gli argomenti Polygon in ST_WITHIN possono contenere solo un anello singolo, ad esempio i poligoni non devono contenere aree vuote.Polygon arguments in ST_WITHIN can contain only a single ring, i.e. the Polygons must not contain holes in them.

QueryQuery

SELECT * 
FROM Families f 
WHERE ST_WITHIN(f.location, {
    'type':'Polygon', 
    'coordinates': [[[31.8, -5], [32, -5], [32, -4.7], [31.8, -4.7], [31.8, -5]]]
})

RisultatiResults

[{
  "id": "WakefieldFamily",
}]

Nota

Come per il funzionamento di tipi non corrispondenti nella query di Azure Cosmos DB, se il valore di località specificato in un argomento è non corretto o non è valido, verrà restituito undefined e il documento valutato verrà omesso nei risultati della query.Similar to how mismatched types works in Azure Cosmos DB query, if the location value specified in either argument is malformed or invalid, then it will evaluate to undefined and the evaluated document to be skipped from the query results. Se la query non restituisce alcun risultato, eseguire ST_ISVALIDDETAILED per eseguire il debug del tipo spatail non valido.If your query returns no results, run ST_ISVALIDDETAILED To debug why the spatail type is invalid.

Azure Cosmos DB supporta anche l'esecuzione di query inverse, ovvero è possibile indicizzare poligoni o linee in Azure Cosmos DB, quindi eseguire una query per le aree che contengono un punto specificato.Azure Cosmos DB also supports performing inverse queries, i.e. you can index Polygons or lines in Azure Cosmos DB, then query for the areas that contain a specified point. Questo modello viene comunemente usato nella logistica per identificare, ad esempio, quando un furgone entra o esce da un'area designata.This pattern is commonly used in logistics to identify e.g. when a truck enters or leaves a designated area.

QueryQuery

SELECT * 
FROM Areas a 
WHERE ST_WITHIN({'type': 'Point', 'coordinates':[31.9, -4.8]}, a.location)

RisultatiResults

[{
  "id": "MyDesignatedLocation",
  "location": {
    "type":"Polygon", 
    "coordinates": [[[31.8, -5], [32, -5], [32, -4.7], [31.8, -4.7], [31.8, -5]]]
  }
}]

ST_ISVALID e ST_ISVALIDDETAILED possono essere utilizzati per verificare la validità di un oggetto spaziale.ST_ISVALID and ST_ISVALIDDETAILED can be used to check if a spatial object is valid. Ad esempio, la seguente query controlla la validità di un punto con un valore di latitudine fuori scala (-132,8).For example, the following query checks the validity of a point with an out of range latitude value (-132.8). ST_ISVALID restituisce solo un valore booleano e ST_ISVALIDDETAILED restituisce il valore booleano e una stringa contenente il motivo per cui è considerato non valido.ST_ISVALID returns just a Boolean value, and ST_ISVALIDDETAILED returns the Boolean and a string containing the reason why it is considered invalid.

** Query Query **

SELECT ST_ISVALID({ "type": "Point", "coordinates": [31.9, -132.8] })

RisultatiResults

[{
  "$1": false
}]

Queste funzioni possono essere usate anche per convalidare i poligoni.These functions can also be used to validate Polygons. Ad esempio, qui viene usata la funzione ST_ISVALIDDETAILED per convalidare un poligono che non è chiuso.For example, here we use ST_ISVALIDDETAILED to validate a Polygon that is not closed.

QueryQuery

SELECT ST_ISVALIDDETAILED({ "type": "Polygon", "coordinates": [[ 
    [ 31.8, -5 ], [ 31.8, -4.7 ], [ 32, -4.7 ], [ 32, -5 ] 
    ]]})

RisultatiResults

[{
   "$1": { 
        "valid": false, 
        "reason": "The Polygon input is not valid because the start and end points of the ring number 1 are not the same. Each ring of a Polygon must have the same start and end points." 
      }
}]

Query di LINQ in .NET SDKLINQ Querying in the .NET SDK

Il .NET SDK di DocumentDB fornisce inoltre metodi stub Distance() e Within() per l'utilizzo all'interno di espressioni LINQ.The DocumentDB .NET SDK also providers stub methods Distance() and Within() for use within LINQ expressions. Il provider LINQ di DocumentDB converte le chiamate di questi metodi nelle chiamate della funzione predefinita di SQL equivalente (ST_DISTANCE e ST_WITHIN rispettivamente).The DocumentDB LINQ provider translates these method calls to the equivalent SQL built-in function calls (ST_DISTANCE and ST_WITHIN respectively).

Di seguito è riportato un esempio di query LINQ che consente di trovare tutti i documenti nella raccolta di Azure Cosmos DB il cui valore "location" è entro un raggio di 30 km dal punto specificato con LINQ.Here's an example of a LINQ query that finds all documents in the Azure Cosmos DB collection whose "location" value is within a radius of 30km of the specified point using LINQ.

Query LINQ per DistanceLINQ query for Distance

foreach (UserProfile user in client.CreateDocumentQuery<UserProfile>(UriFactory.CreateDocumentCollectionUri("db", "profiles"))
    .Where(u => u.ProfileType == "Public" && a.Location.Distance(new Point(32.33, -4.66)) < 30000))
{
    Console.WriteLine("\t" + user);
}

Analogamente, di seguito è riportata una query per trovare tutti i documenti il cui valore "location" è all'interno della casella o del poligono specificato.Similarly, here's a query for finding all the documents whose "location" is within the specified box/Polygon.

Query LINQ per WithinLINQ query for Within

Polygon rectangularArea = new Polygon(
    new[]
    {
        new LinearRing(new [] {
            new Position(31.8, -5),
            new Position(32, -5),
            new Position(32, -4.7),
            new Position(31.8, -4.7),
            new Position(31.8, -5)
        })
    });

foreach (UserProfile user in client.CreateDocumentQuery<UserProfile>(UriFactory.CreateDocumentCollectionUri("db", "profiles"))
    .Where(a => a.Location.Within(rectangularArea)))
{
    Console.WriteLine("\t" + user);
}

Dopo aver compreso come eseguire query sui documenti con LINQ e SQL, è ora possibile esaminare come configurare Azure Cosmos DB per l'indicizzazione spaziale.Now that we've taken a look at how to query documents using LINQ and SQL, let's take a look at how to configure Azure Cosmos DB for spatial indexing.

IndicizzazioneIndexing

Come illustrato nel documento Schema Agnostic Indexing with Azure Cosmos DB (Indicizzazione indipendente dallo schema con Azure DocumentDB), il motore del database Azure Cosmos DB è stato progettato per essere realmente indipendente dallo schema e fornire supporto avanzato per JSON.As we described in the Schema Agnostic Indexing with Azure Cosmos DB paper, we designed Azure Cosmos DB’s database engine to be truly schema agnostic and provide first class support for JSON. Il motore di database ottimizzato per la scrittura di Azure Cosmos DB riconosce a livello nativo i dati spaziali (punti, poligoni e linee) rappresentati nello standard GeoJSON.The write optimized database engine of Azure Cosmos DB natively understands spatial data (points, Polygons and lines) represented in the GeoJSON standard.

In breve, la geometria è proiettata dalle coordinate geodetiche su un piano 2D, quindi suddivisa progressivamente in celle utilizzando un quadtree.In a nutshell, the geometry is projected from geodetic coordinates onto a 2D plane then divided progressively into cells using a quadtree. Queste celle vengono mappate in 1D in base alla posizione della cella all'interno di una curva di riempimento dello spazio di Hilbert, che consente di mantenere la posizione dei punti.These cells are mapped to 1D based on the location of the cell within a Hilbert space filling curve, which preserves locality of points. Quando i dati località vengono indicizzati, passano attraverso un processo noto come mosaico, vale a dire tutte le celle che intersecano una posizione vengono identificate e archiviate come chiavi nell'indice di Azure Cosmos DB.Additionally when location data is indexed, it goes through a process known as tessellation, i.e. all the cells that intersect a location are identified and stored as keys in the Azure Cosmos DB index. In fase di query, anche argomenti come punti e poligoni sono tassellati per estrarre gli intervalli degli ID delle celle pertinenti e quindi usati per recuperare dati dall'indice.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.

Se si specifica un criterio di indicizzazione che include un indice spaziale per /* (tutti i percorsi), tutti i punti trovati all'interno dell'insieme vengono indicizzati per query spaziali efficienti (ST_WITHIN e ST_DISTANCE).If you specify an indexing policy that includes spatial index for /* (all paths), then all points found within the collection are indexed for efficient spatial queries (ST_WITHIN and ST_DISTANCE). Gli indici spaziali non hanno un valore di precisione e utilizzano sempre un valore di precisione predefinito.Spatial indexes do not have a precision value, and always use a default precision value.

Nota

Azure Cosmos DB supporta l'indicizzazione automatica dei tipi di dati Point, Polygon e LineString.Azure Cosmos DB supports automatic indexing of Points, Polygons, and LineStrings

Il seguente frammento JSON mostra un criterio di indicizzazione con indicizzazione spaziale abilitata, ossia indicizza qualsiasi punto GeoJSON trovato all'interno di documenti per le query spaziali.The following JSON snippet shows an indexing policy with spatial indexing enabled, i.e. index any GeoJSON point found within documents for spatial querying. Se si modifica il criterio di indicizzazione tramite il portale di Azure, è possibile specificare il seguente JSON come criterio di indicizzazione per abilitare l’indicizzazione spaziale nella raccolta.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 collection.

JSON criterio di indicizzazione della raccolta con Spatial abilitato per punti e poligoniCollection Indexing Policy JSON with Spatial enabled for points and Polygons

{
   "automatic":true,
   "indexingMode":"Consistent",
   "includedPaths":[
      {
         "path":"/*",
         "indexes":[
            {
               "kind":"Range",
               "dataType":"String",
               "precision":-1
            },
            {
               "kind":"Range",
               "dataType":"Number",
               "precision":-1
            },
            {
               "kind":"Spatial",
               "dataType":"Point"
            },
            {
               "kind":"Spatial",
               "dataType":"Polygon"
            }                
         ]
      }
   ],
   "excludedPaths":[
   ]
}

Ecco un frammento di codice in .NET che illustra come creare una raccolta con indicizzazione spaziale attivata per tutti i percorsi contenenti punti.Here's a code snippet in .NET that shows how to create a collection with spatial indexing turned on for all paths containing points.

Creare una raccolta con indicizzazione spazialeCreate a collection with spatial indexing

DocumentCollection spatialData = new DocumentCollection()
spatialData.IndexingPolicy = new IndexingPolicy(new SpatialIndex(DataType.Point)); //override to turn spatial on by default
collection = await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("db"), spatialData);

Di seguito viene descritto come modificare una raccolta esistente per sfruttare i vantaggi dell'indicizzazione spaziale su tutti i punti archiviati all'interno di documenti.And here's how you can modify an existing collection to take advantage of spatial indexing over any points that are stored within documents.

Modificare una raccolta esistente con l'indicizzazione spazialeModify an existing collection with spatial indexing

Console.WriteLine("Updating collection with spatial indexing enabled in indexing policy...");
collection.IndexingPolicy = new IndexingPolicy(new SpatialIndex(DataType.Point));
await client.ReplaceDocumentCollectionAsync(collection);

Console.WriteLine("Waiting for indexing to complete...");
long indexTransformationProgress = 0;
while (indexTransformationProgress < 100)
{
    ResourceResponse<DocumentCollection> response = await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri("db", "coll"));
    indexTransformationProgress = response.IndexTransformationProgress;

    await Task.Delay(TimeSpan.FromSeconds(1));
}

Nota

Se il valore GeoJSON della posizione all'interno del documento è non corretto o non valido, non verrà indicizzato per le query spaziali.If the location GeoJSON value within the document is malformed or invalid, then it will not get indexed for spatial querying. È possibile convalidare valori della posizione utilizzando ST_ISVALID e ST_ISVALIDDETAILED.You can validate location values using ST_ISVALID and ST_ISVALIDDETAILED.

Se la definizione della raccolta include una chiave di partizione, non viene segnalato lo stato di avanzamento della trasformazione dell'indicizzazione.If your collection definition includes a partition key, indexing transformation progress is not reported.

Passaggi successiviNext steps

Ora che si è appreso come iniziare a usare il supporto geospaziale in Azure Cosmos DB, è possibile:Now that you've learnt about how to get started with geospatial support in Azure Cosmos DB, you can: