Advisor query per Cosmos DB

Cosmos DB ora include Query Advisor, progettato per semplificare la scrittura di query più veloci ed efficienti usando il linguaggio di query di Cosmos DB. Indipendentemente dal fatto che si stia ottimizzando le prestazioni, i costi o la scalabilità, Query Advisor offre raccomandazioni utili per sfruttare al meglio i dati in Azure e Microsoft Fabric.

Perché l'ottimizzazione delle query è importante

Il linguaggio di query per Cosmos DB (in Azure e Fabric) è flessibile, consentendo agli sviluppatori di eseguire query su dati JSON con una sintassi simile a SQL familiare. Man mano che le applicazioni aumentano di complessità, piccole differenze nella struttura di query possono avere un effetto significativo sulle prestazioni e sulle unità richiesta (UR), soprattutto su larga scala.

Ad esempio, due query che restituiscono lo stesso risultato potrebbero differire notevolmente in termini di efficienza in base alla modalità di scrittura dei predicati e alla modalità di applicazione degli indici.

Query Advisor analizza le query e offre raccomandazioni mirate che consentono di:

• Ridurre i costi delle UR identificando espressioni inefficienti o filtri non necessari.
• Migliorare le prestazioni delle query tramite strutture di query più ottimali.
• Comprendere il "perché" dietro ogni suggerimento, con spiegazioni scritte in linguaggio chiaro e intuitivo per gli sviluppatori.

Come funziona

Quando si esegue una query, Query Advisor viene eseguito sul piano di query, valutando i modelli che potrebbero causare un consumo elevato di UR, analisi eccessive o elaborazione potenzialmente non necessaria. Restituisce quindi un set di raccomandazioni che indicano quale parte della query potrebbe limitare le prestazioni e suggerisce potenziali modifiche che potrebbero risultare utili.

Uso di Query Advisor

È possibile abilitare le funzionalità di Advisor query impostando la PopulateQueryAdvice proprietà in QueryRequestOptions su true. Se non specificato, PopulateQueryAdvice il valore predefinito è false. Per accedere ai consigli, usare la proprietà FeedResponse.QueryAdvicestringa .

Importante

Query Advisor funziona solo con .NET SDK per Cosmos DB. Il consiglio della query viene restituito solo al primo round trip. Il consiglio non è disponibile nelle chiamate di continuazione successive.

Si consideri questa query di esempio:

SELECT VALUE
    r.id
FROM
    root r
WHERE
    CONTAINS(r.name, 'Abc')

Di seguito è riportato un esempio di richiesta SDK che esegue questa query e usa Query Advisor:

using Microsoft.Azure.Cosmos;

CosmosClient client = new("<connection-string>");
Container container = client.GetContainer("<database-name>", "<container-name>");

string query = """
SELECT VALUE
    r.id
FROM
    root r
WHERE
    CONTAINS(r.name, 'Abc')
""";

QueryRequestOptions requestOptions = new()
{
    PopulateQueryAdvice = true
};

using FeedIterator<dynamic> itemQuery = container.GetItemQueryIterator<dynamic>(
    query,
    requestOptions: requestOptions);

string? queryAdvice = null;
while (itemQuery.HasMoreResults)
{
    if (queryAdvice is not null)
    {
        break;
    }

    FeedResponse<dynamic> page = await itemQuery.ReadNextAsync();
    queryAdvice = page.QueryAdvice;
}

Console.WriteLine(queryAdvice);

Questa richiesta restituisce un'unica istruzione di consulenza per QA1002:

QA1002: If you are matching on a string prefix, consider using STARTSWITH. [...]

Il consiglio della query contiene tre importanti informazioni:

• ID consiglio query: QA1002
• Descrizione del consiglio: IN questo esempio, If you are matching on a string prefix, consider using STARTSWITH.
• Collegamento alla documentazione: URL per indicazioni dettagliate

Annotazioni

Il collegamento alla documentazione è stato omesso da questo esempio.

Esempi

Si considerino gli esempi seguenti di scenari in cui è possibile usare Query Advisor.

Ottimizzazione dell'utilizzo delle funzioni di sistema

Si consideri questo esempio in cui viene usata la GetCurrentTimestamp funzione:

SELECT
    GetCurrentTicks() 
FROM
    container c
WHERE
    GetCurrentTimestamp() > 10

In questo esempio sono disponibili due consigli restituiti da Query Advisor: QA1008 e QA1009. Ogni suggerimento è separato in una nuova riga nell'output della stringa.

QA1009: Consider using GetCurrentTimestampStatic instead of GetCurrentTimestamp in the WHERE clause. [...]

QA1008: Consider using GetCurrentTicksStatic instead of GetCurrentTicks in the WHERE clause. [...]

Usando questo consiglio, è possibile riscrivere la query con l'alternativa seguente:

SELECT
    GetCurrentTicksStatic() 
FROM
    container c
WHERE
    GetCurrentTimestampStatic() > 10