diff --git a/source/crud/crud.md b/source/crud/crud.md index f28a07ed31..87d21ff053 100644 --- a/source/crud/crud.md +++ b/source/crud/crud.md @@ -820,6 +820,13 @@ database-level aggregation will allow users to receive a cursor from these colle ##### Insert, Update, Replace, Delete, and Bulk Writes +###### Generated identifiers + +The insert and bulk insert operations described below MUST generate identifiers for all documents that do not already +have them. These identifiers SHOULD be prepended to the document so they are the first field, in order to prevent the +server from spending time re-ordering the document. If a document already has a user-provided identifier, the driver MAY +re-order the document so the identifier is the first field. + ```typescript interface Collection { @@ -2481,6 +2488,8 @@ aforementioned allowance in the SemVer spec. - 2024-10-30: Document query limitations in `countDocuments`. +- 2024-10-28: Clarified that generated identifiers should be prepended to documents. + - 2024-10-01: Add sort option to `replaceOne` and `updateOne`. - 2024-09-12: Specify that explain helpers support maxTimeMS. diff --git a/source/crud/tests/README.md b/source/crud/tests/README.md index 1fd809b654..b169859c23 100644 --- a/source/crud/tests/README.md +++ b/source/crud/tests/README.md @@ -737,3 +737,15 @@ that `firstEvent.operationId` is equal to `secondEvent.operationId`. Assert both To force completion of the `w:0` writes, execute `coll.countDocuments` and expect the returned count is `maxMessageSizeBytes / maxBsonObjectSize + 1`. This is intended to avoid incomplete writes interfering with other tests that may use this collection. + +### 16. Generated document identifiers are the first field in their document + +Construct a `MongoClient` (referred to as `client`) with +[command monitoring](../../command-logging-and-monitoring/command-logging-and-monitoring.md) enabled to observe +CommandStartedEvents. For each of `insertOne`, client `bulkWrite`, and collection `bulkWrite`, do the following: + +- Execute the command with a document that does not contain an `_id` field. +- If possible, capture the wire protocol message (referred to as `request`) of the command and assert that the first + field of `request.documents[0]` is `_id`. +- Otherwise, capture the CommandStartedEvent (referred to as `event`) emitted by the command and assert that the first + field of `event.command.documents[0]` is `_id`.