Chiavi di partizioni gerarchiche in Azure Cosmos DB

SI APPLICA A: NoSQL

Azure Cosmos DB distribuisce i dati tra partizioni logiche e fisiche in base alle chiavi di partizioni per abilitare il ridimensionamento orizzontale. Usando le chiavi di partizioni gerarchiche (denominate anche sottopartizioni), è possibile configurare una gerarchia con tre livelli per le chiavi di partizioni per ottimizzare ulteriormente la distribuzione dei dati e per un livello superiore di ridimensionamento.

Se attualmente si usano chiavi sintetiche, si hanno scenari in cui le chiavi di partizioni possono superare 20 GB di dati o si desidera garantire che il documento di ogni tenant sia mappato alla propria partizione logica, le sottopartizioni possono essere utili. Se si usa questa funzionalità, i prefissi della chiave di partizione logica possono superare 20 GB e 10.000 unità di richieste al secondo (UR/s). Le query in base al prefisso vengono instradate in modo efficiente al subset di partizioni che contengono i dati.

Scegliere le chiavi di partizione gerarchica

Se esistono applicazioni multi-tenant e attualmente si isolano i tenant in base alla chiave di partizione, le partizioni gerarchiche possono essere utili. Le partizioni gerarchiche consentono il ridimensionamento oltre il limite di chiavi di partizioni logiche di 20 GB e rappresentano una soluzione efficace se si desidera garantire che ogni documento dei tenant possa essere ridimensionato all'infinito. Se la chiave di partizione corrente o se una singola chiave di partizione raggiunge spesso 20 GB, le partizioni gerarchiche rappresentano una scelta ottimale per il carico di lavoro.

Tuttavia, a seconda della natura del carico di lavoro e della cardinalità della chiave di primo livello, possono esserci alcuni compromessi, che verranno illustrati in dettaglio nella pagina degli scenari di partizione gerarchici.

Quando si sceglie ogni livello della chiave di partizione gerarchica, è importante tenere presenti i concetti generali di partizionamento seguenti e comprendere in che modo ognuno può influire sul carico di lavoro:

Per tutti i contenitori, ogni livello del percorso completo (a partire dal primo livello) della chiave di partizione gerarchica deve:
- Avere una cardinalità elevata. La prima, la seconda e la terza chiave (se applicabile) della partizione gerarchica devono avere tutte un'ampia gamma di valori possibili.
  - La cardinalità bassa al primo livello della chiave di partizione gerarchica limita tutte le operazioni di scrittura al momento dell'inserimento a una sola partizione fisica fino a raggiungere 50 GB e si divide in due partizioni fisiche. Si supponga, ad esempio, che la chiave di primo livello sia su TenantId e che siano presenti solo cinque tenant univoci. Ognuna di queste operazioni dei tenant è limitata a una sola partizione fisica, limitando il consumo di velocità effettiva solo a quello che si trova in una partizione fisica. Ciò è dovuto al fatto che le partizioni gerarchiche si ottimizzano per tutti i documenti con la stessa chiave di primo livello da inserire nella stessa partizione fisica per evitare query full fan-out.
  - Anche se questo potrebbe essere appropriato per i carichi di lavoro in cui si esegue un inserimento unico di tutti i dati dei tenant e le operazioni seguenti sono orientate principalmente alla lettura, questo può essere non ideale per i carichi di lavoro in cui i requisiti aziendali comportano l'inserimento di dati entro un periodo di tempo specifico. Ad esempio, se esistono requisiti aziendali rigorosi per evitare latenze, la massima velocità effettiva che il carico di lavoro può raggiungere teoricamente per l'inserimento dei dati corrisponde al numero di partizioni fisiche * 10.000. Se la chiave di primo livello ha una cardinalità bassa, è probabile che il numero di partizioni fisiche sia 1, a meno che non siano presenti dati sufficienti per la chiave di livello 1 per essere distribuita tra più partizioni dopo le divisioni, che possono richiedere tra 4 e 6 ore per il completamento.
- Distribuire in modo uniforme il consumo di UR e l'archiviazione dei dati in tutte le partizioni logiche. Questa ripartizione garantisce anche la distribuzione uniforme dell'utilizzo di UR e dello spazio di archiviazione tra le partizioni fisiche.
  - Se scegli una chiave di primo livello che sembra avere una cardinalità elevata come UserId, ma in pratica il carico di lavoro esegue operazioni su un solo specifico UserId, è probabile che si verifichi una partizione calda poiché tutte le operazioni sono limitate a una o poche partizioni fisiche.
Carichi di lavoro con intensa attività di lettura: è consigliabile scegliere chiavi di partizioni gerarchiche che appaiono frequentemente nelle query.
- Ad esempio, un carico di lavoro che esegue spesso query per escludere sessioni utente specifiche in un'applicazione multi-tenant può trarre vantaggio dalle chiavi di partizioni gerarchiche di TenantId, UserId e SessionId, in tale ordine. Le query possono essere instradate in modo efficiente solo alle partizioni fisiche pertinenti includendo la chiave di partizione nel predicato del filtro. Per altre informazioni sulla scelta delle chiavi di partizioni per carichi di lavoro con intensa attività di lettura, vedere la panoramica sul partizionamento.
Carichi di lavoro con intensa attività di scrittura: È consigliabile usare un valore cardinale elevato per il primo livello della chiave di partizione gerarchica. La cardinalità elevata implica che la chiave di primo livello (e i livelli successivi) ha almeno migliaia di valori univoci e valori più univoci rispetto al numero di partizioni fisiche.
- Si supponga, ad esempio, di avere un carico di lavoro che isola i tenant in base alla chiave di partizione e che abbia alcuni tenant di grandi dimensioni con attività di scrittura più intensa rispetto ad altri. Attualmente, Azure Cosmos DB interrompe l'inserimento di dati su qualsiasi valore della chiave di partizione se supera i 20 GB di dati. In questo carico di lavoro, Microsoft e Contoso sono tenant di grandi dimensioni e si prevede che la crescita sia molto più veloce rispetto ad altri tenant di Microsoft. Per evitare il rischio di non poter inserire dati per questi tenant, le chiavi di partizione gerarchiche consentono di ridimensionare questi tenant oltre il limite di 20 GB. È possibile aggiungere altri livelli come UserId e SessionId per garantire una maggiore scalabilità tra i tenant.
- Per assicurarsi che il carico di lavoro possa supportare le scritture per tutti i documenti con la stessa chiave di primo livello, è consigliabile usare l'ID elemento come chiave di secondo o terzo livello.
- Se il primo livello non ha cardinalità elevata e si raggiunge il limite di partizione logica di 20 GB nella chiave di partizione, è consigliabile usare una chiave di partizione sintetica anziché una chiave di partizione gerarchica.

Esempio di caso d'uso

Si supponga di avere uno scenario multi-tenant in cui archiviare le informazioni sugli eventi per gli utenti in ogni tenant. Le informazioni sugli eventi potrebbero avere occorrenze di eventi tra cui, ad esempio, accesso, clickstream o eventi di pagamento.

In uno scenario reale, alcuni tenant possono crescere enormemente, con migliaia di utenti, mentre molti altri tenant sono più piccoli e hanno pochi utenti. Il partizionamento per /TenantId potrebbe causare il superamento del limite di archiviazione di 20 GB di Azure Cosmos DB su una singola partizione logica. Il partizionamento per /UserId esegue tutte le query tra partizioni dei tenant. Entrambi gli approcci presentano svantaggi significativi.

L'uso di una chiave di partizione sintetica che combina TenantId e UserId aggiunge complessità all'applicazione. Inoltre, le query delle chiavi di partizioni sintetiche per un tenant sono ancora tra partizioni, a meno che tutti gli utenti non siano noti e specificati in anticipo.

Se il carico di lavoro include tenant con modelli di carico di lavoro approssimativamente identici, la chiave di partizione gerarchica può essere utile. Con le chiavi di partizioni gerarchiche è possibile eseguire prima la partizione in TenantIde quindi in UserId. Se si prevede che la combinazione di TenantId e UserId produca partizioni che superano 20 GB, è anche possibile partizionare ulteriormente fino a un altro livello, ad esempio in SessionId. La profondità complessiva non può superare tre livelli. Quando una partizione fisica supera 50 GB di spazio di archiviazione, Azure Cosmos DB divide automaticamente la partizione fisica in modo che circa la metà dei dati si trovi in una partizione fisica e l'altra metà si trovi nell'altra partizione. In effetti, la sottopartizione implica che un singolo valore TenantId può superare 20 GB di dati ed è possibile per TenantId che dati siano ripartiti in più partizioni fisiche.

Le query che specificano TenantIdo sia TenantId che UserId vengono instradate in modo efficiente solo al subset di partizioni fisiche che contengono i dati pertinenti. Se si specifica il percorso della chiave di partizione con sottopartizioni completo o con prefisso, è possibile evitare in modo efficace una query full fan-out. Ad esempio, se il contenitore aveva 1.000 partizioni fisiche, ma un valore specifico TenantId era solo su cinque partizioni fisiche, la query verrà instradata al numero inferiore di partizioni fisiche pertinenti.

Usare l'ID elemento nella gerarchia

Se il contenitore ha una proprietà con una vasta gamma di valori possibili, è probabile che la proprietà sia una scelta ottimale per la chiave di partizione per l'ultimo livello della gerarchia. Un esempio possibile di questo tipo di proprietà è l'ID elemento. L'ID dell'elemento della proprietà di sistema esiste in ogni elemento nel contenitore. Aggiungendo l'ID elemento come altro livello, si garantisce la possibilità di un ridimensionamento oltre il limite di 20 GB delle chiavi di partizioni logiche. È possibile il ridimensionamento oltre questo limite per il primo livello o per i primi e i secondi livelli di chiavi.

Ad esempio, potrebbe essere disponibile un contenitore per un carico di lavoro multi-tenant partizionato da TenantId e UserId. Se è possibile che una singola combinazione di TenantId e UserId superi 20 GB, è consigliabile partizionare usando tre livelli di chiavi, con la chiave di terzo livello con elevata cardinalità. Un esempio di questo scenario è il caso in cui la chiave di terzo livello sia un GUID con cardinalità naturalmente elevata. È improbabile che la combinazione di TenantId, UserId e un GUID superi 20 GB, quindi la combinazione di TenantId e UserId può essere ridimensionata in modo efficace oltre 20 GB.

Per altre informazioni sull'uso dell'ID elemento come chiave di partizione, vedere la panoramica sul partizionamento.

Introduzione

Importante

L'uso di contenitori che usano chiavi di partizione gerarchica è supportato solo nelle versioni dell'SDK seguenti. È necessario usare un SDK supportato per creare nuovi contenitori con chiavi di partizioni gerarchiche e per eseguire operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD) o di query sui dati. Se si vuole usare un SDK o un connettore attualmente non supportato, inviare una richiesta nel forum della community.

Trovare la versione di anteprima più recente dell'SDK supportato:

SDK	Versioni supportate	Collegamento di Gestione pacchetti
.NET SDK v3	> = 3.33.0	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.33.0/
Java SDK v4	> = 4.42.0	https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/cosmos/azure-cosmos/CHANGELOG.md#4420-2023-03-17/
JavaScript SDK v4	4.0.0	https://www.npmjs.com/package/@azure/cosmos/
Python SDK	> = 4.6.0	https://pypi.org/project/azure-cosmos/4.6.0/

Creare un contenitore usando chiavi di partizioni gerarchiche

Per iniziare, creare un nuovo contenitore usando un elenco predefinito di percorsi chiave di sottopartizionamento fino a tre livelli di profondità.

È possibile creare un nuovo contenitore usando una di queste opzioni:

Portale di Azure
SDK
Modello di Azure Resource Manager
Emulatore di Azure Cosmos DB

Portale di Azure

Il modo più semplice per creare un contenitore e specificare chiavi di partizioni gerarchiche consiste nell'uso del portale di Azure.

Accedere al portale di Azure.
Passare alla pagina dell'account Azure Cosmos DB for NoSQL esistente.
Nel menu a sinistra, selezionare Esplora dati.
In Esplora dati, selezionare l'opzione Nuovo contenitore.
In Nuovo contenitore, per Chiave di partizione immettere /TenantId. Per i campi rimanenti, immettere qualsiasi valore corrispondente allo scenario.

Note

Qui viene usato /TenantId come esempio. È possibile specificare qualsiasi chiave per il primo livello quando si implementano chiavi di partizioni gerarchiche nei propri contenitori.
Selezionare Aggiungi chiave di partizione gerarchica due volte.
Per i secondi e i terzi livelli di sottopartizione, immettere rispettivamente /UserId e /SessionId.
Fare clic su OK per creare il contenitore.

SDK

Quando si crea un nuovo contenitore usando l'SDK, definire un elenco di percorsi chiave di sottopartizionamento fino a tre livelli di profondità. Usare l'elenco di chiavi di sottopartizioni quando si configurano le proprietà del nuovo contenitore.

// List of partition keys, in hierarchical order. You can have up to three levels of keys.
List<string> subpartitionKeyPaths = new List<string> { 
    "/TenantId",
    "/UserId",
    "/SessionId"
};

// Create a container properties object
ContainerProperties containerProperties = new ContainerProperties(
    id: "<container-name>",
    partitionKeyPaths: subpartitionKeyPaths
);

// Create a container that's subpartitioned by TenantId > UserId > SessionId
Container container = await database.CreateContainerIfNotExistsAsync(containerProperties, throughput: 400);

// List of partition keys, in hierarchical order. You can have up to three levels of keys.
List<String> subpartitionKeyPaths = new ArrayList<String>();
subpartitionKeyPaths.add("/TenantId");
subpartitionKeyPaths.add("/UserId");
subpartitionKeyPaths.add("/SessionId");

//Create a partition key definition object with Kind ("MultiHash") and Version V2
PartitionKeyDefinition subpartitionKeyDefinition = new PartitionKeyDefinition();
subpartitionKeyDefinition.setPaths(subpartitionKeyPaths);
subpartitionKeyDefinition.setKind(PartitionKind.MULTI_HASH);
subpartitionKeyDefinition.setVersion(PartitionKeyDefinitionVersion.V2);

// Create a container properties object
CosmosContainerProperties containerProperties = new CosmosContainerProperties("<container-name>", subpartitionKeyDefinition);

// Create a throughput properties object
ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

// Create a container that's subpartitioned by TenantId > UserId > SessionId
Mono<CosmosContainerResponse> container = database.createContainerIfNotExists(containerProperties, throughputProperties);

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);

container = database.create_container(
        id=container_name, partition_key=PartitionKey(path=["/tenantId", "/userId", "/sessionId"], kind="MultiHash")
    )

_, err = db.CreateContainer(context.Background(), azcosmos.ContainerProperties{
	ID: "demo_container",
	PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{
		Paths:   []string{"/TenantId", "/UserId", "/SessionId"},
		Kind:    azcosmos.PartitionKeyKindMultiHash,
		Version: 2,
	},
}, nil)

Modelli di Gestione risorse di Azure

Il modello di Azure Resource Manager per un contenitore sottopartizionato è quasi identico a un contenitore standard. L'unica differenza chiave è il valore del percorso properties/partitionKey. Per altre informazioni sulla creazione di un modello di Azure Resource Manager per una risorsa di Azure Cosmos DB, vedere Informazioni di riferimento sul modello di Azure Resource Manager per Azure Cosmos DB.

Configurare l'oggetto partitionKey usando i valori nella tabella seguente per creare un contenitore sottopartizionato:

Path	valore
`paths`	Elenco di chiavi di partizioni gerarchiche (max tre livelli di profondità)
`kind`	`MultiHash`
`version`	`2`

Esempio di definizione di chiave di partizione

Si supponga, ad esempio, di avere una chiave di partizione gerarchica composta da TenantId>UserId>SessionId. L'oggetto partitionKey verrà configurato per includere tutti e tre i valori nella proprietà paths, un valore kind di MultiHash e un valore version di 2.

Bicipite
JSON

partitionKey: {
  paths: [
    '/TenantId'
    '/UserId'
    '/SessionId'
  ]
  kind: 'MultiHash'
  version: 2
}

"partitionKey": {
    "paths": [
        "/TenantId",
        "/UserId",
        "/SessionId"
    ],
    "kind": "MultiHash",
    "version": 2
}

Per altre informazioni sull'oggetto partitionKey, vedere la specifica ContainerPartitionKey.

Emulatore di Azure Cosmos DB

È possibile testare la funzionalità di sottopartizionamento usando l'ultima versione dell'emulatore locale per Azure Cosmos DB. Per abilitare la il sottopartizionamento nell'emulatore, avviare l'emulatore dalla directory di installazione con il flag /EnablePreview:

.\CosmosDB.Emulator.exe /EnablePreview

Avviso

L'emulatore attualmente non supporta tutte le funzionalità della chiave di partizione gerarchica come portale. L'emulatore attualmente non supporta:

Uso di Esplora dati per creare contenitori con chiavi di partizioni gerarchiche
Uso di Esplora dati per esplorare e interagire con gli elementi usando chiavi di partizioni gerarchiche

Per altre informazioni, vedere Emulatore di Azure Cosmos DB.

Usare gli SDK per gestire contenitori con chiavi di partizioni gerarchiche

Quando esiste un contenitore con chiavi di partizioni gerarchiche, usare le versioni specificate precedentemente degli SDK .NET o Java per eseguire operazioni ed eseguire query su tale contenitore.

Aggiungere un elemento a un contenitore

Esistono due opzioni per aggiungere un nuovo elemento a un contenitore con chiavi di partizioni gerarchiche abilitate:

Estrazione automatica
Specifica manuale del percorso

Estrazione automatica

Se si passa un oggetto con il valore della chiave di partizione impostato, l'SDK può estrarre automaticamente il percorso completo della chiave di partizione.

// Create a new item
UserSession item = new UserSession()
{
    id = "f7da01b0-090b-41d2-8416-dacae09fbb4a",
    TenantId = "Microsoft",
    UserId = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    SessionId = "0000-11-0000-1111"
};

// Pass in the object, and the SDK automatically extracts the full partition key path
ItemResponse<UserSession> createResponse = await container.CreateItemAsync(item);

// Create a new item
UserSession item = new UserSession();
item.setId("f7da01b0-090b-41d2-8416-dacae09fbb4a");
item.setTenantId("Microsoft");
item.setUserId("00aa00aa-bb11-cc22-dd33-44ee44ee44ee");
item.setSessionId("0000-11-0000-1111");
   
// Pass in the object, and the SDK automatically extracts the full partition key path
Mono<CosmosItemResponse<UserSession>> createResponse = container.createItem(item);

 // Create a new item
const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
    SessionId: '0000-11-0000-1111'
}

// Pass in the object, and the SDK automatically extracts the full partition key path
const { resource: document } = await = container.items.create(item);

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

Automatic extraction is not supported in the Go SDK.

Specifica manuale del percorso

La classe PartitionKeyBuilder nell'SDK può costruire un valore per un percorso della chiave di partizione gerarchica definito in precedenza. Usare questa classe quando si aggiunge un nuovo elemento a un contenitore in cui è abilitato il sottopartizionamento.

Suggerimento

Su larga scala, le prestazioni potrebbero essere migliorate se si specifica il percorso completo della chiave di partizione, anche se l'SDK può estrarre il percorso dall'oggetto.

// Create a new item object
PaymentEvent item = new PaymentEvent()
{
    id = Guid.NewGuid().ToString(),
    TenantId = "Microsoft",
    UserId = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    SessionId = "0000-11-0000-1111"
};

// Specify the full partition key path when creating the item
PartitionKey partitionKey = new PartitionKeyBuilder()
            .Add(item.TenantId)
            .Add(item.UserId)
            .Add(item.SessionId)
            .Build();

// Create the item in the container
ItemResponse<PaymentEvent> createResponse = await container.CreateItemAsync(item, partitionKey);

// Create a new item object
UserSession item = new UserSession();
item.setTenantId("Microsoft");
item.setUserId("00aa00aa-bb11-cc22-dd33-44ee44ee44ee");
item.setSessionId("0000-11-0000-1111");
item.setId(UUID.randomUUID().toString());

// Specify the full partition key path when creating the item
PartitionKey partitionKey = new PartitionKeyBuilder()
            .add(item.getTenantId())
            .add(item.getUserId())
            .add(item.getSessionId())
            .build();
       
// Create the item in the container     
Mono<CosmosItemResponse<UserSession>> createResponse = container.createItem(item, partitionKey);

const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
    SessionId: '0000-11-0000-1111'
}

// Specify the full partition key path when creating the item
const partitionKey: PartitionKey = new PartitionKeyBuilder()
    .addValue(item.TenantId)
    .addValue(item.UserId)
    .addValue(item.SessionId)
    .build();

// Create the item in the container
const { resource: document } = await container.items.create(item, partitionKey);

Per Python, assicurarsi che i valori per tutti i campi nel percorso della chiave di partizione siano specificati nella definizione dell'elemento.

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

NewPartitionKey espone un'API simile a un generatore per costruire un valore di chiave di partizione. Il valore è un oggetto PartitionKey che può essere usato per creare elementi nel contenitore.

tenantId := "Microsoft"
userId := "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
sessionId := "0000-11-0000-1111"

pk := azcosmos.NewPartitionKeyString(tenantId).AppendString(userId).AppendString(sessionId)

data := map[string]any{
	"id":        uuid.NewString(),
	"TenantId":  tenantId,
	"UserId":    userId,
	"SessionId": sessionId,
}

container, _ := c.NewContainer(dbName, containerName)

item, _ := json.Marshal(data)
container.CreateItem(context.Background(), pk, item, nil)

Eseguire una ricerca chiave/valore (lettura di punti) di un elemento

Le ricerche chiave/valore (letture di punti) vengono eseguite in modo simile a un contenitore non sottopartizionato. Si supponga, ad esempio, di avere una chiave di partizione gerarchica composta da TenantId>UserId>SessionId. L'identificatore univoco per l'elemento è un GUID. È rappresentato come stringa che funge da identificatore univoco della transazione del documento. Per eseguire una lettura di punti su un singolo elemento, passare la proprietà id dell'elemento e il valore completo per la chiave di partizione, inclusi tutti e tre i componenti del percorso.

// Store the unique identifier
string id = "f7da01b0-090b-41d2-8416-dacae09fbb4a";

// Build the full partition key path
PartitionKey partitionKey = new PartitionKeyBuilder()
    .Add("Microsoft") //TenantId
    .Add("00aa00aa-bb11-cc22-dd33-44ee44ee44ee") //UserId
    .Add("0000-11-0000-1111") //SessionId
    .Build();

// Perform a point read
ItemResponse<UserSession> readResponse = await container.ReadItemAsync<UserSession>(
    id,
    partitionKey
);

// Store the unique identifier
String id = "f7da01b0-090b-41d2-8416-dacae09fbb4a"; 

// Build the full partition key path
PartitionKey partitionKey = new PartitionKeyBuilder()
    .add("Microsoft") //TenantId
    .add("00aa00aa-bb11-cc22-dd33-44ee44ee44ee") //UserId
    .add("0000-11-0000-1111") //SessionId
    .build();
    
// Perform a point read
Mono<CosmosItemResponse<UserSession>> readResponse = container.readItem(id, partitionKey, UserSession.class);

// Store the unique identifier
const id = "f7da01b0-090b-41d2-8416-dacae09fbb4a";

// Build the full partition key path
const partitionKey: PartitionKey = new PartitionKeyBuilder()
    .addValue(item.TenantId)
    .addValue(item.UserId)
    .addValue(item.SessionId)
    .build();

// Perform a point read
const { resource: document } = await container.item(id, partitionKey).read();

item_id = "f7da01b0-090b-41d2-8416-dacae09fbb4a"
pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "0000-11-0000-1111"]
container.read_item(item=item_id, partition_key=pk)

itemId := "some item id"
tenantId := "Microsoft"
userId := "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
sessionId := "0000-11-0000-1111"

// Build the full partition key path
pk := azcosmos.NewPartitionKeyString(tenantId).AppendString(userId).AppendString(sessionId)

// Perform a point read
item, err := container.ReadItem(context.Background(), pk, itemId, nil)

var result map[string]any
json.Unmarshal(item.Value, &result)

Eseguire una query

Il codice SDK usato per eseguire una query in un contenitore sottopartizionato è identico all'esecuzione di una query in un contenitore non sottopartizionato.

Quando la query specifica tutti i valori delle chiavi di partizioni nel filtro WHERE o in un prefisso della gerarchia di chiavi, l'SDK instrada automaticamente la query alle partizioni fisiche corrispondenti. Le query che forniscono solo il "centro" della gerarchia sono query tra partizioni.

Si supponga, ad esempio, di avere una chiave di partizione gerarchica composta da TenantId>UserId>SessionId. I componenti del filtro della query determinano se la query è una query a singola partizione, una query tra partizioni mirata o una query fan-out.

Quesito	Routing.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' AND c.SessionId = '0000-11-0000-1111'`	Instradato alla singola partizione logica e fisica che contiene i dati per i valori specificati di `TenantId`, `UserId` e `SessionId`.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'`	Instradato solo al sottoinsieme mirato di partizioni logiche e fisiche che contengono dati per i valori specificati di `TenantId` e `UserId`. Questa query è una query tra partizioni mirata che restituisce dati per un utente specifico nel tenant.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft'`	Instradato solo al sottoinsieme mirato di partizioni logiche e fisiche che contengono dati per il valore specificato di `TenantId`. Questa query è una query tra partizioni mirata che restituisce dati per tutti gli utenti in un tenant.
`SELECT * FROM c WHERE c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'`	Instradato a tutte le partizioni fisiche, generando una query tra partizioni fan-out.
`SELECT * FROM c WHERE c.SessionId = '0000-11-0000-1111'`	Instradato a tutte le partizioni fisiche, generando una query tra partizioni fan-out.

Query a partizione singola in un contenitore sottopartizionato

Di seguito è riportato un esempio di esecuzione di una query che include tutti i livelli di sottopartizionamento, rendendo effettivamente la query una query a partizione singola.

// Define a single-partition query that specifies the full partition key path
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM c WHERE c.TenantId = @tenant-id AND c.UserId = @user-id AND c.SessionId = @session-id")
    .WithParameter("@tenant-id", "Microsoft")
    .WithParameter("@user-id", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee")
    .WithParameter("@session-id", "0000-11-0000-1111");

// Retrieve an iterator for the result set
using FeedIterator<PaymentEvent> results = container.GetItemQueryIterator<PaymentEvent>(query);

while (results.HasMoreResults)
{
    FeedResponse<UserSession> resultsPage = await resultSet.ReadNextAsync();
    foreach(UserSession result in resultsPage)
    {
        // Process result
    }
}

// Define a single-partition query that specifies the full partition key path
String query = String.format(
    "SELECT * FROM c WHERE c.TenantId = '%s' AND c.UserId = '%s' AND c.SessionId = '%s'",
    "Microsoft",
    "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "0000-11-0000-1111"
);

// Retrieve an iterator for the result set
CosmosPagedFlux<UserSession> pagedResponse = container.queryItems(
    query, options, UserSession.class);

pagedResponse.byPage().flatMap(fluxResponse -> {
    for (UserSession result : page.getResults()) {
        // Process result
    }
    return Flux.empty();
}).blockLast();

// Define a single-partition query that specifies the full partition key path
const query: string = "SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' AND c.SessionId = '0000-11-0000-1111'";

// Retrieve an iterator for the result set
const queryIterator = container.items.query(query);

while (queryIterator.hasMoreResults()) {
    const { resources: results } = await queryIterator.fetchNext();
    // Process result
}

pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "0000-11-0000-1111"]
items = list(container.query_items(
    query="SELECT * FROM r WHERE r.tenantId=@tenant_id and r.userId=@user_id and r.sessionId=@session_id",
    parameters=[
        {"name": "@tenant_id", "value": pk[0]},
        {"name": "@user_id", "value": pk[1]},
        {"name": "@session_id", "value": pk[2]}
    ]
))

tenantId := "Microsoft"
userId := "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
sessionId := "0000-11-0000-1111"

// Build the full partition key path
pk := azcosmos.NewPartitionKeyString(tenantId).AppendString(userId).AppendString(sessionId)

query := "SELECT * FROM r WHERE r.TenantId=@tenant_id and r.UserId=@user_id and r.SessionId=@session_id"

pager := container.NewQueryItemsPager(query, pk, &azcosmos.QueryOptions{
	QueryParameters: []azcosmos.QueryParameter{
		{
			Name:  "@tenant_id",
			Value: tenantId,
		},
		{
			Name:  "@user_id",
			Value: userId,
		},
		{
			Name:  "@session_id",
			Value: sessionId,
		},
	},
})

for pager.More() {
    // Read the next page of results
}

Query a partizione multipla mirata in un contenitore sottopartizionato

Di seguito è riportato un esempio di query che include un sottoinsieme dei livelli di sottopartizionamento, rendendo effettivamente la query una query tra partizioni multiple mirata.

// Define a targeted cross-partition query specifying prefix path[s]
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM c WHERE c.TenantId = @tenant-id")
    .WithParameter("@tenant-id", "Microsoft")

// Retrieve an iterator for the result set
using FeedIterator<PaymentEvent> results = container.GetItemQueryIterator<PaymentEvent>(query);

while (results.HasMoreResults)
{
    FeedResponse<UserSession> resultsPage = await resultSet.ReadNextAsync();
    foreach(UserSession result in resultsPage)
    {
        // Process result
    }
}

// Define a targeted cross-partition query specifying prefix path[s]
String query = String.format(
    "SELECT * FROM c WHERE c.TenantId = '%s'",
    "Microsoft"
);

// Retrieve an iterator for the result set
CosmosPagedFlux<UserSession> pagedResponse = container.queryItems(
    query, options, UserSession.class);

pagedResponse.byPage().flatMap(fluxResponse -> {
    for (UserSession result : page.getResults()) {
        // Process result
    }
    return Flux.empty();
}).blockLast();

// Define a targeted cross-partition query specifying prefix path[s]
const query: string = "SELECT * FROM c WHERE c.TenantId = 'Microsoft'";

// Retrieve an iterator for the result set
const queryIterator = container.items.query(query);

while (queryIterator.hasMoreResults()) {
    const { resources: results } = await queryIterator.fetchNext();
    // Process result
}

pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "0000-11-0000-1111"]
# enable_cross_partition_query should be set to True as the container is partitioned
items = list(container.query_items(
    query="SELECT * FROM r WHERE r.tenantId=@tenant_id and r.userId=@user_id",
    parameters=[
        {"name": "@tenant_id", "value": pk[0]},
        {"name": "@user_id", "value": pk[1]}
    ],
    enable_cross_partition_query=True
))

tenantId := "Microsoft"
userId := "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"

emptyPartitionKey := azcosmos.NewPartitionKey()

query := "SELECT * FROM r WHERE r.TenantId=@tenant_id and r.UserId=@user_id"

pager := container.NewQueryItemsPager(query, emptyPartitionKey, &azcosmos.QueryOptions{
	QueryParameters: []azcosmos.QueryParameter{
		{
			Name:  "@tenant_id",
			Value: tenantId,
		},
		{
			Name:  "@user_id",
			Value: userId,
		},
	},
})

for pager.More() {
    // Read the next page of results
}

Limitazioni e problemi noti

L'uso di contenitori che usano chiavi di partizioni gerarchiche è supportato solo nell'SDK .NET v3, nell'SDK Java v4, nell'SDK Python e nella versione di anteprima dell'SDK JavaScript. È necessario usare un SDK supportato per creare nuovi contenitori con chiavi di partizioni gerarchiche e per eseguire operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD) o di query sui dati. Il supporto per altri SDK, incluso Python, attualmente non è disponibile.
Esistono limitazioni con vari connettori di Azure Cosmos DB, ad esempio con Azure Data Factory.
È possibile specificare chiavi di partizioni gerarchiche solo fino a tre livelli in profondità.
Le chiavi di partizioni gerarchiche attualmente possono essere abilitate solo in nuovi contenitori. È necessario impostare i percorsi delle chiavi di partizioni al momento della creazione del contenitore e non è possibile modificarli in un secondo momento. Per usare partizioni gerarchiche in contenitori esistenti, creare un nuovo contenitore con chiavi di partizione gerarchiche impostate e spostare i dati usando processi di copia del contenitore.
Le chiavi di partizioni gerarchiche attualmente sono supportate solo per account API per NoSQL. Le API per MongoDB e Cassandra attualmente non sono supportate.
Le chiavi di partizione gerarchica attualmente non sono supportate con la funzionalità utenti e autorizzazioni. Non è possibile assegnare un'autorizzazione a un prefisso parziale del percorso della chiave di partizione gerarchica. Le autorizzazioni possono essere assegnate solo all'intero percorso della chiave di partizione logica. Ad esempio, se il partizionamento è stato effettuato da TenantId - >UserId, non è possibile assegnare un'autorizzazione per un valore specifico di TenantId. Tuttavia, è possibile assegnare un'autorizzazione per una chiave di partizione se si specifica sia il valore per TenantId che UserId.

Passaggi successivi

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-07-27