Indexação de métricas no Azure Cosmos DB

Artigo
08/15/2024

APLICA-SE A: NoSQL

O Azure Cosmos DB proporciona 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, especialmente nos casos em que não tem certeza de como modificar a política de indexação).

Versões do SDK suportadas

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

Habilitar métricas de indexação

Você pode habilitar métricas de indexação para uma consulta definindo a PopulateIndexMetrics propriedade como true. Quando não especificado, PopulateIndexMetrics o padrão é .false Recomendamos apenas habilitar as métricas de índice para solucionar problemas de desempenho da consulta. Enquanto as consultas e a política de indexação permanecerem as mesmas, é improvável que as métricas do índice sejam alteradas. Em vez disso, recomendamos identificar consultas caras monitorando a carga e a latência da RU da 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 em itens de consulta e, em seguida, lendo o valor para o 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'])

Exemplo de saída

Neste exemplo de consulta, observamos os caminhos /Item/? utilizados e /Price/? os potenciais índices compostos (/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 únicos utilizados e os índices compostos utilizados, respectivamente, mostram os caminhos incluídos e os índices compostos que a consulta usou. 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 terá qualquer impacto no desempenho da consulta.

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

Potenciais caminhos indexados

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

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

Nota

Você tem algum feedback sobre as métricas de indexação? Queremos ouvi-lo! 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 que um caminho indexado, com base na forma da consulta, tenha um impacto significativo no desempenho da consulta. Por outras palavras, a classificação de impacto do índice é a probabilidade de, sem esse caminho indexado específico, a carga de RU da consulta poder ser substancialmente maior.

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

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

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

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

Exemplos adicionais

Exemplo de consulta

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 /name/?indexados , /age/?, /town/?e /timestamp/?. As métricas do índice também indicam que há uma alta probabilidade de que a adição dos índices (/name ASC, /town ASC, /age ASC) compostos melhore (/name ASC, /town ASC, /timestamp ASC) ainda mais o desempenho.

Próximos passos

Leia mais sobre indexação nos seguintes artigos:

Partilhar via