Operações em massa

Visão geral

Neste guia, você pode aprender como usar o MongoDB Go Driver para executar operações em massa. As operações em massa reduzem o número de chamadas para o servidor , realizando várias operações de gravação em um único método.

As classes Collection e Client fornecem um método BulkWrite(). Você pode usar o método Collection.BulkWrite() para executar várias operações de gravação em uma única coleção. Você pode usar o método Client.BulkWrite() para executar gravações em massa em vários namespaces. No MongoDB, um namespace consiste em um nome de banco de dados e um nome de collection.

Importante

Requisitos de servidor para gravação em massa do cliente

Para executar operações em massa em uma instância do Client, certifique-se de que seu aplicação se conecte ao MongoDB Server v8.0 ou posterior

Dados de amostra

Os exemplos deste guia usam as seguintes estruturas:

Book struct, que modela documentos na collection db.books. Cada documento contém uma descrição de um livro que inclui o título, o autor e o comprimento da página.
Poem struct, que modela documentos na collection db.poems. Cada documento contém uma descrição de um poema que inclui o título, o autor e o ano de publicação.

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

Para executar os exemplos neste guia, carregue os dados de amostra nas collections books e poems usando o seguinte trecho:

bookColl := client.Database("db").Collection("books")
poemColl := client.Database("db").Collection("poems")
books := []interface{}{
	Book{Title: "My Brilliant Friend", Author: "Elena Ferrante", Length: 331},
	Book{Title: "Lucy", Author: "Jamaica Kincaid", Length: 103},
}
poems := []interface{}{
	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)

Dica

Bancos de Dados e Coleções Inexistentes

Se o banco de dados e a collection necessários não existirem quando você executar uma operação de escrita, o servidor implicitamente os criará.

Gravação em massa de collections

Para executar uma operação em massa em um único namespace, chame o método BulkWrite() em uma collection e passe uma array de documentos WriteModel como parâmetro.

Definir modelos de gravação em massa da coleção

Para definir as operações de gravação para sua operação em massa em um namespace, crie um WriteModel para cada inserção, substituição, atualização ou exclusão.

InsertOneModel

Para definir uma operação de inserção para uma escrita em massa, crie um InsertOneModel especificando o documento que você deseja inserir. Para inserir vários documentos, crie um InsertOneModel para cada documento que você deseja inserir.

Você pode especificar o comportamento do InsertOneModel utilizando o seguinte método:

Método	Descrição
`SetDocument()`	The document to insert.

O exemplo a seguir cria duas instâncias InsertOneModel para inserir dois documentos na coleção 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 uma operação de substituição para uma escrita em massa, crie um ReplaceOneModel especificando o documento que deseja substituir e um documento de substituição. Para substituir vários documentos, crie um ReplaceOneModel para cada documento que deseja substituir.

Você pode especificar o comportamento do ReplaceOneModel utilizando os seguintes métodos:

Método	Descrição
`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.

O exemplo a seguir cria um ReplaceOneModel para substituir um documento na coleção books na qual o valor title é "Lucy":

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

UpdateOneModel e UpdateManyModel

Para definir uma operação de atualização para uma escrita em massa, crie um UpdateOneModel especificando o documento que você deseja atualizar e um documento de atualização. Para atualizar vários documentos, use um UpdateManyModel.

Você pode especificar o comportamento de cada um dos modelos de atualização usando os seguintes métodos:

Método	Descrição
`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.

O exemplo a seguir cria um UpdateOneModel para atualizar um documento na collection books, diminuindo o length de um documento por 15 se o author for "Elena Ferrante":

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

DeleteOneModel e DeleteManyModel

Para definir uma operação de exclusão para uma gravação em massa, crie um DeleteOneModel especificando o documento que você deseja excluir. Para excluir vários documentos, use o DeleteManyModel.

Você pode especificar o comportamento de cada um dos modelos de exclusão usando os seguintes métodos:

Método	Descrição
`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.

O exemplo a seguir cria um DeleteManyModel para excluir documentos na collection books na qual o length é maior que 300:

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

Modificar comportamento em nível de collection

Para modificar o comportamento de sua operação de gravação em massa, passe uma instância BulkWriteOptions para o método BulkWrite().

O tipo BulkWriteOptions permite que você configure opções usando os seguintes métodos:

Método	Descrição
`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 em nível de collection

O método BulkWrite() retorna um tipo BulkWriteResult, que inclui informações sobre a operação em massa.

O tipo BulkWriteResult contém as seguintes propriedades:

Propriedade	Descrição
`InsertedCount`	O número de documentos inseridos.
`MatchedCount`	O número de documentos correspondidos pelo filtro de query nas operações de atualização e substituição.
`ModifiedCount`	O número de documentos modificados por atualização e substituição de operações.
`DeletedCount`	O número de documentos excluídos.
`UpsertedCount`	O número de documentos atualizados por atualização e substituição de operações.
`UpsertedIDs`	Um mapa de um índice de operação para o `_id` de cada documento atualizado.
`Acknowledged`	Um valor booleano que indica se a operação de gravação foi reconhecida.

Ordem de execução em nível de coleção

Para especificar se a gravação em massa executa as operações em ordem, você pode definir a opção Ordered como um valor booleano. Para definir esta opção, especifique o campo Ordered de uma instância do BulkWriteOptions.

Pedido

Por padrão, o método BulkWrite() executa operações em massa para que você as adicione e pare se ocorrer um erro.

Dica

Isto é equivalente a passar um valor de true para o método SetOrdered(), como mostrado no seguinte código:

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

Não ordenado

Para executar operações de gravação em massa em qualquer ordem e continuar se ocorrer um erro, passe um valor de false para o método SetOrdered(). O método relata erros após a conclusão da operação.

O exemplo a seguir executa as seguintes ações em qualquer ordem:

Insere dois documentos
Substitui um documento onde o title é "Meu amigo brilhante" por um novo documento
Aumenta o length de cada documento em 10 se o valor atual de length for menor que 200
Exclui todos os documentos onde o valor de campo author inclui "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

Os seguintes documentos estão presentes na collection books após a operação em massa:

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

Gravação em massa do cliente

Para executar uma operação em massa em vários namespaces, chame o método BulkWrite() no seu cliente e passe uma array de documentos ClientWriteModel como parâmetro.

Definir modelos de gravação em massa do cliente

Para especificar as operações de gravação para sua operação em massa em vários namespaces, crie um ClientWriteModel para cada inserção, substituição, atualização ou exclusão. Passe cada modelo de gravação para a estrutura ClientBulkWrite e especifique o banco de dados e a coleção de destino, conforme mostrado no código a seguir:

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

ClientInsertOneModel

Para definir uma operação de inserção para uma escrita em massa, crie um ClientInsertOneModel especificando o documento que você deseja inserir. Para inserir vários documentos, crie um ClientInsertOneModel para cada documento que você deseja inserir.

Você pode especificar o comportamento do ClientInsertOneModel utilizando o seguinte método:

Método	Descrição
`SetDocument()`	The document to insert.

O exemplo a seguir cria duas instâncias ClientInsertOneModel para inserir um documento na coleção books e um documento na coleção 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 uma operação de substituição para uma gravação em massa, crie um ClientReplaceOneModel especificando o documento que deseja substituir e um documento de substituição. Para substituir vários documentos, crie um ClientReplaceOneModel para cada documento que deseja substituir.

Você pode especificar o comportamento do ClientReplaceOneModel utilizando os seguintes métodos:

Método	Descrição
`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 exemplo cria instâncias do ClientReplaceOneModel para definir as seguintes operações:

Substituir operação na coleção books para substituir um documento no qual o valor title é "Lucy"
Substituir operação na coleção poems para substituir um documento no qual o valor title é "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 e ClientUpdateManyModel

Para definir uma operação de atualização para uma escrita em massa, crie um ClientUpdateOneModel especificando o documento que você deseja atualizar e um documento de atualização. Para atualizar vários documentos, use um ClientUpdateManyModel.

Você pode especificar o comportamento de cada um dos modelos de atualização usando os seguintes métodos:

Método	Descrição
`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 exemplo cria instâncias do ClientUpdateOneModel para definir as seguintes operações:

Operação de atualização na coleção books para atualizar um documento no qual o valor author é "Elena Ferrante"
Operação de atualização na coleção poems para atualizar um documento no qual o valor author é "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"}})},
}

Observação

Para atualizar todos os documentos que correspondem aos filtros de consulta do campo author no exemplo anterior, use instâncias ClientUpdateManyModel.

ClientDeleteOneModel e ClientDeleteManyModel

Para definir uma operação de exclusão para uma gravação em massa, crie um ClientDeleteOneModel especificando o documento que você deseja excluir. Para excluir vários documentos, use o ClientDeleteManyModel.

Você pode especificar o comportamento de cada um dos modelos de exclusão usando os seguintes métodos:

Método	Descrição
`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 exemplo cria instâncias do ClientDeleteOneModel para definir as seguintes operações:

Operação Excluir na coleção books para excluir um documento no qual o valor length é 103
Operação Excluir na coleção poems para excluir um documento no qual o valor year é 1855

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

Modificar comportamento no nível do cliente

Para modificar o comportamento de sua operação de gravação em massa, passe uma instância ClientBulkWriteOptions para o método BulkWrite().

O tipo ClientBulkWriteOptions permite que você configure opções usando os seguintes métodos:

Método	Descrição
`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 no nível do cliente

O método BulkWrite() retorna um tipo ClientBulkWriteResult, que inclui informações sobre a operação em massa.

O tipo ClientBulkWriteResult contém as seguintes propriedades:

Propriedade	Descrição
`InsertedCount`	O número de documentos inseridos.
`MatchedCount`	O número de documentos correspondidos pelo filtro de query nas operações de atualização e substituição.
`ModifiedCount`	O número de documentos modificados por atualização e substituição de operações.
`DeletedCount`	O número de documentos excluídos.
`UpsertedCount`	O número de documentos atualizados por atualização e substituição de operações.
`InsertResults`	Um mapa de um índice de operação para o valor `_id` de cada documento inserido.
`UpdateResults`	Um mapa de um índice de operação para o valor `_id` de cada documento atualizado.
`DeleteResults`	Um mapa de um índice de operação para o valor `_id` de cada documento excluído.
`Acknowledged`	Um valor booleano que indica se a operação de gravação foi reconhecida.
`HasVerboseResults`	Um valor booleano que indica se o resultado contém resultados detalhados.

Ordem de execução no nível do cliente

Pedido

Por padrão, o método BulkWrite() executa operações em massa para que você as adicione e pare se ocorrer um erro.

Dica

Isto é equivalente a passar um valor de true para o método SetOrdered(), como mostrado no seguinte código:

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

Não ordenado

O exemplo a seguir executa as seguintes ações em qualquer ordem:

Insere um novo documento nas coleções books e poems
Atualiza um documento na coleção poems que tem um valor title de "The Raincoat"
Substitui um documento na coleção books que tem um 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

Informações adicionais

Para obter um exemplo executável sobre como executar uma operação em massa, consulte Executar operações em massa.

Operações relacionadas

Para saber mais sobre como executar as operações mencionadas, consulte os seguintes guias:

Documentação da API

Para saber mais sobre os métodos ou tipos usados para gravações em massa de coleções, consulte a seguinte documentação da API:

Para saber mais sobre os métodos ou tipos usados para gravações em massa de cliente , consulte a seguinte documentação da API:

Voltar

Upsert

Operações compostas