Come vengono indicizzati i dati da Azure Cosmos DB?How does Azure Cosmos DB index data?

Per impostazione predefinita, tutti i dati di Azure Cosmos DB sono indicizzati.By default, all Azure Cosmos DB data is indexed. Benché per molti clienti sia utile lasciare ad Azure Cosmos DB la gestione automatica di tutti gli aspetti dell'indicizzazione, è possibile specificare criteri di indicizzazione personalizzati per le raccolte durante la creazione in Azure Cosmos DB.Although many customers are happy to let Azure Cosmos DB automatically handle all aspects of indexing, you can specify a custom indexing policy for collections during creation in Azure Cosmos DB. I criteri di indicizzazione in Azure Cosmos DB sono più flessibili e potenti rispetto agli indici secondari disponibili in altre piattaforme di database.Indexing policies in Azure Cosmos DB are more flexible and powerful than secondary indexes that are offered in other database platforms. In Azure Cosmos DB è possibile progettare e personalizzare la forma dell'indice senza sacrificare la flessibilità dello schema.In Azure Cosmos DB, you can design and customize the shape of the index without sacrificing schema flexibility.

Per informazioni sul funzionamento dell'indicizzazione in Azure Cosmos DB, è importante ricordare che la gestione dei criteri di indicizzazione permette di raggiungere un buon equilibrio tra overhead di archiviazione dell'indice, velocità effettiva di scrittura e di query e coerenza delle query.To learn how indexing works in Azure Cosmos DB, it's important to understand that when you manage indexing policy, you can make fine-grained trade-offs between index storage overhead, write and query throughput, and query consistency.

Nel video seguente Andrew Liu, Program Manager di Azure Cosmos DB, illustra le funzionalità di indicizzazione automatica del programma e spiega come ottimizzare e configurare i criteri di indicizzazione nel contenitore di Azure Cosmos DB.In the following video, Azure Cosmos DB Program Manager Andrew Liu demonstrates the Azure Cosmos DB automatic indexing capabilities, and how to tune and configure the indexing policy on your Azure Cosmos DB container.

In questo articolo vengono esaminati i criteri di indicizzazione di Azure Cosmos DB, le modalità di personalizzazione di questi criteri e i compromessi associati.In this article, we take a close look at Azure Cosmos DB indexing policies, at how to customize indexing policy, and associated trade-offs.

Alla fine della lettura, si avranno le risposte alle domande seguenti:After reading this article, you'll be able to answer the following questions:

  • Come è possibile ignorare le proprietà da includere o escludere dall'indicizzazione?How can I override the properties to include or exclude from indexing?
  • Come è possibile configurare l'indice di eventuali aggiornamenti?How can I configure the index for eventual updates?
  • Come si configura l'indicizzazione per eseguire query ORDER BY o di intervallo?How can I configure indexing to perform ORDER BY or range queries?
  • Come è possibile apportare modifiche ai criteri di indicizzazione di una raccolta?How do I make changes to a collection’s indexing policy?
  • Come confrontare archiviazione e prestazioni dei diversi criteri di indicizzazione?How do I compare storage and performance of different indexing policies?

Personalizzare i criteri di indicizzazione di una raccolta Customize the indexing policy of a collection

È possibile personalizzare alcuni aspetti per ottenere il compromesso desiderato tra archiviazione, prestazioni di scrittura e query e coerenza delle query sostituendo i criteri di indicizzazione predefiniti in una raccolta di Azure Cosmos DB.You can customize the trade-offs between storage, write and query performance, and query consistency by overriding the default indexing policy on an Azure Cosmos DB collection. È possibile configurare gli aspetti seguenti:You can configure the following aspects:

  • Includere o escludere documenti e percorsi nell'indice.Include or exclude documents and paths to and from the index. È possibile escludere o includere documenti specifici nell'indice quando si inseriscono o sostituiscono i documenti nella raccolta.You can exclude or include specific documents in the index when you insert or replace the documents in the collection. È anche possibile includere o escludere proprietà JSON specifiche, denominate anche percorsi, per l'indicizzazione tra documenti inclusi in un indice.You can also include or exclude specific JSON properties, also called paths, to be indexed across documents that are included in an index. I percorsi includono caratteri jolly.Paths include wildcard patterns.
  • Configurare diversi tipi di indice.Configure various index types. Per ogni percorso incluso è possibile specificare il tipo di indice richiesto dal percorso per una raccolta.For each included path, you can specify the type of index the path requires for a collection. È possibile specificare il tipo di indice in base ai dati del percorso, al carico di lavoro delle query previsto e alla "precisione" numerica/di stringa.You can specify the type of index based on the path's data, the expected query workload, and numeric/string “precision.”
  • Configurare le modalità di aggiornamento dell'indice.Configure index update modes. Azure Cosmos DB supporta tre modalità di indicizzazione: coerente, differita e nessuna indicizzazione.Azure Cosmos DB supports three indexing modes: Consistent, Lazy, and None. È possibile configurare le modalità di indicizzazione tramite i criteri di indicizzazione in una raccolta di Azure Cosmos DB.You can configure the indexing modes via the indexing policy on an Azure Cosmos DB collection.

Il frammento di codice Microsoft .NET seguente mostra come impostare criteri di indicizzazione personalizzati durante la creazione di una raccolta.The following Microsoft .NET code snippet shows how to set a custom indexing policy when you create a collection. In questo esempio i criteri vengono impostati con un indice di intervallo per stringhe e numeri con la precisione massima.In this example, we set the policy with a Range index for strings and numbers at the maximum precision. È possibile usare questi criteri per eseguire query ORDER BY su stringhe.You can use this policy to execute ORDER BY queries against strings.

DocumentCollection collection = new DocumentCollection { Id = "myCollection" };

collection.IndexingPolicy = new IndexingPolicy(new RangeIndex(DataType.String) { Precision = -1 });
collection.IndexingPolicy.IndexingMode = IndexingMode.Consistent;

await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("db"), collection);   

Nota

Lo schema JSON per i criteri di indicizzazione è stato modificato con la nuova API REST versione 2015-06-03.The JSON schema for indexing policy changed with the release of REST API version 2015-06-03. Con questa versione, lo schema JSON per i criteri di indicizzazione supporta indici di intervallo di stringhe.With that release, the JSON schema for indexing policy supports Range indexes against strings. .NET SDK 1.2.0 e Java, Python e Node.js SDK 1.1.0 supportano il nuovo schema di criteri..NET SDK 1.2.0 and Java, Python, and Node.js SDKs 1.1.0 support the new policy schema. Le versioni precedenti dell'SDK usano l'API REST versione 2015-04-08.Earlier versions of the SDK use the REST API version 2015-04-08. Queste versioni supportano lo schema precedente per i criteri di indicizzazione.They support the earlier schema for indexing policy.

Per impostazione predefinita, Azure Cosmos DB indicizza tutte le proprietà stringa nei documenti in modo coerente con un indice hash.By default, Azure Cosmos DB indexes all string properties within documents consistently with a Hash index. Indicizza tutte le proprietà numeriche nei documenti in modo coerente con un indice di intervallo.It indexes all numeric properties within documents consistently with a Range index.

Personalizzare i criteri di indicizzazione nel portaleCustomize the indexing policy in the portal

È possibile modificare i criteri di indicizzazione di una raccolta nel portale di Azure:You can change the indexing policy of a collection in the Azure portal:

  1. Nel portale passare all'account Azure Cosmos DB e quindi selezionare la raccolta.In the portal, go to your Azure Cosmos DB account, and then select your collection.
  2. Nel menu di spostamento a sinistra scegliere Impostazioni e quindi Criteri di indicizzazione.In the left navigation menu, select Settings, and then select Indexing Policy.
  3. In Criteri di indicizzazione modificare i criteri di indicizzazione e quindi selezionare OK.Under Indexing Policy, change your indexing policy, and then select OK.

Modalità di indicizzazione del database Database indexing modes

Azure Cosmos DB supporta tre modalità di indicizzazione che è possibile configurare tramite i criteri di indicizzazione in una raccolta di Azure Cosmos DB: coerente, differita e nessuna indicizzazione.Azure Cosmos DB supports three indexing modes that you can configure via the indexing policy on an Azure Cosmos DB collection: Consistent, Lazy, and None.

Coerente: se i criteri di una raccolta di Azure Cosmos DB sono coerenti, le query su una determinata raccolta di Azure Cosmos DB seguono lo stesso livello di coerenza specificato per le letture punto (assoluta, con obsolescenza associata, di sessione o finale).Consistent: If an Azure Cosmos DB collection’s policy is Consistent, the queries on a specific Azure Cosmos DB collection follow the same consistency level as specified for the point-reads (strong, bounded-staleness, session, or eventual). L'indice viene aggiornato in modo sincrono come parte dell'aggiornamento del documento, ad esempio come parte di un'operazione di inserimento, sostituzione, aggiornamento ed eliminazione di un documento in una raccolta di Azure Cosmos DB.The index is updated synchronously as part of the document update (insert, replace, update, and delete a document in an Azure Cosmos DB collection).

L'indicizzazione coerente supporta query coerenti al costo di una possibile riduzione della velocità effettiva di scrittura.Consistent indexing supports consistent queries at the cost of a possible reduction in write throughput. Questa riduzione è una funzione dei percorsi univoci che devono essere indicizzati e del "livello di coerenza".This reduction is a function of the unique paths that need to be indexed and the “consistency level.” La modalità di indicizzazione coerente è progettata per carichi di lavoro "scrivi rapidamente, esegui query immediatamente".Consistent indexing mode is designed for “write quickly, query immediately” workloads.

Differita: l'indice viene aggiornato in modo asincrono quando una raccolta di Azure Cosmos DB è inattiva, ovvero quando la capacità di velocità effettiva della raccolta non viene usata completamente per gestire le richieste utente.Lazy: The index is updated asynchronously when an Azure Cosmos DB collection is quiescent, that is, when the collection’s throughput capacity is not fully utilized to serve user requests. La modalità di indicizzazione differita può essere adatta per carichi di lavoro con inserimento immediato ed esecuzione di query successiva che richiedono l'inserimento del documento.The Lazy indexing mode might be suitable for "ingest now, query later" workloads that require document ingestion. Si potrebbero ottenere risultati incoerenti perché i dati vengono inseriti e indicizzati lentamente.Note that you might get inconsistent results because data is ingested and indexed slowly. Questo significa che le query COUNT o i risultati di query specifici possono non essere coerenti o ripetibili in determinati momenti.This means that your COUNT queries or specific query results might not be consistent or repeatable at any given time.

L'indice è in genere in modalità di recupero con dati inseriti.The index is generally in catch-up mode with ingested data. Con l'indicizzazione differita, le modifiche di durata (TTL) comportano l'eliminazione e la nuova creazione dell'indice.With Lazy indexing, time to live (TTL) changes result in the index being dropped and re-created. Questo comportamento rende incoerenti la query COUNT e i risultati delle query per un periodo di tempo.This makes the COUNT and query results inconsistent for a period of time. Per questo motivo, la maggior parte degli account Azure Cosmos DB deve usare la modalità di indicizzazione coerente.Because of this, most Azure Cosmos DB accounts should use the Consistent indexing mode.

Nessuna indicizzazione: a una raccolta con modalità nessuna indicizzazione non è associato alcun indice.None: A collection that has a None index mode has no index associated with it. Questa modalità viene usata in genere se Azure Cosmos DB funge da archivio di coppie chiave/valore e l'accesso ai documenti avviene solo tramite il rispettivo ID proprietà.This is commonly used if Azure Cosmos DB is used as a key-value storage, and documents are accessed only by their ID property.

Nota

La configurazione dei criteri di indicizzazione con nessuna indicizzazione ha l'effetto collaterale di eliminare tutti gli indici esistenti.Configuring the indexing policy with as None has the side effect of dropping any existing index. Usare questa modalità se i modelli di accesso richiedono solo un ID o un collegamento automatico.Use this if your access patterns require only ID or self-link.

Nella tabella seguente viene illustrata la coerenza per le query basata sulla modalità di indicizzazione (Coerente e Differita) configurata per la raccolta e il livello di coerenza specificato per la richiesta di query.The following table shows the consistency for queries based on the indexing mode (Consistent and Lazy) configured for the collection and the consistency level specified for the query request. Questo si applica alle query eseguite tramite qualsiasi interfaccia: API REST, SDK o all'interno di stored procedure e trigger.This applies to queries made by using any interface: REST API, SDKs, or from within stored procedures and triggers.

ConsistencyConsistency Modalità di indicizzazione: coerenteIndexing mode: Consistent Modalità di indicizzazione: differitaIndexing mode: Lazy
AssolutaStrong AssolutaStrong FinaleEventual
Obsolescenza associataBounded staleness Obsolescenza associataBounded staleness FinaleEventual
sessioneSession sessioneSession FinaleEventual
FinaleEventual FinaleEventual FinaleEventual

Azure Cosmos DB restituisce un errore per le query eseguite su raccolte in modalità nessuna indicizzazione.Azure Cosmos DB returns an error for queries made on collections that have a None indexing mode. Le query possono comunque essere eseguite come analisi tramite l'intestazione x-ms-documentdb-enable-scan esplicita nell'API REST o l'opzione di richiesta EnableScanInQuery usando .NET SDK.Queries can still be executed as scans via the explicit x-ms-documentdb-enable-scan header in the REST API or the EnableScanInQuery request option by using the .NET SDK. Alcune funzionalità di query, come ORDER BY, non sono supportate come analisi con EnableScanInQuery.Some query features, like ORDER BY, are not supported as scans with EnableScanInQuery.

La tabella seguente indica la coerenza per le query in base alla modalità di indicizzazione (coerente, differita e nessuna indicizzazione) quando è specificato EnableScanInQuery.The following table shows the consistency for queries based on the indexing mode (Consistent, Lazy, and None) when EnableScanInQuery is specified.

ConsistencyConsistency Modalità di indicizzazione: coerenteIndexing Mode: Consistent Modalità di indicizzazione: differitaIndexing Mode: Lazy Modalità di indicizzazione: nessunaIndexing Mode: None
AssolutaStrong AssolutaStrong FinaleEventual AssolutaStrong
Obsolescenza associataBounded staleness Obsolescenza associataBounded staleness FinaleEventual Obsolescenza associataBounded staleness
sessioneSession sessioneSession FinaleEventual sessioneSession
FinaleEventual FinaleEventual FinaleEventual FinaleEventual

L'esempio di codice seguente mostra come creare una raccolta di Azure Cosmos DB usando .NET SDK con indicizzazione coerente in tutti gli inserimenti di documenti.The following code sample show how create an Azure Cosmos DB collection by using the .NET SDK with Consistent indexing on all document insertions.

 // Default collection creates a Hash index for all string fields and a Range index for all numeric    
 // fields. Hash indexes are compact and offer efficient performance for equality queries.

 var collection = new DocumentCollection { Id ="defaultCollection" };

 collection.IndexingPolicy.IndexingMode = IndexingMode.Consistent;

 collection = await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("mydb"), collection);

Percorsi di indiceIndex paths

Azure Cosmos DB modella i documenti JSON e l'indice come alberi.Azure Cosmos DB models JSON documents and the index as trees. È possibile usare i criteri per i percorsi all'interno dell'albero.You can tune to policies for paths within the tree. All'interno dei documenti è possibile scegliere i percorsi da includere o escludere nell'indicizzazione.Within documents, you can choose the paths to include or exclude from indexing. Questo permette di migliorare le prestazioni di scrittura e ridurre lo spazio di archiviazione dell'indice per gli scenari in cui i modelli di query sono già noti.This can offer improved write performance and lower index storage for scenarios in which the query patterns are known beforehand.

I percorsi di indice iniziano con la radice (/) e terminano in genere con il carattere jolly ?,Index paths start with the root (/) and typically end with the ? come operatore.wildcard operator. Questo operatore indica che per il prefisso esistono più valori possibili.This denotes that there are multiple possible values for the prefix. Ad esempio, per usare SELECT * FROM Families F WHERE F.familyName = "Andersen", è necessario includere un percorso di indice per /"familyName"/?For example, to serve SELECT * FROM Families F WHERE F.familyName = "Andersen", you must include an index path for /familyName/? nei criteri di indicizzazione della raccolta.in the collection’s index policy.

I percorsi di indice possono anche usare il carattere jolly * per specificare un comportamento ricorsivo al di sotto del prefisso.Index paths can also use the * wildcard operator to specify the behavior for paths recursively under the prefix. È ad esempio possibile usare /payload/* per escludere dall'indicizzazione qualsiasi elemento al di sotto della proprietà payload.For example, /payload/* can be used to exclude everything under the payload property from indexing.

Di seguito sono indicati i modelli comuni per la definizione di percorsi di indice:Here are the common patterns for specifying index paths:

pathPath Descrizione/Caso d'usoDescription/use case
/ Percorso predefinito per la raccolta.Default path for collection. Ricorsivo e applicabile all'intero albero del documento.Recursive and applies to the entire document tree.
/prop/?/prop/? Percorso di indice necessario per gestire query come la seguente (rispettivamente con tipi hash e di intervallo):Index path required to serve queries like the following (with Hash or Range types, respectively):

SELECT FROM collection c WHERE c.prop = "value"SELECT FROM collection c WHERE c.prop = "value"

SELECT FROM collection c WHERE c.prop > 5SELECT FROM collection c WHERE c.prop > 5

SELECT FROM collection c ORDER BY c.propSELECT FROM collection c ORDER BY c.prop
/prop/*/prop/* Percorso di indice per tutti i percorsi al di sotto dell'etichetta specificata.Index path for all paths under the specified label. Funziona con le query seguentiWorks with the following queries

SELECT FROM collection c WHERE c.prop = "value"SELECT FROM collection c WHERE c.prop = "value"

SELECT FROM collection c WHERE c.prop.subprop > 5SELECT FROM collection c WHERE c.prop.subprop > 5

SELECT FROM collection c WHERE c.prop.subprop.nextprop = "value"SELECT FROM collection c WHERE c.prop.subprop.nextprop = "value"

SELECT FROM collection c ORDER BY c.propSELECT FROM collection c ORDER BY c.prop
/props/[]/?/props/[]/? Percorso di indice che consente di servire iterazioni e query JOIN su matrici di valori scalari, come ["a", "b", "c"]:Index path required to serve iteration and JOIN queries against arrays of scalars like ["a", "b", "c"]:

SELECT tag FROM tag IN collection.props WHERE tag = "value"SELECT tag FROM tag IN collection.props WHERE tag = "value"

SELECT tag FROM collection c JOIN tag IN c.props WHERE tag > 5SELECT tag FROM collection c JOIN tag IN c.props WHERE tag > 5
/props/[]/subprop/?/props/[]/subprop/? Percorso di indice che consente di servire iterazioni e query JOIN su matrici di oggetti, come [{subprop: "a"}, {subprop: "b"}]:Index path required to serve iteration and JOIN queries against arrays of objects like [{subprop: "a"}, {subprop: "b"}]:

SELECT tag FROM tag IN collection.props WHERE tag.subprop = "value"SELECT tag FROM tag IN collection.props WHERE tag.subprop = "value"

SELECT tag FROM collection c JOIN tag IN c.props WHERE tag.subprop = "value"SELECT tag FROM collection c JOIN tag IN c.props WHERE tag.subprop = "value"
/prop/subprop/?/prop/subprop/? Percorso di indice necessario per gestire le query (rispettivamente con tipi hash e di intervallo):Index path required to serve queries (with Hash or Range types, respectively):

SELECT FROM collection c WHERE c.prop.subprop = "value"SELECT FROM collection c WHERE c.prop.subprop = "value"

SELECT FROM collection c WHERE c.prop.subprop > 5SELECT FROM collection c WHERE c.prop.subprop > 5

Nota

Quando si impostano percorsi di indice personalizzati, è necessario specificare la regola di indicizzazione predefinita per l'intero albero del documento, indicato dal percorso speciale "/*".When you set custom index paths, you are required to specify the default indexing rule for the entire document tree, which is denoted by the special path "/*".

L'esempio seguente configura un percorso specifico con indice di intervallo e un valore di precisione personalizzato pari a 20 byte:The following example configures a specific path with Range index and a custom precision value of 20 bytes:

var collection = new DocumentCollection { Id = "rangeSinglePathCollection" };    

collection.IndexingPolicy.IncludedPaths.Add(
    new IncludedPath { 
        Path = "/Title/?", 
        Indexes = new Collection<Index> { 
            new RangeIndex(DataType.String) { Precision = 20 } } 
        });

// Default for everything else
collection.IndexingPolicy.IncludedPaths.Add(
    new IncludedPath { 
        Path = "/*" ,
        Indexes = new Collection<Index> {
            new HashIndex(DataType.String) { Precision = 3 }, 
            new RangeIndex(DataType.Number) { Precision = -1 } 
        }
    });

collection = await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("db"), pathRange);

Tipi di dati, tipologie e valori di precisione degli indiciIndex data types, kinds, and precisions

Per configurare i criteri di indicizzazione per un percorso, sono disponibili più opzioni.You have multiple options when you configure the indexing policy for a path. È possibile specificare una o più definizioni di indicizzazione per ogni percorso:You can specify one or more indexing definitions for every path:

  • Tipo di dati: stringa, numero, Point, Polygon o LineString (può contenere solo una voce per tipo di dati per percorso).Data type: String, Number, Point, Polygon, or LineString (can contain only one entry per data type per path).
  • Tipo di indice: hash (query di uguaglianza), intervallo (query di uguaglianza, di intervallo o ORDER BY) o spaziale (query spaziali).Index kind: Hash (equality queries), Range (equality, range or ORDER BY queries), or Spatial (spatial queries) .
  • Precisione: per un indice hash, varia da 1 a 8 per stringhe e numeri.Precision: For a Hash index, this varies from 1 to 8 for both strings and numbers. Il valore predefinito è 3.The default is 3. Per un indice di intervallo, questo valore può essere -1 (precisione massima).For a Range index, this value can be -1 (maximum precision). Può variare tra 1 e 100 (precisione massima) per i valori stringa o numerici.It can vary from between 1 and 100 (maximum precision) for string or number values.

Tipologia di indiceIndex kind

Azure Cosmos DB supporta i tipi di indice hash e di intervallo per ogni percorso che può essere configurato per tipi di dati stringa o numerici o per entrambi.Azure Cosmos DB supports Hash index and Range index kinds for every path that can be configured for String or Number data types, or both.

  • Hash supporta query di uguaglianza efficienti e query JOIN.Hash supports efficient equality and JOIN queries. Nella maggior parte dei casi, gli indici hash non richiedono una precisione superiore al valore predefinito di 3 byte.For most use cases, Hash indexes don't need a higher precision than the default value of 3 bytes. I dati possono essere di tipo stringa o numerico.The data type can be String or Number.
  • Intervallo supporta query di uguaglianza efficienti, query di intervallo (con >, <, >=, <=, !=) e query ORDER BY.Range supports efficient equality queries, range queries (using >, <, >=, <=, !=), and ORDER BY queries. Per impostazione predefinita, anche le query ORDER BY richiedono la precisione di indice massima (-1).ORDER By queries by default also require maximum index precision (-1). I dati possono essere di tipo stringa o numerico.The data type can be String or Number.

Azure Cosmos DB supporta anche il tipo di indice spaziale per ogni percorso che può essere specificato per il tipo di dati Point, Polygon o LineString.Azure Cosmos DB also supports the Spatial index kind for every path that can be specified for the Point, Polygon, or LineString data types. Il valore nel percorso specificato deve essere un frammento GeoJSON valido come {"type": "Point", "coordinates": [0.0, 10.0]}.The value at the specified path must be a valid GeoJSON fragment like {"type": "Point", "coordinates": [0.0, 10.0]}.

  • Spatial supporta query spaziali (within e distance) efficienti.Spatial supports efficient spatial (within and distance) queries. Il tipo di dati può essere Point, Polygon o LineString.The data type can be Point, Polygon, or LineString.

Nota

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

Di seguito sono elencati i tipi di indice supportati e gli esempi di query che possono essere utilizzati per rispondere:Here are the supported index kinds and examples of queries that they can be used to serve:

Tipologia di indiceIndex kind Descrizione/Caso d'usoDescription/use case
HashHash Hash over /prop/?Hash over /prop/? (or /) può essere usato per servire in modo efficiente le query seguenti:(or /) can be used to serve the following queries efficiently:

SELECT FROM collection c WHERE c.prop = "value"SELECT FROM collection c WHERE c.prop = "value"

Hash over /props/[]/?Hash over /props/[]/? (or / or /props/) può essere usato per servire in modo efficiente le query seguenti:(or / or /props/) can be used to serve the following queries efficiently:

SELECT tag FROM collection c JOIN tag IN c.props WHERE tag = 5SELECT tag FROM collection c JOIN tag IN c.props WHERE tag = 5
RangeRange Range over /prop/?Range over /prop/? (or /) può essere usato per servire in modo efficiente le query seguenti:(or /) can be used to serve the following queries efficiently:

SELECT FROM collection c WHERE c.prop = "value"SELECT FROM collection c WHERE c.prop = "value"

SELECT FROM collection c WHERE c.prop > 5SELECT FROM collection c WHERE c.prop > 5

SELECT FROM collection c ORDER BY c.propSELECT FROM collection c ORDER BY c.prop
SpatialSpatial Range over /prop/?Range over /prop/? (or /) può essere usato per servire in modo efficiente le query seguenti:(or /) can be used to serve the following queries efficiently:

SELECT FROM collection cSELECT FROM collection c

WHERE ST_DISTANCE(c.prop, {"type": "Point", "coordinates": [0.0, 10.0]}) < 40WHERE ST_DISTANCE(c.prop, {"type": "Point", "coordinates": [0.0, 10.0]}) < 40

SELECT FROM collection c WHERE ST_WITHIN(c.prop, {"type": "Polygon", ... }) --con indicizzazione su punti abilitataSELECT FROM collection c WHERE ST_WITHIN(c.prop, {"type": "Polygon", ... }) --with indexing on points enabled

SELECT FROM collection c WHERE ST_WITHIN({"type": "Point", ... }, c.prop) --con indicizzazione su poligoni abilitataSELECT FROM collection c WHERE ST_WITHIN({"type": "Point", ... }, c.prop) --with indexing on polygons enabled

Per impostazione predefinita, viene restituito un errore per le query con operatori di intervallo, ad esempio >=, se non esiste alcun indice di intervallo (di qualsiasi precisione) per segnalare che potrebbe essere necessaria un'analisi per gestire la query.By default, an error is returned for queries with range operators such as >= if there is no Range index (of any precision) to signal that a scan might be necessary to serve the query. Le query di intervallo possono essere eseguite senza un indice di intervallo usando l'intestazione x-ms-documentdb-enable-scan nell'API REST o l'opzione di richiesta EnableScanInQuery usando .NET SDK.Range queries can be performed without a Range index by using the x-ms-documentdb-enable-scan header in the REST API or the EnableScanInQuery request option by using the .NET SDK. Se la query include altri filtri in base ai quali Azure Cosmos DB può usare l'indice per filtrare, non viene restituito alcun errore.If there are any other filters in the query that Azure Cosmos DB can use the index to filter against, no error is returned.

Le stesse regole sono valide per le query spaziali.The same rules apply for spatial queries. Per impostazione predefinita, viene restituito un errore per le query spaziali se non esiste alcun indice spaziale e non sono presenti altri filtri che possono essere serviti dall'indice.By default, an error is returned for spatial queries if there is no spatial index, and there are no other filters that can be served from the index. Queste query possono essere eseguite come analisi usando x-ms-documentdb-enable-scan o EnableScanInQuery.They can be performed as a scan by using x-ms-documentdb-enable-scan or EnableScanInQuery.

Precisione indiceIndex precision

È possibile usare la precisione dell'indice per ottenere un buon compromesso tra l'overhead di archiviazione dell'indice e le prestazioni delle query.You can use index precision to make trade-offs between index storage overhead and query performance. Per i numeri, è consigliabile usare la configurazione di precisione predefinita -1 (precisione massima).For numbers, we recommend using the default precision configuration of -1 (maximum). Poiché i numeri sono a 8 byte in JSON, questo valore equivale a una configurazione di 8 byte.Because numbers are 8 bytes in JSON, this is equivalent to a configuration of 8 bytes. Selezionando un valore inferiore per la precisione, ad esempio da 1 a 7, i valori compresi in alcuni intervalli vengono associati alla stessa voce di indice.Choosing a lower value for precision, such as 1 through 7, means that values within some ranges map to the same index entry. Per questo motivo, viene ridotto lo spazio di archiviazione dell'indice, ma l'esecuzione delle query potrebbe dover elaborare più documenti.Therefore, you reduce index storage space, but query execution might have to process more documents. Di conseguenza, viene utilizzata una velocità effettiva maggiore nelle unità richiesta.Consequently, it consumes more throughput in request units.

La configurazione di precisione dell'indice ha un'applicazione più pratica con gli intervalli di stringhe.Index precision configuration has more practical application with string ranges. Poiché le stringhe possono avere qualsiasi lunghezza arbitraria, la scelta della precisione dell'indice può influire sulle prestazioni delle query di intervallo di stringhe.Because strings can be any arbitrary length, the choice of the index precision might affect the performance of string range queries. Può anche influire sulla quantità di spazio di archiviazione dell'indice necessaria.It also might affect the amount of index storage space that's required. Gli indici di intervallo di stringhe possono essere configurati con valori compresi tra 1 e 100 o pari a -1 (precisione massima).String Range indexes can be configured with 1 through 100 or -1 (maximum). Se si vuole eseguire query ORDER BY su proprietà stringa, è necessario specificare una precisione pari a -1 per i percorsi corrispondenti.If you want to perform ORDER BY queries against string properties, you must specify a precision of -1 for the corresponding paths.

Gli indici spaziali usano sempre la precisione dell'indice predefinita per tutti i tipi (Point, LineString e Polygon).Spatial indexes always use the default index precision for all types (Point, LineString, and Polygon). Non è possibile eseguire l'override della precisione dell'indice predefinita per indici spaziali.The default index precision for spatial indexes can't be overridden.

L'esempio seguente mostra come aumentare la precisione per gli indici di intervallo in una raccolta tramite .NET SDK.The following example shows how to increase the precision for Range indexes in a collection by using the .NET SDK.

Creare una raccolta con una precisione di indice personalizzataCreate a collection with a custom index precision

var rangeDefault = new DocumentCollection { Id = "rangeCollection" };

// Override the default policy for strings to Range indexing and "max" (-1) precision
rangeDefault.IndexingPolicy = new IndexingPolicy(new RangeIndex(DataType.String) { Precision = -1 });

await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("db"), rangeDefault);   

Nota

Azure Cosmos DB restituisce un errore quando una query usa ORDER BY ma non ha un indice di intervallo sul percorso sottoposto a query con la precisione massima.Azure Cosmos DB returns an error when a query uses ORDER BY but doesn't have a Range index against the queried path with the maximum precision.

Analogamente, è possibile escludere completamente i percorsi dall'indicizzazione.Similarly, you can completely exclude paths from indexing. L'esempio seguente mostra come escludere un'intera sezione dei documenti (sottoalbero) dall'indicizzazione usando il carattere jolly * come operatore.The next example shows how to exclude an entire section of the documents (a subtree) from indexing by using the * wildcard operator.

var collection = new DocumentCollection { Id = "excludedPathCollection" };
collection.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
collection.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/nonIndexedContent/*" });

collection = await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("db"), excluded);

Consenso o rifiuto esplicito dell'indicizzazioneOpt in and opt out of indexing

È possibile specificare se la raccolta deve indicizzare automaticamente tutti i documenti.You can choose whether you want the collection to automatically index all documents. Per impostazione predefinita, tutti i documenti vengono indicizzati automaticamente, ma è possibile disattivare l'indicizzazione automatica.By default, all documents are automatically indexed, but you can turn off automatic indexing. Quando l'indicizzazione è disattivata, i documenti sono accessibili solo tramite i rispettivi collegamenti automatici o tramite query usando l'ID documento.When indexing is turned off, documents can be accessed only through their self-links or by queries by using the document ID.

Con l'indicizzazione automatica disattivata, è comunque possibile aggiungere in modo selettivo solo documenti specifici all'indice.With automatic indexing turned off, you can still selectively add only specific documents to the index. Al contrario, è possibile lasciare attiva l'indicizzazione automatica e scegliere di escludere selettivamente documenti specifici.Conversely, you can leave automatic indexing on and selectively choose to exclude specific documents. Le configurazioni di attivazione o disattivazione dell'indicizzazione sono utili in presenza di un solo subset di documenti su cui eseguire query.Indexing on/off configurations are useful when you have only a subset of documents that needs to be queried.

L'esempio seguente mostra come includere in modo esplicito un documento usando .NET SDK per l'API SQL e la proprietà RequestOptions.IndexingDirective.The following sample shows how to include a document explicitly by using the SQL API .NET SDK and the RequestOptions.IndexingDirective property.

// If you want to override the default collection behavior to either
// exclude (or include) a document in indexing,
// use the RequestOptions.IndexingDirective property.
client.CreateDocumentAsync(UriFactory.CreateDocumentCollectionUri("db", "coll"),
    new { id = "AndersenFamily", isRegistered = true },
    new RequestOptions { IndexingDirective = IndexingDirective.Include });

Modificare i criteri di indicizzazione di una raccoltaModify the indexing policy of a collection

In Azure Cosmos DB è possibile apportare modifiche in tempo reale ai criteri di indicizzazione di una raccolta.In Azure Cosmos DB, you can make changes to the indexing policy of a collection on the fly. Una modifica dei criteri di indicizzazione in una raccolta di Azure Cosmos DB può comportare una modifica nella forma dell'indice.A change in indexing policy on an Azure Cosmos DB collection can lead to a change in the shape of the index. La modifica influisce sui percorsi che possono essere indicizzati, sulla loro precisione e sul modello di coerenza dell'indice stesso.The change affects the paths that can be indexed, their precision, and the consistency model of the index itself. Una modifica nei criteri di indicizzazione richiede una trasformazione dell'indice precedente in uno nuovo.A change in indexing policy effectively requires a transformation of the old index into a new index.

Trasformazioni degli indici onlineOnline index transformations

Funzionamento dell'indicizzazione - Trasformazioni di indici online di Azure Cosmos DB

Le trasformazioni degli indici vengono eseguite online.Index transformations are made online. Questo significa che i documenti indicizzati in base ai vecchi criteri vengono trasformati in modo efficiente in base ai nuovi criteri senza modificare la disponibilità di scrittura o la velocità effettiva di provisioning della raccolta.This means that the documents indexed per the old policy are efficiently transformed per the new policy without affecting the write availability or the provisioned throughput of the collection. La coerenza delle operazioni di lettura e scrittura eseguite tramite l'API REST, gli SDK o all'interno di stored procedure e trigger non cambia durante la trasformazione dell'indice.The consistency of read and write operations made by using the REST API, SDKs, or from within stored procedures and triggers is not affected during index transformation. Quando si apporta una modifica ai criteri di indicizzazione, non si verificano cali di prestazioni o tempo di inattività per le app.There's no performance degradation or downtime to your apps when you make an indexing policy change.

Tuttavia, durante la fase di trasformazione dell’indice, le query sono alla fine coerenti indipendentemente dalla configurazione della modalità indicizzazione (coerente o differita).However, during the time that index transformation is progress, queries are eventually consistent regardless of the indexing mode configuration (Consistent or Lazy). Questo si applica alle query eseguite usando qualsiasi interfaccia: SDK, API REST o all'interno di stored procedure e trigger.This also applies to queries from all interfaces: REST API, SDKs, and from within stored procedures and triggers. Come per l'indicizzazione differita, la trasformazione dell'indice viene eseguita in modo asincrono in background nelle repliche usando le risorse di riserva disponibili per una replica specifica.Just like with Lazy indexing, index transformation is performed asynchronously in the background on the replicas by using the spare resources that are available for a specific replica.

Le trasformazioni degli indici vengono anche eseguite sul posto.Index transformations are also made in place. Azure Cosmos DB non conserva due copie dell'indice e scambia l'indice precedente con quello nuovo.Azure Cosmos DB doesn't maintain two copies of the index and swap out the old index with the new one. Questo significa che non è necessario né viene usato ulteriore spazio su disco nelle raccolte durante la trasformazione dell'indice.This means that no additional disk space is required or consumed in your collections while index transformations occur.

Quando si modificano i criteri di indicizzazione, vengono applicate modifiche per passare dall'indice precedente a quello nuovo prevalentemente in base alle configurazioni delle modalità di indicizzazione.When you change indexing policy, changes are applied to move from the old index to the new primarily based on the indexing mode configurations. Le configurazioni delle modalità di indicizzazione svolgono un ruolo più importante rispetto ad altri valori come i percorsi inclusi/esclusi, i tipi di indice e i valori di precisione.Indexing mode configurations play a larger role than other values like included/excluded paths, index kinds, and precisions.

Se i criteri precedenti e quelli nuovi usano entrambi l'indicizzazione coerente, Azure Cosmos DB esegue una trasformazione dell'indice online.If your old and new policies both use Consistent indexing, Azure Cosmos DB performs an online index transformation. Non è possibile applicare un'altra modifica ai criteri di indicizzazione in modalità di indicizzazione coerente mentre è in corso la trasformazione.You can't apply another indexing policy change that has Consistent indexing mode while the transformation is in progress. È tuttavia possibile passare all'indicizzazione differita o a nessuna indicizzazione mentre è in corso una trasformazione:However, you can move to Lazy or None indexing mode while a transformation is in progress:

  • Quando si passa alla modalità differita, la modifica ai criteri di indicizzazione ha effetto immediatamente.When you move to Lazy, the index policy change is effective immediately. Azure Cosmos DB inizia a ricreare l'indice in modo asincrono.Azure Cosmos DB starts re-creating the index asynchronously.
  • Quando si passa alla modalità nessuna indicizzazione, l'indice viene eliminato immediatamente.When you move to None, the index is dropped immediately. Il passaggio a nessuna indicizzazione è utile quando si vuole annullare una trasformazione in corso e iniziare da capo con criteri di indicizzazione diversi.Moving to None is useful when you want to cancel an in-progress transformation, and start fresh with a different indexing policy.

Il frammento di codice seguente mostra come modificare i criteri di indicizzazione di una raccolta per passare dalla modalità di indicizzazione coerente a quella differita.The following code snippet shows how to modify a collection's indexing policy from Consistent indexing mode to Lazy indexing mode. Se si usa .NET SDK, è possibile avviare una modifica dei criteri di indicizzazione usando il nuovo metodo ReplaceDocumentCollectionAsync.If you’re using the .NET SDK, you can kick off an indexing policy change by using the new ReplaceDocumentCollectionAsync method.

Modificare i criteri di indicizzazione per passare dalla modalità di indicizzazione coerente a quella di indicizzazione differitaModify indexing policy from Consistent to Lazy

// Switch to Lazy indexing mode.
Console.WriteLine("Changing from Default to Lazy IndexingMode.");

collection.IndexingPolicy.IndexingMode = IndexingMode.Lazy;

await client.ReplaceDocumentCollectionAsync(collection);

Tenere traccia dell'avanzamento di una trasformazione dell'indiceTrack progress of index transformation

È possibile tenere traccia della percentuale di avanzamento della trasformazione dell'indice in indice coerente usando la proprietà di risposta IndexTransformationProgress da una chiamata ReadDocumentCollectionAsync.You can track the percentage progress of the index transformation to a Consistent index by using the IndexTransformationProgress response property from a ReadDocumentCollectionAsync call. Altri SDK e l'API REST supportano metodi e proprietà equivalenti per apportare modifiche ai criteri di indicizzazione.Other SDKs, and the REST API, support equivalent properties and methods for making indexing policy changes. È possibile controllare lo stato di avanzamento di una trasformazione dell'indice in indice coerente chiamando ReadDocumentCollectionAsync:You can check the progress of an index transformation to a Consistent index by calling ReadDocumentCollectionAsync:

long smallWaitTimeMilliseconds = 1000;
long progress = 0;

while (progress < 100)
{
    ResourceResponse<DocumentCollection> collectionReadResponse = await client.ReadDocumentCollectionAsync(
        UriFactory.CreateDocumentCollectionUri("db", "coll"));

    progress = collectionReadResponse.IndexTransformationProgress;

    await Task.Delay(TimeSpan.FromMilliseconds(smallWaitTimeMilliseconds));
}

Nota

  • La proprietà IndexTransformationProgress è applicabile solo quando l'indice viene trasformato in indice coerente.The IndexTransformationProgress property is applicable only when transforming to a Consistent index. Usare la proprietà ResourceResponse.LazyIndexingProgress per tenere traccia delle trasformazioni in indice differito.Use the ResourceResponse.LazyIndexingProgress property for tracking transformations to a Lazy index.
  • Le proprietà IndexTransformationProgress e LazyIndexingProgress vengono popolate solo per una raccolta non partizionata, ovvero una raccolta creata senza una chiave di partizione.The IndexTransformationProgress and the LazyIndexingProgress properties are populated only for a non-partitioned collection, that is, a collection that is created without a partition key.

È possibile eliminare l'indice per una raccolta passando alla modalità di indicizzazione nessuna.You can drop the index for a collection by moving to the None indexing mode. Può rivelarsi uno strumento operativo utile se si vuole annullare una trasformazione in corso e avviarne immediatamente una nuova.This might be a useful operational tool if you want to cancel an in-progress transformation, and then immediately start a new one.

Eliminare l'indice per una raccoltaDrop the index for a collection

// Switch to Lazy indexing mode.
Console.WriteLine("Dropping index by changing to to the None IndexingMode.");

collection.IndexingPolicy.IndexingMode = IndexingMode.None;

await client.ReplaceDocumentCollectionAsync(collection);

Quando è necessario apportare modifiche ai criteri di indicizzazione per le raccolte di Azure Cosmos DB?When would you make indexing policy changes to your Azure Cosmos DB collections? I seguenti casi rappresentano la maggior parte dei casi di utilizzo:The following are the most common use cases:

  • Restituire risultati coerenti durante il normale funzionamento, ma tornare alla modalità di indicizzazione differita durante le importazioni di dati in blocco.Serve consistent results during normal operation, but fall back to Lazy indexing mode during bulk data imports.
  • Iniziare a usare nuove funzionalità di indicizzazione nelle raccolte di Azure Cosmos DB correnti.Start using new indexing features on your current Azure Cosmos DB collections. Ad esempio, è possibile usare query geospaziali, che richiedono il tipo di indice spaziale, oppure query di intervallo di stringhe/ORDER BY, che richiedono il tipo di indice di intervallo di stringhe.For example, you can use geospatial querying, which requires the Spatial index kind, or ORDER BY/string range queries, which require the string Range index kind.
  • Selezionare a mano le proprietà da indicizzare e modificarle nel tempo.Hand-select the properties to be indexed, and change them over time.
  • Ottimizzare la precisione di indicizzazione per migliorare le prestazioni delle query o ridurre l'archiviazione utilizzata.Tune indexing precision to improve query performance or to reduce storage consumed.

Nota

Per modificare i criteri di indicizzazione tramite ReplaceDocumentCollectionAsync, è necessario usare .NET SDK versione 1.3.0 o successive.To modify indexing policy by using ReplaceDocumentCollectionAsync, you must use version 1.3.0 or a later version of the .NET SDK.

Perché la trasformazione dell'indice venga completata correttamente, assicurarsi che vi sia sufficiente spazio di archiviazione disponibile nella raccolta.For index transformation to successfully finish, ensure that there is sufficient free storage space available on the collection. Se la raccolta raggiunge la quota di archiviazione, la trasformazione dell'indice viene sospesa.If the collection reaches its storage quota, the index transformation is paused. La trasformazione dell'indice viene ripresa automaticamente quando è disponibile spazio di archiviazione, ad esempio se si eliminano alcuni documenti.Index transformation automatically resumes when storage space is available, for example, if you delete some documents.

Ottimizzazione delle prestazioniPerformance tuning

Le API SQL forniscono informazioni sulle metriche delle prestazioni, ad esempio lo spazio di archiviazione usato per gli indici e il costo della velocità effettiva (unità richiesta) per ogni operazione.The SQL APIs provide information about performance metrics, such as the index storage used and the throughput cost (request units) for every operation. Queste informazioni possono essere usate per confrontare diversi criteri di indicizzazione e per l'ottimizzazione delle prestazioni.You can use this information to compare various indexing policies, and for performance tuning.

Per controllare la quota di archiviazione e l'utilizzo di una raccolta, eseguire una richiesta HEAD o GET sulla risorsa della raccolta.To check the storage quota and usage of a collection, run a HEAD or GET request against the collection resource. Esaminare quindi le intestazioni x-ms-request-quota e x-ms-request-usage.Then, inspect the x-ms-request-quota and the x-ms-request-usage headers. In .NET SDK le proprietà DocumentSizeQuota e DocumentSizeUsage di ResourceResponse<T> contengono questi valori corrispondenti.In the .NET SDK, the DocumentSizeQuota and DocumentSizeUsage properties in ResourceResponse<T> contain these corresponding values.

 // Measure the document size usage (which includes the index size) against   
 // different policies.
 ResourceResponse<DocumentCollection> collectionInfo = await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri("db", "coll"));  
 Console.WriteLine("Document size quota: {0}, usage: {1}", collectionInfo.DocumentQuota, collectionInfo.DocumentUsage);

Per valutare l'overhead di indicizzazione di ogni operazione di scrittura (creazione, aggiornamento o eliminazione), esaminare l'intestazione x-ms-request-charge o la proprietà equivalente RequestCharge in ResourceResponse<T> in .NET SDK per determinare il numero di unità richiesta usate da queste operazioni.To measure the overhead of indexing on each write operation (create, update, or delete), inspect the x-ms-request-charge header (or the equivalent RequestCharge property in ResourceResponse<T> in the .NET SDK) to measure the number of request units that are consumed by these operations.

 // Measure the performance (request units) of writes.     
 ResourceResponse<Document> response = await client.CreateDocumentAsync(UriFactory.CreateDocumentCollectionUri("db", "coll"), myDocument);              
 Console.WriteLine("Insert of document consumed {0} request units", response.RequestCharge);

 // Measure the performance (request units) of queries.    
 IDocumentQuery<dynamic> queryable =  client.CreateDocumentQuery(UriFactory.CreateDocumentCollectionUri("db", "coll"), queryString).AsDocumentQuery();

 double totalRequestCharge = 0;
 while (queryable.HasMoreResults)
 {
    FeedResponse<dynamic> queryResponse = await queryable.ExecuteNextAsync<dynamic>(); 
    Console.WriteLine("Query batch consumed {0} request units",queryResponse.RequestCharge);
    totalRequestCharge += queryResponse.RequestCharge;
 }

 Console.WriteLine("Query consumed {0} request units in total", totalRequestCharge);

Modifiche per la specifica di criteri di indicizzazioneChanges to the indexing policy specification

Il 7 luglio 2015 è stata introdotta una modifica nello schema per i criteri di indicizzazione con l'API REST versione 2015-06-03.A change in the schema for indexing policy was introduced July 7, 2015, with REST API version 2015-06-03. Le relative classi nelle versioni SDK hanno nuove implementazioni per garantire la corrispondenza con lo schema.The corresponding classes in the SDK versions have new implementations to match the schema.

Nella specifica JSON sono state implementate le modifiche seguenti:The following changes were implemented in the JSON specification:

  • I criteri di indicizzazione supportano gli indici di intervallo per le stringhe.Indexing policy supports Range indexes for strings.
  • Ogni percorso può avere più definizioni di indice.Each path can have multiple index definitions. Può averne una per ogni tipo di dati.It can have one for each data type.
  • La precisione di indicizzazione supporta i valori compresi tra 1 e 8 per i numeri, tra 1 e 100 per le stringhe e -1 (precisione massima).Indexing precision supports 1 through 8 for numbers, 1 through 100 for strings, and -1 (maximum precision).
  • I segmenti di percorso non richiedono le virgolette doppie per l'escape di ogni percorso.Path segments don't require a double quotation to escape each path. Ad esempio, è possibile aggiungere un percorso per /title/?For example, you can add a path for /title/? invece di /"title"/?.instead of /"title"/?.
  • Il percorso radice che rappresenta "tutti i percorsi" può essere rappresentato come /\* (oltre a /).The root path that represents "all paths" can be represented as /\* (in addition to /).

Se si dispone di codice per il provisioning delle raccolte con criteri di indicizzazione personalizzati scritto con .NET SDK versione 1.1.0 o precedente, per poter passare all'SDK versione 1.2.0 sarà necessario modificare il codice dell'applicazione per gestire queste modifiche.If you have code that provisions collections with a custom indexing policy written with version 1.1.0 of the .NET SDK or an earlier version, to move to SDK version 1.2.0, you must change your application code to handle these changes. Se non si dispone di codice per la configurazione di criteri di indicizzazione o si prevede di continuare a usare una versione precedente dell'SDK, non è richiesta alcuna modifica.If you don't have code that configures indexing policy, or if you plan to continue using an earlier version of the SDK, no changes are required.

Per un confronto pratico, ecco un esempio di un criterio di indicizzazione personalizzato scritto tramite l'API REST versione 2015-06-03, seguito dallo stesso criterio di indicizzazione scritto con la precedente API REST versione 2015-04-08.For a practical comparison, here's an example of a custom indexing policy written by using REST API version 2015-06-03, followed by the same indexing policy written by using the earlier REST API version 2015-04-08.

Codice JSON del criterio di indicizzazione corrente (API REST versione 2015-06-03)Current indexing policy JSON (REST API version 2015-06-03)

{
   "automatic":true,
   "indexingMode":"Consistent",
   "includedPaths":[
      {
         "path":"/*",
         "indexes":[
            {
               "kind":"Hash",
               "dataType":"String",
               "precision":3
            },
            {
               "kind":"Hash",
               "dataType":"Number",
               "precision":7
            }
         ]
      }
   ],
   "ExcludedPaths":[
      {
         "path":"/nonIndexedContent/*"
      }
   ]
}

Codice JSON del criterio di indicizzazione precedente (API REST versione 2015-04-08)Earlier indexing policy JSON (REST API version 2015-04-08)

{
   "automatic":true,
   "indexingMode":"Consistent",
   "IncludedPaths":[
      {
         "IndexType":"Hash",
         "Path":"/",
         "NumericPrecision":7,
         "StringPrecision":3
      }
   ],
   "ExcludedPaths":[
      "/\"nonIndexedContent\"/*"
   ]
}

Passaggi successiviNext steps

Per alcuni esempi di gestione dei criteri di indicizzazione e per informazioni sul linguaggio di query di Azure Cosmos DB, vedere i collegamenti seguenti:For index policy management samples and to learn more about the Azure Cosmos DB query language, see the following links: