Indizierungsmetriken in Azure Cosmos DB

GILT FÜR: NoSQL

Azure Cosmos DB bietet Indizierungsmetriken, um sowohl genutzte indizierte Pfade als auch empfohlene indizierte Pfade anzuzeigen. Sie können die Indizierungsmetriken verwenden, um die Abfrageleistung zu optimieren, insbesondere in Fällen, in denen Sie nicht sicher sind, wie Sie die Indizierungsrichtlinie) ändern können.

Unterstützte SDK-Versionen

Indizierungsmetriken werden in den folgenden SDK-Versionen unterstützt: | SDK | Unterstützte Versionen | | --- | --- | | .NET SDK v3 | >= 3.21.0 | | Java SDK v4 | >= 4.19.0 | | Python SDK | >= 4.6.0 |

Aktivieren von Indizierungsmetriken

Sie können Indizierungsmetriken für eine Abfrage aktivieren, indem Sie die Eigenschaft PopulateIndexMetrics auf true setzen. Wenn nicht angegeben, wird PopulateIndexMetrics standardmäßig auf false gesetzt. Wir empfehlen die Aktivierung der Indexmetriken nur zur Fehlerbehebung bei der Abfrageleistung. Solange Ihre Abfragen und Indizierungsrichtlinien gleich bleiben, werden sich die Indexmetriken wahrscheinlich nicht ändern. Stattdessen empfehlen wir, teure Abfragen zu identifizieren, indem Sie die Abfrage-RU-Ladung und -Latenz mithilfe von Diagnoseprotokollen überwachen.

.NET SDK

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

Java SDK Sync

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

JavaScript SDK

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

Python SDK

Sie können Indexmetriken erfassen, indem Sie das Schlüsselwort populate_index_metrics in Abfrageelementen übergeben und dann den Wert für den Header „x-ms-cosmos-index-utilization“ aus der Antwort lesen. Dieser Header wird nur zurückgegeben, wenn die Abfrage einige Elemente zurückgibt.

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

Beispielausgabe

In dieser Beispielabfrage sehen wir die genutzten Pfade /Item/? und /Price/? die potenziellen zusammengesetzten Indizes (/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
    ---

Verwendete indizierte Pfade

Die genutzten Einzelindizes bzw. die genutzten zusammengesetzten Indizes zeigen die von der Abfrage verwendeten eingeschlossenen Pfade und zusammengesetzten Indizes. Abfragen können mehrere indizierte Pfade sowie eine Mischung aus einbezogenen Pfaden und zusammengesetzten Indizes verwenden. Wenn ein indizierter Pfad nicht als genutzt aufgeführt ist, hat das Entfernen des indizierten Pfads keine Auswirkungen auf die Leistung der Abfrage.

Betrachten Sie die Liste der verwendeten indizierten Pfade als Beweis dafür, dass eine Abfrage diese Pfade verwendet hat. Wenn Sie nicht sicher sind, ob ein neuer indizierter Pfad die Abfrageleistung verbessert, sollten Sie versuchen, die neuen indizierten Pfade hinzuzufügen und prüfen, ob die Abfrage sie verwendet.

Potenzielle indizierte Pfade

Die potenziellen Einzelindizes bzw. die potenziellen zusammengesetzten Indizes zeigen die eingeschlossenen Pfade und zusammengesetzten Indizes an, die, wenn sie hinzugefügt werden, von der Abfrage verwendet werden könnten. Wenn Sie potenzielle indizierte Pfade sehen, sollten Sie in Erwägung ziehen, diese zu Ihrer Indizierungsrichtlinie hinzuzufügen und beobachten, ob sie die Abfrageleistung verbessern.

Betrachten Sie die Liste der potenziellen Indizierungspfade als Empfehlungen und nicht als schlüssigen Beweis dafür, dass eine Abfrage einen bestimmten Indizierungspfad verwenden wird. Die potenziellen Indizierungspfade sind keine erschöpfende Liste der Indizierungspfade, die eine Abfrage verwenden könnte. Außerdem ist es möglich, dass einige potentielle indizierte Pfade keinen Einfluss auf die Abfrageleistung haben. Fügen Sie die empfohlenen indizierten Pfade hinzu und bestätigen Sie, dass sie die Abfrageleistung verbessern.

Hinweis

Haben Sie ein Feedback zu den Indizierungsmetriken? Teilen Sie uns Ihre Meinung mit! Sie können Feedback direkt an das Azure Cosmos DB-Entwicklungsteam senden: cosmosdbindexing@microsoft.com

Indexauswirkungs-Score

Der Index Impact Score ist die Wahrscheinlichkeit, dass ein indizierter Pfad, basierend auf der Abfrageform, einen signifikanten Einfluss auf die Abfrageleistung hat. Mit anderen Worten, der Index-Impact-Score ist die Wahrscheinlichkeit, dass ohne diesen spezifischen indizierten Pfad die EVU-Last der Abfrage wesentlich höher gewesen wäre.

Es gibt zwei mögliche Index-Impact-Scores: hoch und niedrig. Wenn Sie mehrere potenzielle indizierte Pfade haben, empfehlen wir, sich auf indizierte Pfade mit einem hohen Impact Score zu konzentrieren.

Das einzige Kriterium, das für die Indexauswirkungsbewertung herangezogen wird, ist die Form der Abfrage. In der unten stehenden Abfrage würde dem indizierten Pfad /name/? beispielsweise ein hoher Index Impact Score zugewiesen werden:

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

Die tatsächliche Auswirkung hängt von der Art der Daten ab. Wenn nur wenige Elemente mit dem Filter /name übereinstimmen, wird der indizierte Pfad die RU-Last der Abfrage erheblich verbessern. Wenn jedoch die meisten Elemente ohnehin mit dem /name-Filter übereinstimmen, verbessert der indizierte Pfad die Abfrageleistung möglicherweise nicht. In jedem dieser Fälle würde dem indizierten Pfad /name/? ein hoher Indexauswirkungs-Score zugewiesen, da der indizierte Pfad auf der Grundlage der Abfrageform eine hohe Wahrscheinlichkeit hat, die Abfrageleistung zu verbessern.

Weitere Beispiele

Beispielabfrage

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

Indexmetriken

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

Diese Indexmetriken zeigen, dass die Abfrage die indizierten Pfade /name/?, /age/?, /town/? und /timestamp/? verwendet hat. Die Indexmetriken zeigen auch, dass es eine hohe Wahrscheinlichkeit gibt, dass das Hinzufügen der zusammengesetzten Indizes (/name ASC, /town ASC, /age ASC) und (/name ASC, /town ASC, /timestamp ASC) die Leistung weiter verbessern wird.

Nächste Schritte

Weitere Informationen zur Indizierung erhalten Sie in den folgenden Artikeln:

• Übersicht über die Indizierung
• Gewusst wie: Verwalten der Indizierungsrichtlinie