DOCS-12090: add restrictions for countDocuments

Author: kay-kim

source/includes/table-transactions-operations.rst

@@ -20,8 +20,15 @@
    * - :method:`db.collection.countDocuments()` 
      -
 
-     - Uses the :pipeline:`$group` aggregation stage with a
-       :group:`$sum` expression to perform a count.
+     - Excluding the following query operator expressions:
+     
+       - :query:`$where`
+       - :query:`$near`
+       - :query:`$nearSphere`
+
+       The method uses the :pipeline:`$match` aggregation stage for the
+       query and :pipeline:`$group` aggregation stage with a
+       :group:`$sum` expression to perform the count.
 
    * - :method:`db.collection.distinct()`
      - :dbcommand:`distinct`

source/reference/method/db.collection.countDocuments.txt

@@ -38,7 +38,7 @@ Definition
         - document
 
         - The query selection criteria. To count all documents, specify
-          an empty document.
+          an empty document. See also :ref:`countDocuments-restrictions`.
 
       * - options
         - document
@@ -74,6 +74,9 @@ Definition
 Behavior
 --------
 
+Mechanics
+~~~~~~~~~
+
 Unlike :method:`db.collection.count()`,
 :method:`db.collection.countDocuments()` does not use the metadata to
 return the count. Instead, it performs an aggregation of the document
@@ -94,6 +97,52 @@ aggregation operation and returns just the value of ``n``:
 :method:`db.collection.countDocuments()` errors on an empty or
 non-existing collection or view.
 
+.. _countDocuments-restrictions:
+
+Query Restrictions
+~~~~~~~~~~~~~~~~~~
+
+You cannot use the following query operators as part of the query
+expression for :method:`db.collection.countDocuments()`:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Restricted Operator
+     - Alternative
+
+   * - :query:`$where`
+
+     - As an alternative, use :query:`$expr` instead.
+
+   * - :query:`$near`
+
+     - As an alternative, use :query:`$geoWithin` with :query:`$center`; i.e.
+
+       .. code-block:: javascript
+          :copyable: false
+
+          { $geoWithin: { $center: [ [ <x>, <y> ], <radius> ] } }
+
+   * - :query:`$nearSphere`
+
+     - As an alternative, use :query:`$geoWithin` with :query:`$centerSphere`; i.e.
+
+       .. code-block:: javascript
+          :copyable: false
+
+          { $geoWithin: { $centerSphere: [ [ <x>, <y> ], <radius> ] } }
+
+Transactions
+~~~~~~~~~~~~
+
+.. include:: /includes/extracts/transactions-supported-operation.rst
+
+.. include:: /includes/extracts/transactions-usage.rst
+
+.. |operation| replace:: :method:`db.collection.countDocuments()`
+
 Examples
 --------
 

source/reference/operator/aggregation/match.txt

@@ -49,11 +49,21 @@ Restrictions
 ~~~~~~~~~~~~
 
 - You cannot use :query:`$where` in :pipeline:`$match` queries as part
-  of the aggregation pipeline.
+  of the aggregation pipeline. As an alternative, use :query:`$eval`
+  operator instead.
+
+- You cannot use :query:`$near` or :query:`$nearSphere` in
+  :pipeline:`$match` queries as part of the aggregation pipeline. As an
+  alternative, you can either:
+
+  - Use :pipeline:`$geoNear` stage instead of the :pipeline:`$match` stage.
+
+  - Use :query:`$geoWithin` query operator with :query:`$center` or
+    :query:`$centerSphere` in the :pipeline:`$match` stage.
 
 - To use :query:`$text` in the :pipeline:`$match` stage, the
   :pipeline:`$match` stage has to be the first stage of the pipeline.
- 
+
   .. include:: /includes/extracts/views-unsupported-text-search.rst
 
 Examples