Operaciones masivas

Overview

En esta guía, aprenderá a usar el controlador Go de MongoDB para realizar operaciones masivas. Estas operaciones reducen el número de llamadas al servidor al realizar múltiples operaciones de escritura en un solo método.

El Collection Las clases Client y BulkWrite() proporcionan un método Collection.BulkWrite(). Puede usar el método para realizar múltiples operaciones de escritura en una sola colección. Puede usar el método Client.BulkWrite() para realizar escrituras masivas en múltiples espacios de nombres. En MongoDB, un espacio de nombres consta de 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 Estructura que modela los documentos de la colección db.books. Cada documento contiene la descripción de un libro, que incluye el título, el autor y la extensión de las páginas.
Poem Estructura que modela los documentos de la colección db.poems. Cada documento contiene la descripción de un poema, incluyendo 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, cargue los datos de muestra en las colecciones books y poems utilizando el siguiente fragmento:

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 realiza una operación de escritura, el servidor las crea implícitamente.

Colección Escritura masiva

Para realizar una operación masiva en un solo espacio de nombres, llame al método BulkWrite() en una colección y pase una matriz de Escribe los documentos del modelo como parámetro.

Definir modelos de escritura masiva de colecciones

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, cree un InsertOneModel para cada uno.

Puede especificar el comportamiento de 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 reemplazo para una escritura masiva, cree un ReplaceOneModel que especifique el documento que desea reemplazar y un documento de reemplazo. Para reemplazar varios documentos, cree un ReplaceOneModel para cada documento que desee reemplazar.

Puede especificar el comportamiento de ReplaceOneModel 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 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 el que el valor 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.

Puede 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 su operación de escritura masiva, pase una instancia BulkWriteOptions al método BulkWrite().

El tipo BulkWriteOptions le permite configurar opciones mediante 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 masiva.

El tipo BulkWriteResult contiene las siguientes propiedades:

Propiedad	Descripción
`InsertedCount`	El número de documentos insertados.
`MatchedCount`	La cantidad de documentos que coinciden con el filtro de consulta en las operaciones de actualización y reemplazo.
`ModifiedCount`	El número de documentos modificados mediante operaciones de actualización y reemplazo.
`DeletedCount`	El número de documentos borrados.
`UpsertedCount`	El número de documentos insertados 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 cobro

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 es equivalente 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 escritura masiva en cualquier orden y continuar si se produce un error, pase el valor false al método SetOrdered(). El método informa de los errores una vez completada la operación.

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 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 mediante una URI de conexión. Para obtener más información sobre cómo conectarse a su instancia de MongoDB, consulte la guía "Crear un MongoClient". Este ejemplo también utiliza la restaurants colección de la sample_restaurants base de datos incluida en los conjuntos de datos de ejemplo de Atlas. Puede cargarlos en su base de datos en la versión gratuita de MongoDB Atlas siguiendo la Guía de 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 con 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

Escritura masiva 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 escritura para su operación masiva en varios espacios de nombres, cree un ClientWriteModel para cada inserción, reemplazo, actualización o eliminación. Pase cada modelo de escritura a la estructura ClientBulkWrite y especifique la base de datos y la 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 que especifique el documento que desea insertar. Para insertar varios documentos, cree un ClientInsertOneModel para cada uno.

Puede especificar el comportamiento de 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)},
}

ClienteReemplazarUnModelo

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

Puede especificar el comportamiento de ClientReplaceOneModel 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 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.

Puede 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 es "Elena Ferrante"
Operación de actualización en la colección poems para actualizar un documento en el que el valor author es "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}})},
}

Modificar el comportamiento a nivel de cliente

Para modificar el comportamiento de su operación de escritura masiva, pase una instancia ClientBulkWriteOptions al método BulkWrite().

El tipo ClientBulkWriteOptions le permite configurar opciones mediante 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 masiva.

El tipo ClientBulkWriteResult contiene las siguientes propiedades:

Propiedad	Descripción
`InsertedCount`	El número de documentos insertados.
`MatchedCount`	La cantidad de documentos que coinciden con el filtro de consulta en las operaciones de actualización y reemplazo.
`ModifiedCount`	El número de documentos modificados mediante operaciones de actualización y reemplazo.
`DeletedCount`	El número de documentos borrados.
`UpsertedCount`	El número de documentos insertados 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

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 es equivalente 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 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