Skip to content

Commit 95dd1df

Browse files
norareidynorareidy
authored
DOCSP-18223: added a distinct() page (#338)
* DOCSP-18223: added a distinct() page * DOCSP-18223: update TOC * better example documents * fixed rst mistakes * fixed wording * small wording fix * another small wording fix
1 parent 8cd7801 commit 95dd1df

File tree

5 files changed

+174
-6
lines changed

5 files changed

+174
-6
lines changed

‎source/fundamentals/collations.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _node-fundamentals-collations:
2+
13
==========
24
Collations
35
==========

‎source/fundamentals/crud/query-document.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _node-fundamentals-query-document:
2+
13
===============
24
Specify a Query
35
===============

‎source/fundamentals/crud/read-operations.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Read Operations
66

77
- :doc:`/fundamentals/crud/read-operations/retrieve`
88
- :doc:`/fundamentals/crud/read-operations/cursor`
9+
- :doc:`/fundamentals/crud/read-operations/distinct`
910
- :doc:`/fundamentals/crud/read-operations/sort`
1011
- :doc:`/fundamentals/crud/read-operations/skip`
1112
- :doc:`/fundamentals/crud/read-operations/limit`
@@ -18,6 +19,7 @@ Read Operations
1819

1920
/fundamentals/crud/read-operations/retrieve
2021
/fundamentals/crud/read-operations/cursor
22+
/fundamentals/crud/read-operations/distinct
2123
/fundamentals/crud/read-operations/sort
2224
/fundamentals/crud/read-operations/skip
2325
/fundamentals/crud/read-operations/limit

‎source/fundamentals/crud/read-operations/distinct.txt

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
.. _node-fundamentals-distinct:
2+
3+
========================
4+
Retrieve Distinct Values
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+
Overview
16+
--------
17+
18+
Use the ``distinct()`` method to retrieve all distinct values for a specified field
19+
across a collection.
20+
21+
Sample Documents
22+
~~~~~~~~~~~~~~~~
23+
24+
Consider a collection called ``restaurants`` that contains documents with restaurant data.
25+
The examples on this page use the following ``restaurants`` documents to demonstrate the
26+
usage of ``distinct()``:
27+
28+
.. code-block:: json
29+
30+
[
31+
{ "_id": 1, "restaurant": "White Bear", "borough": "Queens", "cuisine": "Chinese" },
32+
{ "_id": 2, "restaurant": "Via Carota", "borough": "Manhattan", "cuisine": "Italian" },
33+
{ "_id": 3, "restaurant": "Borgatti's", "borough": "Bronx", "cuisine": "Italian" },
34+
{ "_id": 4, "restaurant": "Tanoreen", "borough": "Brooklyn", "cuisine": "Middle Eastern" },
35+
{ "_id": 5, "restaurant": "Äpfel", "borough": "Queens", "cuisine": "German" },
36+
{ "_id": 6, "restaurant": "Samba Kitchen", "borough": "Manhattan", "cuisine": "Brazilian" },
37+
]
38+
39+
.. include:: /includes/access-cursor-note.rst
40+
41+
42+
Distinct
43+
--------
44+
45+
Use a document field name as a parameter for the ``distinct()`` method to return a
46+
list of the field's unique values. You can specify two optional parameters to adjust
47+
the method output:
48+
49+
- A ``query`` parameter to refine your results
50+
- An ``options`` parameter to set collation rules
51+
52+
Example
53+
```````
54+
55+
The "``Queens``" and "``Manhattan``" borough values each appear more than
56+
once in the sample documents. However, the following example retrieves the
57+
unique values of the ``borough`` field:
58+
59+
.. code-block:: javascript
60+
61+
// specify "borough" as the field to return values for
62+
const cursor = collection.distinct("borough");
63+
await cursor.forEach(console.dir);
64+
65+
This code outputs the following ``borough`` values:
66+
67+
.. code-block:: json
68+
:copyable: false
69+
70+
[ "Bronx", "Brooklyn", "Manhattan", "Queens" ]
71+
72+
Query Parameter
73+
~~~~~~~~~~~~~~~
74+
75+
You can specify a query parameter to return unique values for documents that match
76+
your query.
77+
78+
Visit :ref:`node-fundamentals-query-document` for more information on constructing a
79+
query filter.
80+
81+
Example
82+
```````
83+
84+
The following example outputs the distinct values of the ``cuisine`` field but
85+
excludes restaurants in "``Brooklyn``":
86+
87+
.. code-block:: javascript
88+
89+
// exclude Brooklyn restaurants from the output
90+
const query = { borough: { $ne: "Brooklyn" }};
91+
92+
// find the filtered distinct values of "cuisine"
93+
const cursor = collection.distinct("cuisine", query);
94+
await cursor.forEach(console.dir);
95+
96+
In this case, the query filter matches every borough value except for "``Brooklyn``". This
97+
prevents ``distinct()`` from outputting one ``cuisine`` value, "``Middle Eastern``".
98+
The code outputs the following values:
99+
100+
.. code-block:: json
101+
:copyable: false
102+
103+
[ "Brazilian", "Chinese", "German", "Italian" ]
104+
105+
Options Parameter
106+
~~~~~~~~~~~~~~~~~
107+
108+
You can specify the collation to the ``distinct()`` method by defining a
109+
``collation`` field as an ``options`` parameter. This field allows you to set
110+
regional rules for string ordering and comparisons.
111+
112+
See :ref:`node-fundamentals-collations` for instructions on applying collations.
113+
114+
.. note::
115+
116+
When using the ``options`` parameter, you must also specify a ``query`` parameter. If
117+
you don't want to use a query filter, define the query as ``{}``.
118+
119+
Example
120+
```````
121+
122+
The following example uses a ``collation`` field to specify German language ordering
123+
conventions when outputting the distinct ``restaurant`` values:
124+
125+
.. code-block:: javascript
126+
127+
// define an empty query document
128+
const query = {};
129+
// specify German string ordering conventions
130+
const options = { collation: { locale: "de" }};
131+
132+
const cursor = collection.distinct("restaurant", query, options);
133+
await cursor.forEach(console.dir);
134+
135+
In this case, German string ordering conventions place words beginning with "Ä" before
136+
those beginning with "B". The code outputs the following:
137+
138+
.. code-block:: json
139+
:copyable: false
140+
141+
[ "Äpfel", "Borgatti's", "Samba Kitchen", "Tanoreen", "Via Carota", "White Bear" ]
142+
143+
Without specifying a ``collation`` field, the output order would follow default
144+
binary collation rules. These rules place words beginning with "Ä" after the those
145+
with unaccented first letters:
146+
147+
.. code-block:: json
148+
:copyable: false
149+
150+
[ "Borgatti's", "Samba Kitchen", "Tanoreen", "Via Carota", "White Bear", "Äpfel" ]
151+
152+
Additional Information
153+
----------------------
154+
155+
For a runnable example of retrieving distinct values, see :ref:`node-usage-distinct`.
156+
157+
API Documentation
158+
~~~~~~~~~~~~~~~~~
159+
160+
To learn more about the ``distinct()`` method and its parameters, you can visit the
161+
`API documentation <{+api+}/classes/Collection.html#distinct>`__.
162+
163+

‎source/usage-examples/distinct.txt

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,12 @@ Retrieve Distinct Values of a Field
1414
`API documentation <{+api+}/classes/Collection.html#~resultcallback>`__ for
1515
information on the result object.
1616

17-
You can retrieve a list of distinct values for a field across a
18-
collection by using the
17+
You can retrieve a list of :doc:`distinct values </fundamentals/crud/read-operations/distinct>`
18+
for a field across a collection by using the
1919
`collection.distinct() <{+api+}/classes/Collection.html#distinct>`__
20-
method. Call the ``distinct()`` method
21-
on a ``Collection`` object with a document field name parameter as a
22-
``String`` to produce a list that contains one of each of the different
23-
values found in the specified document field as shown below:
20+
method. Call the ``distinct()`` method on a ``Collection`` object with a document
21+
field name parameter as a ``String`` to produce a list that contains one of each
22+
of the different values found in the specified document field as shown below:
2423

2524
.. code-block:: javascript
2625

0 commit comments

Comments
 (0)