$out (aggregation)

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.

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. See Replace Existing Collection for details.

Syntax

The $out stage has the following syntax:

• $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:

  { $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.

  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. For a sharded cluster, the specified output database must already exist.
  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	Required when writing to a time series collection. .. include:: /includes/time-series/fact-time-field-description.rst
  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. Although the metaField field is optional, using metadata can improve query optimization. For example, MongoDB automatically creates a compound index on the metaField and timeField fields for new collections. 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. Possible values are seconds (default), minutes, and 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. 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. Sets the maximum time between timestamps in the same bucket. Possible values are 1-31536000. New in version 6.3.
  bucketRoundingSeconds	Optional. Use with bucketMaxSpanSeconds as an alternative to granularity. Must be equal to 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. New in version 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 string 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 movieCollection = client
    .GetDatabase("sample_mflix")
    .GetCollection<Movie>("movies");
var pipeline = new EmptyPipelineDefinition<Movie>()
    .Out(movieCollection);