Metrische gegevens indexeren in Azure Cosmos DB

VAN TOEPASSING OP: NoSQL

Azure Cosmos DB biedt metrische indexeringsgegevens om zowel gebruikte geïndexeerde paden als aanbevolen geïndexeerde paden weer te geven. U kunt de metrische indexeringsgegevens gebruiken om de queryprestaties te optimaliseren, met name in gevallen waarin u niet zeker weet hoe u het indexeringsbeleid wijzigt).

Ondersteunde SDK-versies

Indexering van metrische gegevens wordt ondersteund in de volgende SDK-versies: | SDK | Ondersteunde versies | | --- | --- | | .NET SDK v3 | >= 3.21.0 | | Java SDK v4 | >= 4.19.0 | | Python SDK | >= 4.6.0 |

Indexering van metrische gegevens inschakelen

U kunt indexering van metrische gegevens voor een query inschakelen door de PopulateIndexMetrics eigenschap in te stellen op true. Als dit niet is opgegeven, PopulateIndexMetrics wordt standaard ingesteld op false. U wordt alleen aangeraden de metrische indexgegevens in te schakelen voor het oplossen van problemen met queryprestaties. Zolang uw query's en indexeringsbeleid hetzelfde blijven, kunnen de metrische indexgegevens waarschijnlijk niet worden gewijzigd. In plaats daarvan raden we u aan dure query's te identificeren door query-RU-kosten en -latentie te controleren met behulp van diagnostische logboeken.

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

    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

U kunt metrische indexgegevens vastleggen door het trefwoord populate_index_metrics door te geven in query-items en vervolgens de waarde voor de header 'x-ms-cosmos-index-tilization' uit het antwoord te lezen. Deze header wordt alleen geretourneerd als de query bepaalde items retourneert.

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

Voorbeelduitvoer

In deze voorbeeldquery bekijken we de gebruikte paden /Item/? en /Price/? de mogelijke samengestelde indexen (/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
    ---

Gebruikte geïndexeerde paden

De gebruikte enkelvoudige indexen en gebruikte samengestelde indexen tonen respectievelijk de opgenomen paden en samengestelde indexen die door de query worden gebruikt. Query's kunnen meerdere geïndexeerde paden gebruiken, evenals een combinatie van opgenomen paden en samengestelde indexen. Als een geïndexeerd pad niet wordt vermeld als gebruikt, heeft het verwijderen van het geïndexeerde pad geen invloed op de prestaties van de query.

Bekijk de lijst met gebruikte geïndexeerde paden als bewijs dat een query deze paden heeft gebruikt. Als u niet zeker weet of een nieuw geïndexeerd pad de queryprestaties verbetert, moet u proberen de nieuwe geïndexeerde paden toe te voegen en te controleren of de query deze gebruikt.

Mogelijke geïndexeerde paden

De potentiële enkelvoudige indexen en gebruikte samengestelde indexen tonen respectievelijk de opgenomen paden en samengestelde indexen die, indien toegevoegd, de query kan gebruiken. Als u potentiële geïndexeerde paden ziet, moet u overwegen deze toe te voegen aan uw indexeringsbeleid en te kijken of ze de queryprestaties verbeteren.

Bekijk de lijst met mogelijke geïndexeerde paden als aanbevelingen in plaats van overtuigend bewijs dat een query een specifiek geïndexeerd pad gebruikt. De mogelijke geïndexeerde paden zijn geen volledige lijst met geïndexeerde paden die door een query kunnen worden gebruikt. Daarnaast is het mogelijk dat sommige mogelijke geïndexeerde paden geen invloed hebben op de queryprestaties. Voeg de aanbevolen geïndexeerde paden toe en bevestig dat ze de queryprestaties verbeteren.

Notitie

Hebt u feedback over de metrische indexeringsgegevens? We willen het horen! U kunt feedback rechtstreeks delen met het technische team van Azure Cosmos DB: cosmosdbindexing@microsoft.com

Indexeffectscore

De indexeffectscore is de kans dat een geïndexeerd pad, op basis van de queryshape, een aanzienlijke invloed heeft op de queryprestaties. Met andere woorden, de indeximpactscore is de kans dat, zonder dat specifieke geïndexeerde pad, de RU-kosten voor query's aanzienlijk hoger zouden zijn geweest.

Er zijn twee mogelijke indeximpactscores: hoog en laag. Als u meerdere mogelijke geïndexeerde paden hebt, raden we u aan om u te richten op geïndexeerde paden met een hoge impactscore.

De enige criteria die worden gebruikt in de indexeffectscore, is de queryshape. In de onderstaande query krijgt het geïndexeerde pad /name/? bijvoorbeeld een hoge indeximpactscore toegewezen:

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

De werkelijke impact is afhankelijk van de aard van de gegevens. Als slechts een paar items overeenkomen met het /name filter, zal het geïndexeerde pad de kosten van de query-RU aanzienlijk verbeteren. Als de meeste items echter toch overeenkomen met het /name filter, kan het geïndexeerde pad de queryprestaties mogelijk niet verbeteren. In elk van deze gevallen krijgt het geïndexeerde pad /name/? een hoge indeximpactscore omdat, op basis van de queryshape, het geïndexeerde pad een hoge kans heeft om de queryprestaties te verbeteren.

Aanvullende voorbeelden

Voorbeeldquery

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

Metrische indexgegevens

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

Deze metrische indexgegevens geven aan dat de query de geïndexeerde paden /name/?, /age/?en /timestamp/?/town/?. De metrische indexgegevens geven ook aan dat er een hoge kans is dat de samengestelde indexen (/name ASC, /town ASC, /age ASC) worden toegevoegd en (/name ASC, /town ASC, /timestamp ASC) dat de prestaties verder worden verbeterd.

Volgende stappen

Lees meer over indexering in de volgende artikelen:

• Overzicht van indexering
• Indexeringsbeleid beheren