db.collection.aggregate()

Error Handling

Se ocorrer um erro, o auxiliar aggregate() lançará uma exceção.

Comportamento do cursor

Em mongosh, se o cursor retornado do db.collection.aggregate() não for atribuído a uma variável utilizando a palavra-chave var , então mongosh automaticamente iterará o cursor até 20 vezes. Consulte Iterar um cursor em mongosh para manipular cursores em mongosh.

Os cursores retornados da agregação suportam apenas métodos de cursor que operam em cursores avaliados (ou seja, cursores cujo primeiro lote foi recuperado), como os seguintes métodos:

Para mais informações, veja:

• Pipeline de agregação

• Referência de agregação

• Limites de Pipeline de Agregação

• aggregate

Sessões

Para cursores criados dentro de uma sessão, você não pode chamar getMore fora da sessão.

Da mesma forma, para cursores criados fora de uma sessão, você não pode chamar getMore dentro de uma sessão.

Transações

db.collection.aggregate() pode ser usado dentro de transações distribuídas.

No entanto, os seguintes estágios não são permitidos nas transações:

• $collStats

• $currentOp

• $indexStats

• $listLocalSessions

• $listSessions

• $out

• $merge

• $planCacheStats

Você também não pode especificar a opção explain.

• Para cursores criados fora de uma transação, você não pode chamar getMore dentro da transação.

• Para cursores criados em uma transação, não é possível chamar getMore fora da transação.

Desconexão do cliente

Para db.collection.aggregate() a operação que não inclua os estágios $out ou $merge:

A partir do MongoDB 4.2, se o cliente que emitiu db.collection.aggregate() se desconectar antes da conclusão da operação, o MongoDB marcará db.collection.aggregate() para encerramento usando killOp.

Configurações de query

Você pode usar as configurações de query para definir dicas de índice, definir filtros de descarte de operação e outros campos. As configurações se aplicam à forma de query em todo o cluster. O cluster mantém as configurações após o fechamento.

O otimizador de query usa as configurações da query como uma entrada adicional durante o planejamento da query, o que afeta o plano selecionado para executar a query. Você também pode usar as configurações de query para bloquear uma forma de query.

Para adicionar configurações de query e explorar exemplos, consulte setQuerySettings.

Você pode adicionar configurações de consulta para os comandos find, distinct e aggregate.

As configurações de consulta têm mais funcionalidade e são preferidas em relação aos filtros de índice obsoletos.

Para remover as configurações de query, use removeQuerySettings. Para obter as configurações de consulta, use um estágio $querySettings em um pipeline de agregação .

Agrupar por e calcular uma soma

A operação de agregação seguinte seleciona documentos com status igual a "A", agrupa os documentos correspondentes pelo campo cust_id e calcula o total para cada campo cust_id a partir da soma do campo amount e classifica os resultados pelo campo total em ordem decrescente:

db.orders.aggregate( [
   { $match: { status: "A" } },
   { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
   { $sort: { total: -1 } }
] )

A operação retorna um cursor com os seguintes documentos:

[
   { _id: "xyz1", total: 100 },
   { _id: "abc1", total: 75 }
]

mongosh itera o cursor retornado automaticamente para imprimir os resultados. Consulte Iterar um cursor em mongosh para manipular cursores manualmente no mongosh.

Retornar informações sobre a operação do pipeline de agregação

O exemplo a seguir usa db.collection.explain() para visualizar informações detalhadas sobre o plano de execução do pipeline de agregação.

db.orders.explain().aggregate( [
   { $match: { status: "A" } },
   { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
   { $sort: { total: -1 } }
] )

A operação retorna um documento que detalha o processamento do pipeline de agregação . Por exemplo, o documento pode mostrar, entre outros detalhes, qual índice, se houver, a operação utilizada. [1] Se a orders for uma coleção fragmentada, o documento também mostrará a divisão de trabalho entre os fragmentos e a operação de mesclagem e, para queries direcionadas, os fragmentos direcionados.

Você pode ver uma saída de explicação mais detalhada passando os modos de explicação executionStats ou allPlansExecution para o método db.collection.explain().

Interação com allowDiskUseByDefault

A partir do MongoDB 6.0, os estágios do pipeline que exigem mais de 100 megabytes de memória para execução gravam arquivos temporários no disco por padrão. Esses arquivos temporários duram durante a execução do pipeline e podem influenciar o espaço de armazenamento na sua instância. Em versões anteriores do MongoDB, você deve passar { allowDiskUse: true } para find individuais e comandos aggregate para habilitar esse comportamento.

Somente find e aggregate comandos podem substituir o parâmetro allowDiskUseByDefault por um ou outro:

• Usando { allowDiskUse: true } para permitir a gravação de arquivos temporários no disco quando allowDiskUseByDefault estiver definido como false

• Usando { allowDiskUse: false } para proibir a gravação de arquivos temporários no disco quando allowDiskUseByDefault estiver definido como true

As mensagens de registro do criador de perfil e as mensagens de registro de diagnóstico incluem um indicador usedDisk se algum estágio de agregação gravou dados em arquivos temporários devido a restrições de memória.

Para obter mais informações, consulte Limites do pipeline de agregação.

Especifique um tamanho de lote inicial

Para especificar um tamanho de lote inicial para o cursor, utilize a seguinte sintaxe para a opção cursor:

cursor: { batchSize: <int> }

Por exemplo, a seguinte operação de agregação especifica o tamanho de lote inicial de 0 para o cursor:

db.orders.aggregate(
                     [
                       { $match: { status: "A" } },
                       { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                       { $sort: { total: -1 } },
                       { $limit: 2 }
                     ],
                     {
                       cursor: { batchSize: 0 }
                     }
                   )

O documento do { cursor: { batchSize: 0 } }, que especifica o tamanho do tamanho do lote inicial, indica um primeiro lote vazio. Esse tamanho de lote é útil para retornar rapidamente um cursor ou uma mensagem de falha sem realizar um trabalho significativo no lado do servidor.

Para especificar o tamanho do lote para operações subsequentes do getMore (após o lote inicial), utilize o campo batchSize ao executar o comando getMore.

mongosh itera o cursor retornado automaticamente para imprimir os resultados. Consulte Iterar um cursor em mongosh para manipular cursores manualmente no mongosh.

Especificar um agrupamento

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

Uma coleção restaurants possui os seguintes documentos:

db.restaurants.insertMany( [
   { _id: 1, category: "café", status: "A" },
   { _id: 2, category: "cafe", status: "a" },
   { _id: 3, category: "cafE", status: "a" }
] )

A operação de agregação a seguir inclui a opção de agrupamento :

db.restaurants.aggregate(
   [ { $match: { status: "A" } }, { $group: { _id: "$category", count: { $sum: 1 } } } ],
   { collation: { locale: "fr", strength: 1 } }
);

Para obter descrições sobre os campos de agrupamento, consulte Documento de agrupamento.

Sugerir um Índice

Crie uma collection food com os seguintes documentos:

db.food.insertMany( [
   { _id: 1, category: "cake", type: "chocolate", qty: 10 },
   { _id: 2, category: "cake", type: "ice cream", qty: 25 },
   { _id: 3, category: "pie", type: "boston cream", qty: 20 },
   { _id: 4, category: "pie", type: "blueberry", qty: 15 }
] )

Crie os seguintes índices:

db.food.createIndex( { qty: 1, type: 1 } );
db.food.createIndex( { qty: 1, category: 1 } );

A seguinte operação de aggregation inclui a opção hint para forçar o uso do índice especificado:

db.food.aggregate(
   [ { $sort: { qty: 1 }}, { $match: { category: "cake", qty: 10  } }, { $sort: { type: -1 } } ],
   { hint: { qty: 1, category: 1 } }
)

Sobrepor readConcern

Utilize a opção readConcern para especificar o read concern para a operação.

Não é possível usar o estágio $out ou $merge em conjunto com a preocupação de leitura "linearizable". Ou seja, se você especificar a preocupação de leitura "linearizable" para db.collection.aggregate(), não poderá incluir nenhum dos estágios no pipeline.

A operação a seguir em um conjunto de réplicas especifica uma read concern de "majority" para ler a cópia mais recente dos dados confirmados como gravados na maioria dos nós.

db.restaurants.aggregate(
   [ { $match: { rating: { $lt: 5 } } } ],
   { readConcern: { level: "majority" } }
)

Especifique um comentário

Uma coleção denominada movies contém documentos formatados como tal:

db.movies.insertOne(
   {
      _id: ObjectId("599b3b54b8ffff5d1cd323d8"),
      title: "Jaws",
      year: 1975,
      imdb: "tt0073195"
   }
)

A operação de agregação a seguir encontra filmes criados em 1995 e inclui a comment opção para fornecer informações de rastreamento logs na db.system.profile coleção , coleção e db.currentOp.

db.movies.aggregate( [ { $match: { year : 1995 } } ], { comment : "match_all_movies_from_1995" } ).pretty()

Em um sistema com a criação de perfil ativada, você pode system.profile a para ver todas as agregações semelhantes recentes, conforme mostrado abaixo:

db.system.profile.find( { "command.aggregate": "movies", "command.comment" : "match_all_movies_from_1995" } ).sort( { ts : -1 } ).pretty()

Isso retornará um conjunto de resultados do perfil no seguinte formato:

{
  "op" : "command",
  "ns" : "video.movies",
  "command" : {
    "aggregate" : "movies",
    "pipeline" : [
      {
        "$match" : {
          "year" : 1995
        }
      }
    ],
    "comment" : "match_all_movies_from_1995",
    "cursor" : {
    },
    "$db" : "video"
  },
  ...
}

Um aplicativo pode codificar qualquer informação arbitrária no comentário para rastrear ou identificar com mais facilidade operações específicas por meio do sistema. Por exemplo, um aplicativo pode anexar um comentário de string incorporando seu ID de processo, ID de thread, nome de host do cliente e o usuário que emitiu o comando.

Usar variáveis em let

Para definir variáveis que você pode acessar em outro lugar no comando, utilize a opção let .

Crie uma collection cakeSales contendo vendas para sabores de bolo:

db.cakeSales.insertMany( [
   { _id: 1, flavor: "chocolate", salesTotal: 1580 },
   { _id: 2, flavor: "strawberry", salesTotal: 4350 },
   { _id: 3, flavor: "cherry", salesTotal: 2150 }
] )

O seguinte exemplo:

• recupera o bolo que tem um salesTotal maior que 3000, que é o bolo com um _id de 2

• define uma variável targetTotal em let, que é referenciada em $gt como $$targetTotal

db.cakeSales.aggregate(
   [
      { $match: {
         $expr: { $gt: [ "$salesTotal", "$$targetTotal" ] }
      } }
   ],
   { let: { targetTotal: 3000 } }
)