db.collection.aggregate() (método mongosh)

Parâmetros

db.collection.aggregate() recebe os seguintes parâmetros:

Error Handling

If an error occurs, the aggregate() helper throws an exception.

Comportamento do cursor

In mongosh, if the aggregate() cursor is not assigned to a variable using the var keyword, mongosh automatically iterates the cursor up to 20 times. See Iterate a Cursor in mongosh for handling cursors in 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

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 operações aggregate() que não incluem os estágios $out ou $merge:

Se o cliente que emitiu aggregate() se desconectar antes da conclusão da operação, o MongoDB marcará aggregate() para encerramento usando killOp.

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 iterates the returned cursor automatically to print the results. See Iterate a Cursor in mongosh for handling cursors manually in 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 } }
] )

The operation returns a document that details the processing of the aggregation pipeline. For example, the document may show, among other details, which index, if any, the operation used. [1] If the orders collection is a sharded collection, the document would also show the division of labor between the shards and the merge operation, and for targeted queries, the targeted shards.

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 iterates the returned cursor automatically to print the results. See Iterate a Cursor in mongosh for handling cursors manually in 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 tem os seguintes documentos:

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

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

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

[ { _id: 'café', count: 3 } ]

A agregação especifica um agrupamento com strength: 1, o que significa que o agrupamento ignora as diferenças entre variantes de maiúsculas e minúsculas. Como resultado:

• O filtro $match corresponde a todos os documentos na coleção e passa esses documentos para o estágio $group.

• O estágio $group ignora as diferenças nas variantes de letras no campo category e coloca todos os documentos em um único grupo.

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.

You cannot use the $out or the $merge stage in conjunction with read concern "linearizable". That is, if you specify "linearizable" read concern for db.collection.aggregate(), you cannot include either stages in the 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, use 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 } }
)