Come configurare gli indici secondari globali di Azure Cosmos DB per NoSQL (anteprima)

2025-05-19

SI APPLICA A: NoSQL

Importante

Gli indici secondari globali di Azure Cosmos DB per NoSQL sono attualmente in anteprima. Questa anteprima viene fornita senza un contratto di servizio. Al momento, non è consigliabile usare indici secondari globali per i carichi di lavoro di produzione. Alcune funzionalità di questa anteprima potrebbero non essere supportate o potrebbero essere limitate. Per altre informazioni, vedere le condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure.

Gli indici secondari globali offrono un modo efficace per ottimizzare le prestazioni delle query e semplificare la logica dell'applicazione archiviando i dati con una chiave di partizione diversa e/o un modello di dati. Questo articolo descrive come creare indici secondari globali e come usarli per evitare query tra partizioni.

Prerequisiti

Un account Azure Cosmos DB esistente.
- Se si ha una sottoscrizione di Azure, creare un nuovo account.
- Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
- In alternativa, è possibile provare Azure Cosmos DB gratuitamente prima di eseguire il commit.

Abilitare gli indici secondari globali

Abilitare la funzionalità di indice secondario globale per l'account Azure Cosmos DB. I backup continui devono essere attivati per l'account prima di abilitare gli indici secondari globali.

Portale di Azure
Interfaccia della riga di comando di Azure

Accedi al portale di Azure.
Passare all'account Azure Cosmos DB per NoSQL.
Nel menu delle risorse selezionare Impostazioni.
Passare alla pagina Funzionalità. Selezionare quindi Indice secondario globale per l'API NoSQL (anteprima) e Abilita.

Usare l'interfaccia della riga di comando di Azure per abilitare la funzionalità di indice secondario globale usando un comando nativo o un'operazione API REST nell'account Azure Cosmos DB per NoSQL.

Accedi all'Azure CLI.
```
az login
```
Annotazioni

Questo richiede l'interfaccia della riga di comando di Azure, vedere come installare l'interfaccia della riga di comando di Azure.

Definire le variabili per il gruppo di risorse e il nome dell'account dell'account Azure Cosmos DB per NoSQL esistente.

# Variable for resource group name
$resourceGroupName="<resource-group-name>"

# Variable for account name
$accountName="<account-name>"

# Variable for Azure subscription
$subscriptionId="<subscription-id>"

Creare un nuovo file JSON denominato capabilities.json usando il manifesto delle funzionalità.
```
{
  "properties": {
    "enableMaterializedViews": true
  }
}
```
Annotazioni

Il nome della proprietà per abilitare gli indici secondari globali è enableMaterializedViews, ovvero il nome della funzionalità precedente. L'abilitazione delle viste materializzate consentirà gli indici secondari globali.

Ottenere l'identificatore dell'account e archiviarlo in una variabile di shell denominata $accountId.

$accountId="/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$accountName"

Abilitare la funzionalità di anteprima dell'indice secondario globale per l'account usando l'API REST e az rest con un verbo HTTP PATCH .

az rest \
    --method PATCH \
    --uri "https://management.azure.com/$accountId/?api-version=2022-11-15-preview" \
    --body @capabilities.json

Creare un indice secondario globale

Dopo aver abilitato la funzionalità di indice secondario globale, è possibile creare indici secondari globali.

Creare un contenitore di origine

Gli indici secondari globali archiviano una copia dei dati dal contenitore di origine. Prima di creare un indice secondario globale, creare il contenitore di origine da cui verrà compilato il contenitore dell'indice. Se si ha già un contenitore nell'account Azure Cosmos DB che si vuole usare come origine, è possibile ignorare questi passaggi.

Usare il portale di Azure, gli SDK di Azure, l'interfaccia della riga di comando di Azure o l'API REST per creare un contenitore di origine denominato gsi-src con /customerId come percorso della chiave di partizione.

Annotazioni

Il campo /customerId viene usato solo come esempio in questo articolo. Per i contenitori personalizzati, selezionare una chiave di partizione che funzioni per la soluzione.
Inserire alcuni elementi nel contenitore di origine. Per seguire gli esempi illustrati in questo articolo, assicurarsi che gli elementi abbiano customerId e emailAddress campi. Un elemento di esempio potrebbe essere simile al seguente:
```
{
  "id": "eaf0338e-2b61-4163-822f-7bef75bf51de",
  "customerId": "36c7cc3d-1709-45c6-819f-10e5586a6cb7",
  "emailAddress": "justine@contoso.com",
  "name": "Justine"
}
```
Suggerimento

In questo esempio il contenitore di origine viene popolato con dati di esempio prima di aggiungere un contenitore di indici. È anche possibile creare un indice secondario globale da un contenitore di origine vuoto.

Creare un contenitore di indici secondario globale

Dopo aver creato il contenitore di origine, è possibile creare un contenitore di indici secondari globale usando il portale di Azure o l'interfaccia della riga di comando di Azure.

Portale di Azure
Interfaccia della riga di comando di Azure

Passare alla sezione Esplora dati nel proprio account Azure Cosmos DB. Selezionare il contenitore di origine, gsi-src in questo esempio, e selezionare Nuovo indice secondario globale nell'elenco a discesa.
L'ID del contenitore di origine sarà compilato automaticamente. Nel campo Index container ID (ID contenitore index ) immettere gsi-target.
Nel campo Global secondary index definition (Definizione indice secondario globale ) immettere SELECT c.customerId, c.emailAddress FROM c.
Nel campo Chiave di partizione immettere /emailAddress.
I contenitori di indici secondari globali devono utilizzare il throughput con scalabilità automatica. Configurare tutte le altre impostazioni del contenitore desiderate e selezionare OK per creare il contenitore dell'indice secondario globale.
Dopo aver creato il contenitore dell'indice secondario globale, i dati vengono sincronizzati automaticamente dal contenitore di origine. Provare a eseguire operazioni di creazione, aggiornamento ed eliminazione nel contenitore di origine. Verranno visualizzate le stesse modifiche propagate agli elementi nell'indice secondario globale.

Creare un indice secondario globale denominato gsi-target con un percorso di chiave di partizione diverso dal contenitore di origine. Per questo esempio, specificare /emailAddress come percorso della chiave di partizione per il contenitore gsi-target.
1. Creare un manifesto di definizione per un indice secondario globale e salvarlo in un file JSON denominato gsi-definition.json. I contenitori per indici secondari globali devono usare la velocità automatica scalabile. In questa fase, è anche possibile definire qualsiasi altra proprietà del contenitore pertinente, ad esempio un criterio di indicizzazione.
```
{
  "location": "West US 2",
  "tags": {},
  "properties": {
    "resource": {
      "id": "gsi-target",
      "partitionKey": {
        "paths": [
          "/emailAddress"
        ]
      },
      "materializedViewDefinition": {
        "sourceCollectionId": "gsi-src",
        "definition": "SELECT c.customerId, c.emailAddress FROM c"
      }
    },
    "options": {
      "autoscaleSettings": {
        "maxThroughput": 1000
      }
    }
  }
}        
```
Importante

Si noti che il percorso della chiave di partizione è impostato su /emailAddress.

La proprietà per la definizione di indici secondari globali è materializedViewDefinition, ovvero il nome precedente di questa funzionalità. sourceCollectionId Definisce il contenitore di origine e definition contiene una query per determinare il modello di dati del contenitore dell'indice. Il contenitore della fonte dell'indice secondario globale e la query di definizione non possono essere modificati dopo la creazione. Altre informazioni sulla definizione di indici secondari globali e vincoli di query.

Eseguire quindi una chiamata API REST per creare l'indice secondario globale come definito nel file gsi-definition.json . Usare l'interfaccia della riga di comando di Azure per effettuare la chiamata API REST.

Creare una variabile per il nome dell'indice secondario globale e del nome del database di origine:

# This should match the resource ID you defined in your json file
$gsiContainerName = "gsi-target"

# Database name for the source and index containers
$databaseName = "<Database that contains source container>"

# Azure Cosmos DB account name
$accountName = "<Azure Cosmos DB account name>"

# Resource name for your Azure Cosmos DB account
$resourceGroupName = "<Resource group for Azure Cosmos DB account>"

# Subscription id for your Azure Cosmos DB account
$subscriptionId = "<Subscription id>"

Costruire l'ID risorsa usando queste variabili.

$accountId = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$accountName"

Effettuare una chiamata API REST per creare l'indice secondario globale:

az rest \
    --method PUT \
    --uri "https://management.azure.com$accountId/sqlDatabases/$databaseName/containers/$gsiContainerName/?api-version=2022-11-15-preview" \
    --body @gsi-definition.json \
    --headers content-type=application/json \
    --output json \
    --verbose

Controllare lo stato della creazione globale del contenitore di indici secondari usando l'API REST:

az rest \
    --method GET \
    --uri "https://management.azure.com$accountId/sqlDatabases/$databaseName/containers/$gsiContainerName/?api-version=2022-11-15-preview" \
    --headers content-type=application/json \
    --query "{mvCreateStatus: properties.Status}"

Dopo aver creato l'indice secondario globale, i dati vengono sincronizzati automaticamente dal contenitore di origine. Provare a eseguire operazioni di creazione, aggiornamento ed eliminazione nel contenitore di origine. Verranno visualizzate le stesse modifiche propagate agli elementi nell'indice secondario globale.

Interrogare i dati dagli indici secondari globali

In questo esempio è presente un contenitore di origine partizionato in customerId e un contenitore di indice secondario globale partizionato in emailAddress. Senza il contenitore di indici, le query che includono solo l'oggetto emailAddress sarebbero tra partizioni, ma ora possono essere eseguite sull'indice secondario globale per aumentare l'efficienza.

L'esecuzione di query sui dati da indici secondari globali è simile all'esecuzione di query sui dati da qualsiasi altro contenitore. È possibile usare il portale di Azure, gli SDK di Azure o l'API REST per eseguire query sui dati negli indici secondari globali.

Container container = client.GetDatabase("gsi-db").GetContainer("gsi-target");

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"));

CosmosAsyncDatabase container = client.getDatabase("gsi-db");
CosmosAsyncContainer container = database.getContainer("gsi-target");

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'", null, MyClass.class);

const database = client.database("gsi-db");
const container = database.container("gsi-target");

const querySpec = {
    query: "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"
 };
const { resources: items } = await container.items
    .query(querySpec)
    .fetchAll();

database = client.get_database_client("gsi-db")
container = database.get_container_client("gsi-target")

query = "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"
container.query_items(
    query=query
)

Passaggi successivi

Panoramica della modellazione dei dati e del partizionamento dell'indice secondario globale