/ /

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 está archivada y ya no recibe soporte. Para actualizar su implementación 6.0, consulte 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 del pipeline. El operador permite que el marco de agregación devuelva conjuntos de resultados de cualquier $out tamaño.

Advertencia

$out reemplaza la colección especificada si existe.Consulte "Reemplazar colección existente" para obtener más información.

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 fragmentada como colección de salida. La colección de entrada de una canalización sí se puede fragmentar. Para generar una colección fragmentada, consulte (disponible a partir de $merge MongoDB).4.2
El operador $out no puede escribir resultados en una colección con tamaño fijo.
Si modifica una colección con un índice de búsqueda Atlas, primero debe eliminar y luego volver a crear el índice de búsqueda. Considere usar en su $merge lugar.

Comparación con `$merge`

Con la introducción de en $merge la 4.2 versión, MongoDB ofrece dos etapas, y, para escribir los resultados de la canalización de agregación en una colección. A continuación, se resumen las capacidades de ambas$merge $outetapas:

$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 MongoDB,5.0 $out puede ejecutarse en nodos secundarios del conjunto de réplicas si todos los nodos del clúster tienen featureCompatibilityVersion configurado en 5.0 o superior y la preferencia de lectura está configurada en secundaria.

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

No todas las versiones del controlador admiten la asignación de $out operaciones a nodos secundarios del conjunto de réplicas. Consulte la documentación del controlador para ver cuándo se agregó compatibilidad con $out ejecutándose en un nodo secundario.

Crear nueva colección

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

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 ya existe,$out al finalizar la agregación, la etapa reemplaza automáticamente la colección existente con $out $out la nueva colección de resultados. En concreto, la 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 no modifica ningún índice existente en $out $out la colección anterior. Si la agregación falla, la operación no modifica 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 iniciado con falla si un --oplog $out cliente emite una canalización de agregación que incluye mongodump --oplog durante el proceso de volcado. Consulte 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 `$out` etapa no está permitida como parte de una definición de vista. Si la definición de vista incluye una canalización anidada (por ejemplo, la definición de vista incluye la etapa `$lookup` o), esta restricción `$facet` `$out` de la etapa también se aplica a las canalizaciones anidadas.
`$lookup` etapa	A partir 4.2 de, no se puede incluir la etapa en la canalización `$out` `$lookup`anidada de la etapa.
`$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 envía los documentos a $out la authors colección en la test base de datos.

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 envía los documentos a $out la authors colección en la reporting base de datos.

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 MongoDB.NET/C# para agregar una $out etapa a una canalización de agregación, llame a Out()método en un PipelineDefinition objeto.

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`