Skip to content

Commit 60ad3c3

Browse files
kanchana-mongodbkanchana-mongodb
authored
DOCSP-13633 document queryHistory aggregation stage (#105)
* DOCSP-13633 document queryHistory aggregation stage * DOCSP-13633 updates for feedback
1 parent b1a5ab2 commit 60ad3c3

File tree

4 files changed

+244
-4
lines changed

4 files changed

+244
-4
lines changed

‎source/query/query-data-lake.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -356,3 +356,4 @@ results.
356356
/admin/optimize-query-performance
357357
/admin/determine-query-status
358358
/admin/terminate-running-query
359+
/query/view-query-history

‎source/query/view-query-history.txt‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
.. _adl-query-history-stage:
2+
3+
================================
4+
Retrieve Data Lake Query History
5+
================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
.. |qh| replace:: ``$queryHistory``
16+
17+
You can retrieve details about the queries that were run in the
18+
past 24 hours using |qh| (aggregation). |qh| returns documents, one per
19+
query, that contain information about the :manual:`aggregate
20+
</reference/command/aggregate>`, :manual:`find
21+
</reference/command/find/>`, and :manual:`count
22+
</reference/command/count/>` queries that were run in the past 24
23+
hours. To run |qh|, use the :manual:`db.aggregate
24+
</reference/method/db.aggregate/#db.aggregate>` helper. |qh| must be
25+
run against the ``admin`` database.
26+
27+
.. _adl-query-history-stage-syntax:
28+
29+
Syntax
30+
------
31+
32+
.. code-block:: json
33+
34+
{
35+
$queryHistory: {
36+
allUsers: <boolean>
37+
}
38+
}
39+
40+
.. _adl-query-history-stage-fields:
41+
42+
Fields
43+
------
44+
45+
.. list-table::
46+
:header-rows: 1
47+
:widths: 10 10 70 10
48+
49+
* - Field
50+
- Type
51+
- Description
52+
- Necessity
53+
54+
* - ``allUsers``
55+
- boolean
56+
- Indicates whether or not to fetch documents for queries run by
57+
all users. Valid values are:
58+
59+
- ``true`` to fetch documents for queries run by all users
60+
- ``false`` to fetch documents for queries run by the current
61+
user only
62+
63+
You must have the ``viewAllHistory`` privilege on the cluster
64+
resource to use this option. If you specify this option, but do
65+
not have ``viewAllHistory`` privilege on the cluster resource,
66+
{+dl+} returns an error.
67+
68+
If omitted, defaults to ``false``.
69+
- Optional
70+
71+
.. _adl-query-history-stage-output:
72+
73+
Output
74+
------
75+
76+
Each document returned by ``$queryHistory`` contains the following
77+
fields:
78+
79+
.. list-table::
80+
:header-rows: 1
81+
:widths: 10 10 80
82+
83+
* - Field
84+
- Type
85+
- Description
86+
87+
* - ``appName``
88+
- string
89+
- Name of the application that issued the query, if available.
90+
91+
* - ``collection``
92+
- string
93+
- Name of the collection on which the the query was executed.
94+
95+
* - ``comment``
96+
- string
97+
- Comment associated with the query, if available. Empty if the
98+
query did not include any comment.
99+
100+
* - ``db``
101+
- string
102+
- Name of the database that contains the collection on which the
103+
query was executed.
104+
105+
* - ``endTime``
106+
- :manual:`ISODate </reference/glossary/#term-isodate>`
107+
- Query completion time.
108+
109+
* - ``error``
110+
- string
111+
- Error, if any, returned by the query. Note that the query status
112+
``0`` indicates errors. Empty string if query ran successfully.
113+
114+
* - ``ok``
115+
- int
116+
- Status of the query. Value can be one of the following:
117+
118+
- ``1``, if query ran successfully
119+
- ``0``, if there were errors when executing the query
120+
121+
* - ``opid``
122+
- :manual:`ObjectId </reference/bson-types/#objectid>`
123+
- Unique identifier of the operation associated with the query.
124+
125+
* - ``startTime``
126+
- :manual:`ISODate </reference/glossary/#term-isodate>`
127+
- Query start time.
128+
129+
* - ``query``
130+
- document
131+
- Query operation that was run.
132+
133+
* - ``user``
134+
- string
135+
- Username of the user who ran the query, if available, in the
136+
following format: ``<authenticationDatabase>.<username>``. Note
137+
that the authentication database for {+adl+} is always
138+
``admin``. If the username of the user who ran the query is not
139+
available, value is empty.
140+
141+
.. _adl-query-history-stage-egs:
142+
143+
Example
144+
-------
145+
146+
For the example below, suppose some of the queries described in the
147+
:doc:`Getting Started tutorial
148+
</tutorial/configure-database-collections/>` were run by ``user1`` on
149+
the ``airbnb`` collection in the ``sample`` database. The following
150+
example returns information on the queries that were run by ``user1``
151+
on the ``airbnb`` collection in the ``sample`` database.
152+
153+
154+
.. code-block:: shell
155+
156+
db.aggregate([{$queryHistory: {}}]).pretty()
157+
158+
|qh| returns one document for each query that was ran on the ``airbnb``
159+
collection in the ``sample`` database.
160+
161+
.. code-block:: json
162+
:copyable: false
163+
164+
{
165+
"_id" : ObjectId("5fdb680f6006e874ad4703fe"),
166+
"query" : {
167+
"0" : {
168+
"$match" : {
169+
"address.market" : "Porto",
170+
"review_scores.review_scores_rating" : {
171+
"$gt" : 79
172+
}
173+
}
174+
}
175+
},
176+
"comment" : "",
177+
"appName" : "MongoDB Shell",
178+
"user" : "admin.user1",
179+
"db" : "sample",
180+
"collection" : "airbnb",
181+
"opid" : ObjectId("16518699ce8f505f3639344a"),
182+
"startTime" : ISODate("2020-12-17T14:15:37.110Z"),
183+
"endTime" : ISODate("2020-12-17T14:15:43.255Z"),
184+
"ok" : 1,
185+
"error" : ""
186+
}
187+
{
188+
"_id" : ObjectId("5fdb681a6006e874ad470403"),
189+
"query" : {
190+
"0" : {
191+
"$match" : {
192+
"address.market" : "New York",
193+
"price" : {
194+
"$lt" : NumberDecimal("200.00")
195+
}
196+
}
197+
},
198+
"1" : {
199+
"$sort" : {
200+
"review_scores_rating" : -1
201+
}
202+
}
203+
},
204+
"comment" : "",
205+
"appName" : "MongoDB Shell",
206+
"user" : "admin.user1",
207+
"db" : "sample",
208+
"collection" : "airbnb",
209+
"opid" : ObjectId("1651869c3b73f63f3639344c"),
210+
"startTime" : ISODate("2020-12-17T14:15:47.527Z"),
211+
"endTime" : ISODate("2020-12-17T14:15:54.021Z"),
212+
"ok" : 1,
213+
"error" : ""
214+
}
215+
{
216+
"_id" : ObjectId("5fdb68276006e874ad47040d"),
217+
"query" : {
218+
"0" : {
219+
"$match" : {
220+
"address.market" : "Barcelona",
221+
"property_type" : "Apartment"
222+
}
223+
},
224+
"1" : {
225+
"$count" : "numApartments"
226+
}
227+
},
228+
"comment" : "",
229+
"appName" : "MongoDB Shell",
230+
"user" : "admin.user1",
231+
"db" : "sample",
232+
"collection" : "airbnb",
233+
"opid" : ObjectId("165186a0409f560a36393457"),
234+
"startTime" : ISODate("2020-12-17T14:16:04.794Z"),
235+
"endTime" : ISODate("2020-12-17T14:16:07.545Z"),
236+
"ok" : 1,
237+
"error" : ""
238+
}

‎source/reference/pipeline/aggr-pipeline.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,5 @@ introduces for the following :manual:`pipeline
2424
/reference/pipeline/collstats
2525
/reference/pipeline/lookup-stage
2626
/reference/pipeline/out
27+
$queryHistory </query/view-query-history/>
2728
/reference/pipeline/sql

‎source/reference/pipeline/out.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -565,10 +565,10 @@ Examples
565565
}
566566
], { background: true })
567567

568-
|out| writes to |json| files in the root of the bucket in the
569-
background. Each |json| file contains all of the documents
570-
with the same ``sale-date`` value. |out| names each file using
571-
the documents' ``sale-date`` value converted to a string.
568+
|out| writes to |json| files in the root of the bucket in the
569+
background. Each |json| file contains all of the documents
570+
with the same ``sale-date`` value. |out| names each file using
571+
the documents' ``sale-date`` value converted to a string.
572572

573573
.. tab:: Atlas Cluster
574574
:tabid: atlas

0 commit comments

Comments
 (0)