Partizionamento e ridimensionamento in Azure Cosmos DBPartition and scale in Azure Cosmos DB

Azure Cosmos DB è un servizio di database multimodello distribuito a livello globale, progettato per favorire prestazioni rapide e prevedibili.Azure Cosmos DB is a globally distributed, multi-model database service designed to help you achieve fast, predictable performance. È ridimensionabile contestualmente all'espansione dell'applicazione.It scales seamlessly along with your application as it grows. Questo articolo offre una panoramica del funzionamento del partizionamento per tutti i modelli di dati in Azure Cosmos DB.This article provides an overview of how partitioning works for all the data models in Azure Cosmos DB. Descrive anche come configurare contenitori Azure Cosmos DB per ridimensionare in modo efficace le applicazioni.It also describes how you can configure Azure Cosmos DB containers to effectively scale your applications.

Il partizionamento e le chiavi di partizione vengono descritti in questo video:Partitioning and partition keys are discussed in this video:

Partizionamento in Azure Cosmos DBPartitioning in Azure Cosmos DB

In Azure Cosmos DB è possibile archiviare dati ed eseguire query su dati senza schema con latenza nell'ordine di millisecondi a una cifra, a qualsiasi livello di scalabilità.In Azure Cosmos DB, you can store and query schema-less data with a single digit millisecond latency at any scale. Azure Cosmos DB offre contenitori per l'archiviazione di dati denominati raccolte (per i documenti), grafici o tabelle.Azure Cosmos DB provides containers for storing data called collections (for documents), graphs, or tables.

I contenitori sono risorse logiche e possono comprendere una o più partizioni fisiche o server.Containers are logical resources and can span one or more physical partitions or servers. Il numero di partizioni è determinato da Azure Cosmos DB in base allo spazio di archiviazione e alla velocità effettiva con provisioning di un contenitore o di un set di contenitori.The number of partitions is determined by Azure Cosmos DB based on the storage size and throughput provisioned for a container or a set of containers.

Una partizione fisica è una quantità fissa di risorsa di archiviazione con backup su disco SSD riservato combinata con una quantità variabile di risorse di calcolo (CPU e memoria).A physical partition is a fixed amount of reserved SSD-backed storage combined with variable amount of compute resources (CPU and memory). Ogni partizione fisica viene replicata per assicurare disponibilità elevata.Each physical partition is replicated for high availability. Ogni set di contenitori può condividere una o più partizioni fisiche.Each set of containers may share one or more physical partitions. Le partizioni fisiche vengono completamente gestite da Azure Cosmos DB, quindi non è necessario scrivere codice complesso o occuparsi personalmente della gestione.Physical partition management is fully managed by Azure Cosmos DB, and you don't have to write complex code or manage your partitions. I contenitori di Azure Cosmos DB sono illimitati in termini di risorse di archiviazione e di velocità effettiva.Azure Cosmos DB containers are unlimited in terms of storage and throughput.

Una partizione logica è una partizione all'interno di una partizione fisica in cui sono archiviati tutti i dati associati al valore di una singola chiave di partizione.A logical partition is a partition within a physical partition that stores all the data associated with a single partition key value. Più partizioni logiche possono essere incluse nella stessa partizione fisica.Multiple logical partitions can end up in the same physical partition. Nel diagramma seguente un singolo contenitore ha tre partizioni logiche.In the following diagram, a single container has three logical partitions. Ogni partizione logica archivia i dati di una chiave di partizione, rispettivamente LAX, AMS e MEL.Each logical partition stores the data for one partition key, LAX, AMS, and MEL respectively. Ognuna delle partizioni logiche LAX, AMS e MEL non può superare il limite massimo di 10 GB per le partizioni logiche.Each of the LAX, AMS, and MEL logical partitions cannot grow beyond the maximum logical partition limit of 10 GB.

Partizionamento delle risorse

Quando un contenitore soddisfa i prerequisiti di partizionamento, il partizionamento è completamente trasparente all'applicazione.When a container meets the partitioning prerequisites, partitioning is completely transparent to your application. Azure Cosmos DB supporta letture e scritture veloci, query, logica transazionale, livelli di coerenza e controllo di accesso con granularità fine tramite metodi/API per una singola risorsa di contenitore.Azure Cosmos DB supports fast reads and writes, queries, transactional logic, consistency levels, and fine-grained access control via methods/APIs to a single container resource. Il servizio gestisce la distribuzione dei dati tra le partizioni fisiche e logiche e il routing delle richieste di query alla partizione corretta.The service handles distributing data across physical and logical partitions and routing of query requests to the right partition.

Funzionamento del partizionamentoHow does partitioning work

Per il partizionamento,How does partitioning work? ogni elemento deve avere una chiave di partizione e una chiave di riga che lo identificano in modo univoco.Each item must have a partition key and a row key, which uniquely identify it. La chiave di partizione funge da partizione logica per i dati e fornisce ad Azure Cosmos DB un limite naturale per la distribuzione dei dati tra le partizioni fisiche.Your partition key acts as a logical partition for your data and provides Azure Cosmos DB with a natural boundary for distributing data across physical partitions. I dati di una singola partizione logica devono essere contenuti all'interno di un'unica partizione fisica, ma la gestione delle partizioni fisiche viene eseguita da Azure Cosmos DB.The data for a single logical partition must reside inside a single physical partition, but physical partition management is managed by Azure Cosmos DB.

In sintesi, il partizionamento in Azure Cosmos DB funziona nel modo seguente:In brief, here's how partitioning works in Azure Cosmos DB:

  • Il provisioning di un set di contenitori Azure Cosmos DB viene effettuato con velocità effettiva di T UR/s (richieste al secondo).You provision a set of Azure Cosmos DB containers with T RU/s (requests per second) throughput.
  • In background Azure Cosmos DB effettua il provisioning delle partizioni fisiche necessarie per gestire T richieste al secondo.Behind the scenes, Azure Cosmos DB provisions physical partitions needed to serve T requests per second. Se T è maggiore della velocità effettiva massima per partizione fisica t, Azure Cosmos DB effettua il provisioning di N = T/t partizioni fisiche.If T is higher than the maximum throughput per physical partition t, then Azure Cosmos DB provisions N = T/t physical partitions. Il valore della velocità effettiva massima per partizione è configurato da Azure Cosmos DB; questo valore viene assegnato in base alla velocità effettiva totale sottoposta a provisioning e alla configurazione hardware usata.The value of maximum throughput per partition(t) is configured by Azure Cosmos DB, this value is assigned based on total provisioned throughput and the hardware configuration used.
  • Azure Cosmos DB alloca lo spazio degli hash delle chiavi di partizione in modo uniforme tra le N partizioni fisiche.Azure Cosmos DB allocates the key space of partition key hashes evenly across the N physical partitions. Pertanto, il numero di partizioni logiche che ogni partizione fisica ospita corrisponde a 1/N * numero di valori di chiave di partizione.So, the number of logical partitions each physical partition hosts is 1/N * number of partition key values.
  • Quando una partizione fisica p raggiunge il limite di archiviazione, Azure Cosmos DB suddivide p in due nuove partizioni fisiche, p1 e p2.When a physical partition p reaches its storage limit, Azure Cosmos DB seamlessly splits p into two new physical partitions, p1 and p2. Distribuisce i valori corrispondenti a circa la metà delle chiavi a ognuna delle nuove partizioni fisiche.It distributes values corresponding to roughly half of the keys to each of the new physical partitions. Questa operazione di suddivisione è invisibile all'applicazione.This split operation is completely invisible to your application. Se una partizione fisica raggiunge il limite di archiviazione e tutti i dati della partizione fisica appartengono alla stessa chiave di partizione logica, l'operazione di suddivisione non viene eseguita.If a physical partition reaches its storage limit and all of the data in the physical partition belongs to the same logical partition key, the split operation does not occur. Il motivo è che tutti i dati di una singola chiave di partizione logica devono trovarsi nella stessa partizione fisica.This is because all the data for a single logical partition key must reside in the same physical partition. In questo caso dovrebbe essere adottata una strategia diversa per la chiave di partizione.In this case, a different partition key strategy should be employed.
  • Quando si esegue il provisioning di una velocità effettiva superiore a t*N, Azure Cosmos DB suddivide una o più partizioni fisiche per supportare la velocità effettiva maggiore.When you provision throughput higher than t*N, Azure Cosmos DB splits one or more of your physical partitions to support the higher throughput.

La semantica delle chiavi di partizione è leggermente diversa in modo da corrispondere alla semantica di ogni API, come illustrato nella tabella seguente:The semantics for partition keys are slightly different to match the semantics of each API, as shown in the following table:

APIAPI Chiave di partizionePartition key Chiave di rigaRow key
SQLSQL Percorso personalizzato della chiave di partizioneCustom partition key path id fissoFixed id
MongoDBMongoDB Chiave di partizione personalizzataCustom shard key _id fissoFixed _id
GremlinGremlin Proprietà chiave di partizione personalizzataCustom partition key property id fissoFixed id
TabellaTable PartitionKey fissoFixed PartitionKey RowKey fissoFixed RowKey

Azure Cosmos DB usa il partizionamento basato su hash.Azure Cosmos DB uses hash-based partitioning. Quando si scrive un elemento, Azure Cosmos DB esegue l'hashing del valore della chiave di partizione e usa il risultato con hash per determinare la partizione in cui archiviare l'elemento.When you write an item, Azure Cosmos DB hashes the partition key value and uses the hashed result to determine which partition to store the item in. Azure Cosmos DB archivia tutti gli elementi con la stessa chiave di partizione nella stessa partizione fisica.Azure Cosmos DB stores all items with the same partition key in the same physical partition.

Procedure consigliate per scegliere una chiave di partizioneBest practices when choosing a partition key

La scelta della chiave di partizione è una decisione importante da prendere in fase di progettazione.The choice of the partition key is an important decision that you have to make at design time. Scegliere un nome proprietà che contenga un'ampia gamma di valori e abbia anche modelli di accesso.Pick a property name that has a wide range of values and has even access patterns. Una procedura consigliata consiste nello scegliere una chiave di partizione con un numero elevato di valori distinti, ad esempio diverse centinaia o migliaia.It's a best practice to have a partition key with a large number of distinct values (e.g., hundreds or thousands). In questo modo, è possibile distribuire il carico di lavoro in modo uniforme tra questi valori.It lets you distribute your workload evenly across these values. Una chiave di partizione ideale appare spesso come filtro nelle query e ha una cardinalità sufficiente per garantire la scalabilità della soluzione.An ideal partition key is one that appears frequently as a filter in your queries and has sufficient cardinality to ensure your solution is scalable.

Se una partizione fisica raggiunge il limite di archiviazione e i dati nella partizione hanno la stessa chiave di partizione, Azure Cosmos DB restituisce il messaggio "Partition key reached maximum size of 10 GB" (La chiave di partizione ha raggiunto la dimensione massima di 10 GB) e la partizione non viene suddivisa.If a physical partition reaches its storage limit and the data in the partition has the same partition key, Azure Cosmos DB returns the "Partition key reached maximum size of 10 GB" message, and the partition is not split. La scelta di una buona chiave di partizione è una decisione molto importante.Choosing a good partition key is a very important decision. Le partizioni fisiche sono un concetto interno di Azure Cosmos DB e sono temporanee.Physical partitions are an internal concept of Azure Cosmos DB and are transient. Con Azure Cosmos DB il numero di partizioni fisiche viene scalato automaticamente in base al carico di lavoro.Azure Cosmos DB will automatically scale the number of physical partitions based on your workload. Pertanto è consigliabile non correlare la progettazione del database al numero di partizioni fisiche mentre bisogna accertarsi di scegliere la chiave di partizione corretta (partizioni logiche).So you shouldn’t corelate your database design based on the number of physical partitions instead you should make sure to choose the right partition key (logical partitions).

Scegliere una chiave di partizione in modo che:Choose a partition key such that:

  • La distribuzione di archiviazione sia uniforme su tutte le chiavi.The storage distribution is even across all the keys.
  • La distribuzione del volume di richieste in un determinato punto nel tempo sia uniforme su tutte le chiavi.The volume distribution of requests at a given point in time is even across all the keys.
  • Le query che vengono richiamate con concorrenza elevata possano essere indirizzate in modo efficiente includendo la chiave di partizione nel predicato del filtro.Queries that are invoked with high concurrency can be efficiently routed by including the partition key in the filter predicate.
  • La scelta di una chiave di partizione con cardinalità più elevata è in genere preferibile perché solitamente produce distribuzione e scalabilità migliori.Choosing a partition key with higher cardinality is generally preferred – becaue it typically yields better distribution and scalability. Ad esempio, una chiave composta può essere formata dalla concatenazione dei valori di più proprietà per aumentare la cardinalità.For example, a composite key can be formed by concatenating values from multiple properties to increase the cardinality.

Quando si sceglie una chiave di partizione tenendo conto delle considerazioni precedenti, non è necessario preoccuparsi del numero di partizioni né della velocità effettiva allocata a ogni partizione fisica in quanto Azure Cosmos DB ridimensiona il numero di partizioni fisiche e può anche scalare le singole partizioni, se necessario.When you choose a partition key with above considerations, you don’t have to worry about the number of partitions or how much throughput is allocated per physical partition, as Azure Cosmos DB scales out the number of physical partitions, and it can also scale the individual partitions as needed.

I contenitori di Azure Cosmos DB possono essere creati come fissi o senza limitazioni nel portale di Azure.Azure Cosmos DB containers can be created as fixed or unlimited in the Azure portal. I contenitori a dimensione fissa hanno un limite massimo di 10 GB e velocità effettiva di 10.000 UR/s.Fixed-size containers have a maximum limit of 10 GB and 10,000 RU/s throughput. Per creare un contenitore illimitato, è necessario specificare una chiave di partizione e una velocità effettiva minima di 1.000 UR/s.To create a container as unlimited, you must specify a partition key and a minimum throughput of 1,000 RU/s. I contenitori di Azure DB Cosmos possono anche essere configurati per condividere la velocità effettiva tra un set di contenitori, in cui ogni contenitore deve specificare una chiave partizione e si può espandere senza limiti.Azure Cosmos DB containers may also be configured to share throughput between a set of containers, in which each container must specificy a partition key and can grow unlimited.

È consigliabile controllare il modo in cui i dati vengono distribuiti tra le partizioni.It is a good idea to check how your data is distributed across partitions. Per controllare la distribuzione dei dati nel portale, accedere al proprio account Azure Cosmos DB e fare clic su Metriche nella sezione Monitoraggio e quindi fare clic sulla scheda Archiviazione per verificare il modo in cui i dati sono partizionati tra partizioni fisiche diverse.To check the data distribution in the portal, go to your Azure Cosmos DB account and click on Metrics in Monitoring section and then click on storage tab to see how your data is partitioned across different physical partitions.

Partizionamento delle risorse

L'immagine a sinistra mostra il risultato di una chiave di partizione non valida, mentre l'immagine a destra mostra il risultato di una chiave di partizione valida.The left image above shows the result of a bad partition key and the right image above shows the result when a good partition key was chosen. Nell'immagine a sinistra è possibile osservare che i dati non sono distribuiti uniformemente tra le partizioni.In the left image, you can see that the data is not evenly distributed across the partitions. È consigliabile scegliere una chiave di partizione che distribuisca i dati in modo simile all'immagine a destra.You should strive to choose a partition key that distributes your data so it looks similar to the right image.

Prerequisiti per il partizionamentoPrerequisites for partitioning

Per consentire la suddivisione automatica delle partizioni fisiche in p1 e p2, come descritto nella sezione Funzionamento del partizionamento, è necessario creare il contenitore con una velocità effettiva di almeno 1.000 UR/s (o condividere la velocità effettiva tra un set di contenitori) e specificare una chiave di partizione.For physical partitions to auto-split into p1 and p2 as described in How does partitioning work, the container must be created with a throughput of 1,000 RU/s or more (or share throughput across a set of containers), and a partition key must be provided. Durante la creazione di un contenitore, ad esempio una raccolta, un grafo o una tabella, nel portale di Azure, selezionare l'opzione di capacità di archiviazione Senza limitazioni per sfruttare i vantaggi della scalabilità illimitata.When creating a container (e.g., a collection, a graph or a table) in the Azure portal, select the Unlimited storage capacity option to take advantage of unlimited scaling.

Se è stato creato un contenitore nel portale di Azure o a livello di codice con velocità effettiva iniziale uguale o maggiore di 1.000 UR/s ed è stata specificata una chiave di partizione, è possibile sfruttare la scalabilità illimitata senza apportare alcuna modifica al contenitore.If you created a container in the Azure portal or programmatically and the initial throughput was 1,000 RU/s or more, and you provided a partition key, you can take advantage of unlimited scaling with no changes to your container. Questo riguarda anche i contenitori con opzione di capacità Fissa, purché il contenitore iniziale sia stato creato con velocità effettiva di almeno 1.000 UR/s e sia stata specificata una chiave di partizione.This includes Fixed containers, so long as the initial container was created with at least 1,000 RU/s of throughput and a partition key is specified.

Tutti i contenitori configurati per condividere la velocità effettiva come parte di un set di contenitori vengono considerati contenitori senza limiti.All containers configured to share throughput as part of a set of containers are treated as Unlimited containers.

Se è stato creato un contenitore con opzione di capacità Fissa senza chiave di partizione o con velocità effettiva minore di 1.000 UR/s, il contenitore non si ridimensionerà automaticamente come descritto in questo articolo.If you created a Fixed container with no partition key or throughput less than 1,000 RU/s, the container will not auto-scale as described in this article. Per eseguire la migrazione dei dati da un contenitore fisso a un contenitore senza limiti, ad esempio uno con velocità effettiva di almeno 1.000 UR/s e una chiave di partizione, è necessario usare l'Utilità di migrazione dati o la Libreria di feed di modifiche.To migrate the data from a fixed container to an unlimited container (for example, one with at least 1,000 RU/s and a partition key), you need to use the Data Migration tool or the Change Feed library.

Partizionamento e velocità effettiva con provisioningPartitioning and provisioned throughput

Azure Cosmos DB è progettato per prestazioni prevedibili.Azure Cosmos DB is designed for predictable performance. Quando si crea un contenitore o un set di contenitori, la velocità effettiva viene riservata in termini di Unità richiesta (UR) al secondo.When you create a container or set of containers, you reserve the throughput in terms of Request Units (RU) per second. A ogni richiesta viene assegnato un addebito di UR proporzionale alla quantità di risorse di sistema, come CPU, memoria e I/O utilizzati dall'operazione.Each request makes an RU charge that is proportional to the amount of system resources like CPU, memory, and IO consumed by the operation. La lettura di un documento di 1 KB con coerenza di sessione usa 1 UR.A read of a 1-KB document with session consistency consumes 1 RU. Un'operazione di lettura corrisponde a 1 RU indipendentemente dal numero di elementi archiviati o dal numero di richieste simultanee in esecuzione contemporaneamente.A read is 1 RU regardless of the number of items stored or the number of concurrent requests running at the same time. Elementi di dimensioni maggiori richiedono più UR a seconda delle dimensioni.Larger items require higher RUs depending on the size. Se si conoscono le dimensioni delle entità e il numero di letture che è necessario supportare per l'applicazione, è possibile effettuare il provisioning della quantità esatta di velocità effettiva necessaria per le esigenze dell'applicazione.If you know the size of your entities and the number of reads you need to support for your application, you can provision the exact amount of throughput required for your application's needs.

Nota

Per usare completamente la velocità effettiva con provisioning di un contenitore o di un set di contenitori, è necessario scegliere una chiave di partizione che permetta di distribuire in modo uniforme le richieste tra tutti i valori di chiave di partizione distinti.To fully utilize throughput provisioned for a container or a set of containers, you must choose a partition key that allows you to evenly distribute requests across all distinct partition key values.

Uso delle API di Azure Cosmos DBWork with the Azure Cosmos DB APIs

È possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure per creare contenitori e ridimensionarli in qualsiasi momento.You can use the Azure portal or Azure CLI to create containers and scale them at any time. Questa sezione mostra come creare contenitori e specificare la velocità effettiva e la chiave di partizione assegnate tramite provisioning usando ogni API.This section shows how to create containers and specify the provisioned throughput and partition key using each API.

API SQLSQL API

L'esempio seguente mostra come creare un contenitore (raccolta) usando l'API SQL.The following sample shows how to create a container (a collection) using SQL API.

DocumentClient client = new DocumentClient(new Uri(endpoint), authKey);
await client.CreateDatabaseAsync(new Database { Id = "db" });

DocumentCollection myCollection = new DocumentCollection();
myCollection.Id = "coll";
myCollection.PartitionKey.Paths.Add("/deviceId");

await client.CreateDocumentCollectionAsync(
    UriFactory.CreateDatabaseUri("db"),
    myCollection,
    new RequestOptions { OfferThroughput = 20000 });

È possibile leggere un elemento (documento) tramite il metodo GET nell'API REST oppure usando ReadDocumentAsync in uno degli SDK.You can read an item (document) using the GET method in the REST API or using ReadDocumentAsync in one of the SDKs.

// Read document. Needs the partition key and the ID to be specified
DeviceReading document = await client.ReadDocumentAsync<DeviceReading>(
  UriFactory.CreateDocumentUri("db", "coll", "XMS-001-FE24C"), 
  new RequestOptions { PartitionKey = new PartitionKey("XMS-0001") });

Per altre informazioni, vedere Partizionamento in Azure Cosmos DB con l'API SQL.For more information, see Partitioning in Azure Cosmos DB using the SQL API.

API di MongoDBMongoDB API

Con l'API MongoDB è possibile creare una raccolta partizionata usando il proprio strumento, driver o SDK preferito.With the MongoDB API, you can create a sharded collection through your favorite tool, driver, or SDK. In questo esempio verrà usato Mongo Shell per creare una raccolta.In this example, we use the Mongo Shell to create a collection.

In Mongo Shell:In the Mongo Shell:

db.runCommand( { shardCollection: "admin.people", key: { region: "hashed" } } )

Risultati:Results:

{
    "_t" : "ShardCollectionResponse",
    "ok" : 1,
    "collectionsharded" : "admin.people"
}

API di tabellaTable API

Per creare una tabella usando l'API di tabella, usare il metodo CreateIfNotExists.To create a table using the Table API, use the CreateIfNotExists method.

CloudTableClient tableClient = storageAccount.CreateCloudTableClient();

CloudTable table = tableClient.GetTableReference("people");
table.CreateIfNotExists(throughput: 800);

La velocità effettiva assegnata tramite provisioning viene impostata come argomento di CreateIfNotExists.Provisioned throughput is set as an argument of CreateIfNotExists. La chiave di partizione viene creata implicitamente come valore PartitionKey.The partition key is implicitly created as the PartitionKey value.

È possibile recuperare una singola entità usando il codice seguente:You can retrieve a single entity by using the following code:

// Create a retrieve operation that takes a customer entity.
TableOperation retrieveOperation = TableOperation.Retrieve<CustomerEntity>("Smith", "Ben");

// Execute the retrieve operation.
TableResult retrievedResult = table.Execute(retrieveOperation);

Per altre informazioni, vedere Sviluppare con l'API Table.For more information, see Develop with the Table API.

API GremlinGremlin API

Con l'API Gremlin, è possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure per creare un contenitore che rappresenta un grafo.With the Gremlin API, you can use the Azure portal or Azure CLI to create a container that represents a graph. In alternativa, poiché Azure Cosmos DB è multimodello, per creare e ridimensionare il contenitore grafo è possibile usare una delle altre API.Alternatively, because Azure Cosmos DB is multi-model, you can use one of the other APIs to create and scale your graph container.

È possibile leggere qualsiasi vertice o arco usando la chiave di partizione e l'ID in Gremlin.You can read any vertex or edge by using the partition key and ID in Gremlin. Per un grafico con area ("USA") come chiave di partizione e "Seattle" come chiave di riga, ad esempio, è possibile trovare un vertice usando la sintassi seguente:For example, for a graph with region ("USA") as the partition key and "Seattle" as the row key, you can find a vertex by using the following syntax:

g.V(['USA', 'Seattle'])

È possibile fare riferimento a un arco usando la chiave di partizione e la chiave di riga.You can reference an edge by using the partition key and the row key.

g.E(['USA', 'I5'])

Per altre informazioni, vedere Uso di un grafo partizionato in Azure Cosmos DB.For more information, see Using a partitioned graph in Azure Cosmos DB.

Progettare per la scalabilitàDesign for scale

Per ridimensionare in modo efficace con Azure Cosmos DB è necessario selezionare una chiave di partizione valida quando si crea il contenitore.To scale effectively with Azure Cosmos DB, you need to pick a good partition key when you create your container. Nello scegliere una chiave di partizione è necessario considerare due aspetti principali:There are two main considerations for choosing a good partition key:

  • Limite delle query e transazioni.Query boundary and transactions. La scelta della chiave di partizione deve bilanciare l'esigenza di poter usare transazioni con il requisito di distribuire le entità tra più chiavi di partizione per garantire una soluzione scalabile.Your choice of partition key should balance the need to use transactions against the requirement to distribute your entities across multiple partition keys to ensure a scalable solution. Da una parte è possibile impostare la stessa chiave di partizione per tutti gli elementi. Questa opzione potrebbe comunque limitare la scalabilità della soluzione.At one extreme, you can set the same partition key for all your items, but this option might limit the scalability of your solution. Dall'altra è possibile assegnare una chiave di partizione univoca per ogni elemento.At the other extreme, you can assign a unique partition key for each item. Questa scelta è altamente scalabile, ma impedisce di usare transazioni tra documenti tramite stored procedure e trigger.This choice is highly scalable, but it prevents you from using cross-document transactions via stored procedures and triggers. Una chiave di partizione ideale consente di usare query efficienti e dispone di una quantità di cardinalità idonea a garantire la scalabilità della soluzione.An ideal partition key enables you to use efficient queries and has sufficient cardinality to ensure your solution is scalable.
  • Evitare i colli di bottiglia in termini di archiviazione e prestazioni.No storage and performance bottlenecks. È importante scegliere una proprietà che consenta di distribuire le scritture su una serie di valori distinti.It's important to pick a property that allows writes to be distributed across various distinct values. Le richieste alla stessa chiave di partizione non possono superare la velocità effettiva allocata tramite provisioning a una partizione e avranno una frequenza limitata.Requests to the same partition key can't exceed the provisioned throughput allocated to a partition and will be rate-limited. È quindi importante scegliere una chiave di partizione che non generi "aree sensibili" all'interno dell'applicazione.So it's important to pick a partition key that doesn't result in "hot spots" within your application. Poiché tutti i dati per una singola chiave di partizione devono essere archiviati in una partizione, è consigliabile evitare le chiavi di partizione con volumi elevati di dati per lo stesso valore.Because all the data for a single partition key must be stored within a partition, you should avoid partition keys that have high volumes of data for the same value.

Verranno ora esaminati alcuni scenari reali con le chiavi di partizione corrette per ognuno:Let's look at a few real-world scenarios and good partition keys for each:

  • Se si implementa un back-end del profilo utente, l'ID utente rappresenta la scelta ideale per una chiave di partizione.If you're implementing a user profile backend, the user ID is a good choice for a partition key.
  • Se si archiviano dati IoT, ad esempio lo stato del dispositivo, un ID dispositivo rappresenta la scelta ideale per una chiave di partizione.If you're storing IoT data, for example, device state, a device ID is a good choice for a partition key.
  • Se si usa Azure Cosmos DB per la registrazione di dati di serie temporali, il nome host o l'ID processo rappresenta la scelta ottimale per una chiave di partizione.If you're using Azure Cosmos DB for logging time-series data, the hostname or process ID is a good choice for a partition key.
  • In presenza di un'architettura multi-tenant, l'ID tenant rappresenta la scelta ideale per una chiave di partizione.If you have a multitenant architecture, the tenant ID is a good choice for a partition key.

In alcuni casi d'uso, ad esempio con IoT e i profili utente, la chiave di partizione può corrispondere al proprio ID (chiave del documento).In some use cases, like IoT and user profiles, the partition key might be the same as your ID (document key). In altri casi, ad esempio i dati di serie temporali, la chiave di partizione potrebbe essere diversa dall'ID.In others, like the time-series data, you might have a partition key that's different from the ID.

Partizionamento e registrazione di dati di serie temporaliPartitioning and logging/time-series data

Uno dei casi d'uso più comuni in Azure Cosmos DB è costituito da registrazione e telemetria.One of the common use cases in Azure Cosmos DB is logging and telemetry. In questo scenario è importante scegliere una chiave di partizione appropriata, perché potrebbe essere necessario scrivere/leggere grandi volumi di dati.It's important to pick a good partition key in this scenario, because you might need to read/write vast volumes of data. La scelta della chiave di partizione dipende dalla frequenza di lettura e scrittura e dai tipi di query che si prevede di eseguire.The choice for a partition key depends on your read-and-write rates and the kinds of queries you expect to run. Di seguito sono riportati alcuni suggerimenti su come scegliere una chiave di partizione efficace:Here are some tips on how to choose a good partition key:

  • Se il caso d'uso prevede frequenze di scrittura ridotte che si accumulano in un lungo periodo di tempo ed è necessario eseguire query per intervalli di timestamp e altri filtri, usare un'implementazione del timestamp.If your use case involves a small rate of writes that accumulate over a long time and you need to query by ranges of timestamps with other filters, use a rollup of the timestamp. Ad esempio, un approccio valido consiste nell'usare la data come chiave di partizione.For example, a good approach is to use date as a partition key. Con questo approccio è possibile eseguire query su tutti i dati per una data specifica da una singola partizione.With this approach, you can query over all the data for a given date from a single partition.
  • Se il carico di lavoro è a elevato utilizzo di scrittura, una caratteristica molto comune in questo scenario, usare una chiave di partizione non basata sul timestamp.If your workload is write-heavy, which is very common in this scenario, use a partition key that is not based on the timestamp. In questo modo, Azure Cosmos DB può distribuire e ridimensionare uniformemente le scritture tra più partizioni.As such, Azure Cosmos DB can distribute and scale writes evenly across various partitions. In questo caso, un nome host, un ID processo, un ID attività o un'altra proprietà con cardinalità elevata è una scelta efficace.Here a hostname, process ID, activity ID, or another property with high cardinality is a good choice.
  • Un altro approccio è quello ibrido, in cui sono presenti più contenitori, uno per ogni giorno/mese, e la chiave di partizione è una proprietà più granulare, ad esempio un nome host.Another approach is a hybrid approach, where you have multiple containers, one for each day/month, and the partition key is a more granular property like hostname. Questo approccio ha il vantaggio di poter impostare una velocità effettiva diversa per ogni contenitore o set di contenitori in base all'intervallo di tempo e alle esigenze di scalabilità e prestazioni.This approach has the benefit that you can set different throughput for each container or a set of containers based on the time window and the scale and performance needs. Ad esempio, un contenitore per il mese in corso può essere sottoposto a provisioning con una velocità effettiva superiore, poiché gestisce letture e scritture.For example, a container for the current month may be provisioned with a higher throughput, because it serves reads and writes. Per i mesi precedenti è possibile effettuare il provisioning di una velocità effettiva inferiore, perché vengono gestite solo letture.Previous months may be provisioned with a lower throughput, because they only serve reads.

Partizionamento e multi-tenancyPartitioning and multitenancy

Se si implementa un'applicazione multi-tenant usando Azure Cosmos DB, è possibile prendere in considerazione due scenari comuni: una chiave di partizione per ogni tenant e un contenitore per ogni tenant.If you are implementing a multitenant application using Azure Cosmos DB, there are two popular designs to consider: one partition key per tenant and one container per tenant. Di seguito sono riportati vantaggi e svantaggi di ogni modello:Here are the pros and cons for each:

  • Una chiave di partizione per ogni tenant.One partition key per tenant. In questo modello i tenant vengono collocati all'interno di un singolo contenitore.In this model, tenants are colocated within a single container. Le query e gli inserimenti per un singolo tenant possono essere eseguiti su un'unica partizione.Queries and inserts for a single tenant can be performed against a single partition. È anche possibile implementare la logica transazionale su tutti gli elementi che appartengono a un tenant.You can also implement transactional logic across all items belonging to a tenant. Poiché più tenant condividono un contenitore, è possibile utilizzare al meglio l'archiviazione e la velocità effettiva assegnata tramite provisioning raggruppando le risorse per tutti i tenant all'interno di un singolo contenitore invece di effettuare il provisioning per ogni tenant.Because multiple tenants share a container, you can better utilize storage and provisioned throughput by pooling resources for all tenants within a single container rather than provisioning for each tenant. Lo svantaggio è che non si ottiene l'isolamento delle prestazioni per ogni tenant.The drawback is that you don't have performance isolation per tenant. L'aumento della velocità effettiva per garantire le prestazioni verrà applicato all'intero contenitore con tutti i tenant, anziché eseguire un aumento mirato per un singolo tenant.Increasing throughput to guarantee performance will apply to the entire container with all the tenants versus targeted increases for an individual tenant.
  • Un contenitore per ogni tenant.One container per tenant. In questo modello ogni tenant ha il proprio contenitore ed è possibile riservare velocità effettiva con prestazioni garantite per ogni tenant.In this model, each tenant has its own container, and you can reserve throughput with guaranteed performance per tenant. Questo modello è più conveniente per applicazioni multi-tenant con un numero ridotto di tenant.This model is more cost-effective for multitenant applications with a few tenants.

È anche possibile usare un approccio ibrido che colloca tenant di dimensioni ridotte e isola i tenant di dimensioni maggiori nei rispettivi contenitori.You can also use a hybrid approach that colocates small tenants together and isolates larger tenants to their own containers.

Passaggi successiviNext steps

In questo articolo è stata presentata una panoramica di concetti e procedure consigliate per la scalabilità e il partizionamento in Azure Cosmos DB.In this article, we provided an overview of concepts and best practices for scaling and partitioning in Azure Cosmos DB.