Skip to content

Commit 16b0647

Browse files
p-mongop
andauthored
expand bulk write documentation (#2154)
Co-authored-by: Oleg Pudeyev <[email protected]>
1 parent b7037e2 commit 16b0647

File tree

2 files changed

+106
-48
lines changed

2 files changed

+106
-48
lines changed

source/index.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ For tutorials on Mongoid, see the `Mongoid Manual <https://docs.mongodb.com/mong
6363
/tutorials/ruby-driver-authentication
6464
/tutorials/user-management
6565
/tutorials/ruby-driver-crud-operations
66+
/tutorials/ruby-driver-bulk-operations
6667
/tutorials/ruby-driver-collection-tasks
6768
/tutorials/ruby-driver-projections
6869
/tutorials/ruby-driver-sessions
@@ -73,7 +74,6 @@ For tutorials on Mongoid, see the `Mongoid Manual <https://docs.mongodb.com/mong
7374
/tutorials/ruby-driver-indexing
7475
/tutorials/ruby-driver-collations
7576
/tutorials/ruby-driver-aggregation
76-
/tutorials/ruby-driver-bulk-operations
7777
/tutorials/ruby-driver-text-search
7878
/tutorials/ruby-driver-geospatial-search
7979
/tutorials/ruby-driver-gridfs
Lines changed: 105 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
***************
2-
Bulk Operations
3-
***************
1+
***********
2+
Bulk Writes
3+
***********
44

55
.. default-domain:: mongodb
66

@@ -14,18 +14,65 @@ Bulk Operations
1414

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

19-
If the ``ordered`` option is set to ``true`` (which is the default),
20-
the operations are applied in order and if any operation fails, subsequent
21-
operations are not attempted. If the ``ordered`` option is set to ``false``,
22-
all specified operations are attempted.
20+
.. code-block:: ruby
21+
22+
collection = client['colors']
23+
collection.bulk_write([
24+
{
25+
update_one: {
26+
filter: {name: 'yellow'},
27+
update: {'$set' => {hex: 'ffff00'}},
28+
},
29+
},
30+
{
31+
update_one: {
32+
filter: {name: 'purple'},
33+
update: {'$set' => {hex: '800080'}},
34+
},
35+
},
36+
], ordered: true, write_concern: {w: :majority})
37+
38+
The following example shows how to execute different types of operations
39+
in the same request:
2340

24-
The ``bulk_write`` method takes three arguments:
41+
.. code-block:: ruby
2542

26-
- A list of operations to execute.
27-
- The ``ordered`` option taking a boolean value. Defaults to ``true``.
28-
- The write concern option. Defaults to the collection's write concern.
43+
collection.bulk_write([
44+
{ insert_one: { x: 1 } },
45+
{ update_one: {
46+
filter: { x: 1 },
47+
update: {'$set' => { x: 2 } },
48+
} },
49+
{ replace_one: {
50+
filter: { x: 2 },
51+
replacement: { x: 3 },
52+
} },
53+
], :ordered => true)
54+
55+
The first argument to ``bulk_write`` is the list of operations to perform.
56+
Each operation must be specified as a hash with exactly one key which is
57+
the operation name and the operation specification as the corresponding
58+
value. The supported operations are detailed below. The ``bulk_write`` method
59+
also accepts the following options:
60+
61+
.. list-table::
62+
:header-rows: 1
63+
:widths: 40 80
64+
65+
* - Option
66+
- Description
67+
* - ``bypass_document_validation``
68+
- ``true`` or ``false``. Whether to bypass document validation.
69+
* - ``ordered``
70+
- If the ``ordered`` option is set to ``true`` (which is the default),
71+
the operations are applied in order and if any operation fails, subsequent
72+
operations are not attempted. If the ``ordered`` option is set to ``false``,
73+
all specified operations are attempted.
74+
* - ``write_concern``
75+
- The write concern for the operation, specified as a hash.
2976

3077
Valid bulk write operations are the following:
3178

@@ -35,11 +82,11 @@ insert_one
3582

3683
.. code-block:: ruby
3784

38-
{ :insert_one => { :x => 1 } }
85+
{ insert_one: { x: 1 } }
3986

4087
.. note::
4188

42-
There is no ``insert_many`` operation. To insert multiple documents,
89+
There is no ``insert_many`` bulk operation. To insert multiple documents,
4390
specify multiple ``insert_one`` operations.
4491

4592

@@ -48,64 +95,75 @@ update_one
4895

4996
.. code-block:: ruby
5097

51-
{ :update_one => { :filter => { :x => 1 },
52-
:update => { '$set' => { :x => 2 } },
53-
:upsert => true } # upsert is optional and defaults to false
54-
}
98+
{ update_one: {
99+
filter: { x: 1 },
100+
update: { '$set' => { x: 2 } },
101+
# upsert is optional and defaults to false
102+
upsert: true,
103+
} }
55104

56105

57106
update_many
58107
===========
59108

60109
.. code-block:: ruby
61110

62-
{ :update_many => { :filter => { :x => 1 },
63-
:update => { '$set' => { :x => 2 } },
64-
:upsert => true } # upsert is optional and defaults to false
65-
}
66-
67-
The following example shows how to pass operations
68-
to the ``bulk_write`` method.
69-
70-
.. code-block:: ruby
71-
72-
coll = client['documents']
73-
coll.bulk_write([ { :insert_one => { :x => 1 }
74-
},
75-
{ :update_one => { :filter => { :x => 1 },
76-
:update => {'$set' => { :x => 2 } }
77-
}
78-
},
79-
{ :replace_one => { :filter => { :x => 2 },
80-
:replacement => { :x => 3 }
81-
}
82-
}
83-
],
84-
:ordered => true)
111+
{ update_many: {
112+
filter: { x: 1 },
113+
update: { '$set' => { x: 2 } },
114+
# upsert is optional and defaults to false
115+
:upsert => true,
116+
} }
85117

86118

87119
replace_one
88120
===========
89121

90122
.. code-block:: ruby
91123

92-
{ :replace_one => { :filter => { :x => 1 },
93-
:replacement => { :x => 2 },
94-
:upsert => true } # upsert is optional and defaults to false
95-
}
124+
{ replace_one: {
125+
filter: { x: 1 },
126+
replacement: { x: 2 },
127+
# upsert is optional and defaults to false
128+
upsert: true,
129+
} }
130+
131+
.. note::
132+
133+
The ``:replace_one`` operation requires that the replacement value is a
134+
document. ``:replace_one`` does not recognize MongoDB update operators in
135+
the replacement value. In a future release the driver is expected to
136+
prohibit using keys beginning with ``$`` in the replacement document.
96137

97138

98139
delete_one
99140
==========
100141

101142
.. code-block:: ruby
102143

103-
{ :delete_one => { :filter => { :x => 1 } } }
144+
{ delete_one: {
145+
filter: { x: 1 },
146+
} }
104147

105148

106149
delete_many
107150
===========
108151

109152
.. code-block:: ruby
110153

111-
{ :delete_many => { :filter => { :x => 1 } } }
154+
{ delete_many: {
155+
filter: { x: 1 },
156+
} }
157+
158+
159+
Bulk Write Splitting
160+
====================
161+
162+
The driver allows the application to submit arbitrarily large bulk write
163+
requests. However, since MongoDB server limits the size of command documents
164+
(currently this limit is 48 MiB), bulk writes that exceed this limit will be
165+
split into multiple requests.
166+
167+
When :ref:`client-side encryption <client-side-encryption>` is used, the
168+
threshold used for bulk write splitting is reduced to allow for overhead in
169+
the ciphertext.

0 commit comments

Comments
 (0)