Indicizzazione delle metriche in Azure Cosmos DB

SI APPLICA A: NoSQL

Azure Cosmos DB fornisce metriche di indicizzazione per mostrare sia i percorsi indicizzati usati che i percorsi indicizzati consigliati. È possibile usare le metriche di indicizzazione per ottimizzare le prestazioni delle query, soprattutto nei casi in cui non si è certi di come modificare i criteri di indicizzazione).

Versioni di SDK supportate

Le metriche di indicizzazione sono supportate nelle versioni dell'SDK seguenti: | SDK | Versioni supportate | | --- | --- | | .NET SDK v3 | >= 3.21.0 | | Java SDK v4 | >= 4.19.0 | | Python SDK | >= 4.6.0 |

Abilitare le metriche di indicizzazione

È possibile abilitare l'indicizzazione delle metriche per una query impostando la proprietà PopulateIndexMetrics su true. Se non specificato, PopulateIndexMetrics si imposta per default su false. Si consiglia di abilitare solo le metriche dell'indice per la risoluzione dei problemi relativi alle prestazioni delle query. Fino a quando le query e i criteri di indicizzazione rimangano invariati, è poco probabile che le metriche dell'indice cambino. Si consiglia invece di identificare query dispendiose monitorando l'addebito e la latenza delle UR di query usando i log di diagnostica.

.NET SDK

    string sqlQueryText = "SELECT TOP 10 c.id FROM c WHERE c.Item = 'value1234' AND c.Price > 2";

    QueryDefinition query = new QueryDefinition(sqlQueryText);

    FeedIterator<Item> resultSetIterator = container.GetItemQueryIterator<Item>(
                query, requestOptions: new QueryRequestOptions
        {
            PopulateIndexMetrics = true
        });

    FeedResponse<Item> response = null;

    while (resultSetIterator.HasMoreResults)
        {
          response = await resultSetIterator.ReadNextAsync();
          Console.WriteLine(response.IndexMetrics);
        }

Java SDK Sync

    SqlQuerySpec querySpec = new SqlQuerySpec("SELECT TOP 10 c.id FROM c WHERE c.Item = 'value1234' AND c.Price > 2");
    CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
    options.setIndexMetricsEnabled(true);

    CosmosPagedIterable<JsonNode> items = container.queryItems(querySpec, options, JsonNode.class);

    // Print
    items.iterableByPage().forEach(itemResponse -> {
        logger.info("diagnostics: {}", itemResponse.getCosmosDiagnostics());
        for (JsonNode item : itemResponse.getResults()) {
            logger.info("Item: {}", item.toString());
        }
    });  

Java SDK Async

    SqlQuerySpec querySpec = new SqlQuerySpec("SELECT TOP 10 c.id FROM c WHERE c.Item = 'value1234' AND c.Price > 2");
    CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
    options.setIndexMetricsEnabled(true);

    CosmosPagedFlux<JsonNode> items = container.queryItems(querySpec, options, JsonNode.class);
    
    // Print
    items.byPage(100).flatMap(itemsResponse -> {
        logger.info("diagnostics: {}",itemsResponse.getCosmosDiagnostics());
        for (JsonNode item : itemsResponse.getResults()) {
            logger.info("Item: {}", item.toString());
        }
        executeCountQueryPrintSingleResultNumber.incrementAndGet();
        return Flux.just(itemsResponse);
    }).blockLast();   

JavaScript SDK

const querySpec = {
    query: "SELECT TOP 10 c.id FROM c WHERE c.Item = 'value1234' AND c.Price > 2",
  };
const { resources: resultsIndexMetrics, indexMetrics } = await container.items
    .query(querySpec, { populateIndexMetrics: true })
    .fetchAll();
console.log("IndexMetrics: ", indexMetrics);

Python SDK

È possibile acquisire le metriche degli indici passando la parola chiave populate_index_metrics negli elementi di query e quindi leggendo il valore per l'intestazione "x-ms-cosmos-index-utilization" dalla risposta. Questa intestazione viene restituita solo se la query restituisce alcuni elementi.

query_items = container.query_items(query="Select * from c",
    enable_cross_partition_query=True,
    populate_index_metrics=True)

print(container.client_connection.last_response_headers['x-ms-cosmos-index-utilization'])

Output di esempio

In questa query di esempio vengono osservati i percorsi utilizzati /Item/?, /Price/? e i potenziali indici compositi (/Item ASC, /Price ASC).

Index Utilization Information
  Utilized Single Indexes
    Index Spec: /Item/?
    Index Impact Score: High
    ---
    Index Spec: /Price/?
    Index Impact Score: High
    ---
  Potential Single Indexes
  Utilized Composite Indexes
  Potential Composite Indexes
    Index Spec: /Item ASC, /Price ASC
    Index Impact Score: High
    ---

Percorsi indicizzati utilizzati

Gli indici singoli e gli indici compositi utilizzati mostrano rispettivamente i percorsi compresi e gli indici compositi usati dalla query. Le query possono usare più percorsi indicizzati, nonché una combinazione di percorsi compresi e indici compositi. Se un percorso indicizzato non è elencato come usato, la rimozione del percorso indicizzato non avrà alcun impatto sulle prestazioni della query.

Si consideri l'elenco dei percorsi indicizzati utilizzati come prova che una query usa quei percorsi. Se non si è certi che un nuovo percorso indicizzato migliorerà le prestazioni delle query, provare ad aggiungere i nuovi percorsi indicizzati e verificare se la query li usa.

Eventuali percorsi indicizzati

I potenziali indici singoli e potenziali indici compositi mostrano rispettivamente i percorsi inclusi e gli indici compositi che, se aggiunti, la query potrebbe usare. Se vengono visualizzati eventuali percorsi indicizzati, è consigliabile aggiungerli ai criteri di indicizzazione e osservare se migliorano le prestazioni delle query.

Si consideri l'elenco di eventuali percorsi indicizzati come raccomandazioni anziché come una prova definitiva del fatto che una query userà un percorso indicizzato specifico. Gli eventuali percorsi indicizzati non sono un elenco completo di percorsi indicizzati che una query potrebbe usare. Inoltre, è possibile che alcuni eventuali percorsi indicizzati non abbiano alcun impatto sulle prestazioni delle query. Aggiungere i percorsi indicizzati consigliati e verificare che migliorino le prestazioni delle query.

Nota

Avete dei feedback sulle metriche di indicizzazione? Fatecelo sapere! È possibile condividere i feedback direttamente con il team di progettazione di Azure Cosmos DB: cosmosdbindexing@microsoft.com

Punteggio di impatto dell'indice

Il punteggio di impatto dell'indice è la probabilità che un percorso indicizzato, basato sul modello della query, abbia un impatto significativo sulle prestazioni delle query. In altre parole, il punteggio di impatto dell'indice rappresenta la probabilità che, senza tale percorso indicizzato specifico, l'addebito per le RU di query sarebbe stato notevolmente superiore.

Esistono due possibili punteggi di impatto sull'indice: alto e basso. Se è presente più di un eventuale percorso indicizzato, si consiglia di concentrarsi sui percorsi indicizzati con un punteggio di impatto elevato.

Gli unici criteri utilizzati nel punteggio di impatto dell'indice sono i modelli della query. Nella query seguente, ad esempio, al percorso indicizzato /name/? verrebbe assegnato un punteggio di impatto elevato sull'indice:

SELECT * 
FROM c
WHERE c.name = "Samer"

Impatto effettivo a seconda della natura dei dati. Se solo alcuni elementi corrispondono al /name filtro, il percorso indicizzato migliorerà notevolmente l'addebito UR delle query. Tuttavia, se la maggior parte degli elementi corrisponde comunque al /name filtro, il percorso indicizzato potrebbe non migliorare le prestazioni delle query. In ognuno di questi casi, al percorso indicizzato /name/? verrebbe assegnato un punteggio di impatto elevato sull'indice perché, in base al modello della query, il percorso indicizzato ha una probabilità elevata di migliorare le prestazioni delle query.

Esempi aggiuntivi

Query di esempio

SELECT c.id 
FROM c 
WHERE c.name = 'Tim' AND c.age > 15 AND c.town = 'Redmond' AND c.timestamp > 2349230183

Metriche dell'indice

Index Utilization Information
  Utilized Single Indexes
    Index Spec: /name/?
    Index Impact Score: High
    ---
    Index Spec: /age/?
    Index Impact Score: High
    ---
    Index Spec: /town/?
    Index Impact Score: High
    ---
    Index Spec: /timestamp/?
    Index Impact Score: High
    ---
  Potential Single Indexes
  Utilized Composite Indexes
  Potential Composite Indexes
    Index Spec: /name ASC, /town ASC, /age ASC
    Index Impact Score: High
    ---
    Index Spec: /name ASC, /town ASC, /timestamp ASC
    Index Impact Score: High
    ---

Queste metriche dell’indice mostrano che la query ha usato i percorsi indicizzati /name/?, /age/?, /town/?e /timestamp/?. Le metriche dell'indice indicano anche che è altamente probabile che l'aggiunta di indici compositi (/name ASC, /town ASC, /age ASC) e (/name ASC, /town ASC, /timestamp ASC) migliorerà ulteriormente le prestazioni.

Passaggi successivi

Altre informazioni sull'indicizzazione sono disponibili negli articoli seguenti:

• Panoramica dell'indicizzazione
• Come gestire i criteri di indicizzazione