/ /

Operadores

Estágios do pipeline de agregação

Página inicial do Docs

Manual do banco de dados

Referência

Operadores

Estágios do pipeline de agregação

$out (agregação)

Esta versão da documentação foi arquivada e não é mais suportada. Para atualizar seu sistema do 6.0, consulte osprocedimentos de atualização do MongoDB 7.0 .

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.

Aviso

$out substitui a collection especificada, se existir. Consulte Substituir collection existente para obter detalhes.

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 um conjunto de réplicas ou um autônomo, se o banco de dados de saída não existir, o também criará o banco de`$out` dados. Para um cluster fragmentado, o banco de dados de saída especificado já deve existir.
coll	O nome da collection de saída.

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 usar `$out` dentro de transações.
Coleções de Time Series	Um agregação pipeline não pode usar para gerar uma coleção de séries `$out` temporais.
ver definição	O estágio não é permitido `$out` 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 `$lookup` `$facet` estágio ou), essa `$out` restrição de estágio também se aplica aos pipelines aninhados.
`$lookup` estágio	A partir 4.2 de, você não pode incluir o estágio no pipeline `$out` `$lookup`aninhado do estágio.
`$facet` estágio	O`$facet`estágio do pipeline aninhado não pode incluir o estágio`$out`.
`$unionWith` estágio	O`$unionWith`estágio do pipeline aninhado não pode incluir o estágio`$out`.
`"linearizable"` Leia a preocupação	O estágio `$out` não pode ser usado em conjunto com 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" } }
] )

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

Os exemplos de C# nesta página utilizam o banco de dados sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver MongoDB .NET/C#.

A seguinte classe Movie modela os documentos na collection sample_mflix.movies:

public class Movie
{
    public ObjectId Id { get; set; }
    public int Runtime { get; set; }
    
    public string Title { get; set; }
    public string Rated { get; set; }
    public List<string> Genres { get; set; }
    public string Plot { get; set; }
    
    public ImdbData Imdb { get; set; }
    public int Year { get; set; }
    public int Index { get; set; }
    
    public string[] Comments { get; set; }
   
    [BsonElement("lastupdated")]
    public DateTime LastUpdated { get; set; }
}

Observação

ConventionPack para Pascal Case

As classes C# nesta página usam Pascal case para seus nomes de propriedade, mas os nomes de campo na coleção MongoDB usam Camel case. Para considerar essa diferença, você pode usar o seguinte código para registrar um ConventionPack quando o aplicativo iniciar:

var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true);

Para usar o driver MongoDB .NET/C# para adicionar um estágio $out a um pipeline de agregação, chame o método Out() em um objeto PipelineDefinition.

O exemplo a seguir cria um estágio de pipeline que grava os resultados do pipeline na coleção movies:

var movieCollection = client
    .GetDatabase("sample_mflix")
    .GetCollection<Movie>("movies");
var pipeline = new EmptyPipelineDefinition<Movie>()
    .Out(movieCollection);

Os exemplos do Node.js nesta página utilizam o banco de dados do sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver do MongoDB Node.js

Para usar o driver Node.js do MongoDB para adicionar um estágio $out a um pipeline de agregação , use o operador $out em um objeto de pipeline.

O exemplo a seguir cria uma etapa do pipeline que grava os resultados do pipeline na coleção movies. O exemplo em seguida executa o pipeline de agregação:

const pipeline = [{ $out: { db: "sample_mflix", coll: "movies" } }];
const cursor = collection.aggregate(pipeline);
return cursor;

Voltar

$merge

$planCacheStats

Definição

Aviso

Sintaxe

Importante

Comparação com $merge

Comportamentos

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

Criar nova collection

Substituir collection existente

Erros de validação de esquema

Restrições de índice

majority Preocupação de leitura

Interação com mongodump

Restrições

Exemplos

Saída para o mesmo banco de dados

Gerar saídas para um banco de dados diferente

Observação

Observação

ConventionPack para Pascal Case

Comparação com `$merge`

`majority` Preocupação de leitura

Interação com `mongodump`