Estágios do pipeline de agregação

Nesta página

Compatibilidade

Estágios
Lista alfabética de estágios

Nos métodos db.collection.aggregate() e db.aggregate() , os estágios do pipeline aparecem em uma matriz. Na interface do usuário do Atlas, você pode organizar os estágios do pipeline usando o construtor de pipeline de agregação. Os documentos passam pelas etapas em sequência.

Compatibilidade

Você pode usar as etapas de pipeline para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Estágios

`db.collection.aggregate()` Estágios

Todas as etapas, exceto as fases $out, $merge, $geoNear, $changeStream e $changeStreamSplitLargeEvent, podem aparecer várias vezes em um pipeline.

Observação

Para obter detalhes sobre um operador específico, incluindo sintaxe e exemplos, clique no link para a página de referência do operador.

db.collection.aggregate( [ { <stage> }, ... ] )

Estágio	Descrição
`$addFields`	Adiciona novos campos aos documentos. Semelhante ao `$project`, `$addFields` remodela cada documento no fluxo; especificamente, adicionando novos campos aos documentos de saída que contêm os campos existentes dos documentos de entrada e os campos recém-adicionados. `$set` é um alias para `$addFields`.
`$bucket`	Categoriza documentos recebidos em grupos, chamados blocos, com base em uma expressão especificada e limites de blocos.
`$bucketAuto`	Categoriza documentos recebidos em um número específico de grupos, chamados blocos, com base em uma expressão especificada. Os limites dos compartimentos são determinados automaticamente em uma tentativa de distribuir uniformemente os documentos no número especificado de compartimentos.
`$changeStream`	Retorna um cursor Alterar coluna para a coleção. Esse estágio só pode ocorrer uma vez em um pipeline de agregação e deve ocorrer como o primeiro estágio.
`$changeStreamSplitLargeEvent`	Divide change stream grandes que excedem 16 MB em fragmentos menores retornados em um cursor de change stream de alterações. Você só pode usar `$changeStreamSplitLargeEvent` em um pipeline `$changeStream` e ele deve ser o estágio final no pipeline.
`$collStats`	Retorna estatísticas sobre uma coleção ou visualização.
`$count`	Retorna uma contagem do número de documentos nesta etapa do pipeline de agregação. Distinto do acumulador de agregação do `$count`.
`$densify`	Cria novos documentos em uma sequência de documentos onde determinados valores em um campo estão faltando.
`$documents`	Retorna documentos literais de expressões de entrada.
`$facet`	Processa vários aggregation pipelines em um único estágio no mesmo conjunto de documentos de entrada. Permite a criação de agregações multifacetadas capazes de caracterizar dados em várias dimensões, ou facets, em um único estágio.
`$fill`	Preenche `null` e os valores de campo ausentes nos documentos.
`$geoNear`	Retorna um fluxo ordenado de documentos baseado na proximidade de um ponto geoespacial. Incorpora a funcionalidade do `$match`, `$sort` e `$limit` para dados geoespaciais. Os documentos de saída incluem um campo de distância adicional e podem incluir um campo de identificador de local.
`$graphLookup`	Executa uma pesquisa recursiva em uma coleção. Para cada documento de saída, adiciona um novo campo de matriz que contém resultados transversais da busca recursiva por esse documento.
`$group`	Agrupa documentos de entrada por uma expressão de identificador especificada e aplica a(s) expressão(ões) acumuladora(s), se especificada(s), para cada grupo. Consome todos os documentos de entrada e gera um documento por cada grupo distinto. Os documentos de saída só contêm o campo identificador e, se especificado, campos acumulados.
`$indexStats`	Retorna estatísticas sobre o uso de cada índice para a coleção.
`$limit`	Passa os primeiros n documentos não modificados para o pipeline onde n é o limite especificado. Para cada documento de entrada, gera um documento (para os primeiros n documentos) ou zero documentos (após os primeiros n documentos).
`$listSearchIndexes`	Retorna informações sobre Atlas Search indexes em uma coleção especificada.
`$listSessions`	Lista todas as sessões que estão ativas há muito tempo para propagar para a coleção `system.sessions`.
`$lookup`	Executa uma junção externa esquerda a outra collection no mesmo banco de dados para filtrar documentos da collection "associada" para processamento.
`$match`	Filtra o fluxo de documentos para permitir que apenas documentos correspondentes passem sem modificações para o próximo estágio do pipeline. O `$match` utiliza consultas MongoDB padrão. Para cada documento de entrada, gera um documento (uma correspondência) ou zero documentos (nenhuma correspondência).
`$merge`	Escreve os documentos resultantes do aggregation pipeline em uma coleção. O estágio pode incorporar (inserir novos documentos, mesclar documentos, substituir documentos, manter documentos existentes, falhar na operação, processar documentos com um pipeline de atualização personalizado) os resultados em uma coleção de saída. Para usar o estágio `$merge` , ele deve ser o último estágio do pipeline.
`$out`	Escreve os documentos resultantes do aggregation pipeline em uma coleção. Para usar o estágio `$out`, ele deve ser o último estágio no pipeline.
`$planCacheStats`	Retorna informações de cache do plano para uma coleção.
`$project`	Remodela cada documento no fluxo, adicionando novos campos ou removendo campos existentes. Para cada documento de entrada, gera um documento. Consulte também `$unset` para remover campos existentes.
`$redact`	Remodela cada documento no fluxo restringindo o conteúdo de cada documento com base nas informações armazenadas nos próprios documentos. Incorpora a funcionalidade do `$project` e `$match`. Pode ser usado para implementar a redação em nível de campo. Para cada documento de entrada, gera um ou zero documentos.
`$replaceRoot`	Substitui um documento pelo documento incorporado especificado. A operação substitui todos os campos existentes no documento de entrada, incluindo o campo `_id`. Especifique um documento incorporado no documento de entrada para promover o documento incorporado ao nível superior. `$replaceWith` é um alias para o estágio `$replaceRoot`.
`$replaceWith`	Substitui um documento pelo documento incorporado especificado. A operação substitui todos os campos existentes no documento de entrada, incluindo o campo `_id`. Especifique um documento incorporado no documento de entrada para promover o documento incorporado ao nível superior. `$replaceWith` é um alias para o estágio `$replaceRoot`.
`$sample`	Seleciona aleatoriamente o número especificado de documentos de sua entrada.
`$search`	Realiza uma procurar de texto completo do campo ou campos em uma collection do Atlas . Observação `$search` está disponível apenas para clusters do MongoDB Atlas, e não está disponível para implantações autogerenciadas. Para saber mais, consulte Estágios de pipeline de agregação do Atlas Search.
`$searchMeta`	Retorna diferentes tipos de documentos de resultado de metadados para a query Pesquisa do Atlas em relação a uma collection do Atlas . Observação `$searchMeta` está disponível apenas para clusters do MongoDB Atlas que executam o MongoDB v4.4.9 ou superior e não está disponível para implantações autogerenciadas. Para saber mais, consulte Estágios de pipeline de agregação do Atlas Search.
`$set`	Adiciona novos campos aos documentos. Semelhante ao `$project`, `$set` remodela cada documento no fluxo; especificamente, adicionando novos campos aos documentos de saída que contêm os campos existentes dos documentos de entrada e os campos recém-adicionados. `$set` é um alias para o estágio `$addFields`.
`$setWindowFields`	Agrupa documentos em janelas e aplica um ou mais operadores aos documentos em cada janela. Novidades na versão 5.0.
`$skip`	Ignora os primeiros n documentos, em que n é o número de pulos especificado, e passa os documentos restantes sem modificações para o pipeline. Para cada documento de entrada, produz zero documentos (para os primeiros n documentos) ou um documento (se após os primeiros n documentos).
`$sort`	Reordena o fluxo de documentos por uma chave de classificação especificada. Apenas a ordem muda; os documentos permanecem inalterados. Para cada documento de entrada, gera um documento.
`$sortByCount`	Agrupa documentos recebidos com base no valor de uma expressão especificada e, em seguida, calcula a contagem de documentos em cada grupo distinto.
`$unionWith`	Executa uma união de duas coleções; ou seja, combina resultados de pipeline de duas coleções em um único conjunto de resultados.
`$unset`	Remove/exclui campos dos documentos. `$unset` é um alias para o estágio `$project` que remove campos.
`$unwind`	Desconstrói um campo de array a partir dos documentos de entrada para gerar um documento para cada elemento. Cada documento de saída substitui a array por um valor de elemento. Para cada documento de entrada, produz n documentos onde n é o número de elementos de array e pode ser zero para uma array vazia.
`$vectorSearch`	Realiza uma pesquisa ANN em um vetor no campo especificado de uma coleção do Atlas . Novidade na versão 6.0.11. Observação `$vectorSearch` está disponível apenas para clusters do MongoDB Atlas que executam o MongoDB v6.0.11 ou superior e não está disponível para implantações autogerenciadas. Para saber mais, consulte Estágios de pipeline de agregação do Atlas Search.

Para saber que operadores de expressão de agregação devem ser usados nos estágios do pipeline, consulte Operadores de pipeline de agregação.

`db.aggregate()` Estágios

O MongoDB também fornece o método db.aggregate() :

db.aggregate( [ { <stage> }, ... ] )

As seguintes etapas utilizam o método db.aggregate() e não o método db.collection.aggregate().

Estágio	Descrição
`$changeStream`	Retorna um cursor Alterar coluna para a coleção. Esse estágio só pode ocorrer uma vez em um pipeline de agregação e deve ocorrer como o primeiro estágio.
`$currentOp`	Retorna informações sobre operações ativas e/ou dormentes para a implementação do MongoDB.
`$listLocalSessions`	Lista todas as sessões ativas recentemente em uso na `mongos` ou instância`mongod` conectada no momento. Essas sessões podem ainda não ter sido propagadas para a coleção `system.sessions`.
`$documents`	Retorna documentos literais de valores de entrada.

Estágios disponíveis para atualizações

Você pode usar o pipeline de agregação para atualizações em:

Comando	`mongosh` Métodos
`findAndModify`	db.collection.findOneAndUpdate() db.collection.findAndModify()
`update`	db.collection.updateOne() db.collection.updateMany() Bulk.find.update() Bulk.find.updateOne() Bulk.find.upsert()

Para as atualizações, o pipeline pode consistir nos seguintes estágios:

$addFields e seu alias $set
$project e seu alias $unset
$replaceRoot e seu nome alternativo $replaceWith.

Lista alfabética de estágios

Nome	Descrição
`$addFields`	Adiciona novos campos aos documentos. Produz documentos que contêm todos os campos existentes dos documentos de entrada e novos campos adicionados.
`$bucket`	Categoriza documentos recebidos em grupos, chamados blocos, com base em uma expressão especificada e limites de blocos.
`$bucketAuto`	Categoriza documentos recebidos em um número específico de grupos, chamados blocos, com base em uma expressão especificada. Os limites dos compartimentos são determinados automaticamente em uma tentativa de distribuir uniformemente os documentos no número especificado de compartimentos.
`$changeStream`	Retorna um cursor change stream para a collection ou reconhecimento de data center. Esse estágio só pode ocorrer uma vez em um pipeline de agregação e deve ocorrer como o primeiro estágio.
`$changeStreamSplitLargeEvent`	Divide change stream grandes que excedem 16 MB em fragmentos menores retornados em um cursor de change stream de alterações. Você só pode usar `$changeStreamSplitLargeEvent` em um pipeline `$changeStream` e ele deve ser o estágio final no pipeline.
`$collStats`	Retorna estatísticas sobre uma coleção ou visualização.
`$count`	Retorna uma contagem do número de documentos nesta etapa do pipeline de agregação. Distinto do acumulador de agregação do `$count`.
`$currentOp`	Retorna informações sobre operações ativas e/ou dormentes para a implementação do MongoDB. Para executar, use o método `db.aggregate()` .
`$densify`	Cria novos documentos em uma sequência de documentos onde determinados valores em um campo estão faltando.
`$documents`	Retorna documentos literais de valores de entrada.
`$facet`	Processa vários aggregation pipelines em um único estágio no mesmo conjunto de documentos de entrada. Permite a criação de agregações multifacetadas capazes de caracterizar dados em várias dimensões, ou facets, em um único estágio.
`$fill`	Preenche `null` e os valores de campo ausentes nos documentos.
`$geoNear`	Retorna um fluxo ordenado de documentos baseado na proximidade de um ponto geoespacial. Incorpora a funcionalidade do `$match`, `$sort` e `$limit` para dados geoespaciais. Os documentos de saída incluem um campo de distância adicional e podem incluir um campo de identificador de local.
`$graphLookup`	Executa uma pesquisa recursiva em uma coleção. Para cada documento de saída, adiciona um novo campo de matriz que contém resultados transversais da busca recursiva por esse documento.
`$group`	Agrupa documentos de entrada por uma expressão de identificador especificada e aplica a(s) expressão(ões) acumuladora(s), se especificada(s), para cada grupo. Consome todos os documentos de entrada e gera um documento por cada grupo distinto. Os documentos de saída só contêm o campo identificador e, se especificado, campos acumulados.
`$indexStats`	Retorna estatísticas sobre o uso de cada índice para a coleção.
`$limit`	Passa os primeiros n documentos não modificados para o pipeline onde n é o limite especificado. Para cada documento de entrada, gera um documento (para os primeiros n documentos) ou zero documentos (após os primeiros n documentos).
`$listLocalSessions`	Lista todas as sessões ativas recentemente em uso na `mongos` ou instância`mongod` conectada no momento. Essas sessões podem ainda não ter sido propagadas para a coleção `system.sessions`.
`$listSearchIndexes`	Retorna informações sobre Atlas Search indexes em uma coleção especificada.
`$listSessions`	Lista todas as sessões que estão ativas há muito tempo para propagar para a coleção `system.sessions`.
`$lookup`	Executa uma junção externa esquerda a outra collection no mesmo banco de dados para filtrar documentos da collection "associada" para processamento.
`$match`	Filtra o fluxo de documentos para permitir que apenas documentos correspondentes passem sem modificações para o próximo estágio do pipeline. O `$match` utiliza consultas MongoDB padrão. Para cada documento de entrada, gera um documento (uma correspondência) ou zero documentos (nenhuma correspondência).
`$merge`	Escreve os documentos resultantes do aggregation pipeline em uma coleção. O estágio pode incorporar (inserir novos documentos, mesclar documentos, substituir documentos, manter documentos existentes, falhar na operação, processar documentos com um pipeline de atualização personalizado) os resultados em uma coleção de saída. Para usar o estágio `$merge` , ele deve ser o último estágio do pipeline. Novidades na versão 4.2.
`$out`	Escreve os documentos resultantes do aggregation pipeline em uma coleção. Para usar o estágio `$out`, ele deve ser o último estágio no pipeline.
`$planCacheStats`	Retorna informações de cache do plano para uma coleção.
`$project`	Remodela cada documento no fluxo, adicionando novos campos ou removendo campos existentes. Para cada documento de entrada, gera um documento.
`$redact`	Remodela cada documento no fluxo restringindo o conteúdo de cada documento com base nas informações armazenadas nos próprios documentos. Incorpora a funcionalidade do `$project` e `$match`. Pode ser usado para implementar a redação em nível de campo. Para cada documento de entrada, gera um ou zero documentos.
`$replaceRoot`	Substitui um documento pelo documento incorporado especificado. A operação substitui todos os campos existentes no documento de entrada, incluindo o campo `_id`. Especifique um documento incorporado no documento de entrada para promover o documento incorporado ao nível superior.
`$replaceWith`	Substitui um documento pelo documento incorporado especificado. A operação substitui todos os campos existentes no documento de entrada, incluindo o campo `_id`. Especifique um documento incorporado no documento de entrada para promover o documento incorporado ao nível superior. Apelido para `$replaceRoot`.
`$sample`	Seleciona aleatoriamente o número especificado de documentos de sua entrada.
$search	Executa um pesquisar de texto completo do campo ou campo em uma collection do Atlas. Observação `$search` está disponível apenas para clusters do MongoDB Atlas, e não está disponível para implantações autogerenciadas. Para saber mais, consulte Estágios de pipeline de agregação do Atlas Search.
$searchMeta	Retorna diferentes tipos de documentos de resultado de metadados para a query Pesquisa do Atlas em relação a uma collection do Atlas . Observação `$searchMeta` está disponível apenas para clusters do MongoDB Atlas que executam o MongoDB v4.4.9 ou superior e não está disponível para implantações autogerenciadas. Para saber mais, consulte Estágios de pipeline de agregação do Atlas Search.
`$set`	Adiciona novos campos aos documentos. Produz documentos que contêm todos os campos existentes dos documentos de entrada e novos campos adicionados. Apelido para `$addFields`.
`$setWindowFields`	Agrupa documentos em janelas e aplica um ou mais operadores aos documentos em cada janela. Novidades na versão 5.0.
`$shardedDataDistribution`	Fornece dados e informações de distribuição de tamanho em collection fragmentadas. Novidades na versão 6.0.3.
`$skip`	Ignora os primeiros n documentos, em que n é o número de pulos especificado, e passa os documentos restantes sem modificações para o pipeline. Para cada documento de entrada, produz zero documentos (para os primeiros n documentos) ou um documento (se após os primeiros n documentos).
`$sort`	Reordena o fluxo de documentos por uma chave de classificação especificada. Apenas a ordem muda; os documentos permanecem inalterados. Para cada documento de entrada, gera um documento.
`$sortByCount`	Agrupa documentos recebidos com base no valor de uma expressão especificada e, em seguida, calcula a contagem de documentos em cada grupo distinto.
`$unionWith`	Executa uma união de duas coleções; ou seja, combina resultados de pipeline de duas coleções em um único conjunto de resultados. Novidades na versão 4.4.
`$unset`	Remove/exclui campos dos documentos. Apelido para o estágio `$project` que exclui/remove campos.
`$unwind`	Desconstrói um campo de array a partir dos documentos de entrada para gerar um documento para cada elemento. Cada documento de saída substitui a array por um valor de elemento. Para cada documento de entrada, produz n documentos onde n é o número de elementos de array e pode ser zero para uma array vazia.

← $bit

$addFields (agregação) →

Compatibilidade

Estágios

db.collection.aggregate() Estágios

Observação

Observação

Observação

Observação

db.aggregate() Estágios

Estágios disponíveis para atualizações

Lista alfabética de estágios

Observação

Observação

`db.collection.aggregate()` Estágios

`db.aggregate()` Estágios