Operaciones masivas

Overview

En esta guía, puedes aprender cómo usar el MongoDB Go Driver para realizar operaciones por lotes. Las operaciones por lotes reducen el número de llamadas al servidor al ejecutar múltiples operaciones de escritura en un solo método.

La Collection y las clases Client ambas proporcionan un método BulkWrite(). Puedes utilizar el método Collection.BulkWrite() para realizar múltiples operaciones de guardar en una sola colección. Puedes usar el método Client.BulkWrite() para realizar escrituras masivas en varios espacios de nombres. En MongoDB, un namespace consiste en un nombre de base de datos y un nombre de colección.

Importante

Requisito del servidor de escritura masiva del cliente

Para realizar operaciones en bloque en una instancia de Client, asegúrate de que tu aplicación se conecte a MongoDB Server v8.0 o posterior

Datos de muestra

Los ejemplos de esta guía utilizan las siguientes estructuras:

Book struct, que modela documentos en la colección db.books. Cada documento contiene una descripción de un libro que incluye el título, el autor y la extensión de páginas.
Poem struct, que modela documentos en la colección db.poems. Cada documento contiene una descripción de un poema que incluye el título, el autor y el año de publicación.

type Book struct {
	Title  string
	Author string
	Length int32
}
type Poem struct {
	Title  string
	Author string
	Year   int32
}

Para ejecutar los ejemplos de esta guía, carga los datos de muestra en las colecciones books y poems usando el siguiente snippet:

bookColl := client.Database("db").Collection("books")
poemColl := client.Database("db").Collection("poems")
books := []any{
	Book{Title: "My Brilliant Friend", Author: "Elena Ferrante", Length: 331},
	Book{Title: "Lucy", Author: "Jamaica Kincaid", Length: 103},
}
poems := []any{
	Poem{Title: "Song of Myself", Author: "Walt Whitman", Year: 1855},
	Poem{Title: "The Raincoat", Author: "Ada Limon", Year: 2018},
}
bookInsert, err := bookColl.InsertMany(context.TODO(), books)
poemInsert, err := poemColl.InsertMany(context.TODO(), poems)

Tip

Bases de datos y colecciones inexistentes

Si la base de datos y la colección necesarias no existen cuando realizas una operación de guardar, el servidor las crea implícitamente.

Guardar masivo de colecciones

Para realizar una operación masiva en un único namespace, llama al método BulkWrite() sobre una colección y pasa un arreglo de WriteModel documentos como un parámetro.

Define los modelos de guardado masivo de la colección

Para definir las operaciones de escritura para su operación masiva en un espacio de nombres, cree un WriteModel para cada inserción, reemplazo, actualización o eliminación.

InsertOneModel

Para definir una operación de inserción para una escritura masiva, cree un InsertOneModel que especifique el documento que desea insertar. Para insertar varios documentos, crea un InsertOneModel para cada documento que desees insertar.

Puede especificar el comportamiento del InsertOneModel utilizando el siguiente método:

Método	Descripción
`SetDocument()`	The document to insert.

El siguiente ejemplo crea dos instancias de InsertOneModel para insertar dos documentos en la colección books:

models := []mongo.WriteModel{
	mongo.NewInsertOneModel().SetDocument(Book{Title: "Beloved", Author: "Toni Morrison", Length: 324}),
	mongo.NewInsertOneModel().SetDocument(Book{Title: "Outline", Author: "Rachel Cusk", Length: 258}),
}

ReemplazarUnModelo

Para definir una operación de sustitución para una escritura por lotes, cree un ReplaceOneModel especificando el documento que desea sustituir y un documento de reemplazo. Para reemplazar varios documentos, crea un ReplaceOneModel para cada documento que desees reemplazar.

Se puede especificar el comportamiento de ReplaceOneModel mediante los siguientes métodos:

Método	Descripción
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to replace.
`SetHint()`	The index to use to scan for documents.
`SetReplacement()`	The document to replace the matched document with.
`SetSort()`	The sort order for matching documents. The replace operation replaces only the first document according to the sort criteria.
`SetUpsert()`	Whether to insert a new document if the query filter doesn't match any documents.

El siguiente ejemplo crea un ReplaceOneModel para reemplazar un documento en la colección books en la que el valor de title es "Lucy":

models := []mongo.WriteModel{
	mongo.NewReplaceOneModel().SetFilter(bson.D{{"title", "Lucy"}}).
		SetReplacement(Book{Title: "On Beauty", Author: "Zadie Smith", Length: 473}),
}

UpdateOneModel y UpdateManyModel

Para definir una operación de actualización para una escritura masiva, cree un UpdateOneModel que especifique el documento que desea actualizar y un documento de actualización. Para actualizar varios documentos, utilice UpdateManyModel un.

Puedes especificar el comportamiento de cada uno de los modelos de actualización utilizando los siguientes métodos:

Método	Descripción
`SetArrayFilters()`	The array elements the update applies to.
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to update.
`SetHint()`	The index to use to scan for documents.
`SetSort()`	The criteria to use when ordering matching documents. This method is only available for the `UpdateOneModel` class.
`SetUpdate()`	The modifications to apply on the matched documents.
`SetUpsert()`	Whether to insert a new document if the query filter doesn't match any documents.

El siguiente ejemplo crea un UpdateOneModel para actualizar un documento en la colección books, decrementando el length de un documento en 15 si el author es "Elena Ferrante":

models := []mongo.WriteModel{
	mongo.NewUpdateOneModel().SetFilter(bson.D{{"author", "Elena Ferrante"}}).
		SetUpdate(bson.D{{"$inc", bson.D{{"length", -15}}}}),
}

DeleteOneModel y DeleteManyModel

Para definir una operación de eliminación para una escritura masiva, cree un DeleteOneModel que especifique el documento que desea eliminar. Para eliminar varios documentos, utilice el DeleteManyModel.

Puede especificar el comportamiento de cada uno de los modelos de borrado utilizando los siguientes métodos:

Método	Descripción
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to delete.
`SetHint()`	The index to use to scan for documents.

El siguiente ejemplo crea un DeleteManyModel para eliminar documentos en la colección books en los que length es mayor que 300:

models := []mongo.WriteModel{
	mongo.NewDeleteManyModel().SetFilter(bson.D{{"length", bson.D{{"$gt", 300}}}}),
}

Modificar el comportamiento a nivel de colección

Para modificar el comportamiento de tu operación de guardar masiva, pasa una instancia BulkWriteOptions al método BulkWrite().

El tipo BulkWriteOptions te permite configurar opciones usando los siguientes métodos:

Método	Descripción
`SetBypassDocumentValidation()`	Specifies whether the operation can opt-out of document level validation. Default: `false`
`SetComment()`	Specifies a comment to attach to the operation. Default: `nil`
`SetLet()`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the `let` field for the delete and update commands in the MongoDB Server manual. Default: `nil`
`SetOrdered()`	Specifies whether the driver stops performing write operations after an error occurs. Default: `true`

Valor de retorno a nivel de colección

El método BulkWrite() devuelve un tipo BulkWriteResult, que incluye información sobre la operación en masa.

El tipo BulkWriteResult contiene las siguientes propiedades:

Propiedad	Descripción
`InsertedCount`	El número de documentos insertados.
`MatchedCount`	El número de documentos coincidentes por el filtro de query en las operaciones de actualización y reemplazo.
`ModifiedCount`	El número de documentos modificados por las operaciones de actualización y reemplazo.
`DeletedCount`	El número de documentos borrados.
`UpsertedCount`	El número de documentos insertados o actualizados mediante operaciones de actualización y reemplazo.
`UpsertedIDs`	Un mapa de un índice de operación al `_id` de cada documento insertado.
`Acknowledged`	Un valor booleano que indica si se reconoció la operación de escritura.

Orden de ejecución a nivel de colección

Para especificar si la escritura masiva realiza las operaciones en orden, puede establecer la opción Ordered en un valor booleano. Para configurar esta opción, especifique el campo Ordered de una instancia BulkWriteOptions.

Ordenado

De forma predeterminada, el método BulkWrite() ejecuta operaciones masivas en el orden en que las agregó y se detiene si ocurre un error.

Tip

Esto equivale a pasar un valor de true al método SetOrdered(), como se muestra en el siguiente código:

opts := options.BulkWrite().SetOrdered(true)

Desordenado

Para ejecutar operaciones de guardado masivo en cualquier orden y continuar si se produce un error, pasa un valor de false al método SetOrdered(). El método informa de los errores después de que la operación se complete.

El siguiente ejemplo realiza las siguientes acciones en cualquier orden:

Inserta dos documentos
Reemplaza un documento donde title es "Mi brillante amigo" con un nuevo documento
Incrementa el length de cada documento en 10 si el valor actual de length es menor que 200
Elimina todos los documentos donde el valor del campo author incluye "Jam"

models := []mongo.WriteModel{
	mongo.NewInsertOneModel().SetDocument(Book{Title: "Middlemarch", Author: "George Eliot", Length: 904}),
	mongo.NewInsertOneModel().SetDocument(Book{Title: "Pale Fire", Author: "Vladimir Nabokov", Length: 246}),
	mongo.NewReplaceOneModel().SetFilter(bson.D{{"title", "My Brilliant Friend"}}).
		SetReplacement(Book{Title: "Atonement", Author: "Ian McEwan", Length: 351}),
	mongo.NewUpdateManyModel().SetFilter(bson.D{{"length", bson.D{{"$lt", 200}}}}).
		SetUpdate(bson.D{{"$inc", bson.D{{"length", 10}}}}),
	mongo.NewDeleteManyModel().SetFilter(bson.D{{"author", bson.D{{"$regex", "Jam"}}}}),
}
// Specifies that the bulk write is unordered
opts := options.BulkWrite().SetOrdered(false)
// Runs the bulk write operation and prints a summary of the
// data changes
results, err := bookColl.BulkWrite(context.TODO(), models, opts)
if err != nil {
	panic(err)
}
fmt.Printf("Number of documents inserted: %d\n", results.InsertedCount)
fmt.Printf("Number of documents replaced or updated: %d\n", results.ModifiedCount)
fmt.Printf("Number of documents deleted: %d\n", results.DeletedCount)

Number of documents inserted: 2
Number of documents replaced or updated: 2
Number of documents deleted: 1

Los siguientes documentos están presentes en la colección books después de la operación masiva:

{"title":"Atonement","author":"Ian McEwan","length":351}
{"title":"Middlemarch","author":"George Eliot","length":904}
{"title":"Pale Fire","author":"Vladimir Nabokov","length":246}

Ejemplo de operación masiva: archivo completo

Nota

Configuración de ejemplo

Este ejemplo se conecta a una instancia de MongoDB utilizando un URI de conexión. Para aprender más sobre cómo conectarte a tu instancia de MongoDB, consulta Crear un MongoClient. Este ejemplo también utiliza la colección restaurants en la base de datos sample_restaurants incluida en los conjuntos de datos de muestra de Atlas. Puede cargarlos en su base de datos en el nivel gratuito de MongoDB Atlas siguiendo los pasos en Introducción a Atlas.

El siguiente ejemplo es un archivo totalmente ejecutable que realiza las siguientes acciones:

Coincide con un documento en el que el valor del campo name es "Towne Cafe" y lo reemplaza por un nuevo documento con el valor del campo name establecido en "New Towne Cafe" y el valor del campo cuisine establecido en "French"
Coincide con un documento en el que el valor del campo name es Riviera Caterer y actualiza el valor del campo name a "Riviera Cafe".

// Runs bulk write operations on a collection by using the Go driver
package main
import (
	"context"
	"fmt"
	"log"
	"os"
	"github.com/joho/godotenv"
	"go.mongodb.org/mongo-driver/v2/bson"
	"go.mongodb.org/mongo-driver/v2/mongo"
	"go.mongodb.org/mongo-driver/v2/mongo/options"
)
// Defines a Restaurant struct as a model for documents in the "restaurants" collection
type Restaurant struct {
	Name         string
	RestaurantId string        `bson:"restaurant_id,omitempty"`
	Cuisine      string        `bson:"cuisine,omitempty"`
	Address      any           `bson:"address,omitempty"`
	Borough      string        `bson:"borough,omitempty"`
	Grades       []any         `bson:"grades,omitempty"`
}
func main() {
	if err := godotenv.Load(); err != nil {
		log.Println("No .env file found")
	}
	var uri string
	if uri = os.Getenv("MONGODB_URI"); uri == "" {
		log.Fatal("You must set your 'MONGODB_URI' environment variable. See\n\t https://www.mongodb.com/es/docs/drivers/go/current/connect/mongoclient/#environment-variable")
	}
	client, err := mongo.Connect(options.Client().ApplyURI(uri))
	if err != nil {
		panic(err)
	}
	defer func() {
		if err = client.Disconnect(context.TODO()); err != nil {
			panic(err)
		}
	}()
	coll := client.Database("sample_restaurants").Collection("restaurants")
	// Creates write models that specify replace and update operations
	models := []mongo.WriteModel{
		mongo.NewReplaceOneModel().SetFilter(bson.D{{"name", "Towne Cafe"}}).
			SetReplacement(Restaurant{Name: "New Towne Cafe", Cuisine: "French"}),
		mongo.NewUpdateOneModel().SetFilter(bson.D{{"name", "Riviera Caterer"}}).
			SetUpdate(bson.D{{"$set", bson.D{{"name", "Riviera Cafe"}}}}),
	}
	// Specifies that the bulk write is ordered
	opts := options.BulkWrite().SetOrdered(true)
	// Runs a bulk write operation for the specified write operations
	results, err := coll.BulkWrite(context.TODO(), models, opts)
	if err != nil {
		panic(err)
	}
	// When you run this file for the first time, it should print output similar to the following:
	// Number of documents replaced or modified: 2
	fmt.Printf("Number of documents replaced or modified: %d", results.ModifiedCount)
}

Number of documents matched: 2
Number of documents modified: 2

Guardado Masivo del Cliente

Para realizar una operación masiva en múltiples espacios de nombres, llame al BulkWrite() método en su cliente y pase una matriz de documentos ClientWriteModel como parámetro.

Define modelos de guardado masivo del cliente

Para especificar las operaciones de guardado para tu operación masiva en varios namespaces, crea un ClientWriteModel para cada inserción, reemplazo, actualización o borrado. Pasa cada modelo de escritura a la estructura ClientBulkWrite y especifica la base de datos y colección de destino, como se muestra en el siguiente código:

writes := []mongo.ClientBulkWrite{
  {"<database name>", "<collection name>", <write model>},
  ...
}

ClientInsertOneModel

Para definir una operación de inserción para una escritura masiva, cree un ClientInsertOneModel especificando el documento que desea insertar. Para insertar varios documentos, crea un ClientInsertOneModel para cada documento que desees insertar.

Puede especificar el comportamiento del ClientInsertOneModel utilizando el siguiente método:

Método	Descripción
`SetDocument()`	The document to insert.

El siguiente ejemplo crea dos instancias ClientInsertOneModel para insertar un documento en la colección books y un documento en la colección poems:

bookInsertDoc := Book{Title: "Parable of the Sower", Author: "Octavia E. Butler", Length: 320}
poemInsertDoc := Poem{Title: "Fame is a fickle food", Author: "Emily Dickinson", Year: 1659}
writes := []mongo.ClientBulkWrite{
	{"db", "books", mongo.NewClientInsertOneModel().SetDocument(bookInsertDoc)},
	{"db", "poems", mongo.NewClientInsertOneModel().SetDocument(poemInsertDoc)},
}

ClientReplaceOneModel

Para definir una operación de reemplazo en una escritura por lotes, cree un ClientReplaceOneModel especificando el documento que desea reemplazar y un documento de reemplazo. Para reemplazar varios documentos, cree un ClientReplaceOneModel para cada documento que desee reemplazar.

Se puede especificar el comportamiento de ClientReplaceOneModel mediante los siguientes métodos:

Método	Descripción
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to replace.
`SetHint()`	The index to use to scan for documents.
`SetReplacement()`	The document to replace the matched document with.
`SetSort()`	The sort order for matching documents. The replace operation replaces only the first document according to the sort criteria.
`SetUpsert()`	Whether to insert a new document if the query filter doesn't match any documents.

Este ejemplo crea ClientReplaceOneModel instancias para definir las siguientes operaciones:

Operación de reemplazo en la colección books para reemplazar un documento en el que el valor title es "Lucy"
Operación de reemplazo en la colección poems para reemplazar un documento en el que el valor title es "Song of Myself"

writes := []mongo.ClientBulkWrite{
	{"db", "books", mongo.NewClientReplaceOneModel().
		SetFilter(bson.D{{"title", "Lucy"}}).
		SetReplacement(Book{Title: "On Beauty", Author: "Zadie Smith", Length: 473})},
	{"db", "poems", mongo.NewClientReplaceOneModel().
		SetFilter(bson.D{{"title", "Song of Myself"}}).
		SetReplacement(Poem{Title: "America", Author: "Walt Whitman", Year: 1888})},
}

ClientUpdateOneModel y ClientUpdateManyModel

Para definir una operación de actualización para una escritura masiva, crea un ClientUpdateOneModel especificando el documento que deseas actualizar y un documento de actualización. Para actualizar varios documentos, utiliza un ClientUpdateManyModel.

Puedes especificar el comportamiento de cada uno de los modelos de actualización utilizando los siguientes métodos:

Método	Descripción
`SetArrayFilters()`	The array elements the update applies to.
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to update.
`SetHint()`	The index to use to scan for documents.
`SetSort()`	The criteria to use when ordering matching documents. This method is only available for the `ClientUpdateOneModel` class.
`SetUpdate()`	The modifications to apply on the matched documents.
`SetUpsert()`	Whether to insert a new document if the query filter doesn't match any documents.

Este ejemplo crea ClientUpdateOneModel instancias para definir las siguientes operaciones:

Operación de actualización en la colección books para actualizar un documento en el que el valor author sea "Elena Ferrante"
Operación de actualización en la colección poems para actualizar un documento en el que el valor author sea "Ada Limon"

writes := []mongo.ClientBulkWrite{
	{"db", "books", mongo.NewClientUpdateOneModel().
		SetFilter(bson.D{{"author", "Elena Ferrante"}}).
		SetUpdate(bson.D{{"$inc", bson.D{{"length", -15}}}})},
	{"db", "poems", mongo.NewClientUpdateOneModel().
		SetFilter(bson.D{{"author", "Ada Limon"}}).
		SetUpdate(bson.D{{"author", "Ada Limón"}})},
}

Nota

Para actualizar todos los documentos que coinciden con los filtros de query de campo author en el ejemplo anterior, usa instancias de ClientUpdateManyModel.

ClientDeleteOneModel y ClientDeleteManyModel

Para definir una operación de eliminación para una escritura masiva, cree un ClientDeleteOneModel que especifique el documento que desea eliminar. Para eliminar varios documentos, utilice el ClientDeleteManyModel.

Puede especificar el comportamiento de cada uno de los modelos de borrado utilizando los siguientes métodos:

Método	Descripción
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to delete.
`SetHint()`	The index to use to scan for documents.

Este ejemplo crea ClientDeleteOneModel instancias para definir las siguientes operaciones:

Operación de eliminación en la colección books para eliminar un documento en el que el valor length es 103
Operación de eliminación en la colección poems para eliminar un documento en el que el valor year es 1855

writes := []mongo.ClientBulkWrite{
	{"db", "books", mongo.NewClientDeleteOneModel().
		SetFilter(bson.D{{"length", 103}})},
	{"db", "poems", mongo.NewClientDeleteOneModel().
		SetFilter(bson.D{{"year", 1855}})},
}

Modifica el Comportamiento a Nivel de Cliente

Para modificar el comportamiento de tu operación de guardar masiva, pasa una instancia ClientBulkWriteOptions al método BulkWrite().

El tipo ClientBulkWriteOptions te permite configurar opciones usando los siguientes métodos:

Método	Descripción
`SetBypassDocumentValidation()`	Specifies whether the operation can opt-out of document level validation. Default: `false`
`SetOrdered()`	Specifies whether the driver stops performing write operations after an error occurs. Default: `true`
`SetComment()`	Specifies a comment to attach to the operation. Default: `nil`
`SetLet()`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the `let` field for the delete and update commands in the MongoDB Server manual. Default: `nil`
`SetWriteConcern()`	Specifies the write concern for the operations. Default: `nil`
`SetVerboseResults()`	Specifies whether detailed information about each successful operation is included in the result. Default: `false`

Valor de retorno a nivel de cliente

El método BulkWrite() devuelve un tipo ClientBulkWriteResult, que incluye información sobre la operación en masa.

El tipo ClientBulkWriteResult contiene las siguientes propiedades:

Propiedad	Descripción
`InsertedCount`	El número de documentos insertados.
`MatchedCount`	El número de documentos coincidentes por el filtro de query en las operaciones de actualización y reemplazo.
`ModifiedCount`	El número de documentos modificados por las operaciones de actualización y reemplazo.
`DeletedCount`	El número de documentos borrados.
`UpsertedCount`	El número de documentos insertados o actualizados mediante operaciones de actualización y reemplazo.
`InsertResults`	Un mapa de un índice de operación al valor `_id` de cada documento insertado.
`UpdateResults`	Un mapa de un índice de operación al valor `_id` de cada documento actualizado.
`DeleteResults`	Un mapa de un índice de operación al valor `_id` de cada documento eliminado.
`Acknowledged`	Un valor booleano que indica si se reconoció la operación de escritura.
`HasVerboseResults`	Un valor booleano que indica si el resultado contiene resultados detallados.

Orden de Ejecución a Nivel de Cliente

Ordenado

Por defecto, el método BulkWrite() ejecuta las operaciones en lote en el orden en que se agregaron y se detiene si se produce un error.

Tip

Esto equivale a pasar un valor de true al método SetOrdered(), como se muestra en el siguiente código:

opts := options.ClientBulkWrite().SetOrdered(true)

Desordenado

El siguiente ejemplo realiza las siguientes acciones en cualquier orden:

Inserta un nuevo documento en las colecciones books y poems
Actualiza un documento en la colección poems que tiene un valor title de "The Raincoat"
Reemplaza un documento en la colección books que tiene un valor de title de "My Brilliant Friend"

writes := []mongo.ClientBulkWrite{
	{"db", "books", mongo.NewClientInsertOneModel().
		SetDocument(Book{Title: "Middlemarch", Author: "George Eliot", Length: 904})},
	{"db", "poems", mongo.NewClientInsertOneModel().
		SetDocument(Poem{Title: "Mad Girl's Love Song", Author: "Sylvia Plath", Year: 1953})},
	{"db", "poems", mongo.NewClientUpdateOneModel().
		SetFilter(bson.D{{"title", "The Raincoat"}}).
		SetUpdate(bson.D{{"title", "The Conditional"}})},
	{"db", "books", mongo.NewClientReplaceOneModel().
		SetFilter(bson.D{{"title", "My Brilliant Friend"}}).
		SetReplacement(Book{Title: "The Story of a New Name", Author: "Elena Ferrante", Length: 480})},
}
opts := options.ClientBulkWrite().SetOrdered(false)
results, err := client.BulkWrite(context.TODO(), writes, opts)
if err != nil {
	panic(err)
}
fmt.Printf("Number of documents inserted: %d\n", results.InsertedCount)
fmt.Printf("Number of documents replaced or updated: %d\n", results.ModifiedCount)

Number of documents inserted: 2
Number of documents replaced or updated: 2

Información Adicional

Para obtener más información sobre cómo realizar las operaciones mencionadas, consulte las siguientes guías:

Documentación de la API

Para obtener más información sobre los métodos o tipos utilizados para operaciones de escritura masiva en colecciones, consulta la siguiente documentación de la API:

Para obtener más información sobre los métodos o tipos utilizados para escrituras masivas de clientes, consulte la siguiente documentación de API:

Volver

Delete Documents

Transacciones