$out (agregação)

Comparação com $merge

O MongoDB fornece dois estágios, $merge e $out, para escrever os resultados do aggregation pipeline em uma collection. A seguir, resumimos as capacidades dos dois estágios:

Operações de leitura $out são executadas em membros secundários do conjunto de réplicas

A partir do MongoDB 5.0, $out pode ser executado em nós secundários do conjunto de réplicas se todos os nós no cluster tiverem featureCompatibilityVersion definido como 5.0 ou superior e a read preference estiver definida como secundária.

As operações de leitura da instrução $out ocorrem nos nós secundários, enquanto as operações de gravação ocorrem somente nos nós primários.

Nem todas as versões de driver aceitam o direcionamento de operações $out para nós secundários de conjuntos de réplicas. Verifique a documentação do driver para ver quando ele passou a oferecer suporte a $out em execução em um secundário.

Criar nova collection

A operação $out cria uma nova collection se ainda não houver uma.

A collection não fica visível até que a aggregation seja concluída. Se ela falhar, o MongoDB não criará a collection.

Substituir collection existente

Se a collection especificada pela operação $out já existir, após a conclusão da aggregation, o estágio $out substituirá atomicamente a collection existente pela nova collection de resultados. Especificamente, a operação $out:

1. Cria uma collection temporária.

2. Copia os índices da collection existente para a collection temporária.

3. Insere os documentos na collection temporária.

4. Chama o comando renameCollection com dropTarget: true para renomear a collection temporária para a collection de destino.

Se existe uma collection especificada e a operação $out especifica as opções do timeseries, então as seguintes restrições se aplicam:

1. A collection existente deve ser uma coleção de séries temporais.

2. A collection existente não deve ser uma visualização.

3. As opções de timeseries incluídas no estágio $out devem corresponder exatamente às da collection existente.

A operação $out não altera nenhum índice existente na collection anterior. Se a aggregation falhar, a operação $out não fará alterações na collection pré-existente.

Restrições de índice

O pipeline não será concluído se os documentos produzidos por ele violarem qualquer índice único, incluindo o índice no campo _id da collection de saída original.

Se a operação $out modificar uma coleção com um índice do Atlas Search, você deverá excluir e recriar o índice de pesquisa. Considere usar $merge.

majority Preocupação de leitura

Você pode especificar o nível de preocupação de leitura "majority" de uma agregação que inclui um estágio $out.

Interação com mongodump

Um mongodump iniciado com --oplog falhará se um cliente emitir um pipeline de agregação que contiver $out durante o processo de despejo. Consulte mongodump --oplog para obter mais informações.

Restrições

Saída para o mesmo banco de dados

A seguinte operação de aggregation reposiciona os dados na collection books no banco de dados test para que tenham títulos agrupados por autores e então grava os resultados na collection authors e no banco de dados test.

db.getSiblingDB("test").books.aggregate( [
    { $group : { _id : "$author", books: { $push: "$title" } } },
    { $out : "authors" }
] )

Primeiro estágio ($group):

O estágio $group se agrupa pelos authors e usa $push para adicionar os títulos a um campo de array books:

{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }
{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }

Segundo estágio ($out):

O estágio $out envia os documentos para a collection authors no banco de dados test.

Para visualizar os documentos na collection de saída, execute a seguinte operação:

db.getSiblingDB("test").authors.find()

A collection contém os seguintes documentos:

{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }
{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }

Gerar saídas para um banco de dados diferente

$out pode gerar saídas para uma coleção em um banco de dados diferente de onde a agregação é executada.

A operação de aggregation a seguir reposiciona os dados na collection books para ter títulos agrupados por autores e então grava os resultados na collection authors no banco de dados reporting:

db.getSiblingDB("test").books.aggregate( [
    { $group : { _id : "$author", books: { $push: "$title" } } },
    { $out : { db: "reporting", coll: "authors" } }
] )

Primeiro estágio ($group):

O estágio $group se agrupa pelos authors e usa $push para adicionar os títulos a um campo de array books:

{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }
{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }

Segundo estágio ($out):

O estágio $out envia os documentos para a collection authors no banco de dados reporting.

Para visualizar os documentos na collection de saída, execute a seguinte operação:

db.getSiblingDB("reporting").authors.find()

A collection contém os seguintes documentos:

{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }
{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }