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:

copy

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:

copy

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¶

copy

{ insert_one: { x: 1 } }

Note

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

update_one¶

copy

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

update_many¶

copy

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

replace_one¶

copy

{ 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¶

copy

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

delete_many¶

copy

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

Bulk Write Splitting¶

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 Operations Projection →