DOCSP-13421 document background: true aggregation option (#99)

* DOCSP-13421 document background: true aggregation option

* DOCSP-13421 updates for review feedback

* DOCSP-13421 updates for feedback

Author: kanchana-mongodb

source/reference/pipeline/out.txt

@@ -18,13 +18,13 @@
 
 |out| takes documents returned by the aggregation pipeline and writes
 them to a specified collection. The |out| operator must be the last
-stage in the
-:manual:`aggregation pipeline </reference/operator/aggregation-pipeline/>`.
-In {+adl+}, you can use |out| to write data from any one of the 
-:ref:`supported <datalake-configuration-file-overview>` {+data-lake-stores+} 
-or multiple :ref:`supported <datalake-configuration-file-overview>` 
-{+data-lake-stores+} when using :ref:`federated queries <federated-queries>` 
-to any one of the following: 
+stage in the :manual:`aggregation pipeline 
+</reference/operator/aggregation-pipeline/>`. In {+adl+}, you can use 
+|out| to write data from any one of the :ref:`supported 
+<datalake-configuration-file-overview>` {+data-lake-stores+} or 
+multiple :ref:`supported <datalake-configuration-file-overview>` 
+{+data-lake-stores+} when using :ref:`federated queries 
+<federated-queries>` to any one of the following: 
 
 - |s3| buckets with read and write permissions
 - |service| cluster :manual:`namespace 
@@ -302,6 +302,40 @@ Fields
              the ID of the project that contains your {+dl+}.
            - Optional
 
+.. _adl-out-stage-options:
+
+Options 
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 10 60 10
+
+   * - Option
+     - Type
+     - Description 
+     - Necessity
+
+   * - ``background``
+     - boolean
+     - For |out| to |s3| only.
+     
+       Flag to run aggregation operations in the background. If 
+       omitted, defaults to ``false``. When set to ``true``, {+adl+} 
+       runs the queries in the background. 
+
+       .. code-block:: json 
+          :copyable: false 
+
+          { "background" : true }
+       
+       Use this option if you want to submit other new queries without 
+       waiting for currently running queries to complete or disconnect 
+       your {+dl+} connection while the queries continue to run in the 
+       background. 
+     
+     - Optional
+
 .. _adl-out-stage-egs:
 
 Examples
@@ -313,12 +347,14 @@ Examples
    .. tab:: S3
       :tabid: s3
 
+      **Create a Filename**
+
       The following examples show |out| syntaxes for dynamically
       creating a filename from a constant string or from the fields of
       the same or different data types in the documents that reach the
       |out| stage.
 
-      **Simple String Example**
+      *Simple String Example*
 
       .. example::
 
@@ -373,7 +409,7 @@ Examples
             ``big_box_store/3.bson.gz`` through
             ``big_box_store/5.bson.gz``.
 
-      **Single Field from Documents**
+      *Single Field from Documents*
 
       .. example::
 
@@ -405,7 +441,7 @@ Examples
          documents' ``sale-date`` value converted to a string.
 
 
-      **Multiple Fields from Documents**
+      *Multiple Fields from Documents*
 
       .. example::
 
@@ -452,7 +488,7 @@ Examples
          the documents' ``name`` and ``unique-id`` values.
 
 
-      **Multiple Types of Fields from Documents**
+      *Multiple Types of Fields from Documents*
 
       .. example::
 
@@ -490,9 +526,9 @@ Examples
             }
 
          |out| writes 154 MiB of data to compressed |json| files, where
-         each file contains all documents with the same ``store-number``,
-         ``sale-date``, and ``part-id`` values.  To name each file, |out|
-         concatenates:
+         each file contains all documents with the same 
+         ``store-number``, ``sale-date``, and ``part-id`` values.  To 
+         name each file, |out| concatenates:
 
          - A constant string value of ``big-box-store/``,
          - A string value of a unique store number in the
@@ -503,6 +539,37 @@ Examples
          - A string value of part ID from the ``part-id`` field, and 
          - A forward slash (``/``).
 
+      **Run Query in the background**
+
+      The following example shows |out| syntax for running an 
+      aggregation pipeline that ends with the |out| stage in the 
+      background.
+
+      .. code-block:: json 
+         :emphasize-lines: 16
+
+         db.foo.aggregate([
+           {
+             "$out" : {
+               "s3" : {
+                 "bucket" : "my-s3-bucket",
+                 "region" : "us-east-1",
+                 "filename" : {
+                   "$toString" : "$sale-date"
+                 },
+                 "format" : {
+                   "name" : "json"
+                 }
+               }
+             }
+           }
+         ], { background: true })
+
+         |out| writes to |json| files in the root of the bucket in the 
+         background. Each |json| file contains all of the documents 
+         with the same ``sale-date`` value. |out| names each file using 
+         the documents' ``sale-date`` value converted to a string. 
+
    .. tab:: Atlas Cluster
       :tabid: atlas
 
@@ -598,6 +665,7 @@ Examples
 
 .. seealso::
 
-   - :manual:`$out Aggregation Stage Reference </reference/operator/aggregation/out>` 
+   - :manual:`$out Aggregation Stage Reference 
+     </reference/operator/aggregation/out>` 
    - `Tutorial: Federated Queries and $out to S3 
      <https://developer.mongodb.com/how-to/atlas-data-lake-federated-queries-out-aws-s3>`__

source/supported-unsupported/mql-support.txt

@@ -41,24 +41,32 @@ Aggregation Commands
 
      - The following limitations apply:
 
-       * {+adl+} supports only the ``explain``, ``cursor``, and ``comment`` 
-         options. For the ``comment`` option, {+adl+} supports only type 
-         ``string``.
-       * {+adl+} supports :pipeline:`$geoNear` and :pipeline:`$graphLookup`   
-         :manual:`aggregation pipeline stages
-         </reference/operator/aggregation-pipeline>` in queries on {+dl+} 
-         collections that are mapped to one |service| collection only. 
-         {+adl+} doesn't support these :manual:`aggregation pipeline 
-         stages </reference/operator/aggregation-pipeline>` for:
+       * {+adl+} supports the ``explain``, ``cursor``, ``comment``, 
+         and ``background`` options only. For the ``comment`` option, 
+         {+adl+} supports only type ``string``. {+adl+} supports 
+         ``{"background" : <boolean>}`` option for 
+         :ref:`adl-out-stage` to |s3| only. The ``background`` option 
+         is not available for other :manual:`aggregation pipeline 
+         stages </reference/operator/aggregation-pipeline>`. See 
+         :ref:`$out Options <adl-out-stage-options>` for more 
+         information.
+       * {+adl+} supports :pipeline:`$geoNear` and 
+         :pipeline:`$graphLookup` :manual:`aggregation pipeline stages 
+         </reference/operator/aggregation-pipeline>` in queries on 
+         {+dl+} collections that are mapped to one |service| collection 
+         only. {+adl+} doesn't support these :manual:`aggregation 
+         pipeline stages </reference/operator/aggregation-pipeline>` 
+         for:
 
          - |s3| or |http| {+data-lake-stores+}.
-         - Queries on {+dl+} collections that are mapped to multiple |service| 
-           collections. 
+         - Queries on {+dl+} collections that are mapped to multiple 
+           |service| collections. 
 
          See :ref:`query-atlas` for more information.
        * {+adl+} Doesn't support the ``$collStats``, ``$indexStats``, 
-         ``$listLocalSessions``, and ``$listSessions`` :manual:`aggregation 
-         pipeline stages </reference/operator/aggregation-pipeline>`.
+         ``$listLocalSessions``, and ``$listSessions`` 
+         :manual:`aggregation pipeline stages 
+         </reference/operator/aggregation-pipeline>`.
 
    * - :manual:`count </reference/command/count>`