1
- ***************
2
- Bulk Operations
3
- ***************
1
+ ***********
2
+ Bulk Writes
3
+ ***********
4
4
5
5
.. default-domain:: mongodb
6
6
@@ -14,18 +14,65 @@ Bulk Operations
14
14
15
15
The bulk write API sends several write operations to the server in a single
16
16
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:
18
19
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:
23
40
24
- The ``bulk_write`` method takes three arguments:
41
+ .. code-block:: ruby
25
42
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.
29
76
30
77
Valid bulk write operations are the following:
31
78
@@ -35,11 +82,11 @@ insert_one
35
82
36
83
.. code-block:: ruby
37
84
38
- { : insert_one => { :x => 1 } }
85
+ { insert_one: { x: 1 } }
39
86
40
87
.. note::
41
88
42
- There is no ``insert_many`` operation. To insert multiple documents,
89
+ There is no ``insert_many`` bulk operation. To insert multiple documents,
43
90
specify multiple ``insert_one`` operations.
44
91
45
92
@@ -48,64 +95,75 @@ update_one
48
95
49
96
.. code-block:: ruby
50
97
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
+ } }
55
104
56
105
57
106
update_many
58
107
===========
59
108
60
109
.. code-block:: ruby
61
110
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
+ } }
85
117
86
118
87
119
replace_one
88
120
===========
89
121
90
122
.. code-block:: ruby
91
123
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.
96
137
97
138
98
139
delete_one
99
140
==========
100
141
101
142
.. code-block:: ruby
102
143
103
- { :delete_one => { :filter => { :x => 1 } } }
144
+ { delete_one: {
145
+ filter: { x: 1 },
146
+ } }
104
147
105
148
106
149
delete_many
107
150
===========
108
151
109
152
.. code-block:: ruby
110
153
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