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?

In questo articolo viene illustrato come utilizzare i dati spaziali con l'API di SQL.This article shows how to work with spatial data with the SQL API. Vedere questo GitHub progetto per esempi di codice.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 agli oggetti in dati geospaziali e terra.In most applications, these correspond to objects on the earth and 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 d'uso comuni spesso comportano query di prossimità, ad esempio, "Trova tutti i negozi quasi il percorso corrente".Common use cases often involve proximity queries, for example, "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 di 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 di alimentari, continua, 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 di longitudine vengono misurati dal primo meridiano e sono compresi tra-180 gradi e gradi 180.0 e i valori di latitudine vengono misurati dall'equatore e sono compresi tra-90.0 gradi e 90.0 gradi.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 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.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":"cosmosdb-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 e LineString, Polygon, GeoJSON specifica inoltre la rappresentazione per la modalità di raggruppamento più posizioni geospaziale, nonché come associare le proprietà arbitrarie geolocation come un funzionalità.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 di dati geospaziali sono rappresentate in molti sistemi di coordinate di riferimento (CR), ciascuno con i relativi frame di riferimento e le unità di misura.Since the shape of the earth is irregular, coordinates of geospatial data are 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":"cosmosdb",
    "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 SQL, è possibile utilizzare il Point e Polygon classi all'interno di Microsoft.Azure.Documents.Spatial dello spazio dei nomi per incorporare le informazioni sul percorso all'interno di oggetti di applicazione.If you're working with the SQL 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 = "cosmosdb", 
        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 ulteriori informazioni sul set completo di funzioni incorporate nel linguaggio SQL, vedere Query Azure Cosmos DB.For more details on the complete set of built-in functions in the SQL language, see 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 ulteriori informazioni sugli indici spaziali, vedere la sezione seguente.For more details on spatial indexing, 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.

Argomenti poligono ST_WITHIN possono contenere solo un anello singolo, vale a dire i poligoni non devono contenere fori in essi contenuti.Polygon arguments in ST_WITHIN can contain only a single ring, that is, 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

Simile al lavoro tipi come non corrispondenti nella query di database Cosmos di Azure, se il valore del percorso specificato nell'argomento non è corretto o non valido, quindi restituisce definito e il documento deve essere ignorato dai risultati della query valutato.Similar to how mismatched types work in Azure Cosmos DB query, if the location value specified in either argument is malformed or invalid, then it evaluates to undefined and the evaluated document to be skipped from the query results. Se la query non restituisce alcun risultato, esecuzione ST_ISVALIDDETAILED per eseguire il debug perché il tipo spaziale è valido.If your query returns no results, run ST_ISVALIDDETAILED To debug why the spatial type is invalid.

DB Cosmos Azure supporta inoltre l'esecuzione di query inversa, ovvero, è possibile indicizzare poligoni o righe nel database di Azure Cosmos, quindi eseguire una query per le aree che contengono un punto specificato.Azure Cosmos DB also supports performing inverse queries, that is, 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 in logistica per identificare, ad esempio, quando un autocarro entra o esce da un'area designata.This pattern is commonly used in logistics to identify for example, 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 SDK .NET di SQL anche provider stub metodi Distance() e Within() per l'utilizzo all'interno di espressioni LINQ.The SQL .NET SDK also providers stub methods Distance() and Within() for use within LINQ expressions. Il provider LINQ SQL converte le chiamate ai metodi per le chiamate di funzione predefinita di SQL equivalente (ST_DISTANCE e ST_WITHIN rispettivamente).The SQL 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 una query LINQ che trova tutti i documenti della raccolta di Azure Cosmos database il cui valore di "location" è all'interno di un raggio di 30 km dell'oggetto specificato virgola utilizzando 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 30 km 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 con ottimizzazione per la scrittura di Azure Cosmos DB è in grado di comprendere in modo nativo rappresentati nello standard GeoJSON i dati spaziali (punti, poligoni e le righe).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. Inoltre quando i dati sulla località sono indicizzati, passano attraverso un processo noto come a mosaico, vale a dire tutte le celle che intersecano una posizione vengono identificate e archiviate come chiavi nell'indice Azure Cosmos DB.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. 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 frammento JSON seguente illustra un criterio di indicizzazione con indicizzazione spaziale attivato, ovvero, qualsiasi punto GeoJSON trovato all'interno dei documenti per le query spaziali di indice.The following JSON snippet shows an indexing policy with spatial indexing enabled, that is, index any GeoJSON point found within documents for spatial querying. Se si desidera modificare i criteri di indicizzazione tramite il portale di Azure, è possibile specificare il codice JSON seguente per criteri di indicizzazione per abilitare l'indicizzazione nella raccolta di spaziali.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

Nolearned che avete sperimentato su come iniziare con supporto geospaziali in Azure Cosmos DB, è possibile:Nolearned you've learnt about how to get started with geospatial support in Azure Cosmos DB, you can: