Navigation

Bulk Writes

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

{ insert_one: { x: 1 } }

Note

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

update_one

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

update_many

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

replace_one

{ 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

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

delete_many

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