$out (aggregation stage)（聚合阶段）

Definition定义

$out

Takes the documents returned by the aggregation pipeline and writes them to a specified collection. You can specify the output database.获取聚合管道返回的文档并将其写入指定的集合。您可以指定输出数据库。

The $out stage must be the last stage in the pipeline. The $out operator lets the aggregation framework return result sets of any size.$out阶段必须是管道中的最后一个阶段。$out运算符允许聚合框架返回任何大小的结果集。

Warning

If the collection specified by the $out operation already exists, then the $out stage atomically replaces the existing collection with the new results collection upon completion of the aggregation. 如果$out操作指定的集合已经存在，则$out阶段会在聚合完成后用新的结果集合原子性地替换现有集合。See Replace Existing Collection for details.有关详细信息，请参阅替换现有集合。

Syntax语法

The $out stage has the following syntax:$out阶段具有以下语法：

• $out can take a string to specify only the output collection (i.e. output to a collection in the same database):可以使用字符串仅指定输出集合（即输出到同一数据库中的集合）：

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

• $out can take a document to specify the output database as well as the output collection:可以使用文档来指定输出数据库和输出集合：

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

• Starting in MongoDB 7.0.3 and 7.1, $out can take a document to output to a time series 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" ,
      }
    }
  }

  Important

  Changing Time Series Granularity改变时间序列粒度

  After creating a time series collection, you can modify its granularity using the collMod method. However, you can only increase the timespan covered by each bucket. You cannot decrease it.创建时间序列集合后，可以使用collMod方法修改其粒度。但是，您只能增加每个桶覆盖的时间跨度。你不能减少它。

  Field字段	Description描述
  db	The output database name.输出数据库名称。 For a replica set or a standalone, if the output database does not exist, $out also creates the database.对于副本集或单机版副本，如果输出数据库不存在，$out也会创建数据库。
  coll	The output collection name.输出集合名称。
  timeseries	A document that specifies the configuration to use when writing to a time series collection. The timeField is required. All other fields are optional.指定写入时间序列集合时使用的配置的文档。timeField是必需的。所有其他字段都是可选的。
  timeField	Required when writing to a time series collection. The name of the field which contains the date in each time series document. Documents in a time series collection must have a valid BSON date as the value for the timeField.写入时间序列集合时需要。每个时间序列文档中包含日期的字段的名称。时间序列集合中的文档必须具有有效的BSON日期作为timeField的值。
  metaField	Optional. 可选。The name of the field which contains metadata in each time series document. The metadata in the specified field should be data that is used to label a unique series of documents. 每个时间序列文档中包含元数据的字段的名称。指定字段中的元数据应该是用于标记一系列唯一文档的数据。The metadata should rarely, if ever, change The name of the specified field may not be _id or the same as the timeseries.timeField. The field can be of any data type.元数据应该很少（如果有的话）更改。指定字段的名称可能不是_id或与timeseries.timeField不同。该字段可以是任何数据类型。 Although the metaField field is optional, using metadata can improve query optimization. 虽然metaField字段是可选的，但使用元数据可以改善查询优化。For example, MongoDB automatically creates a compound index on the metaField and timeField fields for new collections. 例如，MongoDB会自动在metaField和timeField字段上为新集合创建复合索引。If you do not provide a value for this field, the data is bucketed solely based on time.如果不为此字段提供值，则数据将仅基于时间进行分组。
  granularity	Optional. 可选。Do not use if setting bucketRoundingSeconds and bucketMaxSpanSeconds.如果设置bucketRoundingSeconds和bucketMaxSpanSeconds，则不要使用。 Possible values are seconds (default), minutes, and hours.可能的值是seconds（默认值）、minutes和hours。 Set granularity to the value that most closely matches the time between consecutive incoming timestamps. This improves performance by optimizing how MongoDB stores data in the collection.将granularity设置为与连续传入时间戳之间的时间最接近的值。这通过优化MongoDB在集合中存储数据的方式来提高性能。 For more information on granularity and bucket intervals, see Set Granularity for Time Series Data.有关粒度和桶间隔的更多信息，请参阅设置时间序列数据的粒度。
  bucketMaxSpanSeconds	Optional. 可选。Use with bucketRoundingSeconds as an alternative to granularity. 使用bucketRoundingSeconds作为granularity的替代方案。Sets the maximum time between timestamps in the same bucket.设置同一桶中时间戳之间的最大时间间隔。 Possible values are 1-31536000.可能的值为1-31536000。 New in version 6.3.在版本6.3中新增。
  bucketRoundingSeconds	Optional. 可选。Use with bucketMaxSpanSeconds as an alternative to granularity. Must be equal to bucketMaxSpanSeconds.使用bucketMaxSpanSeconds作为粒度的替代方案。必须等于bucketMaxSpanSeconds。 When a document requires a new bucket, MongoDB rounds down the document's timestamp value by this interval to set the minimum time for the bucket.当文档需要新的桶时，MongoDB会按此间隔对文档的时间戳值进行四舍五入，以设置桶的最小时间。 New in version 6.3.在版本6.3中新增。

Behaviors行为

Examples示例

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

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

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; }
}

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

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

var pipeline = new EmptyPipelineDefinition<Movie>()
    .Out(movieCollection);

const pipeline = [{ $out: { db: "sample_mflix", coll: "movies" } }];

const cursor = collection.aggregate(pipeline);
return cursor;