Skip to content

Commit 668f3dc

Browse files
norareidynorareidy
authored
DOCSP-41971: Bulk write (#130)
* DOCSP-41971: Bulk write * edits * JS feedback * api links
1 parent df79843 commit 668f3dc

File tree

4 files changed

+293
-3
lines changed

4 files changed

+293
-3
lines changed

‎source/includes/write/bulk-write.php

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
6+
$client = new MongoDB\Client($uri);
7+
8+
// start-db-coll
9+
$collection = $client->sample_restaurants->restaurants;
10+
// end-db-coll
11+
12+
// start-run-bulk
13+
$result = $collection->bulkWrite(
14+
[
15+
[
16+
'insertOne' => [
17+
['name' => 'Mongo\'s Deli'],
18+
['cuisine' => 'Sandwiches'],
19+
['borough' => 'Manhattan'],
20+
['restaurant_id' => '1234'],
21+
],
22+
],
23+
[
24+
'updateOne' => [
25+
['name' => 'Mongo\'s Deli'],
26+
['$set' => ['cuisine' => 'Sandwiches and Salads']],
27+
],
28+
],
29+
[
30+
'deleteMany' => [
31+
['borough' => 'Manhattan'],
32+
],
33+
],
34+
]
35+
);
36+
// end-run-bulk
37+
38+
// start-bulk-options
39+
$result = $collection->bulkWrite(
40+
[
41+
[
42+
'insertOne' => [
43+
['name' => 'Mongo\'s Pizza'],
44+
['cuisine' => 'Italian'],
45+
['borough' => 'Queens'],
46+
['restaurant_id' => '5678'],
47+
],
48+
],
49+
[
50+
'deleteOne' => [
51+
['restaurant_id' => '5678'],
52+
],
53+
],
54+
],
55+
['ordered' => false]
56+
);
57+
// end-bulk-options

‎source/tutorial/codecs.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _php-codecs:
2+
13
======
24
Codecs
35
======

‎source/write.txt

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,12 @@ Write Data to MongoDB
2121
.. toctree::
2222
:titlesonly:
2323
:maxdepth: 1
24-
24+
25+
/write/update
26+
/write/insert
2527
/write/delete
2628
/write/replace
27-
/write/insert
28-
/write/update
29+
/write/bulk-write
2930
/write/gridfs
3031

3132
Overview

‎source/write/bulk-write.txt

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
.. _php-bulk-write:
2+
3+
=====================
4+
Bulk Write Operations
5+
=====================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: insert, update, replace, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to perform multiple write operations
24+
in a single database call by using **bulk write operations**.
25+
26+
Consider a scenario in which you want to insert a document into a collection,
27+
update multiple other documents, then delete a document. If you use
28+
individual methods, each operation requires its own database call. Instead,
29+
you can use a bulk operation to reduce the number of calls to the database.
30+
31+
Sample Data
32+
~~~~~~~~~~~
33+
34+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
35+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
36+
from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
37+
and assign the following value to your ``$collection`` variable:
38+
39+
.. literalinclude:: /includes/write/bulk-write.php
40+
:language: php
41+
:dedent:
42+
:start-after: start-db-coll
43+
:end-before: end-db-coll
44+
45+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
46+
:atlas:`Get Started with Atlas </getting-started>` guide.
47+
48+
.. _php-bulk-operations:
49+
50+
Bulk Operations
51+
---------------
52+
53+
To run a bulk write operation, pass an array of write operations to the
54+
``MongoDB\Collection::bulkWrite()`` method. Use the following syntax to
55+
specify the write operations:
56+
57+
.. code-block:: php
58+
59+
[
60+
[ 'deleteMany' => [ $filter ] ],
61+
[ 'deleteOne' => [ $filter ] ],
62+
[ 'insertOne' => [ $document ] ],
63+
[ 'replaceOne' => [ $filter, $replacement, $options ] ],
64+
[ 'updateMany' => [ $filter, $update, $options ] ],
65+
[ 'updateOne' => [ $filter, $update, $options ] ],
66+
]
67+
68+
.. tip::
69+
70+
For more information about delete, insert, replace, and update
71+
operations, see the :ref:`Write operation guides <php-write>`.
72+
73+
When you call the ``bulkWrite()`` method, the library automatically runs the
74+
write operations in the order they're specified in the array. To learn how to
75+
instruct ``bulkWrite()`` to run the write operations in an arbitrary order,
76+
see the :ref:`php-bulk-modify` section.
77+
78+
Example
79+
~~~~~~~
80+
81+
This example runs the following write operations on the ``restaurants``
82+
collection:
83+
84+
- **Insert operation** to insert a document in which the ``name`` value is
85+
``'Mongo's Deli'``
86+
87+
- **Update operation** to update the ``cuisine`` field of a document in
88+
which the ``name`` value is ``'Mongo's Deli'``
89+
90+
- **Delete operation** to delete all documents in which the ``borough`` value
91+
is ``'Manhattan'``
92+
93+
.. literalinclude:: /includes/write/bulk-write.php
94+
:start-after: start-run-bulk
95+
:end-before: end-run-bulk
96+
:language: php
97+
:dedent:
98+
99+
.. _php-bulk-modify:
100+
101+
Modify Bulk Write Behavior
102+
--------------------------
103+
104+
You can modify the behavior of the ``MongoDB\Collection::bulkWrite()`` method by
105+
passing an array that specifies option values as a parameter. The following table
106+
describes the options you can set in the array:
107+
108+
.. list-table::
109+
:widths: 30 70
110+
:header-rows: 1
111+
112+
* - Option
113+
- Description
114+
115+
* - ``bypassDocumentValidation``
116+
- | Specifies whether the operation bypasses document validation. This lets you
117+
modify documents that don't meet the schema validation requirements, if any
118+
exist. For more information about schema validation, see :manual:`Schema
119+
Validation </core/schema-validation/#schema-validation>` in the {+mdb-server+}
120+
manual.
121+
| Defaults to ``false``.
122+
123+
* - ``codec``
124+
- | Sets the codec to use for encoding or decoding documents. Bulk writes
125+
use the codec for ``insertOne()`` and ``replaceOne()`` operations.
126+
For more information, see the :ref:`php-codecs` guide.
127+
128+
* - ``writeConcern``
129+
- | Sets the write concern for the operation.
130+
For more information, see :manual:`Write Concern </reference/write-concern/>`
131+
in the {+mdb-server+} manual.
132+
133+
* - ``let``
134+
- | Specifies a document with a list of values to improve operation readability.
135+
Values must be constant or closed expressions that don't reference document
136+
fields. For more information, see the :manual:`let statement
137+
</reference/command/update/#std-label-update-let-syntax>` in the
138+
{+mdb-server+} manual.
139+
140+
* - ``ordered``
141+
- | If set to ``true``: when a single write fails, the operation stops without
142+
performing the remaining writes and throws an exception.
143+
| If set to ``false``: when a single write fails, the operation continues to
144+
attempt the remaining write operations, if any, then throws an exception.
145+
| Defaults to ``true``.
146+
147+
* - ``comment``
148+
- | Attaches a comment to the operation. For more information, see the :manual:`insert command
149+
fields </reference/command/insert/#command-fields>` guide in the
150+
{+mdb-server+} manual.
151+
152+
* - ``session``
153+
- | Specifies the client session to associate with the operation.
154+
155+
The following example calls the ``bulkWrite()`` method to perform an
156+
insert and delete operation and sets the ``ordered`` option to
157+
``false``:
158+
159+
.. literalinclude:: /includes/write/bulk-write.php
160+
:start-after: start-bulk-options
161+
:end-before: end-bulk-options
162+
:language: php
163+
:dedent:
164+
165+
If the library runs the insert operation first, one document is deleted.
166+
If it runs the delete operation first, no documents are deleted.
167+
168+
.. note::
169+
170+
Unordered bulk operations do not guarantee order of execution. The order can
171+
differ from the way you list them to optimize the runtime.
172+
173+
.. _php-bulk-return-value:
174+
175+
Return Value
176+
------------
177+
178+
The ``MongoDB\Collection::bulkWrite()`` method returns a ``MongoDB\BulkWriteResult``
179+
object. This class contains the following member functions:
180+
181+
.. list-table::
182+
:widths: 30 70
183+
:header-rows: 1
184+
185+
* - Function
186+
- Description
187+
188+
* - ``getDeletedCount()``
189+
- | Returns the number of documents deleted, if any.
190+
191+
* - ``getInsertedCount()``
192+
- | Returns the number of documents inserted, if any.
193+
194+
* - ``getInsertedIds()``
195+
- | Returns a map of ``_id`` field values for inserted documents, if any.
196+
197+
* - ``getMatchedCount()``
198+
- | Returns the number of documents matched during update and replace
199+
operations, if applicable.
200+
201+
* - ``getModifiedCount()``
202+
- | Returns the number of documents modified, if any.
203+
204+
* - ``getUpsertedCount()``
205+
- | Returns the number of documents upserted, if any.
206+
207+
* - ``getUpsertedIds()``
208+
- | Returns a map of ``_id`` field values for upserted documents, if any.
209+
210+
* - ``isAcknowledged()``
211+
- | Returns a boolean indicating whether the bulk operation was acknowledged.
212+
213+
Additional Information
214+
----------------------
215+
216+
To learn how to perform individual write operations, see the following guides:
217+
218+
- :ref:`php-write-insert`
219+
- :ref:`php-write-update`
220+
- :ref:`php-write-delete`
221+
- :ref:`php-write-replace`
222+
223+
API Documentation
224+
~~~~~~~~~~~~~~~~~
225+
226+
To learn more about any of the methods or types discussed in this
227+
guide, see the following API documentation:
228+
229+
- :phpmethod:`MongoDB\Collection::bulkWrite()`
230+
- :phpclass:`MongoDB\BulkWriteResult`

0 commit comments

Comments
 (0)