Métriques d'indexation dans Azure Cosmos DB

Article
08/15/2024

S’APPLIQUE À : NoSQL

Azure Cosmos DB fournit des métriques d’indexation pour afficher à la fois les chemins indexés utilisés et les chemins indexés recommandés. Vous pouvez utiliser les métriques d’indexation pour optimiser les performances des requêtes, en particulier dans les cas où vous ne savez pas comment modifier la stratégie d’indexation.

Versions prises en charge du kit de développement logiciel (SDK)

Les métriques d’indexation sont prises en charge dans les versions du SDK suivantes : | SDK | Versions prises en charge | | --- | --- | | SDK .NET v3 | >= 3.21.0 | | SDK Java v4 | >= 4.19.0 | | SDK Python | >= 4.6.0 |

Activer les métriques d’indexation

Vous pouvez activer les métriques d’indexation pour une requête en affectant à la propriété PopulateIndexMetrics la valeur true. En l'absence de toute spécification, PopulateIndexMetrics prend false comme valeur par défaut. Nous vous recommandons uniquement d’activer les métriques d’indexation pour le dépannage des performances des requêtes. Tant que vos requêtes et votre stratégie d’indexation restent les mêmes, il est peu probable que les métriques d’indexation changent. Au lieu de cela, nous vous recommandons d’identifier les requêtes coûteuses en surveillant la charge et la latence des requêtes à l’aide des journaux de diagnostic.

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

Vous pouvez capturer les métriques d’index en passant le mot clé populate_index_metrics dans les éléments de requête, puis en lisant la valeur de l’en-tête « x-ms-cosmos-index-utilization » à partir de la réponse. Cet en-tête est retourné uniquement si la requête retourne certains éléments.

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

Exemple de sortie

Dans cet exemple de requête, nous observons les chemins utilisés /Item/? et /Price/?, et les index composites potentiels (/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
    ---

Chemins indexés utilisés

Les index uniques utilisés et les index composites utilisés indiquent respectivement les chemins inclus et les index composites utilisés par la requête. Les requêtes peuvent utiliser plusieurs chemins indexés, ainsi qu’une combinaison de chemins inclus et d’index composites. Si un chemin indexé n’est pas utilisé, la suppression du chemin indexé n’aura aucun impact sur les performances de la requête.

Considérez la liste des chemins indexés utilisés comme preuve qu’une requête a utilisé ces chemins. Si vous ne savez pas si un nouveau chemin indexé améliore les performances des requêtes, vous devez essayer d’ajouter les nouveaux chemins indexés et vérifier si la requête les utilise.

Chemins indexés potentiels

Les index uniques potentiels et les index composites potentiels représentent respectivement les chemins inclus et les index composites qui, s’ils sont ajoutés, peuvent être utilisés par la requête. Si vous voyez des chemins indexés potentiels, vous devez envisager de les ajouter à votre stratégie d’indexation et observer s’ils améliorent les performances des requêtes.

Considérez la liste des chemins indexés potentiels comme des recommandations plutôt que des preuves concluantes qu’une requête utilisera un chemin indexé spécifique. Les chemins indexés potentiels ne sont pas une liste exhaustive des chemins indexés qu’une requête peut utiliser. En outre, il est possible que certains chemins indexés potentiels n’aient aucun impact sur les performances des requêtes. Ajoutez les chemins indexés recommandés et confirmez qu’ils améliorent les performances des requêtes.

Notes

Avez-vous des commentaires sur les métriques d’indexation ? Nous attendons vos remarques ! N’hésitez pas à partager vos commentaires directement avec l’équipe d’ingénierie Azure Cosmos DB :cosmosdbindexing@microsoft.com

Score d’impact de l’index

Le score d’impact de l’index est la probabilité qu’un chemin indexé, sur la base de la forme de la requête, ait un impact significatif sur les performances des requêtes. En d’autres termes, le score d’impact de l’index est la probabilité que, sans ce chemin indexé spécifique, les frais de la requête RU aient été sensiblement plus élevés.

Il existe deux résultats possibles d’impact d’index : élevé et faible. Si vous disposez de plusieurs chemins indexés potentiels, nous vous recommandons de vous concentrer sur les chemins indexés avec un score d’impact élevé.

Le seul critère utilisé dans le score d’impact de l’index est la forme de la requête. Par exemple, dans la requête ci-dessous, le chemin indexé /name/? se voit attribuer un score d’impact d’index élevé :

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

Impact réel en fonction de la nature des données. Si seuls quelques éléments correspondent au filtre /name, le chemin indexé améliore considérablement le coût de la charge en unités de requête. Toutefois, si la plupart des éléments correspondent au filtre /name, le chemin indexé peut ne pas améliorer les performances des requêtes. Dans chacun de ces cas, le chemin indexé /name/? se voit attribuer un score d’impact d’index élevé, car, sur la base de la forme de la requête, le chemin indexé a une probabilité élevée d’améliorer les performances des requêtes.

Exemples supplémentaires

Exemple de requête

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