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.
Las clases Collection y Client ambas proporcionan un método BulkWrite(). Puedes usar el método Collection.BulkWrite() para realizar varias operaciones de guardar en una sola colección. Puede utilizar 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:
Bookstruct, que modela documentos en la coleccióndb.books. Cada documento contiene una descripción de un libro que incluye el título, el autor y la extensión de páginas.Poemstruct, que modela documentos en la coleccióndb.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() en una colección y pasa un arreglo de documentos WriteModel como parámetro.
Define los modelos de guardado masivo de la colección
Para definir las operaciones de guardado para tu operación en un solo namespace, crea un WriteModel para cada inserción, reemplazo, actualización o borrar.
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 |
|---|---|
| El documento a insertar. |
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}), }
ReplaceOneModel
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 |
|---|---|
| El tipo de intercalación lingüística que se debe utilizar al ordenar resultados. |
| El filtro de query especifica qué documento se debe reemplazar. |
| El índice que se debe usar para buscar documentos. |
| El documento con el que se debe reemplazar el documento coincidente. |
| El orden de clasificación para los documentos coincidentes. La operación de reemplazo sustituye únicamente el primer documento según los criterios de clasificación. |
| Si se debe insertar un nuevo documento si el filtro de query no coincide con ningún documento. |
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, crea un UpdateOneModel especificando el documento que deseas actualizar y un documento de actualización. Para actualizar varios documentos, utiliza un UpdateManyModel.
Puedes especificar el comportamiento de cada uno de los modelos de actualización utilizando los siguientes métodos:
Método | Descripción |
|---|---|
| Los elementos del arreglo a los que se aplica la actualización. |
| El tipo de intercalación lingüística que se debe utilizar al ordenar resultados. |
| El filtro de query que especifica qué documento actualizar. |
| El índice que se debe usar para buscar documentos. |
| Los criterios que se deben usar para ordenar los documentos coincidentes. Este método solo está disponible para la clase |
| Las modificaciones que se deben aplicar a los documentos que coinciden. |
| Si se debe insertar un nuevo documento si el filtro de query no coincide con ningún documento. |
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 borrado para un guardado masivo, crea un DeleteOneModel especificando el documento que deseas borrar. Para borrar varios documentos, utiliza el DeleteManyModel.
Puede especificar el comportamiento de cada uno de los modelos de borrado utilizando los siguientes métodos:
Método | Descripción |
|---|---|
| El tipo de intercalación lingüística que se debe utilizar al ordenar resultados. |
| El filtro de query que especifica qué documento borrar. |
| El índice que se debe usar para buscar documentos. |
El siguiente ejemplo crea un DeleteManyModel para borrar documentos en la colección books en los que el length sea 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 |
|---|---|
| Especifica si la operación puede optar por no realizar la validación a nivel de documento. |
| Especifica un comentario para adjuntar a la operación. |
| Especifica un documento con una lista de valores para mejorar la legibilidad de la operación. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos del documento. Para obtener más información, consulte el |
| Especifica si el controlador deja de realizar operaciones de escritura después de que se produzca un error. |
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 |
|---|---|
| El número de documentos insertados. |
| El número de documentos coincidentes por el filtro de query en las operaciones de actualización y reemplazo. |
| El número de documentos modificados por las operaciones de actualización y reemplazo. |
| El número de documentos borrados. |
| El número de documentos insertados o actualizados mediante operaciones de actualización y reemplazo. |
| Un mapa de un índice de operación al |
| Un valor booleano que indica si la operación de guardar fue confirmada. |
Orden de ejecución a nivel de colección
Para especificar si el proceso de escritura masiva realiza las operaciones en orden, puedes establecer la opción Ordered en un valor booleano. Para configurar esta opción, especifica el campo Ordered de una instancia BulkWriteOptions.
Ordenado
Por defecto, el método BulkWrite() ejecuta operaciones de procesamiento por lotes en el orden en que se añadieron 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 el
titlees "Mi amiga estupenda" con un documento nuevoIncrementa el
lengthde cada documento en10si el valor actual delengthes menor que200Elimina todos los documentos en los que el valor del campo
authorincluye"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
namees"Towne Cafe"y lo reemplaza por un nuevo documento con el valor del camponameestablecido en"New Towne Cafe"y el valor del campocuisineestablecido en"French"Coincide con un documento en el que el valor del campo
nameesRiviera Caterery actualiza el valor del camponamea"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 varios espacios de nombres, llama al método BulkWrite() en tu cliente y pasa un arreglo 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 |
|---|---|
| El documento a insertar. |
El siguiente ejemplo crea dos instancias de 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 |
|---|---|
| El tipo de intercalación lingüística que se debe utilizar al ordenar resultados. |
| El filtro de query especifica qué documento se debe reemplazar. |
| El índice que se debe usar para buscar documentos. |
| El documento con el que se debe reemplazar el documento coincidente. |
| El orden de clasificación para los documentos coincidentes. La operación de reemplazo sustituye únicamente el primer documento según los criterios de clasificación. |
| Si se debe insertar un nuevo documento si el filtro de query no coincide con ningún documento. |
Este ejemplo crea ClientReplaceOneModel instancias para definir las siguientes operaciones:
Operación de reemplazo en la colección
bookspara reemplazar un documento en el que el valortitlees"Lucy"Operación de reemplazo en la colección
poemspara reemplazar un documento en el que el valortitlees"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 |
|---|---|
| Los elementos del arreglo a los que se aplica la actualización. |
| El tipo de intercalación lingüística que se debe utilizar al ordenar resultados. |
| El filtro de query que especifica qué documento actualizar. |
| El índice que se debe usar para buscar documentos. |
| Los criterios que se deben usar para ordenar los documentos coincidentes. Este método solo está disponible para la clase |
| Las modificaciones que se deben aplicar a los documentos que coinciden. |
| Si se debe insertar un nuevo documento si el filtro de query no coincide con ningún documento. |
Este ejemplo crea ClientUpdateOneModel instancias para definir las siguientes operaciones:
Operación de actualización en la colección
bookspara actualizar un documento en el que el valorauthorsea"Elena Ferrante"Operación de actualización en la colección
poemspara actualizar un documento en el que el valorauthorsea"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 borrado para un guardado masivo, crea un ClientDeleteOneModel especificando el documento que deseas borrar. Para borrar varios documentos, utiliza el ClientDeleteManyModel.
Puede especificar el comportamiento de cada uno de los modelos de borrado utilizando los siguientes métodos:
Método | Descripción |
|---|---|
| El tipo de intercalación lingüística que se debe utilizar al ordenar resultados. |
| El filtro de query que especifica qué documento borrar. |
| El índice que se debe usar para buscar documentos. |
Este ejemplo crea ClientDeleteOneModel instancias para definir las siguientes operaciones:
La operación de eliminación en la colección
bookspara borrar un documento en el que el valor delengthes103La operación de eliminación en la colección
poemspara borrar un documento en el que el valor deyeares1855
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 |
|---|---|
| Especifica si la operación puede optar por no realizar la validación a nivel de documento. |
| Especifica si el controlador deja de realizar operaciones de escritura después de que se produzca un error. |
| Especifica un comentario para adjuntar a la operación. |
| Especifica un documento con una lista de valores para mejorar la legibilidad de la operación. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos del documento. Para obtener más información, consulte el |
| Especifica la preocupación de escritura para las operaciones. |
| Especifica si se incluye información detallada sobre cada operación exitosa en el resultado. |
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 |
|---|---|
| El número de documentos insertados. |
| El número de documentos coincidentes por el filtro de query en las operaciones de actualización y reemplazo. |
| El número de documentos modificados por las operaciones de actualización y reemplazo. |
| El número de documentos borrados. |
| El número de documentos insertados o actualizados mediante operaciones de actualización y reemplazo. |
| Un mapa de un índice de operaciones al valor |
| Un mapa de un índice de operación al valor |
| Un mapa de un índice de operación al valor |
| Un valor booleano que indica si la operación de guardar fue confirmada. |
| Un valor booleano que indica si el resultado contiene resultados detallados. |
Orden de Ejecución a Nivel de Cliente
Para especificar si el proceso de escritura masiva realiza las operaciones en orden, puedes establecer la opción Ordered en un valor booleano. Para configurar esta opción, especifica el campo Ordered de una instancia ClientBulkWriteOptions.
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
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 un nuevo documento en las colecciones
booksypoemsActualiza un documento en la colección
poemsque tiene un valortitlede"The Raincoat"Reemplaza un documento en la colección
booksque tiene un valor detitlede"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 la API: