DOCS-9120: emphasize BSON limit on distinct, propose agg alternative

Author: schmalliso

source/includes/note-distinct-bson-limit-agg-alternative.rst

@@ -0,0 +1,8 @@
+.. note::
+
+   Results must not be larger than the maximum :ref:`BSON size
+   <limit-bson-document-size>`. If your results exceed the maximum
+   BSON size, use the aggregation pipeline to retrieve distinct
+   values using the :pipeline:`$group` operator, as described in
+   :ref:`Retrieve Distinct Values with the Aggregation Pipeline
+   <aggregation-group-distinct-values>`.

source/includes/table-sql-to-mongo-select-examples.yaml

@@ -343,6 +343,13 @@ sql19: |
           SELECT DISTINCT(status)
           FROM people
 mongo19: |
+         .. code-block:: javascript
+            :emphasize-lines: 1
+
+            db.people.aggregate( [ { $group : { _id : "$status" } } ] )
+         
+         or, for distinct value sets that do not exceed the :ref:`BSON size limit <limit-bson-document-size>`
+
          .. code-block:: javascript
             :emphasize-lines: 1
 

source/reference/command/distinct.txt

@@ -36,9 +36,11 @@ Definition
 
    .. include:: /includes/apiargs/dbcommand-distinct-field.rst
 
+   .. include:: /includes/note-distinct-bson-limit-agg-alternative.rst
+
    MongoDB also provides the shell wrapper method
    :method:`db.collection.distinct()` for the :dbcommand:`distinct`
-   command. Additionally, many MongoDB :term:`drivers <driver>` also
+   command. Additionally, many MongoDB :term:`drivers <driver>`
    provide a wrapper method. Refer to the specific driver documentation.
 
 Behavior

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

@@ -22,8 +22,9 @@ Definition
    .. include:: /includes/apiargs/method-db.collection.distinct-param.rst
 
    The :method:`db.collection.distinct()` method provides a wrapper
-   around the :dbcommand:`distinct` command. Results must not be larger
-   than the maximum :ref:`BSON size <limit-bson-document-size>`.
+   around the :dbcommand:`distinct` command.
+
+   .. include:: /includes/note-distinct-bson-limit-agg-alternative.rst
 
 .. _distinct-method-options: