DOCSP-20351 Add indexed matchComments field to query history (#222)

* DOCSP-20351 Add indexed matchComments field to query history

* DOCSP-20351 updates for review feedback

* DOCSP-20351 updates for copy review feedback

* DOCSP-20351 remove separate syntax for comment in match

* DOCSP-20351 updates for review feedback

* DOCSP-20351 updates to the tutorials page

* DOCSP-20351 changed field name to queryFilterComments

* DOCSP-20351 updates for feedback

Author: kanchana-mongodb

.gitignore

@@ -23,3 +23,4 @@ handouts/mongodb-logo-eps-converted-to.pdf
 source/figures/
 giza.log
 backups/*
+.vscode/

snooty.toml

@@ -3,7 +3,7 @@ title = "MongoDB Atlas Data Lake"
 
 intersphinx = ["https://docs.mongodb.com/manual/objects.inv","https://docs.atlas.mongodb.com/objects.inv","https://docs.mongodb.com/database-tools/objects.inv","https://docs.mongodb.com/mongodb-shell/objects.inv"]
 
-toc_landing_pages = ["/config/config-data-lake", "/tutorial/getting-started", "/admin/query-with-sql", "/query/query-data-lake", "/tutorial/connect", "/supported-unsupported/mql-support", "/tutorial/configure-connection", "/reference/api/datalakes-api", "/reference/cli/administration-commands", "/reference/pipeline/aggr-pipeline", "/tutorials" ]
+toc_landing_pages = ["/config/config-data-lake", "/tutorial/getting-started", "/admin/query-with-sql", "/query/query-data-lake", "/tutorial/connect", "/supported-unsupported/mql-support", "/tutorial/configure-connection", "/tutorials"]
 
 [constants]
 adl = "Atlas Data Lake"

source/query/view-query-history.txt

@@ -20,7 +20,10 @@ query, that contain information about the :manual:`aggregate
 </reference/command/aggregate>`, :manual:`find 
 </reference/command/find/>`, and :manual:`count 
 </reference/command/count/>` queries that were run in the past 24 
-hours. To run |qh|, use the :manual:`db.aggregate 
+hours. You can filter on the fields returned by |qh| in subsequent 
+pipeline stages such as :pipeline:`$match`.
+
+To run |qh|, use the :manual:`db.aggregate 
 </reference/method/db.aggregate/#db.aggregate>` helper. |qh| must be 
 run against the ``admin`` database.
 
@@ -78,7 +81,7 @@ fields:
 
 .. list-table::
    :header-rows: 1
-   :widths: 10 10 80 
+   :widths: 10 15 75 
 
    * - Field 
      - Type 
@@ -122,6 +125,12 @@ fields:
      - Error, if any, returned by the query. Note that the query status 
        ``0`` indicates errors. Empty string if query ran successfully. 
 
+   * - ``queryFilterComments``
+     - array of strings
+     - Comment strings included with the ``$comment`` operator inside 
+       the query pipeline. Omitted if the query didn't include the 
+       ``$comment`` operator.
+
    * - ``ok``
      - int 
      - Status of the query. Value can be one of the following: 
@@ -154,8 +163,14 @@ fields:
 
 .. _adl-query-history-stage-egs:
 
-Example 
--------
+Examples 
+--------
+
+The examples below use the ``Database0.Collection0`` collection 
+described in the :ref:`Get Started tutorial <adl-tutorials>`.
+
+Retrieve Details About the Queries 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For the example below, suppose some of the queries described in the 
 :ref:`Getting Started tutorial <gst-run-queries>` were run by ``user1`` 
@@ -304,3 +319,76 @@ following example returns information on the queries that were run by
 	   "ok" : 1,
 	   "background" : true
    }
+
+Filter |qh| Output for Specific Queries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For the example below, suppose a query similar to the following is  
+run against the ``Database0.Collection0`` collection described in the 
+:ref:`Getting Started tutorial <adl-tutorials>`. The query includes 
+unique strings to help identify the query in the results returned by 
+the |qh| stage. You can attach a comment to a query using the 
+:manual:`aggregate </reference/command/aggregate/>` command ``comment`` 
+option or the :manual:`$comment </reference/operator/query/comment/>` 
+operator. This example uses both ways to attach the unique strings with 
+the query.
+
+.. code-block:: shell 
+
+   use Database0
+   db.Collection0.aggregate([ { $match: {"account_id": 557378, "$comment": "test"}},{$sort: {"transactions.symbol": -1}} ],{"comment":"exampleQuery"})
+
+.. tabs:: 
+
+   .. tab:: comment Option Example
+      :tabid: option
+
+      To retrieve the query history using the string value of the 
+      ``comment`` option of the :manual:`aggregate 
+      </reference/command/aggregate/>` command, run the following 
+      commands against the ``admin`` database:
+
+      .. code-block:: json
+
+         use admin 
+         db.aggregate([{$queryHistory: {}}, {$match: {"comment": "exampleQuery"}} ]) 
+
+   .. tab:: $comment Operator Example
+      :tabid: operator
+
+      To retrieve the query history using the string value of the 
+      ``$comment`` operator in the :pipeline:`$match` query, run the 
+      following commands against the ``admin`` database.
+
+      .. code-block:: json
+
+         use admin 
+         db.aggregate([{$queryHistory: {}}, {$match: {queryFilterComments: "test"}}]) 
+
+|qh| finds the query that included the specified string and returns 
+results similar to the following: 
+
+.. code-block:: json
+   :copyable: false
+
+   [
+     {
+       "_id": ObjectId("61e1e4c29e62172566d8e9b6"),
+       "query": [
+         { "$match": { "account_id": 557378, "$comment": "test" } },
+         { "$sort": { "transactions.symbol": -1 } }
+       ],
+       "comment": "exampleQuery",
+       "appName": "mongosh 1.1.8",
+       "user": "admin.user1",
+       "db": "Database0",
+       "collection": "Collection0",
+       "opid": ObjectId("16ca3ed2577016e68d60358c"),
+       "startTime": ISODate("2022-01-14T21:01:27.346Z"),
+       "endTime": ISODate("2022-01-14T21:01:54.627Z"),
+       "ok": 1,
+       "error": "",
+       "background": false,
+       "queryFilterComments": [ "test" ]
+     }
+   ]

source/tutorials.txt

@@ -14,9 +14,9 @@ following actions:
 
 - `Get MongoDB Data Into Parquet 
   <https://www.mongodb.com/developer/how-to/mongodb-data-parquet/>`__ - 
-  This tutorial shows you how to use {+adl+} to get data from your 
-  |service| Cluster or |s3| Bucket in to Apache Parquet, which provides 
-  high performance querying capability on cloud object storage.
+  This tutorial shows you how to use {+adl+} to get data in any format 
+  from your |service| Cluster or |s3| Bucket in to Apache Parquet, 
+  which allows you to query data in the cloud very fast.
 
 - `Query From Multiple MongoDB Databases <https://www.mongodb.com/developer/how-to/query-multiple-databases-with-atlas-data-lake/>`__ - 
   This tutorial shows you how to use {+adl+} to query data across 
@@ -30,4 +30,4 @@ following actions:
 - `Copy Data Automatically From MongoDB to an AWS S3 Bucket <https://www.mongodb.com/developer/how-to/automated-continuous-data-copying-from-mongodb-to-s3/>`__ - 
   This tutorial shows you how to use |service| :atlas:`triggers 
   </triggers/>` and {+adl+} to write data from your |service| Cluster 
-  to your |aws| |s3| bucket on an automated schedule.
+  to your |aws| |s3| bucket continuously on a schedule.