Skip to content

Commit 59a5dad

Browse files
jmikolabenjirewis
jmikola
and
benjirewis
authored
DRIVERS-1340: Allow w:0 and hint if supported by server (#1057)
update supports hint on 4.2+. delete and findAndModify support hint on 4.4+. Add APM assertions for successful commands to ensure that w:0 is actually used. Co-authored-by: Benjamin Rewis <[email protected]>
1 parent aef211f commit 59a5dad

File tree

47 files changed

+4745
-2573
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+4745
-2573
lines changed

‎source/crud/crud.rst

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Driver CRUD API
1212
:Status: Approved
1313
:Type: Standards
1414
:Minimum Server Version: 2.6
15-
:Last Modified: June 2, 2021
15+
:Last Modified: August 31, 2021
1616

1717
.. contents::
1818

@@ -946,7 +946,8 @@ Insert, Update, Replace, Delete, and Bulk Writes
946946
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
947947
* This option is only supported by servers >= 4.2. Older servers >= 3.4 will report an error for using this option.
948948
* For servers < 3.4, the driver MUST raise an error if the caller explicitly provides a value.
949-
* For unacknowledged writes using OP_UPDATE or OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
949+
* For unacknowledged writes using OP_UPDATE, the driver MUST raise an error if the caller explicitly provides a value.
950+
* For unacknowledged writes using OP_MSG and servers < 4.2, the driver MUST raise an error if the caller explicitly provides a value.
950951
*
951952
* @see https://docs.mongodb.com/manual/reference/command/update/
952953
*/
@@ -991,7 +992,8 @@ Insert, Update, Replace, Delete, and Bulk Writes
991992
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
992993
* This option is only supported by servers >= 4.2. Older servers >= 3.4 will report an error for using this option.
993994
* For servers < 3.4, the driver MUST raise an error if the caller explicitly provides a value.
994-
* For unacknowledged writes using OP_UPDATE or OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
995+
* For unacknowledged writes using OP_UPDATE, the driver MUST raise an error if the caller explicitly provides a value.
996+
* For unacknowledged writes using OP_MSG and servers < 4.2, the driver MUST raise an error if the caller explicitly provides a value.
995997
*
996998
* @see https://docs.mongodb.com/manual/reference/command/update/
997999
*/
@@ -1027,7 +1029,8 @@ Insert, Update, Replace, Delete, and Bulk Writes
10271029
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
10281030
* This option is only supported by servers >= 4.4. Older servers >= 3.4 will report an error for using this option.
10291031
* For servers < 3.4, the driver MUST raise an error if the caller explicitly provides a value.
1030-
* For unacknowledged writes using OP_DELETE or OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
1032+
* For unacknowledged writes using OP_DELETE, the driver MUST raise an error if the caller explicitly provides a value.
1033+
* For unacknowledged writes using OP_MSG and servers < 4.4, the driver MUST raise an error if the caller explicitly provides a value.
10311034
*
10321035
* @see https://docs.mongodb.com/manual/reference/command/delete/
10331036
*/
@@ -1081,7 +1084,8 @@ Bulk Write Models
10811084
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
10821085
* This option is only supported by servers >= 4.4. Older servers >= 3.4 will report an error for using this option.
10831086
* For servers < 3.4, the driver MUST raise an error if the caller explicitly provides a value.
1084-
* For unacknowledged writes using OP_DELETE or OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
1087+
* For unacknowledged writes using OP_DELETE, the driver MUST raise an error if the caller explicitly provides a value.
1088+
* For unacknowledged writes using OP_MSG and servers < 4.4, the driver MUST raise an error if the caller explicitly provides a value.
10851089
*
10861090
* @see https://docs.mongodb.com/manual/reference/command/delete/
10871091
*/
@@ -1156,7 +1160,8 @@ Bulk Write Models
11561160
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
11571161
* This option is only supported by servers >= 4.2. Older servers >= 3.4 will report an error for using this option.
11581162
* For servers < 3.4, the driver MUST raise an error if the caller explicitly provides a value.
1159-
* For unacknowledged writes using OP_UPDATE or OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
1163+
* For unacknowledged writes using OP_UPDATE, the driver MUST raise an error if the caller explicitly provides a value.
1164+
* For unacknowledged writes using OP_MSG and servers < 4.2, the driver MUST raise an error if the caller explicitly provides a value.
11601165
*
11611166
* @see https://docs.mongodb.com/manual/reference/command/update/
11621167
*/
@@ -1217,7 +1222,8 @@ Bulk Write Models
12171222
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
12181223
* This option is only supported by servers >= 4.2. Older servers >= 3.4 will report an error for using this option.
12191224
* For servers < 3.4, the driver MUST raise an error if the caller explicitly provides a value.
1220-
* For unacknowledged writes using OP_UPDATE or OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
1225+
* For unacknowledged writes using OP_UPDATE, the driver MUST raise an error if the caller explicitly provides a value.
1226+
* For unacknowledged writes using OP_MSG and servers < 4.2, the driver MUST raise an error if the caller explicitly provides a value.
12211227
*
12221228
* @see https://docs.mongodb.com/manual/reference/command/update/
12231229
*/
@@ -1278,7 +1284,8 @@ Bulk Write Models
12781284
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
12791285
* This option is only supported by servers >= 4.2. Older servers >= 3.4 will report an error for using this option.
12801286
* For servers < 3.4, the driver MUST raise an error if the caller explicitly provides a value.
1281-
* For unacknowledged writes using OP_UPDATE or OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
1287+
* For unacknowledged writes using OP_UPDATE, the driver MUST raise an error if the caller explicitly provides a value.
1288+
* For unacknowledged writes using OP_MSG and servers < 4.2, the driver MUST raise an error if the caller explicitly provides a value.
12821289
*
12831290
* @see https://docs.mongodb.com/manual/reference/command/update/
12841291
*/
@@ -1699,7 +1706,7 @@ Find And Modify
16991706
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
17001707
* This option is only supported by servers >= 4.4. Older servers >= 4.2 will report an error for using this option.
17011708
* For servers < 4.2, the driver MUST raise an error if the caller explicitly provides a value.
1702-
* For unacknowledged writes using OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
1709+
* For unacknowledged writes and servers < 4.4, the driver MUST raise an error if the caller explicitly provides a value.
17031710
*
17041711
* @see https://docs.mongodb.com/manual/reference/command/findAndModify/
17051712
*/
@@ -1762,7 +1769,7 @@ Find And Modify
17621769
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
17631770
* This option is only supported by servers >= 4.4. Older servers >= 4.2 will report an error for using this option.
17641771
* For servers < 4.2, the driver MUST raise an error if the caller explicitly provides a value.
1765-
* For unacknowledged writes using OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
1772+
* For unacknowledged writes and servers < 4.4, the driver MUST raise an error if the caller explicitly provides a value.
17661773
*
17671774
* @see https://docs.mongodb.com/manual/reference/command/findAndModify/
17681775
*/
@@ -1856,7 +1863,7 @@ Find And Modify
18561863
* This option is sent only if the caller explicitly provides a value. The default is to not send a value.
18571864
* This option is only supported by servers >= 4.4. Older servers >= 4.2 will report an error for using this option.
18581865
* For servers < 4.2, the driver MUST raise an error if the caller explicitly provides a value.
1859-
* For unacknowledged writes using OP_MSG, the driver MUST raise an error if the caller explicitly provides a value.
1866+
* For unacknowledged writes and servers < 4.4, the driver MUST raise an error if the caller explicitly provides a value.
18601867
*
18611868
* @see https://docs.mongodb.com/manual/reference/command/findAndModify/
18621869
*/
@@ -2014,12 +2021,10 @@ Q: Where is ``singleBatch`` in FindOptions?
20142021
Q: Why are client-side errors raised for some unsupported options?
20152022
Server versions before 3.4 were inconsistent about reporting errors for unrecognized command options and may simply ignore them, which means a client-side error is the only way to inform users that such options are unsupported. For unacknowledged writes using OP_MSG, a client-side error is necessary because the server has no chance to return a response (even though a 3.6+ server is otherwise capable of reporting errors for unrecognized options). For unacknowledged writes using legacy opcodes (i.e. OP_INSERT, OP_UPDATE, and OP_DELETE), the message body has no field with which to express these options so a client-side error is the only mechanism to inform the user that such options are unsupported. The spec does not explicitly refer to unacknowledged writes using OP_QUERY primarily because a response document is always returned and drivers generally would not consider using OP_QUERY precisely for that reason.
20162023

2017-
Q: Why are client-side errors raised when options are provided for unacknowledged write operations, even on server versions that support those options?
2018-
Even if the server supports an option, that option could be incorrectly formatted or contain outdated information (e.g. a "hint" option referencing an index that no longer exists). This is a problem during unacknowledged writes because the server cannot return an error response to alert the client of an incorrect option. By always raising a client-side error when options are specified for unacknowledged writes, users are prevented from performing operations with options that do not work.
2019-
20202024
Changes
20212025
=======
20222026

2027+
* 2021-08-31: Allow unacknowledged hints on write operations if supported by server (reverts previous change).
20232028
* 2021-06-02: Introduce WriteError.details and clarify WriteError construction
20242029
* 2021-06-01: Add let to AggregateOptions
20252030
* 2021-01-21: Update estimatedDocumentCount to use $collStats stage for servers >= 4.9

‎source/crud/tests/unified/bulkWrite-deleteMany-hint-unacknowledged.json

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
{
2+
"description": "bulkWrite-deleteMany-hint-unacknowledged",
3+
"schemaVersion": "1.0",
4+
"createEntities": [
5+
{
6+
"client": {
7+
"id": "client0",
8+
"observeEvents": [
9+
"commandStartedEvent"
10+
]
11+
}
12+
},
13+
{
14+
"database": {
15+
"id": "database0",
16+
"client": "client0",
17+
"databaseName": "db0"
18+
}
19+
},
20+
{
21+
"collection": {
22+
"id": "collection0",
23+
"database": "database0",
24+
"collectionName": "coll0",
25+
"collectionOptions": {
26+
"writeConcern": {
27+
"w": 0
28+
}
29+
}
30+
}
31+
}
32+
],
33+
"initialData": [
34+
{
35+
"collectionName": "coll0",
36+
"databaseName": "db0",
37+
"documents": [
38+
{
39+
"_id": 1,
40+
"x": 11
41+
},
42+
{
43+
"_id": 2,
44+
"x": 22
45+
},
46+
{
47+
"_id": 3,
48+
"x": 33
49+
}
50+
]
51+
}
52+
],
53+
"tests": [
54+
{
55+
"description": "Unacknowledged deleteMany with hint string fails with client-side error on pre-4.4 server",
56+
"runOnRequirements": [
57+
{
58+
"maxServerVersion": "4.2.99"
59+
}
60+
],
61+
"operations": [
62+
{
63+
"object": "collection0",
64+
"name": "bulkWrite",
65+
"arguments": {
66+
"requests": [
67+
{
68+
"deleteMany": {
69+
"filter": {
70+
"_id": {
71+
"$gt": 1
72+
}
73+
},
74+
"hint": "_id_"
75+
}
76+
}
77+
]
78+
},
79+
"expectError": {
80+
"isClientError": true
81+
}
82+
}
83+
],
84+
"expectEvents": [
85+
{
86+
"client": "client0",
87+
"events": []
88+
}
89+
]
90+
},
91+
{
92+
"description": "Unacknowledged deleteMany with hint document fails with client-side error on pre-4.4 server",
93+
"runOnRequirements": [
94+
{
95+
"maxServerVersion": "4.2.99"
96+
}
97+
],
98+
"operations": [
99+
{
100+
"object": "collection0",
101+
"name": "bulkWrite",
102+
"arguments": {
103+
"requests": [
104+
{
105+
"deleteMany": {
106+
"filter": {
107+
"_id": {
108+
"$gt": 1
109+
}
110+
},
111+
"hint": {
112+
"_id": 1
113+
}
114+
}
115+
}
116+
]
117+
},
118+
"expectError": {
119+
"isClientError": true
120+
}
121+
}
122+
],
123+
"expectEvents": [
124+
{
125+
"client": "client0",
126+
"events": []
127+
}
128+
]
129+
},
130+
{
131+
"description": "Unacknowledged deleteMany with hint string on 4.4+ server",
132+
"runOnRequirements": [
133+
{
134+
"minServerVersion": "4.4.0"
135+
}
136+
],
137+
"operations": [
138+
{
139+
"object": "collection0",
140+
"name": "bulkWrite",
141+
"arguments": {
142+
"requests": [
143+
{
144+
"deleteMany": {
145+
"filter": {
146+
"_id": {
147+
"$gt": 1
148+
}
149+
},
150+
"hint": "_id_"
151+
}
152+
}
153+
]
154+
},
155+
"expectResult": {
156+
"$$unsetOrMatches": {
157+
"acknowledged": {
158+
"$$unsetOrMatches": false
159+
}
160+
}
161+
}
162+
}
163+
],
164+
"expectEvents": [
165+
{
166+
"client": "client0",
167+
"events": [
168+
{
169+
"commandStartedEvent": {
170+
"command": {
171+
"delete": "coll0",
172+
"deletes": [
173+
{
174+
"q": {
175+
"_id": {
176+
"$gt": 1
177+
}
178+
},
179+
"hint": {
180+
"$$type": [
181+
"string",
182+
"object"
183+
]
184+
},
185+
"limit": 0
186+
}
187+
],
188+
"writeConcern": {
189+
"w": 0
190+
}
191+
}
192+
}
193+
}
194+
]
195+
}
196+
]
197+
},
198+
{
199+
"description": "Unacknowledged deleteMany with hint document on 4.4+ server",
200+
"runOnRequirements": [
201+
{
202+
"minServerVersion": "4.4.0"
203+
}
204+
],
205+
"operations": [
206+
{
207+
"object": "collection0",
208+
"name": "bulkWrite",
209+
"arguments": {
210+
"requests": [
211+
{
212+
"deleteMany": {
213+
"filter": {
214+
"_id": {
215+
"$gt": 1
216+
}
217+
},
218+
"hint": {
219+
"_id": 1
220+
}
221+
}
222+
}
223+
]
224+
},
225+
"expectResult": {
226+
"$$unsetOrMatches": {
227+
"acknowledged": {
228+
"$$unsetOrMatches": false
229+
}
230+
}
231+
}
232+
}
233+
],
234+
"expectEvents": [
235+
{
236+
"client": "client0",
237+
"events": [
238+
{
239+
"commandStartedEvent": {
240+
"command": {
241+
"delete": "coll0",
242+
"deletes": [
243+
{
244+
"q": {
245+
"_id": {
246+
"$gt": 1
247+
}
248+
},
249+
"hint": {
250+
"$$type": [
251+
"string",
252+
"object"
253+
]
254+
},
255+
"limit": 0
256+
}
257+
],
258+
"writeConcern": {
259+
"w": 0
260+
}
261+
}
262+
}
263+
}
264+
]
265+
}
266+
]
267+
}
268+
]
269+
}

0 commit comments

Comments
 (0)