$out（聚合）

定义

$out

获取聚合管道返回的文档并将其写入指定的collection。您可以指定输出数据库。

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

警告

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

语法

$out 阶段使用以下语法：

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

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

• $out 可以使用文档来指定输出数据库以及输出collection：

  { $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 相同。字段可以是任何类型。
  granularity	可选。如果设置 bucketRoundingSeconds 和 bucketMaxSpanSeconds，请勿使用。 可能的值为 seconds（默认）、minutes、和 hours。 将 granularity 设置为最接近连续输入时间戳之间时间的值。这可通过优化 MongoDB 在集合中存储数据的方式来提高性能。 有关粒度和桶间隔的更多信息，请参阅设置时间序列数据的粒度。
  bucketMaxSpanSeconds	可选。与 bucketRoundingSeconds 结合使用以作为 granularity 的替代方案。设置同一存储桶中不同时间戳之间的最大时间间隔。 可能的值为 1-31536000。 6.3 版本中的新功能。
  bucketRoundingSeconds	可选。与 bucketMaxSpanSeconds 结合使用作为 granularity 的替代方案。必须等于 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" ] }