Skip to content

Commit 109d271

Browse files
jmd-mongojmd-mongo
authored
DOCSP-31508 listSampledQueries stage (#4095)
* DOCSP-31508 listSampledQueries stage * wip * adds mention to release notes * internal review * internal rev * internal review * list * internal review * external review * adds Limitations * clean up
1 parent a15cf65 commit 109d271

File tree

4 files changed

+219
-1
lines changed

4 files changed

+219
-1
lines changed

‎source/includes/extracts-agg-stages.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,11 @@ content: |
102102
outputs either one document (for the first *n* documents) or
103103
zero documents (after the first *n* documents).
104104
105+
* - :pipeline:`$listSampledQueries`
106+
107+
- Lists sampled queries for all collections or a specific
108+
collection.
109+
105110
* - :pipeline:`$listSearchIndexes`
106111
107112
- .. include:: /includes/atlas-search-commands/command-descriptions/getSearchIndexes-description.rst

‎source/reference/operator/aggregation-pipeline.txt

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,12 @@ Alphabetical Listing of Stages
185185
- Lists all active sessions recently in use on the currently connected
186186
:binary:`~bin.mongos` or :binary:`~bin.mongod` instance. These sessions may
187187
have not yet propagated to the ``system.sessions`` collection.
188-
188+
189+
* - :pipeline:`$listSampledQueries`
190+
191+
- Lists sampled queries for all collections or a specific
192+
collection.
193+
189194
* - :pipeline:`$listSearchIndexes`
190195

191196
- .. include:: /includes/atlas-search-commands/command-descriptions/getSearchIndexes-description.rst
@@ -395,6 +400,7 @@ Alphabetical Listing of Stages
395400
/reference/operator/aggregation/indexStats
396401
/reference/operator/aggregation/limit
397402
/reference/operator/aggregation/listLocalSessions
403+
/reference/operator/aggregation/listSampledQueries
398404
/reference/operator/aggregation/listSearchIndexes
399405
/reference/operator/aggregation/listSessions
400406
/reference/operator/aggregation/lookup

‎source/reference/operator/aggregation/listSampledQueries.txt

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
===================
2+
$listSampledQueries
3+
===================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. pipeline:: $listSampledQueries
17+
18+
Returns sampled queries for all collections or a specific
19+
collection. Sampled queries are used by the
20+
``analyzeShardKey`` command to calculate metrics about the read and
21+
write distribution of a shard key.
22+
23+
Syntax
24+
------
25+
26+
``$listSampledQueries`` has this syntax:
27+
28+
.. code-block:: javascript
29+
30+
{
31+
$listSampledQueries: { namespace: <namespace> }
32+
}
33+
34+
Behavior
35+
--------
36+
37+
- To list sampled queries for a single collection, specify
38+
the collection in the ``namespace`` argument.
39+
40+
- To list sampled queries for all collections, omit the ``namespace``
41+
argument.
42+
43+
Access Control
44+
--------------
45+
46+
``$listSampledQueries`` requires the :authrole:`clusterMonitor` role
47+
on the cluster.
48+
49+
Limitations
50+
-----------
51+
52+
- You cannot use ``$listSampledQueries`` on Atlas
53+
:atlas:`multitenant </docs/atlas/build-multi-tenant-arch/>`
54+
configurations.
55+
- You cannot use ``$listSampledQueries`` on standalone deployments.
56+
- You cannot use ``$listSampledQueries`` directly against a
57+
:option:`--shardsvr <mongod --shardsvr>` replica set.
58+
When running on a sharded cluster, ``$listSampledQueries``
59+
must run against a ``mongos``.
60+
61+
Examples
62+
--------
63+
64+
List Sampled Queries for All Collections
65+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66+
67+
The following aggregation operation lists all sampled queries for all
68+
collections in the replica set:
69+
70+
.. code-block:: javascript
71+
72+
db.aggregate( [ { $listSampledQueries: { } } ] )
73+
74+
List Sampled Queries for A Specific Collection
75+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76+
77+
The following aggregation operation lists all sampled queries for a
78+
``post`` collections on the ``social`` database:
79+
80+
.. code-block:: javascript
81+
82+
db.aggregate( [ { $listSampledQueries: { namespace: "social.post" } } ] )
83+
84+
Output
85+
------
86+
87+
The output fields differ for read and write queries.
88+
89+
Read Queries
90+
~~~~~~~~~~~~
91+
92+
.. code-block:: none
93+
:copyable: false
94+
95+
{
96+
_id: <uuid>,
97+
ns: "<database>.<collection>",
98+
collectionUuid: <collUUID>,
99+
cmdName: <find|aggregate|count|distinct>,
100+
cmd: {
101+
filter: <object>,
102+
collation: <object>,
103+
let: <object>
104+
},
105+
expireAt: <date>
106+
}
107+
108+
109+
.. list-table::
110+
:header-rows: 1
111+
112+
* - Field Name
113+
- Type
114+
- Description
115+
116+
* - ``_id``
117+
- UUID
118+
- Sample ID for the query.
119+
120+
* - ``ns``
121+
- string
122+
- Namespace of the sampled collection.
123+
124+
* - ``collectionUuid``
125+
- UUID
126+
- ID of the sampled collection.
127+
128+
* - ``cmdName``
129+
- string
130+
- Name of the sampled command. Can be one of:
131+
132+
- ``"find"``
133+
- ``"aggregate"``
134+
- ``"count"``
135+
- ``"distinct"``
136+
137+
* - ``cmd.filter``
138+
- object
139+
- Filter the command ran with, if applicable.
140+
141+
* - ``cmd.collation``
142+
- object
143+
- Collation the command ran with, if applicable.
144+
145+
* - ``cmd.let``
146+
- object
147+
- Custom variables the command ran with, if applicable.
148+
149+
* - ``expireAt``
150+
- date
151+
- Date that the sample expires.
152+
153+
Write Queries
154+
~~~~~~~~~~~~~
155+
156+
.. code-block:: none
157+
:copyable: false
158+
159+
{
160+
_id: <uuid>,
161+
ns: "<database>.<collection>",
162+
collectionUuid: <collUUID>,
163+
cmdName: <update|delete|findAndModify>,
164+
cmd: <object>,
165+
expireAt: <date>
166+
}
167+
168+
.. list-table::
169+
:header-rows: 1
170+
171+
* - Field Name
172+
- Type
173+
- Description
174+
175+
* - ``_id``
176+
- UUID
177+
- Sample ID for the query.
178+
179+
* - ``ns``
180+
- string
181+
- Namespace of the sampled collection.
182+
183+
* - ``collectionUuid``
184+
- UUID
185+
- ID of the sampled collection.
186+
187+
* - ``cmdName``
188+
- string
189+
- Name of the sampled command. Can be one of:
190+
191+
- ``"update"``
192+
- ``"delete"``
193+
- ``"findAndModify"``
194+
195+
* - ``cmd``
196+
- object
197+
- Command object
198+
199+
* - ``expireAt``
200+
- date
201+
- Date that the sample expires.

‎source/release-notes/7.0.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,16 @@ Aggregation Stages
6060

6161
- Description
6262

63+
* - :pipeline:`$listSampledQueries`
64+
65+
- Lists sampled queries for all collections or a specific
66+
collection.
67+
6368
* - :pipeline:`$listSearchIndexes`
6469

6570
- .. include:: /includes/atlas-search-commands/command-descriptions/getSearchIndexes-description.rst
6671

72+
6773
General Changes
6874
---------------
6975

0 commit comments

Comments
 (0)