[DOCS-5986] Remove documentation of shell's wrapped query format, including $-prefixed query options and _addSpecial() Created: 06/Aug/15  Updated: 30/Oct/23  Resolved: 21/Jul/16

Status: Closed
Project: Documentation
Component/s: Server
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Task Priority: Major - P3
Reporter: David Storch Assignee: Kay Kim (Inactive)
Resolution: Done Votes: 0
Labels: docs-3.2
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Documented
Related
related to DOCS-8343 $comment is not well documented Closed
related to DOCS-5987 Doc the find and getMore commands Closed
Participants:
Days since reply: 7 years, 30 weeks ago

 Description   

Wrapped query form

As part of the find and getMore commands project (see SERVER-15176), a version 3.2 shell will no longer accept a query predicate in "wrapped form". In contrast, a 3.0 shell will accept the query predicate {a: {$gt: 3}} in the following three forms:

db.coll.find({a: {$gt: 3}})
db.coll.find({query: {a: {$gt: 3}}})
db.coll.find({$query: {a: {$gt: 3}}})

A 3.2 shell will not accept the second two of this queries, which are in wrapped form. In particular, the second query means to look for documents where the "query" field contains the literal subobject "{a: {$gt: 3}}}", and the third query will be rejected due to an unknown top-level query operator "$query".

$-prefixed options

The wrapped query form used to offer a way to pass $-prefixed like query options, such as $snapshot:

db.coll.find({$query: {a: {$gt: 3}}, $snapshot: true});

This is no longer valid shell syntax. Instead, options like snapshot must be set using the appropriate shell helper:

db.coll.find({a: {$gt: 3}}).snapshot();

_addSpecial()

The shell offers a method called _addSpecial() that could be used to add $-prefixed options like $snapshot to the query:

db.coll.find({a: {$gt: 3}})._addSpecial("$snapshot", true)

Although this technically will still work for the time being, _addSpecial() is now a private shell helper and should no longer be documented. Again, this query should use the .snapshot() helper.

Action to take

All documentation of the wrapped query form, including the $-prefixed query options and _addSpecial() should be removed in the 3.2 manual. This affects (at least) the following pages:

Notably, this does not apply to $natural. Documentation of $natural should still be accurate, as this is part of the sort or hint specification, and therefore not a top-level query option.

There should be equivalent shell helpers for each of these $-options; we need to do an audit making sure that the shell helpers for each option are adequately documented.



 Comments   
Comment by Kay Kim (Inactive) [ 21/Jul/16 ]

put back the content in the pages and clarified the deprecation is only on the mongo shell side.

Comment by Githook User [ 15/Jul/16 ]

Author:

{u'username': u'kay-kim', u'name': u'kay', u'email': u'kay.kim@10gen.com'}

Message: Revert "DOCS-5986 : Remove documentation of $query and $<options>"

This reverts commit 1ac9aeb82724c4c4db8a392124f5d51063317b9a.
Branch: master
https://github.com/mongodb/docs/commit/06edad2c13964e367607a3700abbadb7635ac973

Comment by Ravind Kumar (Inactive) [ 20/Nov/15 ]

https://github.com/mongodb/docs/pull/2418

Comment by Githook User [ 19/Nov/15 ]

Author:

{u'username': u'rkumar-mongo', u'name': u'ravind', u'email': u'ravind.kumar@10gen.com'}

Message: DOCS-5986 : Remove documentation of $query and $<options>

Round 2: CR changes

Round 1:

  • Added 'deprecated' warnings to $<options>
  • Removed cursor.addOption(), added deprecation warning

Signed-off-by: kay <kay.kim@10gen.com>
Branch: master
https://github.com/mongodb/docs/commit/1ac9aeb82724c4c4db8a392124f5d51063317b9a

Comment by David Storch [ 23/Oct/15 ]

We should also consider removing documentation of the .addOption() helper: https://docs.mongodb.org/manual/reference/method/cursor.addOption/. The integer codes accepted by this helper are specific to OP_QUERY find and are not used in find command. The "modern" way to, say, specify a noTimeout cursor is:

db.coll.find().noCursorTimeout();

We will have to make sure that we have added documentation for all of the new shell helpers. I would be happy to help audit the contents of https://docs.mongodb.org/manual/reference/method/js-cursor/ as we prepare the docs for 3.2.

Generated at Thu Feb 08 07:51:24 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.