From 2955d19e2429ffd026a622ac96371e3cc2177f1f Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 28 Oct 2024 12:00:01 -0400 Subject: [PATCH 1/4] DRIVERS-1408 - Add guidance on adding _id fields to documents to CRUD spec --- source/crud/crud.md | 8 ++++++++ source/crud/tests/README.md | 7 +++++++ 2 files changed, 15 insertions(+) diff --git a/source/crud/crud.md b/source/crud/crud.md index cce5aede63..8d77222c42 100644 --- a/source/crud/crud.md +++ b/source/crud/crud.md @@ -815,6 +815,12 @@ 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. + ```typescript interface Collection { @@ -2474,6 +2480,8 @@ aforementioned allowance in the SemVer spec. ## Changelog +- 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..38d07f960b 100644 --- a/source/crud/tests/README.md +++ b/source/crud/tests/README.md @@ -737,3 +737,10 @@ 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. Perform an `insert` command using `client` and assert that one CommandStartedEvent (referred to as +`event`) was observed, and that the first field of `event.command.documents[0]` is `_id`. From 1afe0c023deb2f7729121d6b2229d962f22a3048 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 28 Oct 2024 16:16:46 -0400 Subject: [PATCH 2/4] Update prose test --- source/crud/tests/README.md | 9 +++++++-- source/transactions/transactions.md | 1 - 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/source/crud/tests/README.md b/source/crud/tests/README.md index 38d07f960b..fe09beb163 100644 --- a/source/crud/tests/README.md +++ b/source/crud/tests/README.md @@ -742,5 +742,10 @@ that may use this collection. Construct a `MongoClient` (referred to as `client`) with [command monitoring](../../command-logging-and-monitoring/command-logging-and-monitoring.md) enabled to observe -CommandStartedEvents. Perform an `insert` command using `client` and assert that one CommandStartedEvent (referred to as -`event`) was observed, and that the first field of `event.command.documents[0]` is `_id`. +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. +- Assert that the first field of `request.documents[0]` is `_id` +- Otherwise, capture the CommandStartedEvent (referred to as `event`) emitted by the command. +- Assert that the first field of `event.command.documents[0]` is `_id`. diff --git a/source/transactions/transactions.md b/source/transactions/transactions.md index 979b7eb4e4..42bf7a30f3 100644 --- a/source/transactions/transactions.md +++ b/source/transactions/transactions.md @@ -1072,7 +1072,6 @@ objective of avoiding duplicate commits. ## **Changelog** - - 2024-10-28: Clarify when drivers must add TransientTransactionError label. - 2024-10-28: Note read preference must always be primary in a transaction. From 48ce014aceb95e0568d02f19b032d5863e7723ef Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 30 Oct 2024 09:34:53 -0400 Subject: [PATCH 3/4] Clarify user-supplied ID fields --- source/crud/crud.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/crud/crud.md b/source/crud/crud.md index 8d77222c42..b063d40e6d 100644 --- a/source/crud/crud.md +++ b/source/crud/crud.md @@ -819,7 +819,8 @@ database-level aggregation will allow users to receive a cursor from these colle 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. +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 { From e57594a5e06ca72d7194ecd2bdf9a1c2774d3e36 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Thu, 31 Oct 2024 11:52:21 -0400 Subject: [PATCH 4/4] Update source/crud/tests/README.md Co-authored-by: Jeremy Mikola --- source/crud/tests/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/crud/tests/README.md b/source/crud/tests/README.md index fe09beb163..b169859c23 100644 --- a/source/crud/tests/README.md +++ b/source/crud/tests/README.md @@ -745,7 +745,7 @@ Construct a `MongoClient` (referred to as `client`) with 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. -- Assert that the first field of `request.documents[0]` is `_id` -- Otherwise, capture the CommandStartedEvent (referred to as `event`) emitted by the command. -- Assert that the first field of `event.command.documents[0]` is `_id`. +- 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`.