Skip to content

Commit 12935ac

Browse files
mungitoperritojeff-allen-mongo
mungitoperrito
authored and
jeff-allen-mongo
committed
DOCS-13883 docs for operator
1 parent 2be9cdf commit 12935ac

File tree

7 files changed

+257
-22
lines changed

7 files changed

+257
-22
lines changed

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,9 @@ content: |
114114
* - :expression:`$pow`
115115
- Raises a number to the specified exponent.
116116
117+
* - :expression:`$rand`
118+
- Returns a random value between 0 and 1
119+
117120
* - :expression:`$round`
118121
- Rounds a number to to a whole integer *or* to a specified
119122
decimal place.

‎source/meta/aggregation-quick-reference.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -417,6 +417,7 @@ Index of Expression Operators
417417
- :expression:`$pow`
418418
- :group:`$push`
419419
- :expression:`$radiansToDegrees`
420+
- :expression:`$rand`
420421
- :expression:`$range`
421422
- :expression:`$reduce`
422423
- :expression:`$regexFind`

‎source/reference/operator/aggregation.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1044,6 +1044,7 @@ Alphabetical Listing of Expression Operators
10441044
/reference/operator/aggregation/pow
10451045
/reference/operator/aggregation/push
10461046
/reference/operator/aggregation/radiansToDegrees
1047+
/reference/operator/aggregation/rand
10471048
/reference/operator/aggregation/range
10481049
/reference/operator/aggregation/reduce
10491050
/reference/operator/aggregation/regexFind

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

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
===================
2+
$rand (aggregation)
3+
===================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. expression:: $rand
17+
18+
.. versionadded:: 4.4.2
19+
20+
The :expression:`$rand` operator generates a random value between 0
21+
and 1 each time it is called.
22+
23+
Examples
24+
--------
25+
26+
This code creates a small collection with 100 documents which we will
27+
use in these examples. (Increase the value of ``N`` if you want to
28+
experiment with larger data sets).
29+
30+
.. code-block:: javascript
31+
32+
N = 100
33+
bulk = db.collection.initializeUnorderedBulkOp()
34+
for (i = 0; i < N; i++) { bulk.insert({_id: i, r: 0}) }
35+
bulk.execute()
36+
37+
Consider the following examples:
38+
39+
The ``$rand`` operator can be used in a pipeline to select random
40+
documents from a collection. In this example we use the same database
41+
and ``$rand`` to select about half the documents.
42+
43+
.. code-block:: javascript
44+
45+
db.collection.aggregate(
46+
[
47+
{ $match:
48+
{
49+
$expr:
50+
{
51+
$lt: [0.5, {$rand: {} } ]
52+
}
53+
}
54+
},
55+
{
56+
$count: "numMatches"
57+
}
58+
]
59+
)
60+
61+
.. code-block:: javascript
62+
:copyable: false
63+
64+
// Output of 5 runs on the sample collection
65+
{ "numMatches" : 49 }
66+
{ "numMatches" : 52 }
67+
{ "numMatches" : 54 }
68+
{ "numMatches" : 48 }
69+
{ "numMatches" : 59 }
70+
71+
.. note::
72+
73+
This example returns different results each time. Smaller datasets
74+
show more variability in repeated runs. The number of documents
75+
selected each time approaches the expected value (in this case 50%)
76+
as the collection size grows.
77+
78+
Update operations accept aggregation pipelines. In this example the
79+
``$rand`` operator is used to insert a different random number into each
80+
document in a collection.
81+
82+
.. code-block:: javascript
83+
84+
db.collection.updateMany({}, [
85+
{
86+
$set:
87+
{
88+
"r":
89+
{
90+
$rand: {}
91+
}
92+
}
93+
}
94+
]
95+
)
96+
97+
This is brief excerpt showing the results of the update:
98+
99+
.. code-block:: javascript
100+
:copyable: false
101+
102+
db.collection.aggregate(
103+
[
104+
{
105+
$project: {_id:0, r:1 }
106+
}
107+
]
108+
)
109+
110+
{ "r" : 0.9141450086748962 }
111+
{ "r" : 0.151174715006409 }
112+
{ "r" : 0.4311952154820518 }
113+
{ "r" : 0.08106914853292181 }
114+
...
115+
116+
.. seealso::
117+
118+
:expression:`$let`, :query:`$rand`.
119+

‎source/reference/operator/query-others.txt

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
=====================
2+
Other Query Operators
3+
=====================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. include:: /includes/extracts/operators-toc-explanation.rst
14+
15+
.. list-table::
16+
:widths: 30,70
17+
:header-rows: 1
18+
19+
* - Name
20+
21+
- Description
22+
23+
* - :query:`$comment`
24+
25+
- Allows use of commented code within the query language.
26+
27+
* - :query:`$rand`
28+
29+
- Generates a random number between 0 and 1.
30+
31+
.. toctree::
32+
:titlesonly:
33+
:hidden:
34+
35+
/reference/operator/query/comment
36+
/reference/operator/query/rand
37+

‎source/reference/operator/query.txt

Lines changed: 28 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -299,8 +299,10 @@ Bitwise
299299

300300
/reference/operator/query-bitwise
301301

302-
Comments
303-
~~~~~~~~
302+
.. _query-projection-operators:
303+
304+
Projection Operators
305+
--------------------
304306

305307
.. only:: website
306308

@@ -312,21 +314,33 @@ Comments
312314

313315
- Description
314316

315-
* - :query:`$comment`
317+
* - :projection:`$`
318+
319+
- Projects the first element in an array that matches the query condition.
320+
321+
* - :projection:`$elemMatch`
316322

317-
- Adds a comment to a query predicate.
323+
- Projects the first element in an array that matches the specified :projection:`$elemMatch` condition.
324+
325+
* - :projection:`$meta`
326+
327+
- Projects the document's score assigned during :query:`$text` operation.
328+
329+
* - :projection:`$slice`
330+
331+
- Limits the number of elements projected from an array. Supports skip and limit slices.
318332

319333

320334
.. toctree::
321335
:titlesonly:
322336
:hidden:
323337

324-
/reference/operator/query/comment
338+
/reference/operator/projection
325339

326-
.. _query-projection-operators:
340+
.. _query-other-operators:
327341

328-
Projection Operators
329-
--------------------
342+
Other Operators
343+
---------------
330344

331345
.. only:: website
332346

@@ -338,25 +352,17 @@ Projection Operators
338352

339353
- Description
340354

341-
* - :projection:`$`
342-
343-
- Projects the first element in an array that matches the query condition.
344-
345-
* - :projection:`$elemMatch`
346-
347-
- Projects the first element in an array that matches the specified :projection:`$elemMatch` condition.
348-
349-
* - :projection:`$meta`
350-
351-
- Projects the document's score assigned during :query:`$text` operation.
355+
* - :query:`$comment`
352356

353-
* - :projection:`$slice`
357+
- Allows use of commented code within the query language.
354358

355-
- Limits the number of elements projected from an array. Supports skip and limit slices.
359+
* - :query:`$rand`
356360

361+
- Generates a random number between 0 and 1.
357362

358363
.. toctree::
359364
:titlesonly:
360365
:hidden:
361366

362-
/reference/operator/projection
367+
/reference/operator/query-others
368+

‎source/reference/operator/query/rand.txt

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
=====
2+
$rand
3+
=====
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. query:: $rand
14+
15+
*Syntax*: ``{$rand: {} }``
16+
17+
:query:`$rand` generates a random value between 0 and 1 each time it
18+
is called.
19+
20+
Consider the following example:
21+
22+
This code creates a small collection with 100 documents which we will
23+
use in this example. (Increase the value of ``N`` if you want to
24+
experiment with larger data sets).
25+
26+
.. code-block:: javascript
27+
28+
N = 100
29+
bulk = db.collection.initializeUnorderedBulkOp()
30+
for (i = 0; i < N; i++) { bulk.insert({_id: i, r: 0}) }
31+
bulk.execute()
32+
33+
The ``$rand`` operator can be used to select random documents from a
34+
collection. In this example we use the database just created and
35+
select about half the documents.
36+
37+
.. code-block:: javascript
38+
39+
db.collection.find(
40+
{
41+
$expr:
42+
{
43+
$lt: [0.5, {$rand: {} } ]
44+
}
45+
}
46+
).count()
47+
48+
.. code-block:: javascript
49+
:copyable: false
50+
51+
// Output of 5 runs on the sample collection
52+
51
53+
53
54+
49
55+
45
56+
47
57+
58+
.. note::
59+
60+
This example returns different results each time. Smaller data
61+
sets show more variability in repeated runs. The number of
62+
documents selected each time approaches the expected value (in
63+
this case 50%) as the collection size grows.
64+
65+
.. seealso::
66+
67+
:expression:`$let`, :expression:`$rand`.
68+

0 commit comments

Comments
 (0)