$out (agregação)

Nesta página

Definição

Sintaxe
Comportamentos
Exemplos

Definição

$out

Pega os documentos retornados pelo pipeline de agregação e os grava na coleção especificada. Você pode especificar o banco de dados de saída.

O estágio $out deve ser o último estágio no pipeline. O operador $out permite que a framework de aggregation retorne definições de resultados de qualquer tamanho.

Sintaxe

O estágio $out tem a seguinte sintaxe:

$out pode usar um documento para especificar o banco de dados de saída, bem como a coleção de saída:

{ $out: { db: "<output-db>", coll: "<output-collection>" } }

Campo	Descrição
db	O nome do banco de dados de saída. Para umconjunto de réplicas do ou um autônomo, se o banco de banco de dados de saída não existir, o `$out` também criará o banco de dados de dados. Para um cluster fragmentado, o banco de dados de saída especificado já deve existir.
coll	O nome da collection de saída.

$out pode usar uma string para especificar somente a collection de saída (ou seja, saída para uma collection no mesmo banco de dados):
```
{ $out: "<output-collection>" } // Output collection is in the same database
```

Importante

Você não pode especificar uma collection fragmentada como collection de saída. A collection de entrada de um pipeline pode ser fragmentada. Para gerar a saída para uma collection fragmentada, consulte $merge (disponível começando no MongoDB 4.2).
O operador $out não pode gravar resultados em uma capped collection.
Se você modificar uma coleção com um índice do Atlas Search, deverá primeiro excluir e depois recriar o índice de pesquisa. Então considere usar $merge.

Comparação com `$merge`

Com a introdução de $merge na versão 4.2, O MongoDB fornece duas etapas, $merge e $out, para escrever os resultados do pipeline de agregação em uma coleção. A seguir, resumimos as capacidades dos dois estágios:

$out

$merge

Pode enviar para uma coleção no mesmo banco de dados ou em um banco de dados diferente.

Pode enviar para uma coleção no mesmo banco de dados ou em um banco de dados diferente.

Cria uma nova coleta se a coleta de saída ainda não existir.

Cria uma nova coleta se a coleta de saída ainda não existir.

Substitui completamente a coleção de saída se ela já existir.

Pode incorporar resultados (inserir novos documentos, mesclar documentos, substituir documentos, manter documentos existentes, falhar a operação, processar documentos com um pipeline de atualização personalizado) a uma coleção existente.
Pode substituir o conteúdo da collection, mas somente se os resultados da aggregation contiverem uma correspondência para todos os documentos existentes na collection.

Não é possível gerar saída para uma coleção fragmentada. A coleção de entrada, no entanto, pode ser fragmentada.

Pode gerar saída para uma coleção fragmentada. A coleta de entrada também pode ser fragmentada.

Corresponde às declarações SQL:
- INSERT INTO T2 SELECT * FROM T1
- SELECT * INTO T2 FROM T1

Corresponde à declaração SQL:

MERGE T2 AS TARGET
USING (SELECT * FROM T1) AS SOURCE
ON MATCH (T2.ID = SOURCE.ID)
WHEN MATCHED THEN
  UPDATE SET TARGET.FIELDX = SOURCE.FIELDY
WHEN NOT MATCHED THEN
  INSERT (FIELDX)
  VALUES (SOURCE.FIELDY)

Criar/Atualizar visualizações materializadas

Comportamentos

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

A partir do MongoDB 5.0, $out poderá 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 suportam o direcionamento de operações $out para nós secundários do conjunto de réplicas. Verifique a documentação do driver para ver quando seu driver 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 :

Cria uma collection temporária.
Copia os índices da collection existente para a collection temporária.
Insere os documentos na collection temporária.
Chama o comando renameCollection com dropTarget: true para renomear a collection temporária para a collection de destino.

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.

Erros de validação de esquema

Se sua coleção coll usar validação de esquema e tiver validationAction definido como error, inserir um documento inválido com $out gerará um erro. A operação $out não faz alterações na coleção preexistente, e os documentos retornados pelo pipeline de agregação não são adicionados à coleção coll.

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 collection uma com um índice do Atlas Search , você deverá excluir e recriar o índice do Atlas Search . Considere usar $merge em vez disso.

`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 aggregation pipeline que inclua $out durante o processo de descarte. Consulte mongodump --oplog para mais informações.

Restrições

Restrições	Descrição
Transações	Um pipeline de agregação não pode utilizar `$out` dentro de transações.
Coleções de Time Series	Um pipeline de agregação não pode utilizar `$out` para gerar uma coleção de séries temporais.
ver definição	O estágio `$out` não é permitido como parte de uma definição de visualização. Se a definição de visualização incluir pipeline aninhado (por exemplo, a definição de visualização inclui o estágio `$lookup` ou `$facet` ), essa restrição de estágio `$out` também se aplica aos pipelines aninhados.
`$lookup` estágio	A partir de 4.2, você não pode incluir o estágio no pipeline `$out` aninhado do `$lookup`estágio .
`$facet` estágio	`$facet` pipeline aninhado do estágio não pode conter o estágio `$out`.
`$unionWith` estágio	`$unionWith` pipeline aninhado do estágio não pode conter o estágio `$out`.
`"linearizable"` Leia a preocupação	O estágio `$out` não pode ser usado em conjunto com a preocupação de leitura `"linearizable"`. Se você especificar a preocupação de leitura `"linearizable"` para `db.collection.aggregate()`, não poderá incluir o estágio `$out` no pipeline.

Exemplos

No banco de dados do test, crie uma collection books com os seguintes documentos:

db.getSiblingDB("test").books.insertMany([
   { "_id" : 8751, "title" : "The Banquet", "author" : "Dante", "copies" : 2 },
   { "_id" : 8752, "title" : "Divine Comedy", "author" : "Dante", "copies" : 1 },
   { "_id" : 8645, "title" : "Eclogues", "author" : "Dante", "copies" : 2 },
   { "_id" : 7000, "title" : "The Odyssey", "author" : "Homer", "copies" : 10 },
   { "_id" : 7020, "title" : "Iliad", "author" : "Homer", "copies" : 10 }
])

Se o banco de dados test ainda não existir, a operação de inserção criará o banco de dados e a collection books.

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

Observação

Para um conjunto de réplicas ou um autônomo, se o banco de dados de saída não existir, o $out também criará o banco de dados.

Para um cluster fragmentado, o banco de dados de saída especificado já deve existir.

$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" } }
] )