Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / /

$out (agregação)

Nesta página

  • Definição
  • Sintaxe
  • Comportamentos
  • Exemplos
$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 do pipeline. O operador $out permite que o framework de aggregation retorne conjuntos de resultados de qualquer tamanho.

Aviso

Se a coleção especificada pela operação $out já existir, então a etapa $out substituirá atomicamente a coleção existente pela nova coleção de resultados após a conclusão da agregação. Consulte Substituir coleção existente para mais informações.

O estágio $out tem a seguinte sintaxe:

  • $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
  • $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>" } }
  • A partir do MongoDB 7.0.3 e 7.1, $out pode levar um documento para a saída para uma coleção de séries temporais:

    { $out:
    { db: "<output-db>", coll: "<output-collection>",
    timeseries: {
    timeField: "<field-name>",
    metaField: "<field-name>",
    granularity: "seconds" || "minutes" || "hours" ,
    }
    }
    }

    Importante

    Alterando a granularidade de série temporal

    Depois de criar uma coleção de séries temporais, você poderá modificar sua granularidade usando o método collMod. No entanto, você só pode aumentar o intervalo de tempo coberto por cada bucket. Você não pode diminuí-lo.

    Campo
    Descrição
    db

    O nome do banco de dados de saída.

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

    coll

    O nome da collection de saída.

    timeseries

    Um documento que especifica a configuração a ser usada ao gravar em uma coleção de séries temporais. O timeField é obrigatório. Todos os outros campos são opcionais.

    timeField

    Obrigatório ao gravar em uma coleção de séries temporais. .. include:: /includes/time-series/fact-time-field-description.rst

    metaField

    Opcional. O nome do campo que contém metadados em cada documento de série temporal. Os metadados no campo especificado devem ser dados utilizados para rotular uma série exclusiva de documentos. Os metadados raramente devem mudar. O nome do campo especificado não pode ser _id ou o mesmo que o timeseries.timeField. O campo pode ser de qualquer tipo de dados.

    Embora o campo metaField seja opcional, o uso de metadados pode melhorar a otimização da query. Por exemplo, o MongoDB cria automaticamente um índice composto nos campos metaField e timeField para novas collections. Se você não fornecer um valor para este campo, os dados serão agrupados exclusivamente com base no tempo.

    granularity

    Opcional. Não use se estiver configurando bucketRoundingSeconds e bucketMaxSpanSeconds.

    Os valores possíveis são seconds (padrão), minutes e hours.

    Defina granularity como o valor que mais se aproxima do tempo entre carimbos de data/hora consecutivos de entrada. Isso melhora o desempenho otimizando a forma como o MongoDB armazena dados na collection.

    Para obter mais informações sobre granularidade e intervalos de bucket, consulte Definir granularidade para dados de séries temporais.

    bucketMaxSpanSeconds

    Opcional. Use com bucketRoundingSeconds como alternativa a granularity. Define o tempo máximo entre os carimbos de data/hora no mesmo bloco.

    Os valores possíveis são 1-31536000.

    Novidades na versão 6.3.

    bucketRoundingSeconds

    Opcional. Use com bucketMaxSpanSeconds como alternativa a granularity. Deve ser igual a bucketMaxSpanSeconds.

    Quando um documento requer um novo bucket, o MongoDB arredonda para baixo o valor de carimbo de data/hora do documento por esse intervalo para definir o tempo mínimo para o bucket.

    Novidades na versão 6.3.

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 uma saída para uma collection fragmentada, consulte $merge.

  • 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.

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:

$out
  • 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.

  • A partir do MongoDB 7.0.3 e 7.1, é possível gerar uma saída para uma coleção de séries temporais.

  • Não é possível enviar para uma coleção de séries temporais.

  • 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

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.

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.

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.

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.

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.

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

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
Descrição
Um aggregation pipeline não pode usar $out dentro das transações.
O estágio $out não é permitido como parte de uma definição de visualização. Se a definição de visualização incluir um pipeline aninhado (por exemplo, a definição de visualização incluir estágio $lookup ou $facet), essa restrição de $out estágios também se aplicará aos pipelines aninhados.
$lookup estágio
Você não pode incluir o estágio do $out no $lookup do estágio do pipeline aninhado.
$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 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.

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.

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

Observação

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

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

Voltar

$merge