Dicas de desempenho de consulta para SDKs do Azure Cosmos DB

Reduzir chamadas do Plano de Consulta

Para executar uma consulta, um plano de consulta precisa ser criado. Em geral, isso representa uma solicitação de rede para o Gateway do Azure Cosmos DB, que aumenta a latência da operação de consulta. Há duas maneiras de remover essa solicitação e reduzir a latência da operação de consulta:

Otimizando consultas de partição única com execução direta otimista

O Azure Cosmos DB NoSQL tem uma otimização chamada Optimistic Direct Execution (ODE), que pode melhorar a eficiência de determinadas consultas NoSQL. Especificamente, as consultas que não exigem distribuição incluem aquelas que podem ser executadas em uma única partição física ou que têm respostas que não exigem paginação. As consultas que não exigem distribuição podem ignorar com confiança alguns processos, como a geração de planos de consulta do lado do cliente e a regravação de consultas, reduzindo assim a latência da consulta e o custo da RU. Se você especificar a chave de partição na própria solicitação ou consulta (ou tiver apenas uma partição física) e os resultados da sua consulta não exigirem paginação, o ODE poderá melhorar suas consultas.

ODE agora está disponível no .NET SDK versão 3.38.0 e posterior. Quando você executa uma consulta e especifica uma chave de partição na própria solicitação ou consulta, ou seu banco de dados tem apenas uma partição física, sua execução de consulta pode aproveitar os benefícios do ODE. Para habilitar o ODE, defina EnableOptimisticDirectExecution como true em QueryRequestOptions.

Consultas de partição única que apresentam funções GROUP BY, ORDER BY, DISTINCT e agregação (como soma, média, min e max) podem se beneficiar significativamente do uso do ODE. No entanto, em cenários em que a consulta está direcionada a várias partições ou ainda requer paginação, a latência da resposta da consulta e o custo da RU podem ser maiores do que sem o uso do ODE. Portanto, ao usar o ODE, recomendamos:

• Especifique a chave de partição na própria chamada ou consulta.
• Certifique-se de que o tamanho dos dados não aumentou e causou a divisão da partição.
• Certifique-se de que os resultados da sua consulta não exijam paginação para obter todos os benefícios do ODE.

Aqui estão alguns exemplos de consultas simples de partição única que podem se beneficiar do ODE:

- SELECT * FROM r
- SELECT * FROM r WHERE r.pk == "value"
- SELECT * FROM r WHERE r.id > 5
- SELECT r.id FROM r JOIN id IN r.id
- SELECT TOP 5 r.id FROM r ORDER BY r.id
- SELECT * FROM r WHERE r.id > 5 OFFSET 5 LIMIT 3 

Pode haver casos em que consultas de partição única ainda podem exigir distribuição se o número de itens de dados aumentar com o tempo e seu banco de dados do Azure Cosmos DB dividir a partição. Exemplos de consultas em que isso pode ocorrer incluem:

- SELECT Count(r.id) AS count_a FROM r
- SELECT DISTINCT r.id FROM r
- SELECT Max(r.a) as min_a FROM r
- SELECT Avg(r.a) as min_a FROM r
- SELECT Sum(r.a) as sum_a FROM r WHERE r.a > 0 

Algumas consultas complexas podem sempre exigir distribuição, mesmo que tenham como alvo uma única partição. Exemplos de tais consultas incluem:

- SELECT Sum(id) as sum_id FROM r JOIN id IN r.id
- SELECT DISTINCT r.id FROM r GROUP BY r.id
- SELECT DISTINCT r.id, Sum(r.id) as sum_a FROM r GROUP BY r.id
- SELECT Count(1) FROM (SELECT DISTINCT r.id FROM root r)
- SELECT Avg(1) AS avg FROM root r 

É importante observar que o ODE nem sempre recupera o plano de consulta e, como resultado, não é capaz de não permitir ou desativar consultas sem suporte. Por exemplo, após a divisão da partição, essas consultas não são mais qualificadas para ODE e, portanto, não serão executadas porque a avaliação do plano de consulta do lado do cliente as bloqueará. Para garantir a compatibilidade/continuidade do serviço, é fundamental garantir que apenas as consultas que são totalmente suportadas em cenários sem ODE (ou seja, executam e produzem o resultado correto no caso geral de várias partições) são usadas com o ODE.

Usar a geração do Plano de Consulta local

O SQL SDK inclui uma ServiceInterop.dll nativa para analisar e otimizar consultas localmente. ServiceInterop.dll é suportado apenas na plataforma Windows x64 . Os seguintes tipos de aplicativos usam processamento de host de 32 bits por padrão. Para alterar o processamento do host para o processamento de 64 bits, siga estas etapas, com base no tipo do seu aplicativo:

• Para aplicativos executáveis, você pode alterar o processamento do host definindo o destino da plataforma como x64 na janela Propriedades do projeto, na guia Compilar.

• Para projetos de teste baseados em VSTest, você pode alterar o processamento do host selecionando Test>Settings>Default Processor Architecture como X64 no menu Teste do Visual Studio.

• Para aplicativos Web ASP.NET implantados localmente, você pode alterar o processamento do host selecionando Usar a versão de 64 bits do IIS Express para sites e projetos em Opções de Ferramentas>>Projetos e Soluções> Projetos da Web.

• Para ASP.NET aplicativos Web implantados no Azure, você pode alterar o processamento do host selecionando a plataforma de 64 bits em Configurações do aplicativo no portal do Azure.

Usar consultas de partição única

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle' AND c.state = 'Washington'"
{
    // ...
}

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { PartitionKey = new PartitionKey("Washington")}))
{
    // ...
}

IDocumentQuery<dynamic> query = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT * FROM c WHERE c.city = 'Seattle'", 
    new FeedOptions 
    { 
        PartitionKey = new PartitionKey("Washington")
    }).AsDocumentQuery();

Evite recriar o iterador desnecessariamente

Quando todos os resultados da consulta são consumidos pelo componente atual, você não precisa recriar o iterador com a continuação para cada página. Sempre prefira drenar a consulta completamente, a menos que a paginação seja controlada por outro componente de chamada:

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { PartitionKey = new PartitionKey("Washington")}))
{
    while (feedIterator.HasMoreResults) 
    {
        foreach(MyItem document in await feedIterator.ReadNextAsync())
        {
            // Iterate through documents
        }
    }
}

IDocumentQuery<dynamic> query = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT * FROM c WHERE c.city = 'Seattle'", 
    new FeedOptions 
    { 
        PartitionKey = new PartitionKey("Washington")
    }).AsDocumentQuery();
while (query.HasMoreResults) 
{
    foreach(Document document in await queryable.ExecuteNextAsync())
    {
        // Iterate through documents
    }
}

Sintonize o grau de paralelismo

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxConcurrency = -1 }))
{
    // ...
}

IDocumentQuery<dynamic> query = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT * FROM c WHERE c.city = 'Seattle'", 
    new FeedOptions 
    { 
        MaxDegreeOfParallelism = -1, 
        EnableCrossPartitionQuery = true 
    }).AsDocumentQuery();

Vamos supor que

• D = Padrão Número máximo de tarefas paralelas (= número total de processadores na máquina cliente)
• P = Número máximo de tarefas paralelas especificado pelo utilizador
• N = Número de partições que precisam ser visitadas para responder a uma consulta

A seguir estão as implicações de como as consultas paralelas se comportariam para diferentes valores de P.

• (P == 0) => Modo Serial
• (P == 1) => Máximo de uma tarefa
• (P > 1) => Tarefas paralelas Min (P, N)
• (P < 1) => Tarefas paralelas Min (N, D)

Ajustar o tamanho da página

Quando você emite uma consulta SQL, os resultados são retornados de forma segmentada se o conjunto de resultados for muito grande.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxItemCount = 1000}))
{
    // ...
}

IQueryable<dynamic> authorResults = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT p.Author FROM Pages p WHERE p.Title = 'About Seattle'", 
    new FeedOptions { MaxItemCount = 1000 });

Quando uma consulta é executada, os dados resultantes são enviados dentro de um pacote TCP. Se você especificar um valor muito baixo para MaxItemCount, o número de viagens necessárias para enviar os dados dentro do pacote TCP será alto, o que afetará o desempenho. Portanto, se você não tiver certeza de qual valor definir para a MaxItemCount propriedade, é melhor defini-lo como -1 e deixar o SDK escolher o valor padrão.

Ajuste o tamanho do buffer

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxBufferedItemCount = -1}))
{
    // ...
}

IQueryable<dynamic> authorResults = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT p.Author FROM Pages p WHERE p.Title = 'About Seattle'", 
    new FeedOptions { MaxBufferedItemCount = -1 });

A pré-busca funciona da mesma forma, independentemente do grau de paralelismo, e há um único buffer para os dados de todas as partições.

Próximos passos

Para saber mais sobre o desempenho usando o SDK do .NET:

• Práticas recomendadas para o Azure Cosmos DB .NET SDK
• Dicas de desempenho para o SDK do Azure Cosmos DB .NET V3
• Dicas de desempenho para o SDK do Azure Cosmos DB .NET V2

Reduzir chamadas do Plano de Consulta

Para executar uma consulta, um plano de consulta precisa ser criado. Em geral, isso representa uma solicitação de rede para o Gateway do Azure Cosmos DB, que aumenta a latência da operação de consulta.

Usar cache do Plano de Consulta

O plano de consulta, para uma consulta com escopo para uma única partição, é armazenado em cache no cliente. Isso elimina a necessidade de fazer uma chamada para o gateway para recuperar o plano de consulta após a primeira chamada. A chave para o plano de consulta armazenado em cache é a cadeia de caracteres de consulta SQL. Você precisa ter certeza de que a consulta está parametrizada. Caso contrário, a pesquisa de cache do plano de consulta geralmente será uma falha de cache, pois é improvável que a cadeia de caracteres de consulta seja idêntica entre chamadas. O cache do plano de consulta é habilitado por padrão para Java SDK versão 4.20.0 e superior e para Spring Data Azure Cosmos DB SDK versão 3.13.0 e superior.

Usar consultas de partição única parametrizadas

Para consultas parametrizadas que têm como escopo uma chave de partição com setPartitionKey e CosmosQueryRequestOptions não contêm agregações (incluindo Distinct, DCount, Group By), o plano de consulta pode ser evitado:

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));

ArrayList<SqlParameter> paramList = new ArrayList<SqlParameter>();
paramList.add(new SqlParameter("@city", "Seattle"));
SqlQuerySpec querySpec = new SqlQuerySpec(
        "SELECT * FROM c WHERE c.city = @city",
        paramList);

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

Sintonize o grau de paralelismo

As consultas paralelas funcionam consultando várias partições em paralelo. No entanto, os dados de um contêiner particionado individual são obtidos em série em relação à consulta. Então, use setMaxDegreeOfParallelism para CosmosQueryRequestOptions definir o valor para o número de partições que você tem. Se você não sabe o número de partições, você pode usar setMaxDegreeOfParallelism para definir um número alto, e o sistema escolhe o mínimo (número de partições, entrada fornecida pelo usuário) como o grau máximo de paralelismo. Definir o valor como -1 permitirá que o SDK decida a simultaneidade ideal.

É importante notar que as consultas paralelas produzem os melhores benefícios se os dados forem distribuídos uniformemente em todas as partições em relação à consulta. Se o contêiner particionado for particionado de tal forma que todos ou a maioria dos dados retornados por uma consulta estejam concentrados em algumas partições (uma partição na pior das hipóteses), o desempenho da consulta será degradado.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));
options.setMaxDegreeOfParallelism(-1);

// Define the query

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

Vamos supor que

• D = Padrão Número máximo de tarefas paralelas (= número total de processadores na máquina cliente)
• P = Número máximo de tarefas paralelas especificado pelo utilizador
• N = Número de partições que precisam ser visitadas para responder a uma consulta

A seguir estão as implicações de como as consultas paralelas se comportariam para diferentes valores de P.

• (P == 0) => Modo Serial
• (P == 1) => Máximo de uma tarefa
• (P > 1) => Tarefas paralelas Min (P, N)
• (P == -1) => Min (N, D) tarefas paralelas

Ajustar o tamanho da página

Quando você emite uma consulta SQL, os resultados são retornados de forma segmentada se o conjunto de resultados for muito grande. Por padrão, os resultados são retornados em partes de 100 itens ou 4 MB, o limite atingido primeiro. Aumentar o tamanho da página reduzirá o número de viagens de ida e volta necessárias e aumentará o desempenho de consultas que retornam mais de 100 itens. Se você não tem certeza de qual valor definir, 1000 normalmente é uma boa escolha. O consumo de memória aumentará à medida que o tamanho da página aumentar, portanto, se sua carga de trabalho for sensível à memória, considere um valor menor.

Você pode usar o pageSize parâmetro em iterableByPage() para API de sincronização e byPage() para API assíncrona, para definir um tamanho de página:

//  Sync API
Iterable<FeedResponse<MyItem>> filteredItemsAsPages =
    container.queryItems(querySpec, options, MyItem.class).iterableByPage(continuationToken,pageSize);

for (FeedResponse<MyItem> page : filteredItemsAsPages) {
    for (MyItem item : page.getResults()) {
        //...
    }
}

//  Async API
Flux<FeedResponse<MyItem>> filteredItemsAsPages =
    asyncContainer.queryItems(querySpec, options, MyItem.class).byPage(continuationToken,pageSize);

filteredItemsAsPages.map(page -> {
    for (MyItem item : page.getResults()) {
        //...
    }
}).subscribe();

Ajuste o tamanho do buffer

A consulta paralela é projetada para pré-buscar resultados enquanto o lote atual de resultados está sendo processado pelo cliente. A pré-busca ajuda na melhoria geral da latência de uma consulta. setMaxBufferedItemCount limita CosmosQueryRequestOptions o número de resultados pré-buscados. Para maximizar a pré-busca, defina o maxBufferedItemCount para um número maior do que o pageSize (NOTA: Isso também pode resultar em alto consumo de memória). Para minimizar a pré-busca, defina o maxBufferedItemCount igual ao pageSize. Se você definir esse valor como 0, o sistema determinará automaticamente o número de itens a serem armazenados em buffer.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));
options.setMaxBufferedItemCount(-1);

// Define the query

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

A pré-busca funciona da mesma forma, independentemente do grau de paralelismo, e há um único buffer para os dados de todas as partições.

Próximos passos

Para saber mais sobre o desempenho usando o Java SDK:

• Práticas recomendadas para o SDK Java V4 do Azure Cosmos DB
• Dicas de desempenho para o SDK Java V4 do Azure Cosmos DB

Reduzir chamadas do Plano de Consulta

Para executar uma consulta, um plano de consulta precisa ser criado. Em geral, isso representa uma solicitação de rede para o Gateway do Azure Cosmos DB, que aumenta a latência da operação de consulta. Há uma maneira de remover essa solicitação e reduzir a latência da operação de consulta de partição única. Para consultas de partição única, especifique o valor da chave de partição para o item e passe-o como partition_key argumento:

items = container.query_items(
        query="SELECT * FROM r where r.city = 'Seattle'",
        partition_key="Washington"
    )

Ajustar o tamanho da página

Quando você emite uma consulta SQL, os resultados são retornados de forma segmentada se o conjunto de resultados for muito grande. O max_item_count permite definir o número máximo de itens a serem retornados na operação de enumeração.

items = container.query_items(
        query="SELECT * FROM r where r.city = 'Seattle'",
        partition_key="Washington",
        max_item_count=1000
    )

Próximos passos

Para saber mais sobre como usar o Python SDK for API for NoSQL:

• SDK Python do Azure Cosmos DB para API para NoSQL
• Guia de início rápido: biblioteca de cliente do Azure Cosmos DB para NoSQL para Python

Reduzir chamadas do Plano de Consulta

Para executar uma consulta, um plano de consulta precisa ser criado. Em geral, isso representa uma solicitação de rede para o Gateway do Azure Cosmos DB, que aumenta a latência da operação de consulta. Há uma maneira de remover essa solicitação e reduzir a latência da operação de consulta de partição única. Para consultas de partição única, o escopo de uma consulta para uma única partição pode ser realizado de duas maneiras.

Usando uma expressão de consulta parametrizada e especificando a chave de partição na instrução de consulta. A consulta é composta programaticamente para SELECT * FROM todo t WHERE t.partitionKey = 'Bikes, Touring Bikes':

// find all items with same categoryId (partitionKey)
const querySpec = {
    query: "select * from products p where p.categoryId=@categoryId",
    parameters: [
        {
            name: "@categoryId",
            value: "Bikes, Touring Bikes"
        }
    ]
};

// Get items 
const { resources } = await container.items.query(querySpec).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

Ou especifique partitionKey e FeedOptions passe-o como argumento:

const querySpec = {
    query: "select * from products p"
};

const { resources } = await container.items.query(querySpec, { partitionKey: "Bikes, Touring Bikes" }).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

Ajustar o tamanho da página

Quando você emite uma consulta SQL, os resultados são retornados de forma segmentada se o conjunto de resultados for muito grande. O maxItemCount permite definir o número máximo de itens a serem retornados na operação de enumeração.

const querySpec = {
    query: "select * from products p where p.categoryId=@categoryId",
    parameters: [
        {
            name: "@categoryId",
            value: items[2].categoryId
        }
    ]
};

const { resources } = await container.items.query(querySpec, { maxItemCount: 1000 }).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

Próximos passos

Para saber mais sobre como usar o SDK do Node.js para API para NoSQL:

• SDK do Node.js do Azure Cosmos DB para API para NoSQL
• Guia de início rápido - Biblioteca de cliente do Azure Cosmos DB para NoSQL para Node.js