$out（聚合）

定义

$out

将聚合管道返回的文档写入指定的集合。您可以指定输出数据库。

$out阶段必须是管道中的最后一个阶段。$out运算符允许聚合框架返回任何大小的结果集。

警告

如果$out操作指定的集合已存在，则在聚合完成后，$out阶段会原子性地用新的结果集合替换现有集合。有关详细信息，请参阅替换现有集合

语法

输出阶段 $out 有以下语法

• $out 可以接受一个字符串来指定仅输出集合（即输出到同一数据库中的集合）

  { $out: "<output-collection>" } // Output collection is in the same database

• $out 可以接受一个文档来指定输出数据库以及输出集合

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

• 从 MongoDB 7.0.3 和 7.1 开始，$out 可以接受一个文档来输出到时间序列集合:

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

  重要

  更改时间序列粒度

  创建时间序列集合后，您可以使用 collMod 方法修改其粒度。但是，您只能增加每个桶覆盖的时间跨度。您不能减少它。

  字段	描述
  db	输出数据库名。 对于副本集或独立服务器，如果输出数据库不存在，$out 也会创建数据库。
  coll	输出集合名。
  timeseries	一个文档，指定写入时间序列集合时使用的配置。必须提供 timeField。其他所有字段都是可选的。
  timeField	写入时间序列集合时必须提供。.. include:: /includes/time-series/fact-time-field-description.rst
  metaField	可选。包含每个时间序列文档元数据的字段的名称。在指定的字段中的元数据应该是用于标记唯一文档序列的数据。元数据很少或几乎不会改变。指定字段的名称不得为 _id 或与 timeseries.timeField 相同。字段可以是任何数据类型。 尽管 metaField 字段是可选的，但使用元数据可以提高查询优化。例如，MongoDB自动为新集合在 metaField 和 timeField 字段上创建组合索引。如果您不为此字段提供值，数据将仅基于时间进行桶划分。
  granularity	可选。如果设置了 bucketRoundingSeconds 和 bucketMaxSpanSeconds，则不要使用。 可能的值是 seconds（默认值）、minutes 和 hours。 将 granularity 设置为与连续传入时间戳之间的时间最接近的值。这通过优化MongoDB在集合中存储数据的方式来提高性能。 有关粒度和桶间隔的更多信息，请参阅为时间序列数据设置粒度。
  bucketMaxSpanSeconds	可选。与bucketRoundingSeconds一起使用，作为粒度的替代方案。设置同一桶中时间戳之间的最大时间间隔。 可能值为1-31536000。 新特性版本6.3.
  bucketRoundingSeconds	可选。与bucketMaxSpanSeconds一起使用，作为粒度的替代方案。必须等于bucketMaxSpanSeconds。 当文档需要新的桶时，MongoDB将文档的时间戳值按此间隔向下舍入，以设置桶的最小时间。 新特性版本6.3.

行为

示例

在 test 数据库中，创建一个包含以下文档的集合 books

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

如果 test 数据库不存在，则插入操作将创建数据库以及 books 集合。

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

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

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

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

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

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