$out (etapa de agregación)

Definición

$out

Toma los documentos devueltos por la canalización de agregación y los guarda en una colección especificada. Puede especificar la base de datos de salida.

La etapa $out debe ser la última etapa del pipeline. El operador $out permite que el marco de agregación devuelva conjuntos de resultados de cualquier tamaño.

Advertencia

Si la colección especificada por la operación $out ya existe, entonces la etapa $out reemplaza de forma atómica la colección existente con la nueva colección de resultados al completar la agregación. Ver Reemplazar colección existente para más detalles.

Sintaxis

La etapa $out tiene la siguiente sintaxis:

• $out puede tomar un string para especificar solo la colección de salida (es decir, salida a una colección en la misma base de datos):

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

• $out puede utilizar un documento para especificar la base de datos de salida, así como la colección de salida:

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

• A partir de MongoDB 7.0.3 y 7.1, $out puede tomar un documento para emitir a un colección de series de tiempo:

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

  Importante

  Cambio de la granularidad de las series de tiempo

  Después de crear una colección de series de tiempo, se puede modificar la granularidad utilizando el método collMod. Sin embargo, solo se puede aumentar el intervalo de tiempo cubierto por cada bucket. No se puede disminuir.

  Campo	Descripción
  db	El nombre de la base de datos de salida. Para un Set de réplicas o un autónomo, si la base de datos de salida no existe, $out también crea la base de datos. Para un clúster particionado, la base de datos de salida especificada ya debe existir.
  coll	El nombre de la colección de salida.
  timeseries	Un documento que especifica la configuración a utilizar al escribir en una colección de series de tiempo. El timeField es necesario. Todos los demás campos son opcionales.
  timeField	Requerido al escribir en una colección de series de tiempo. El nombre del campo que contiene la fecha en cada documento de serie de tiempo. Los documentos en una colección de series de tiempo deben tener una fecha BSON válida como valor para el timeField.
  metaField	Opcional. El nombre del campo que contiene los metadatos en cada documento de serie de tiempo. Los metadatos del campo especificado deben ser datos que se utilicen para etiquetar una serie única de documentos. Los metadatos difícilmente cambien. El nombre del campo especificado no puede ser _id ni el mismo que el timeseries.timeField. El campo puede ser de cualquier tipo de dato. Aunque el campo metaField es opcional, el uso de metadatos puede mejorar la optimización de query. Por ejemplo, MongoDB crea un índice compuesto automáticamente en los campos metaField y timeField para las nuevas colecciones. Si no proporcionas un valor para este campo, los datos se agrupan únicamente en función del tiempo.
  granularity	Opcional. No utilice si se configuran bucketRoundingSeconds y bucketMaxSpanSeconds. Los valores posibles son seconds (por defecto), minutes y hours. Configure granularity al valor que más se asemeje al intervalo de tiempo entre las marcas de tiempo entrantes consecutivas. Esto mejora el rendimiento al optimizar cómo MongoDB almacena los datos en la colección. Para obtener más información sobre la granularidad y los intervalos de agrupación, consulta Configurar granularidad para datos de series de tiempo.
  bucketMaxSpanSeconds	Opcional. Utilice con bucketRoundingSeconds como alternativa a granularity. Establece el tiempo máximo entre marcas de tiempo en el mismo bucket. Los valores posibles son de 1 a 31536000. Nuevo en la versión 6.3.
  bucketRoundingSeconds	Opcional. Utilice con bucketMaxSpanSeconds como alternativa a granularity. Debe ser igual a bucketMaxSpanSeconds. Cuando un documento requiere un nuevo bucket, MongoDB redondea hacia abajo el valor de la marca de tiempo del documento según este intervalo para establecer el tiempo mínimo para el bucket. Nuevo en la versión 6.3.

Comportamientos

Ejemplos

db.movies.aggregate( [
    { $match : { runtime : { $gt : 1000 } } },
    { $group : { _id : "$year", movies: { $push: "$title" } } },
    { $out : "movies_by_year" }
] )

db.movies_by_year.find().sort( { _id: 1 } )

[
  { _id: 1978, movies: [ 'Centennial' ] },
  { _id: 1994, movies: [ 'Baseball' ] }
]

db.movies.aggregate( [
    { $match : { runtime : { $gt : 1000 } } },
    { $group : { _id : "$year", movies: { $push: "$title" } } },
    { $out : { db: "reporting", coll: "movies_by_year" } }
] )

db.movies_by_year.find().sort( { _id: 1 } )

[
  { _id: 1978, movies: [ 'Centennial' ] },
  { _id: 1994, movies: [ 'Baseball' ] }
]

[BsonIgnoreExtraElements]
public class Movie
{
    [BsonId]
    public ObjectId Id { get; set; }
    [BsonElement("title")]
    public string Title { get; set; } = null!;
    [BsonElement("year")]
    public int? Year { get; set; }
    [BsonElement("runtime")]
    public int? Runtime { get; set; }
    [BsonElement("rated")]
    public string? Rated { get; set; }
    [BsonElement("metacritic")]
    public int Metacritic { get; set; }
    [BsonElement("plot")]
    public string? Plot { get; set; }
    [BsonElement("type")]
    public string? Type { get; set; }
    [BsonElement("cast")]
    public string[]? Cast { get; set; }
    [BsonElement("directors")]
    public string[]? Directors { get; set; }
    [BsonElement("writers")]
    public string[]? Writers { get; set; }
    [BsonElement("imdb")]
    public ImdbData? Imdb { get; set; }
}

var outCollection = _client
    .GetDatabase("sample_mflix")
    .GetCollection<Movie>("top_movies");
var pipeline = new EmptyPipelineDefinition<Movie>()
    .Match(Builders<Movie>.Filter.Eq(m => m.Metacritic, 100))
    .Sort(Builders<Movie>.Sort.Ascending(m => m.Title))
    .Out(outCollection);

{"_id": "...", "title": "Best Kept Secret", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "Boyhood", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "Fanny and Alexander", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "Lawrence of Arabia", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "The Conformist", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "The Godfather", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "The Leopard", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "The Wizard of Oz", "runtime": "...", "metacritic": 100, "imdb": "..."}

const pipeline = [{ $out: { db: "sample_mflix", coll: "movies" } }];
const cursor = collection.aggregate(pipeline);
return cursor;