Assistente de Consulta para Cosmos DB

O Cosmos DB agora apresenta o Assistente de Consulta, projetado para ajudá-lo a escrever consultas mais rápidas e eficientes usando a linguagem de consulta do Cosmos DB. Se você estiver otimizando para desempenho, custo ou escalabilidade, o Assistente de Consulta fornece recomendações acionáveis para ajudá-lo a aproveitar ao máximo seus dados no Azure e no Microsoft Fabric.

Por que a otimização de consultas é importante

A linguagem de consulta do Cosmos DB (no Azure e fabric) é flexível, permitindo que os desenvolvedores consultem dados JSON com sintaxe semelhante a SQL familiar. À medida que os aplicativos crescem em complexidade, pequenas diferenças na estrutura de consulta podem ter um efeito significativo nas RUs (unidades de solicitação e desempenho), especialmente em grande escala.

Por exemplo, duas consultas que retornam o mesmo resultado podem diferir drasticamente na eficiência com base em como os predicados são escritos e como os índices são aplicados.

O Assistente de Consulta analisa suas consultas e oferece recomendações direcionadas para ajudá-lo:

• Reduza os custos de RU identificando expressões ineficientes ou filtros desnecessários.
• Melhore o desempenho da consulta por meio de estruturas de consulta mais ideais.
• Entenda o "por quê" por trás de cada sugestão, com explicações escritas em linguagem clara e amigável para os desenvolvedores.

Como funciona

Quando você executa uma consulta, o Assistente de Consulta executa seu plano de consulta, avaliando padrões que podem causar alto consumo de RU, verificações excessivas ou processamento potencialmente desnecessário. Em seguida, ele retorna um conjunto de recomendações que indicam qual parte da consulta pode estar limitando o desempenho e sugere possíveis alterações que podem ajudar.

Usando o Assistente de Consulta

Você pode habilitar os recursos do Assistente de Consulta definindo a PopulateQueryAdvice propriedade como QueryRequestOptionstrue. Quando não especificado, PopulateQueryAdvice o padrão é false. Para acessar o conselho, use a propriedade de cadeia de caracteres FeedResponse.QueryAdvice.

Importante

O Assistente de Consulta funciona apenas com o SDK do .NET para Cosmos DB. O conselho de consulta também é retornado apenas na primeira viagem de ida e volta. O conselho não está disponível nas chamadas de continuação subsequentes.

Considere esta consulta de exemplo:

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

Aqui está um exemplo de uma solicitação do SDK que executa essa consulta e usa o Assistente de Consulta:

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

Esta solicitação retorna uma única instrução de conselho para QA1002:

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

O conselho de consulta contém três informações importantes:

• A ID do Conselho de Consulta: QA1002
• A descrição do conselho: NESTE exemplo, If you are matching on a string prefix, consider using STARTSWITH.
• O link para a documentação: uma URL para diretrizes detalhadas

Observação

O link para a documentação foi omitido deste exemplo.

Exemplos

Considere os exemplos a seguir de cenários em que você pode usar o Assistente de Consulta.

Otimizando o uso da função do sistema

Considere este exemplo em que a GetCurrentTimestamp função é usada:

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

Neste exemplo, há dois conselhos retornados pelo Assistente de Consulta: QA1008 e QA1009. Cada conselho é separado em uma nova linha na saída da cadeia de caracteres.

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

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

Usando este conselho, você pode reescrever a consulta para a seguinte alternativa:

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