[CDRIVER-4173] mongoc_collection_find_and_modify documentation is not fully correct Created: 04/Oct/21  Updated: 28/Oct/23  Resolved: 12/May/23

Status: Closed
Project: C Driver
Component/s: docs
Affects Version/s: None
Fix Version/s: 1.24.0

Type: Bug Priority: Minor - P4
Reporter: Fermín Galán Assignee: Kevin Albertson
Resolution: Fixed Votes: 0
Labels: documentation, neweng
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Quarter: FY24Q2

 Description   

From driver documentation for find_and_modify operation at http://mongoc.org/libmongoc/current/mongoc_collection_find_and_modify.html?highlight=find_and_modify:

"Returns either the document before or after modification based on the _new parameter."

However, as far as I checked what is returned (in the reply parameter) is not the document, but a kind of "wraper" with the document:

{
	"lastErrorObject": {
		"n": 1,
		"updatedExisting": true
	},
	"value": <here is the document>,
	"ok": 1.0
}

Not this is not the behaviour if we use findAndModify() in the MongoShell. Example:

> db.x.insert({x:1})
WriteResult({ "nInserted" : 1 })
> db.x.findAndModify({query: {x:1}, update: {$inc: {x:1}}, new: true })
{ "_id" : ObjectId("615acd3a3b41c7be44a3374e"), "x" : 2 }

I understand the driver documentation should explain this (thus, this issue is a kind of "documentation bug").



 Comments   
Comment by Githook User [ 12/May/23 ]

Author:

{'name': 'Kevin Albertson', 'email': 'kevin.albertson@mongodb.com', 'username': 'kevinAlbs'}

Message: CDRIVER-4173 clarify the `reply` contains the full server reply (#1263)

  • note that `reply` contains full server reply
  • fix documented return of `mongoc_collection_find_and_modify`
  • remove notes of MongoDB 3.2

The minimum supported server version of the C driver is 3.6. Documentation can assume user is using 3.6 or newer.

  • link to findAndModify command manual page
  • group "returns `false`" and "sets `error`"

Co-authored-by: vector-of-bool <vectorofbool@gmail.com>

  • Revert "remove notes of MongoDB 3.2"

This reverts commit 591ade57d4bd2f78c8d98d9e3e7729ae153f9ea2.

  • add replacement for findAndModify

---------

Co-authored-by: vector-of-bool <vectorofbool@gmail.com>
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/bddb24c0e4ab71e99e45350de41dabd19ce83537

Comment by Fermín Galán [ 10/May/23 ]

Done!

Comment by Kevin Albertson [ 09/May/23 ]

fermin.galanmarquez@telefonica.com that would be much appreciated. Here is the PR: https://github.com/mongodb/mongo-c-driver/pull/1263

Comment by Fermín Galán [ 09/May/23 ]

I have realized that the ticket has progressed to "code review" status.

Could you provide the link to the pull request with the modifications? I could have a look if you want an provide user-based feedback

Comment by Kevin Albertson [ 04/Oct/21 ]

Hi fermin.galanmarquez@telefonica.com, thank you for the report!

I agree that the driver documentation is incorrect. The reply document is the raw server reply from the findAndModify command. To see that in the MongoDB shell

> db.runCommand({findAndModify: "coll", query: {}, remove: true})
{
        "lastErrorObject" : {
                "n" : 0
        },
        "value" : null,
        "ok" : 1,
        "$clusterTime" : {
                "clusterTime" : Timestamp(1633378700, 1),
                "signature" : {
                        "hash" : BinData(0,"AAAAAAAAAAAAAAAAAAAAAAAAAAA="),
                        "keyId" : NumberLong(0)
                }
        },
        "operationTime" : Timestamp(1633378700, 1)
}

Generated at Wed Feb 07 21:20:09 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.