/ /

Operadores

Etapas de la pipeline de agregación

Docs Home

Manual de base de datos

Referencia

Operadores

Etapas de la pipeline de agregación

$out (agregación)

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 6.0, consulta el Procedimientos de actualización de MongoDB 7.0 .

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 en la pipeline. El operador $out permite que el marco de agregación devuelva conjuntos de resultados de cualquier tamaño.

Advertencia

$out reemplaza la colección especificada si existe. Consulta Reemplazar colección existente para más detalles.

Sintaxis

La etapa $out tiene la siguiente sintaxis:

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

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.

Importante

No se puede especificar una colección particionada como la colección de salida. La colección de entrada para una pipeline puede ser particionado. Para enviar la salida a una colección particionada, vea $merge (Disponible a partir de MongoDB 4.2).
El operador $out no puede escribir resultados en una colección con tamaño fijo.
Si modificas una colección con un índice de Búsqueda Atlas, debes borrar primero y luego volver a crear el índice de búsqueda. Considera usar $merge en su lugar.

Comparación con `$merge`

Con la introducción de $merge en la versión 4.2, MongoDB proporciona dos etapas, $merge y $out, para escribir los resultados del pipeline de agregación en una colección. Lo siguiente resume las capacidades de las dos etapas:

$out

$merge

Se puede enviar a una colección en la misma base de datos o en una base de datos diferente.

Se puede enviar a una colección en la misma base de datos o en una base de datos diferente.

Cree una nueva colección si la colección de salida no existe ya.

Cree una nueva colección si la colección de salida no existe ya.

Se debe reemplazar por completo la colección de salida si ya existe.

Puede incorporar resultados (insertar nuevos documentos, fusionar documentos, reemplazar documentos, mantener documentos existentes, fallar la operación, procesar documentos con un pipeline de actualización personalizado) en una colección existente.
Puedes reemplazar el contenido de la colección, pero solo si los resultados de la agregación contienen una coincidencia con todos los documentos existentes de la colección.

No se puede enviar a una colección particionada. Sin embargo, la colección de entrada se puede particionar.

Puede dar salida a una colección fragmentada. La colección de entrada también se puede fragmentar.

Corresponde a las instrucciones SQL:
- INSERT INTO T2 SELECT * FROM T1
- SELECT * INTO T2 FROM T1

Corresponde a la instrucción SQL:

MERGE T2 AS TARGET
USING (SELECT * FROM T1) AS SOURCE
ON MATCH (T2.ID = SOURCE.ID)
WHEN MATCHED THEN
  UPDATE SET TARGET.FIELDX = SOURCE.FIELDY
WHEN NOT MATCHED THEN
  INSERT (FIELDX)
  VALUES (SOURCE.FIELDY)

Crear/actualizar vistas materializadas

Comportamientos

Ejecutar operaciones de lectura $out en nodos secundarios del set de réplicas

A partir de la versión 5.0 de MongoDB, $out puede ejecutarse en nodos secundarios de sets de réplicas si todos los nodos del clúster tienen featureCompatibilityVersion establecida en 5.0 o superior y la preferencia de lectura configurada en secundaria.

Las operaciones de lectura de la $out instrucción ocurren en los nodos secundarios, mientras que las operaciones de escritura solo ocurren en los nodos primarios.

No todas las versiones del driver admiten el direccionamiento de operaciones $out a los nodos secundarios del set de réplicas. Consulta la documentación de tu controlador para saber cuándo tu controlador agregó compatibilidad con $out en ejecución en un secundario.

Crear nueva colección

La operación $out crea una nueva colección si aún no existe ninguna.

La colección aparece cuando se completa la agregación. Si la agregación falla, MongoDB no crea la colección.

Sustituir la colección existente

Si la colección especificada por la operación $out ya existe, entonces, al completarse la agregación, la etapa $out reemplaza atómicamente la colección existente con los nuevos resultados de la colección. Específicamente, la $out operación:

Crea una colección temporal.
Copia los índices de la colección existente a la colección temporal.
Inserta los documentos en la colección temporal.
Llama al comando renameCollection con dropTarget: true para renombrar la colección temporal a la colección de destino.

La operación $out no cambia los índices que existían en la colección anterior. Si la agregación falla, la operación $out no realiza ningún cambio en la colección preexistente.

Errores de validación de esquema

Si su colección coll utiliza la validación de esquemas y tiene validationAction establecido en error, al insertar un documento no válido con $out se arroja un error. La operación $out no realiza cambios en la colección preexistente y los documentos devueltos por la canalización de agregación no se añaden a la colección coll.

Restricciones de índices

El pipeline no se completará si los documentos producidos por el mismo violan algunos índices únicos, incluido el índice en el campo _id de la colección de salida original.

Si la operación $out modifica una colección con un índice Atlas Search, debe eliminar y volver a crear el índice de búsqueda. Considere usar $merge en su lugar.

`majority` readConcern

Puede especificar el nivel de consistencia de lectura "majority" para una agregación que incluya una etapa $out.

Interacción con `mongodump`

Un mongodump que comenzó con --oplog falla si un cliente emite una canalización de agregación que incluye $out durante el proceso de vaciado. Ver mongodump --oplog para obtener más información.

Restricciones

Restricciones	Descripción
Transacciones	Una canalización de agregación no puede utilizar `$out` dentro de transacciones.
Colecciones de series de tiempo	Un pipeline de agregación no puede usar `$out` para generar una colección de series de tiempo.
ver definición	La etapa `$out` no está permitida como parte de una definición de vista. Si la definición de la vista incluye una pipeline anidada (por ejemplo, si la definición de la vista incluye la etapa `$lookup` o `$facet`), esta restricción de etapa `$out` también se aplica a las pipelines anidadas.
`$lookup` etapa	A partir de 4.2, no puedes incluir la etapa `$out` en la etapa `$lookup` en la pipeline anidada.
`$facet` etapa	`$facet` El pipeline anidado de la etapa no puede incluir la etapa `$out`.
`$unionWith` etapa	`$unionWith` El pipeline anidado de la etapa no puede incluir la etapa `$out`.
`"linearizable"` readConcern	La etapa `$out` no se puede usar junto con el nivel de consistencia de lectura `"linearizable"`. Si especificas `"linearizable"` nivel de consistencia de lectura para `db.collection.aggregate()`, no podrás incluir la etapa `$out` en la pipeline.

Ejemplos

En la base de datos test, cree una colección books con los siguientes documentos:

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

Si la base de datos test no existe aún, la operación de inserción crea la base de datos así como la colección books.

Salida a la misma base de datos

La siguiente operación de agregación dinamiza los datos de la colección books en la base de datos test para tener los títulos agrupados por autores y, a continuación, guarda los resultados en la colección authors, también en la base de datos test.

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

Primera etapa ($group):

La etapa de $group agrupa por authors y utiliza $push para añadir los títulos a un campo de arreglo books:

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

Segunda etapa ($out):

La etapa $out genera los documentos en la colección authors en la base de datos test.

Para ver los documentos en la colección de salida, ejecute la siguiente operación:

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

La colección contiene los siguientes documentos:

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

Salida a una base de datos diferente

Nota

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.

$out puede generar salida a una colección en una base de datos diferente de donde se ejecuta la agregación.

La siguiente operación de agregación dinamiza los datos de la colección books para agrupar los títulos por autores y luego guarda los resultados en la colección authors de la base de datos reporting:

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

Primera etapa ($group):

La etapa de $group agrupa por authors y utiliza $push para añadir los títulos a un campo de arreglo books:

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

Segunda etapa ($out):

La etapa $out genera los documentos en la colección authors en la base de datos reporting.

Para ver los documentos en la colección de salida, ejecute la siguiente operación:

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

La colección contiene los siguientes documentos:

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

Los ejemplos de C# en esta página utilizan la base de datos sample_mflix de los conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulta Primeros pasos en la documentación del controlador de MongoDB .NET/C#.

La siguiente clase Movie modela los documentos en la colección sample_mflix.movies:

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

Nota

ConventionPack para Pascal Case

Las clases de C# en esta página utilizan Pascal case para los nombres de sus propiedades, pero los nombres de los campos en la colección de MongoDB utilizan camel case. Para tener en cuenta esta diferencia, se puede usar el siguiente código para registrar un ConventionPack cuando la aplicación se inicie:

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

Para usar el controlador de MongoDB .NET/C# para añadir una etapa $out a un pipeline de agregación, llama al Out() método en un objeto PipelineDefinition.

El siguiente ejemplo crea una etapa de pipeline que escribe los resultados del pipeline en la colección movies:

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

Los ejemplos de Node.js en esta página utilizan la base de datos sample_mflix de los conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulte Primeros pasos en la documentación del controlador de MongoDB Node.js.

Para utilizar el controlador de MongoDB Node.js para agregar una etapa de $out a una canalización de agregación, utilice el Operador $out en un objeto de canalización.

El siguiente ejemplo crea una etapa del pipeline que escribe los resultados del pipeline en la colección movies. A continuación, el ejemplo ejecuta el pipeline de agregación:

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

Volver

$merge

$planCacheStats

Definición

Advertencia

Sintaxis

Importante

Comparación con $merge

Comportamientos

Ejecutar operaciones de lectura $out en nodos secundarios del set de réplicas

Crear nueva colección

Sustituir la colección existente

Errores de validación de esquema

Restricciones de índices

majority readConcern

Interacción con mongodump

Restricciones

Ejemplos

Salida a la misma base de datos

Salida a una base de datos diferente

Nota

Nota

ConventionPack para Pascal Case

Comparación con `$merge`

`majority` readConcern

Interacción con `mongodump`