Uploaded image for project: 'Documentation'
  1. Documentation
  2. DOCS-5986

Remove documentation of shell's wrapped query format, including $-prefixed query options and _addSpecial()

    Details

    • Type: Task
    • Status: Closed
    • Priority: Major - P3
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Server
    • Labels:
    • # Replies:
      5
    • Last comment by Customer:
      true
    • Sprint:
      Docs Sprint 2016(0711-0729)

      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.

        Attachments

          Issue Links

            Activity

              People

              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Days since reply:
                  1 year, 17 weeks, 2 days ago
                  Date of 1st Reply: