Indexación de métricas en Azure Cosmos DB

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 admitidas del SDK

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

Habilitación de métricas de indexación

Puede habilitar las métricas de indexación para una consulta estableciendo la PopulateIndexMetrics propiedad en true. Cuando no se especifica, PopulateIndexMetrics el valor predeterminado 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 iguales, es poco probable que cambien las métricas de índice. En su lugar, recomendamos identificar consultas costosas mediante la supervisión de la carga de RU de las consultas y la latencia a través de 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());
        }
    });  

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

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 clave "populate_index_metrics" en los elementos de consulta y, a continuación, 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'])

Go SDK

Para habilitar las métricas de indexación en el SDK de Go, establezca PopulateIndexMetricstrue en en queryOptions. Los datos de métricas de índice de QueryItemsResponse están base64 codificados y deben descodificarse para poder usarlos.

La habilitación de las métricas de indexación conlleva sobrecarga, por lo que solo debe realizarse cuando se depuran consultas lentas y no se recomienda en producción.

	pager := container.NewQueryItemsPager("SELECT c.id FROM c WHERE CONTAINS(LOWER(c.description), @word)", azcosmos.NewPartitionKey(), &azcosmos.QueryOptions{
		PopulateIndexMetrics: true,
		QueryParameters: []azcosmos.QueryParameter{
			{
				Name:  "@word",
				Value: "happy",
			},
		},
	})

	if pager.More() {
		page, _ := pager.NextPage(context.Background())
		
    // process results

		decoded, _ := base64.StdEncoding.DecodeString(*page.IndexMetrics)
		log.Println("Index metrics", string(decoded))
	}

Una vez descodificado, las métricas de índice están disponibles en formato JSON. Por ejemplo:

{
    "UtilizedSingleIndexes": [
        {
            "FilterExpression": "",
            "IndexSpec": "/description/?",
            "FilterPreciseSet": true,
            "IndexPreciseSet": true,
            "IndexImpactScore": "High"
        }
    ],
    "PotentialSingleIndexes": [],
    "UtilizedCompositeIndexes": [],
    "PotentialCompositeIndexes": []
}

Salida de ejemplo

En esta consulta de ejemplo, observamos las rutas de acceso utilizadas /Item/? y /Price/?, así como 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, respectivamente, muestran 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 en el índice e índices compuestos. Si una ruta de acceso indizada no aparece como se utiliza, quitar la ruta de acceso indizada no tendrá ningún impacto en el rendimiento de la consulta.

Considere la lista de rutas de acceso indexadas usadas como evidencia de que una consulta usó esas rutas de acceso. Si no está seguro de si una nueva ruta de acceso indizada 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 utilizar. Si ve posibles rutas de acceso indexadas, debe considerar 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 indizada como recomendaciones en lugar de evidencia concluyente de que una consulta usará una ruta de acceso indexada específica. Las posibles rutas de acceso indizada no son una lista exhaustiva de rutas de acceso indizada que una consulta podría usar. Además, es posible que algunas rutas de acceso indexadas potenciales 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 algún comentario sobre las métricas de indexación? Queremos conocerlos. No dude en compartir sus 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 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 sustancialmente mayor.

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

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

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

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

Ejemplos adicionales

Consulta de ejemplo

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

Métricas del í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
    ---

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 es muy probable que agregar los índices (/name ASC, /town ASC, /age ASC) y (/name ASC, /town ASC, /timestamp ASC) compuestos mejore aún más el rendimiento.

Pasos siguientes

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

• Visión general de la indexación
• Cómo administrar la directiva de indexación