[CDRIVER-3546] Document that MONGOC_QUERY_EXHAUST does not apply to aggregate Created: 21/Feb/20  Updated: 28/Oct/23  Resolved: 02/Mar/20

Status: Closed
Project: C Driver
Component/s: docs
Affects Version/s: 1.16.1
Fix Version/s: 1.17.0-beta, 1.17.0

Type: Bug Priority: Major - P3
Reporter: Victor Stewart Assignee: Kevin Albertson
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

MongoDB server version: 4.2.2


Issue Links:
Related
related to DRIVERS-535 Support Exhaust Cursor in OP_MSG Closed

 Description   

Whenever I use MONGOC_QUERY_EXHAUST with mongoc_collection_aggregate I'm getting this error...

mongo_read_cursor(): 5.9,"unrecognized field 'exhaust'"



 Comments   
Comment by Githook User [ 02/Mar/20 ]

Author:

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

Message: CDRIVER-3546 clarify MONGOC_QUERY_EXHAUST

It only applies to find, not aggregate
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/01a646c548f45c35eb88beed0d919afe330aa197

Comment by Kevin Albertson [ 23/Feb/20 ]

Glad to help! And that's a good point, I'll update the docs to note to note MONGOC_QUERY_EXHAUST is not valid for aggregate.

Comment by Victor Stewart [ 23/Feb/20 ]

Really appreciate the comprehensive response. I assumed that this was the correct behavior, but just wanted to call public note to it as this is incongruent with the documentation as it implicitly suggests that all mongoc_query_flags_t values are valid for aggregate calls. I'd just suggest making a note of this exception in the documentation.

Comment by Kevin Albertson [ 22/Feb/20 ]

Hi vdog5@mac.com, exhaust cursors cannot be created for the "aggregate" command, only cursors created from "find".

I believe the error you are seeing is coming from the server. libmongoc's mongoc_collection_aggregate parses options documented here but sends extra options to the server as part of the "aggregate" command (for future-proofing).

I can't find short definitive documentation to prove that "aggregate" does not support exhaust cursors, but here is some relevant history in case you are curious. (TL;DR though
exhaust cursors only only supported on "find", there are future plans to support them for "aggregate").

The wire protocol for "find" differs a bit from "aggregate" and has changed throughout different MongoDB server releases.

In MongoDB pre 3.2, "find" was implemented with the OP_QUERY opcode. "aggregate" used the OP_QUERY opcode too, but as a command (i.e. though it used the OP_QUERY opcode, it used the special namespace "db.$cmd", and results were returned differently). "find" cursors respected the exhaust flag, but command cursors did not support it.

In MongoDB 3.2-3.4, "find" was implemented in terms of an OP_QUERY command. Drivers still supported exhaust cursors for "find", but would have to downgrade to the older protocol to support it. Our driver specification for the "find" command verifies this:

The "find" command does not support the exhaust flag from OP_QUERY. Drivers that support exhaust MUST fallback to existing OP_QUERY wire protocol messages.

In MongoDB 3.6, the server implemented a new unified opcode, OP_MSG. There are plans to support exhaust cursors in OP_MSG (for both "find" and "aggregate") in DRIVERS-535, but currently drivers still only support exhaust cursors on "find" via the legacy OP_QUERY protocol.

As an aside, since I was curious I tried it, if you attempt to set the exhaust flag on an OP_QUERY command, a 4.2 server returns "The 'exhaust' OP_QUERY flag is invalid for commands".

Best,
Kevin

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