Skip to content

Commit c614e24

Browse files
rustagirrustagir
authored
DOCSP-49150: bulkWrite docs + api (#250)
* DOCSP-49150: bulkWrite docs + api * first pass fixes * JT PR fixes 1 * upgrade composer package vs * JT PR fixes 2 * small fix * JT PR fixes 3 * remove reference to writeconcern option * add return values sections * object -> instance * NR PR fixes 1 * returns -> throws
1 parent 05aad5c commit c614e24

27 files changed

+1421
-83
lines changed

‎composer/composer.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
"name": "mongodb/docs-php-library",
33
"description": "MongoDB PHP Library Documentation",
44
"require": {
5-
"ext-mongodb": "^2.0",
6-
"mongodb/mongodb": "^2.0"
5+
"ext-mongodb": "^2.1",
6+
"mongodb/mongodb": "^2.1"
77
},
88
"require-dev": {
99
"doctrine/coding-standard": "^12.0",

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ intersphinx = [
99

1010
toc_landing_pages = [
1111
"/reference/class/MongoDBClient",
12+
"/reference/class/MongoDBClientBulkWrite",
1213
"/reference/class/MongoDBCollection",
1314
"/reference/class/MongoDBDatabase",
1415
"/reference/class/MongoDBGridFSBucket",

‎source/includes/extracts-bulkwriteexception.yaml

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
ref: bulkwriteexception-result
22
content: |
33
If a :php:`MongoDB\Driver\Exception\BulkWriteException
4-
<mongodb-driver-exception-bulkwriteexception>` is thrown, users should call
5-
:php:`getWriteResult() <mongodb-driver-writeexception.getwriteresult>` and
4+
<mongodb-driver-exception-bulkwriteexception>` is thrown, you can call
5+
:php:`getWriteResult() <mongodb-driver-bulkwriteexception.getwriteresult>` and
66
inspect the returned :php:`MongoDB\Driver\WriteResult
77
<mongodb-driver-writeresult>` object to determine the nature of the error.
88
@@ -11,11 +11,22 @@ content: |
1111
too long). Alternatively, a write operation may have failed outright (e.g.
1212
unique key violation).
1313
---
14+
ref: bulkwriteexception-client-result
15+
content: |
16+
If a :php:`MongoDB\Driver\Exception\BulkWriteCommandException
17+
<mongodb-driver-exception-bulkwritecommandexception>` is thrown, you can call
18+
:php:`getWriteErrors() <mongodb-driver-bulkwritecommandexception.getwriteerrors>` and
19+
inspect the information in the returned array to determine the nature of the error.
20+
21+
For example, a write operation may have been successfully applied to the
22+
primary server but failed to satisfy the write concern. Alternatively, a
23+
write operation may have failed outright, for example for violating the
24+
unique key constraint.
25+
---
1426
ref: bulkwriteexception-ordered
1527
content: |
16-
In the case of a bulk write, the result may indicate multiple successful write
28+
In the case of a bulk write, the result might indicate multiple successful write
1729
operations and/or errors. If the ``ordered`` option is ``true``, some
1830
operations may have succeeded before the first error was encountered and the
1931
exception thrown. If the ``ordered`` option is ``false``, multiple errors may
2032
have been encountered.
21-
...

‎source/includes/extracts-error.yaml

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,16 @@ ref: error-driver-bulkwriteexception
22
content: |
33
:php:`MongoDB\Driver\Exception\BulkWriteException
44
<mongodb-driver-exception-bulkwriteexception>` for errors related to the write
5-
operation. Users should inspect the value returned by :php:`getWriteResult()
6-
<mongodb-driver-writeexception.getwriteresult>` to determine the nature of the
5+
operation. You can inspect the value returned by :php:`getWriteResult()
6+
<mongodb-driver-bulkwriteexception.getwriteresult>` to determine the nature of the
7+
error.
8+
---
9+
ref: error-driver-client-bulkwriteexception
10+
content: |
11+
:php:`MongoDB\Driver\Exception\BulkWriteCommandException
12+
<mongodb-driver-exception-bulkwritecommandexception>` for errors related to the write
13+
operation. You can inspect the value returned by :php:`getWriteErrors()
14+
<mongodb-driver-bulkwritecommandexception.getwriteerrors>` to determine the nature of the
715
error.
816
---
917
ref: error-driver-invalidargumentexception
@@ -49,4 +57,3 @@ ref: error-gridfs-corruptfileexception
4957
content: |
5058
:phpclass:`MongoDB\GridFS\Exception\CorruptFileException` if the file's
5159
metadata or chunk documents contain unexpected or invalid data.
52-
...

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

Lines changed: 122 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,22 @@
55
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
66
$client = new MongoDB\Client($uri);
77

8-
// start-db-coll
9-
$collection = $client->sample_restaurants->restaurants;
10-
// end-db-coll
11-
128
// start-run-bulk
13-
$result = $collection->bulkWrite(
9+
$restaurantCollection = $client->sample_restaurants->restaurants;
10+
11+
$result = $restaurantCollection->bulkWrite(
1412
[
1513
[
1614
'insertOne' => [
17-
['name' => 'Mongo\'s Deli'],
18-
['cuisine' => 'Sandwiches'],
19-
['borough' => 'Manhattan'],
20-
['restaurant_id' => '1234'],
15+
['name' => 'Mongo\'s Deli'],
16+
['cuisine' => 'Sandwiches'],
17+
['borough' => 'Manhattan'],
18+
['restaurant_id' => '1234'],
2119
],
2220
],
2321
[
2422
'updateOne' => [
25-
['name' => 'Mongo\'s Deli'],
23+
['name' => 'Mongo\'s Deli'],
2624
['$set' => ['cuisine' => 'Sandwiches and Salads']],
2725
],
2826
],
@@ -36,14 +34,14 @@
3634
// end-run-bulk
3735

3836
// start-bulk-options
39-
$result = $collection->bulkWrite(
37+
$result = $restaurantCollection->bulkWrite(
4038
[
4139
[
4240
'insertOne' => [
43-
['name' => 'Mongo\'s Pizza'],
44-
['cuisine' => 'Italian'],
45-
['borough' => 'Queens'],
46-
['restaurant_id' => '5678'],
41+
['name' => 'Mongo\'s Pizza'],
42+
['cuisine' => 'Italian'],
43+
['borough' => 'Queens'],
44+
['restaurant_id' => '5678'],
4745
],
4846
],
4947
[
@@ -55,3 +53,112 @@
5553
['ordered' => false]
5654
);
5755
// end-bulk-options
56+
57+
// start-bulk-client-insert-one
58+
$restaurantCollection = $client->sample_restaurants->restaurants;
59+
$movieCollection = $client->sample_mflix->movies;
60+
61+
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
62+
$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
63+
64+
$bulkWrite = $bulkWrite->withCollection($movieCollection);
65+
$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);
66+
// end-bulk-client-insert-one
67+
68+
// start-bulk-client-update-one
69+
$restaurantCollection = $client->sample_restaurants->restaurants;
70+
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
71+
72+
$bulkWrite->updateOne(
73+
['name' => 'Dandelion Bakery'],
74+
['$set' => ['grade' => 'B+']],
75+
['upsert' => true],
76+
);
77+
// end-bulk-client-update-one
78+
79+
// start-bulk-client-update-many
80+
$restaurantCollection = $client->sample_restaurants->restaurants;
81+
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
82+
83+
$bulkWrite->updateMany(
84+
['name' => 'Starbucks'],
85+
['$set' => ['cuisine' => 'Coffee (Chain)']],
86+
);
87+
// end-bulk-client-update-many
88+
89+
// start-bulk-client-replace-one
90+
$restaurantCollection = $client->sample_restaurants->restaurants;
91+
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
92+
93+
$bulkWrite->replaceOne(
94+
['name' => 'Dandelion Bakery'],
95+
['name' => 'Flower Patisserie', 'cuisine' => 'Bakery & Cafe'],
96+
);
97+
// end-bulk-client-replace-one
98+
99+
// start-bulk-client-delete-one
100+
$restaurantCollection = $client->sample_restaurants->restaurants;
101+
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
102+
103+
$bulkWrite->deleteOne(
104+
['borough' => 'Queens'],
105+
);
106+
// end-bulk-client-delete-one
107+
108+
// start-bulk-client-delete-many
109+
$restaurantCollection = $client->sample_restaurants->restaurants;
110+
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
111+
112+
$bulkWrite->deleteMany(
113+
['name' => ['$regex' => 'p{2,}']],
114+
);
115+
// end-bulk-client-delete-many
116+
117+
// start-bulk-client
118+
$restaurantCollection = $client->sample_restaurants->restaurants;
119+
$movieCollection = $client->sample_mflix->movies;
120+
// Creates the bulk write command and sets the target namespace.
121+
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
122+
// Specifies insertion of one document.
123+
$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
124+
// Specifies a `$set` update to one document with the upsert option
125+
// enabled.
126+
$bulkWrite->updateOne(
127+
['name' => 'Dandelion Bakery'],
128+
['$set' => ['grade' => 'B+']],
129+
['upsert' => true],
130+
);
131+
// Changes the target namespace.
132+
$bulkWrite = $bulkWrite->withCollection($movieCollection);
133+
// Specifies insertion of one document.
134+
$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);
135+
// Specifies deletion of documents in which `title` has two consective
136+
// 'd' characters.
137+
$bulkWrite->deleteMany(
138+
['title' => ['$regex' => 'd{2,}']],
139+
);
140+
// Specifies replacement of one document.
141+
$bulkWrite->replaceOne(
142+
['runtime' => ['$gte' => 200]],
143+
['title' => 'Seven Samurai', 'runtime' => 203],
144+
);
145+
146+
// Performs the bulk write operation.
147+
$result = $client->bulkWrite($bulkWrite);
148+
// Prints a summary of results.
149+
echo 'Inserted documents: ', $result->getInsertedCount(), PHP_EOL;
150+
echo 'Modified documents: ', $result->getModifiedCount(), PHP_EOL;
151+
echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;
152+
// end-bulk-client
153+
154+
// start-bulk-client-options
155+
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection(
156+
$restaurantCollection,
157+
['ordered' => false]
158+
);
159+
// end-bulk-client-options
160+
161+
// start-bulk-client-unordered-behavior
162+
$bulkWrite->insertOne(['_id' => 4045, 'title' => 'The Green Ray']);
163+
$bulkWrite->deleteOne(['_id' => 4045]);
164+
// end-bulk-client-unordered-behavior

‎source/reference.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ API Documentation
1111

1212
BSON </reference/bson>
1313
MongoDB\Client </reference/class/MongoDBClient>
14+
MongoDB\ClientBulkWrite </reference/class/MongoDBClientBulkWrite>
1415
MongoDB\Database </reference/class/MongoDBDatabase>
1516
MongoDB\Collection </reference/class/MongoDBCollection>
1617
MongoDB\GridFS\Bucket </reference/class/MongoDBGridFSBucket>

‎source/reference/class/MongoDBBulkWriteCommandResult.txt

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
=====================================
2+
MongoDB\\BulkWriteCommandResult Class
3+
=====================================
4+
5+
Definition
6+
----------
7+
8+
.. phpclass:: MongoDB\BulkWriteCommandResult
9+
10+
This class contains information about a completed client bulk write operation. It
11+
is returned from :phpmethod:`MongoDB\Client::bulkWrite()`.
12+
13+
Methods
14+
-------
15+
16+
.. list-table::
17+
:widths: 30 70
18+
:header-rows: 1
19+
20+
* - Method
21+
- Description
22+
23+
* - ``getInsertedCount()``
24+
- | Returns the total number of documents inserted by all
25+
insert operations in the bulk write command.
26+
27+
* - ``getMatchedCount()``
28+
- | Returns the total number of documents matched by all
29+
update and replace operations in the bulk write command.
30+
31+
* - ``getModifiedCount()``
32+
- | Returns the total number of documents modified by all update
33+
and replace operations in the bulk write command.
34+
35+
* - ``getUpsertedCount()``
36+
- | Returns the total number of documents upserted by all update
37+
and replace operations in the bulk write command.
38+
39+
* - ``getDeletedCount()``
40+
- | Return the total number of documents deleted by all delete
41+
operations in the bulk write command.
42+
43+
* - ``getInsertResults()``
44+
- | Returns a map of results of each successful insert operation. Each
45+
operation is represented by an integer key, which contains a
46+
document with information corresponding to the operation such
47+
as the inserted ``_id`` value.
48+
49+
* - ``getUpdateResults()``
50+
- | Returns a map of results of each successful update operation. Each
51+
operation is represented by an integer key, which contains a
52+
document with information corresponding to the operation.
53+
54+
* - ``getDeleteResults()``
55+
- | Returns a map of results of each successful delete operation.
56+
Each operation is represented by an integer key, which contains
57+
a document with information corresponding to the operation.
58+
59+
* - ``isAcknowledged()``
60+
- | Returns a boolean indicating whether the server acknowledged
61+
the bulk operation.
62+
63+
To learn more about the information returned from the server when you
64+
perform a client bulk write operation, see the :manual:`Output
65+
</reference/method/Mongo.bulkWrite/#output>` section of the
66+
``Mongo.bulkWrite`` shell method reference.
67+
68+
See Also
69+
--------
70+
71+
- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide

‎source/reference/class/MongoDBBulkWriteResult.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Definition
77

88
.. phpclass:: MongoDB\BulkWriteResult
99

10-
This class contains information about an executed bulk write operation. It
10+
This class contains information about a completed bulk write operation. It
1111
encapsulates a :php:`MongoDB\Driver\WriteResult <class.mongodb-driver-writeresult>`
1212
object and is returned from :phpmethod:`MongoDB\Collection::bulkWrite()`.
1313

@@ -33,4 +33,4 @@ Methods
3333
- :phpmethod:`MongoDB\BulkWriteResult::getModifiedCount()`
3434
- :phpmethod:`MongoDB\BulkWriteResult::getUpsertedCount()`
3535
- :phpmethod:`MongoDB\BulkWriteResult::getUpsertedIds()`
36-
- :phpmethod:`MongoDB\BulkWriteResult::isAcknowledged()`
36+
- :phpmethod:`MongoDB\BulkWriteResult::isAcknowledged()`

‎source/reference/class/MongoDBClient.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Methods
3232
__construct() </reference/method/MongoDBClient__construct>
3333
__get() </reference/method/MongoDBClient__get>
3434
addSubscriber() </reference/method/MongoDBClient-addSubscriber>
35+
bulkWrite() </reference/method/MongoDBClient-bulkWrite>
3536
createClientEncryption() </reference/method/MongoDBClient-createClientEncryption>
3637
dropDatabase() </reference/method/MongoDBClient-dropDatabase>
3738
getCollection() </reference/method/MongoDBClient-getCollection>
@@ -52,6 +53,7 @@ Methods
5253
- :phpmethod:`MongoDB\Client::__construct()`
5354
- :phpmethod:`MongoDB\Client::__get()`
5455
- :phpmethod:`MongoDB\Client::addSubscriber()`
56+
- :phpmethod:`MongoDB\Client::bulkWrite()`
5557
- :phpmethod:`MongoDB\Client::createClientEncryption()`
5658
- :phpmethod:`MongoDB\Client::dropDatabase()`
5759
- :phpmethod:`MongoDB\Client::getCollection()`
@@ -67,4 +69,4 @@ Methods
6769
- :phpmethod:`MongoDB\Client::selectCollection()`
6870
- :phpmethod:`MongoDB\Client::selectDatabase()`
6971
- :phpmethod:`MongoDB\Client::startSession()`
70-
- :phpmethod:`MongoDB\Client::watch()`
72+
- :phpmethod:`MongoDB\Client::watch()`

0 commit comments

Comments
 (0)