Docs Menu

Docs HomeRuby MongoDB Driver

Bulk Writes

On this page

  • insert_one
  • update_one
  • update_many
  • replace_one
  • delete_one
  • delete_many
  • Bulk Write Splitting

The bulk write API sends several write operations to the server in a single command. Use the bulk write API to reduce the number of network round-trips when performing several writes at a time. For example, to efficiently perform multiple updates, one might do:

collection = client['colors']
collection.bulk_write([
{
update_one: {
filter: {name: 'yellow'},
update: {'$set' => {hex: 'ffff00'}},
},
},
{
update_one: {
filter: {name: 'purple'},
update: {'$set' => {hex: '800080'}},
},
},
], ordered: true, write_concern: {w: :majority})

The following example shows how to execute different types of operations in the same request:

collection.bulk_write([
{ insert_one: { x: 1 } },
{ update_one: {
filter: { x: 1 },
update: {'$set' => { x: 2 } },
} },
{ replace_one: {
filter: { x: 2 },
replacement: { x: 3 },
} },
], :ordered => true)

The first argument to bulk_write is the list of operations to perform. Each operation must be specified as a hash with exactly one key which is the operation name and the operation specification as the corresponding value. The supported operations are detailed below. The bulk_write method also accepts the following options:

Option
Description
bypass_document_validation
true or false. Whether to bypass document validation.
ordered
If the ordered option is set to true (which is the default), the operations are applied in order and if any operation fails, subsequent operations are not attempted. If the ordered option is set to false, all specified operations are attempted.
write_concern
The write concern for the operation, specified as a hash.

Valid bulk write operations are the following:

{ insert_one: { x: 1 } }

Note

There is no insert_many bulk operation. To insert multiple documents, specify multiple insert_one operations.

{ update_one: {
filter: { x: 1 },
update: { '$set' => { x: 2 } },
# upsert is optional and defaults to false
upsert: true,
} }
{ update_many: {
filter: { x: 1 },
update: { '$set' => { x: 2 } },
# upsert is optional and defaults to false
:upsert => true,
} }
{ replace_one: {
filter: { x: 1 },
replacement: { x: 2 },
# upsert is optional and defaults to false
upsert: true,
} }

Note

The :replace_one operation requires that the replacement value is a document. :replace_one does not recognize MongoDB update operators in the replacement value. In a future release the driver is expected to prohibit using keys beginning with $ in the replacement document.

{ delete_one: {
filter: { x: 1 },
} }
{ delete_many: {
filter: { x: 1 },
} }

The driver allows the application to submit arbitrarily large bulk write requests. However, since MongoDB server limits the size of command documents (currently this limit is 48 MiB), bulk writes that exceed this limit will be split into multiple requests.

When client-side encryption is used, the threshold used for bulk write splitting is reduced to allow for overhead in the ciphertext.

←  CRUD OperationsProjection →