Métricas de indexação no Azure Cosmos DB

Artigo
08/15/2024

APLICA-SE A: NoSQL

O Azure Cosmos DB fornece métricas de indexação para mostrar os caminhos indexados utilizados e os caminhos indexados recomendados. Você pode usar as métricas de indexação para otimizar o desempenho da consulta, principalmente nos casos nos quais você não tenha certeza de como modificar a política de indexação).

Versões com suporte SDK

As métricas de indexação têm suporte nas seguintes versões do SDK: | SDK | Versões suportadas | | --- | --- | | .NET SDK v3 | >= 3.21.0 | | Java SDK v4 | >= 4.19.0 | | Python SDK | >= 4.6.0 |

Habilitar as métricas de indexação

Você pode habilitar métricas de indexação para uma consulta definindo a propriedade PopulateIndexMetrics como true. Se não for especificado, a PopulateIndexMetrics será padronizada como false. Só recomendamos habilitar as métricas de indexação para solucionar problemas de desempenho de consulta. Enquanto suas consultas e a política de indexação permanecerem iguais, é improvável que as métricas de indexação sejam alteradas. Em vez disso, recomendamos identificar consultas dispendiosas monitorando a cobrança e a latência de RU de consulta usando logs de diagnóstico.

    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);
        }

    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());
        }
    });

    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();

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);

Você pode capturar métricas de índice passando a palavra-chave populate_index_metrics nos itens de consulta e, em seguida, lendo o valor do cabeçalho "x-ms-cosmos-index-utilization" da resposta. Esse cabeçalho será retornado somente se a consulta retornar alguns itens.

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'])

Saída de exemplo

Nesta consulta de exemplo, observamos os caminhos utilizados /Item/? e /Price/?, e os índices compostos potenciais (/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
    ---

Caminhos indexados utilizados

Os índices individuais e os índices compostos utilizados mostram, respectivamente, os caminhos incluídos e os índices compostos usados pela consulta. As consultas podem usar vários caminhos indexados, bem como uma combinação de caminhos incluídos e índices compostos. Se um caminho indexado não estiver listado como utilizado, a remoção do caminho indexado não causará nenhum impacto sobre o desempenho da consulta.

Considere a lista de caminhos indexados utilizados como evidência de que uma consulta utilizou esses caminhos. Se você não tiver certeza se um novo caminho indexado melhorará o desempenho da consulta, tente adicionar os novos caminhos indexados e verificar se a consulta os utiliza.

Caminhos indexados potenciais

Os índices individuais potenciais e os índices compostos potenciais mostram, respectivamente, os caminhos incluídos e os índices compostos que a consulta pode utilizar caso sejam adicionados. Se você vir possíveis caminhos indexados, considere adicioná-los à política de indexação, e observe se eles melhoram o desempenho da consulta.

Considere a lista de caminhos indexados potenciais como recomendações, em vez de evidências concretas de que uma consulta usará um caminho indexado específico. Os caminhos indexados potenciais não são uma lista completa de caminhos indexados que uma consulta pode utilizar. Além disso, é possível que alguns caminhos indexados potenciais não tenham nenhum impacto no desempenho da consulta. Adicione os caminhos indexados recomendados e confirme se eles melhoram o desempenho da consulta.

Observação

Você tem algum comentário sobre as métricas de indexação? Queremos saber sua opinião! Sinta-se à vontade para compartilhar comentários diretamente com a equipe de engenharia do Azure Cosmos DB: cosmosdbindexing@microsoft.com

Pontuação de impacto do índice

A pontuação de impacto do índice é a probabilidade de um caminho indexado, com base na forma da consulta, ter um impacto significativo no desempenho da consulta. Em outras palavras, a pontuação de impacto do índice é a probabilidade de que, sem esse caminho indexado específico, o custo de RU da consulta teria sido substancialmente maior.

Há duas pontuações de impacto do índice possíveis: alta e baixa. Se você tiver vários caminhos indexados potenciais, recomendamos focar em caminhos indexados com uma pontuação alta de impacto.

O único critério usado na pontuação de impacto do índice é a forma de consulta. Por exemplo, na consulta abaixo, ao caminho indexado /name/? seria atribuído a uma pontuação alta de impacto do índice:

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

O impacto real, dependendo da natureza dos dados. Se apenas alguns itens corresponderem ao filtro /name, o caminho indexado melhorará substancialmente o custo de da consulta. No entanto, se a maioria dos itens acabar correspondendo ao filtro /name, o caminho indexado poderá não melhorar o desempenho da consulta. Em cada um desses casos, o caminho indexado /name/? recebe uma pontuação alta de impacto do índice porque, com base na forma da consulta, o caminho indexado tem uma alta probabilidade de melhorar o desempenho da consulta.

Mais exemplos

Consulta de exemplo

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

Métricas de índice

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
    ---

Essas métricas de índice mostram que a consulta usou os caminhos indexados /name/?, /age/?, /town/? e /timestamp/?. As métricas de índice também indicam que há uma alta probabilidade de que adicionar os índices compostos (/name ASC, /town ASC, /age ASC) e (/name ASC, /town ASC, /timestamp ASC) melhorarão ainda mais o desempenho.

Próximas etapas

Leia mais sobre indexação nos seguintes artigos:

Compartilhar via