Métricas de indexación de Azure Cosmos DB

SE APLICA A: NoSQL

Azure Cosmos DB proporciona métricas de indexación para mostrar las rutas de acceso indexadas utilizadas y las rutas de acceso indexadas recomendadas. Puede usar las métricas de indexación para optimizar el rendimiento de las consultas, especialmente en los casos en los que no está seguro de cómo modificar la directiva de indexación).

Versiones de SDK compatibles

Las métricas de indexación son compatibles con las siguientes versiones del SDK: | SDK | Versiones compatibles | --- | --- | .NET SDK v3 | >= 3.21.0 | | Java SDK v4 | >= 4.19.0 | | Python SDK | >= 4.6.0 |

Habilitación de las métricas de indexación

Puede habilitar las métricas de indexación para una consulta estableciendo la propiedad PopulateIndexMetrics en true. Si no se especifica, el valor predeterminado de PopulateIndexMetrics es false. Solo se recomienda habilitar las métricas de índice para solucionar problemas de rendimiento de las consultas. Siempre que las consultas y la directiva de indexación permanezcan igual, es poco probable que las métricas de índice cambien. En su lugar, se recomienda identificar consultas costosas mediante la supervisión de la latencia y el cargo de RU de consulta mediante registros de diagnóstico.

SDK de .NET

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

Sincronización del SDK de Java

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

Asincronización del SDK de Java

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

SDK de JavaScript

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

SDK de Python

Puede capturar métricas de índice pasando la palabra clave populate_index_metrics en los elementos de consulta y después leyendo el valor del encabezado "x-ms-cosmos-index-utilization" de la respuesta. Este encabezado solo se devuelve si la consulta devuelve algunos elementos.

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

Salida de ejemplo

En esta consulta de ejemplo, se observan las rutas de acceso utilizadas /Item/? y /Price/? y los posibles índices compuestos (/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
    ---

Rutas de acceso indexadas utilizadas

Los índices únicos utilizados y los índices compuestos utilizados muestran respectivamente las rutas de acceso incluidas y los índices compuestos que usó la consulta. Las consultas pueden usar varias rutas de acceso indexadas, así como una combinación de rutas de acceso incluidas e índices compuestos. Si una ruta de acceso indexada no aparece como utilizada, la eliminación de la ruta de acceso indexada no tendrá ningún impacto en el rendimiento de la consulta.

Considere la lista de rutas de acceso indexadas utilizadas como prueba de que una consulta ha usado esas rutas de acceso. Si no está seguro de si una nueva ruta de acceso indexada mejorará el rendimiento de las consultas, debe intentar agregar las nuevas rutas de acceso indexadas y comprobar si la consulta las usa.

Posibles rutas de acceso indexadas

Los índices simples potenciales y los índices compuestos potenciales muestran, respectivamente, las rutas de acceso incluidas y los índices compuestos que, si se agregan, la consulta podría usarse. Si ve posibles rutas de acceso indexadas, considere la posibilidad de agregarlas a la directiva de indexación y observar si mejoran el rendimiento de las consultas.

Considere la lista de posibles rutas de acceso indexadas como recomendaciones en lugar de evidencia concluyente de que una consulta usará una ruta de acceso indexada específica. Las posibles rutas de acceso indexadas no son una lista exhaustiva de rutas de acceso indexadas que una consulta podría usar. Además, es posible que algunas rutas de acceso indexadas posibles no tengan ningún impacto en el rendimiento de las consultas. Agregue las rutas de acceso indexadas recomendadas y confirme que mejoran el rendimiento de las consultas.

Nota:

¿Tiene comentarios sobre las métricas de indexación? Queremos conocerlos. No dude en compartir comentarios directamente con el equipo de ingeniería de Azure Cosmos DB: cosmosdbindexing@microsoft.com.

Puntuación de impacto del índice

La puntuación de impacto del índice es la probabilidad de que una ruta de acceso indexada, basada en la forma de la consulta, tenga un impacto significativo en el rendimiento de las consultas. En otras palabras, la puntuación de impacto del índice es la probabilidad de que, sin esa ruta de acceso indexada específica, el cargo de RU de consulta habría sido considerablemente mayor.

Hay dos posibles puntuaciones de impacto en el índice: alta y baja. Si tiene varias rutas de acceso indexadas posibles, se recomienda centrarse en rutas de acceso indexadas con una puntuación de impacto alta.

Los únicos criterios usados en la puntuación de impacto del índice son la forma de la consulta. Por ejemplo, en la consulta siguiente, a la ruta de acceso indexada /name/? se le asignaría una puntuación de impacto de índice alta:

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

El impacto real depende de la naturaleza de los datos. Si solo unos pocos elementos coinciden con el filtro /name, la ruta de acceso indexada mejorará considerablemente el cargo de RU de consulta. Sin embargo, si la mayoría de los elementos terminan igualando el filtro /name de todos modos, es posible que la ruta de acceso indexada no termine mejorando el rendimiento de las consultas. En cada uno de estos casos, a la ruta de acceso indexada /name/? se le asignaría una puntuación de impacto de índice alta porque, en función de la forma de la consulta, la ruta de acceso indexada tiene una alta probabilidad de mejorar el rendimiento de las consultas.

Ejemplos adicionales

Ejemplo de consulta

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

Indexación de métricas

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

Estas métricas de índice muestran que la consulta usó las rutas de acceso indexadas /name/?, /age/?, /town/? y /timestamp/?. Las métricas de índice también indican que hay una alta probabilidad de que al agregar los índices compuestos (/name ASC, /town ASC, /age ASC) y (/name ASC, /town ASC, /timestamp ASC) mejorará aún más el rendimiento.

Pasos siguientes

Obtenga más información acerca de la indexación en los siguientes artículos:

• Introducción a la indexación
• Cómo administrar la directiva de indexación