Skip to content

Commit 9622639

Browse files
norareidynorareidy
authored
DOCSP-45198: Distinct values (#111)
* DOCSP-45198: Distinct values * edits * RR feedback
1 parent 41cd85e commit 9622639

File tree

3 files changed

+227
-0
lines changed

3 files changed

+227
-0
lines changed

Diff for: ‎source/includes/read/distinct.rb

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
require 'bundler/inline'
2+
3+
gemfile do
4+
source 'https://rubygems.org'
5+
gem 'mongo'
6+
end
7+
8+
uri = '<connection string>'
9+
10+
Mongo::Client.new(uri) do |client|
11+
# Access the database and collection
12+
# start-db-coll
13+
database = client.use('sample_restaurants')
14+
collection = database[:restaurants]
15+
# end-db-coll
16+
17+
# Retrieves distinct values of the "borough" field
18+
# start-distinct
19+
results = collection.distinct('borough')
20+
results.each do |value|
21+
puts value
22+
end
23+
# end-distinct
24+
25+
# Retrieves distinct "borough" field values for documents with a "cuisine" value of "Italian"
26+
# start-distinct-with-query
27+
results = collection.distinct('borough', { cuisine: 'Italian' })
28+
results.each do |value|
29+
puts value
30+
end
31+
# end-distinct-with-query
32+
33+
# Retrieves distinct "name" field values for documents matching the "borough" and "cuisine" fields query
34+
# and uses primary preferred read preference
35+
# start-distinct-with-opts
36+
filter = { borough: 'Bronx', cuisine: 'Pizza' }
37+
options = { read: { mode: :primary_preferred } }
38+
results = collection.distinct('name', filter, options)
39+
40+
results.each do |value|
41+
puts value
42+
end
43+
# end-distinct-with-opts
44+
end

Diff for: ‎source/read.txt

+1
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,5 @@ Read Data from MongoDB
2626
Specify a Query </read/specify-a-query>
2727
Specify Documents to Return </read/specify-documents-to-return>
2828
Specify Fields to Return </read/project>
29+
Distinct Field Values </read/distinct>
2930
Count Documents </read/count>

Diff for: ‎source/read/distinct.txt

+182
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
.. _ruby-distinct:
2+
3+
==============================
4+
Retrieve Distinct Field Values
5+
==============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: read, unique, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to retrieve the
24+
distinct values of a specified field across a collection.
25+
26+
Within a collection, documents might contain different values for a
27+
single field. For example, one document in a ``restaurants`` collection has a
28+
``borough`` value of ``'Manhattan'``, and another has a ``borough`` value of
29+
``'Queens'``. You can use the {+driver-short+} to retrieve all the unique values
30+
that a field contains across multiple documents in a collection.
31+
32+
Sample Data
33+
~~~~~~~~~~~
34+
35+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
36+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
37+
from your {+language+} application, create a ``Mongo::Client`` object that connects to
38+
an Atlas cluster and assign the following values to your ``database`` and ``collection``
39+
variables:
40+
41+
.. literalinclude:: /includes/read/distinct.rb
42+
:language: ruby
43+
:dedent:
44+
:start-after: start-db-coll
45+
:end-before: end-db-coll
46+
47+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
48+
:atlas:`Get Started with Atlas </getting-started>` guide.
49+
50+
Retrieve Distinct Values
51+
------------------------
52+
53+
To retrieve the distinct values for a specified field, call the ``distinct``
54+
method and pass in the name of the field you want to find distinct values for.
55+
56+
Retrieve Values Across a Collection
57+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58+
59+
The following example retrieves the distinct values of the ``borough`` field in
60+
the ``restaurants`` collection:
61+
62+
.. io-code-block::
63+
:copyable:
64+
65+
.. input:: /includes/read/distinct.rb
66+
:start-after: start-distinct
67+
:end-before: end-distinct
68+
:language: ruby
69+
:dedent:
70+
71+
.. output::
72+
:visible: false
73+
74+
Bronx
75+
Brooklyn
76+
Manhattan
77+
Missing
78+
Queens
79+
Staten Island
80+
81+
The operation returns an array that stores each distinct ``borough`` field value. Although
82+
several documents have the same value in the ``borough`` field, each value appears in the
83+
results only once.
84+
85+
Retrieve Values Across Specified Documents
86+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87+
88+
You can provide a **query filter** to the ``distinct`` method to find the distinct
89+
field values across a subset of documents in a collection. A query filter is an expression
90+
that specifies search criteria used to match documents in an operation.
91+
92+
.. TODO: To learn more about creating a query filter, see the :ref:`ruby-specify-query` guide.
93+
94+
The following example retrieves the distinct values of the ``borough`` field for
95+
all documents that have a ``cuisine`` field value of ``'Italian'``:
96+
97+
.. io-code-block::
98+
:copyable:
99+
100+
.. input:: /includes/read/distinct.rb
101+
:start-after: start-distinct-with-query
102+
:end-before: end-distinct-with-query
103+
:language: ruby
104+
:dedent:
105+
106+
.. output::
107+
:visible: false
108+
109+
Bronx
110+
Brooklyn
111+
Manhattan
112+
Queens
113+
Staten Island
114+
115+
Modify Distinct Behavior
116+
~~~~~~~~~~~~~~~~~~~~~~~~
117+
118+
You can modify the behavior of the ``distinct`` method by passing a
119+
``Hash`` object that specifies option values. The following table describes the
120+
options you can set to customize the operation:
121+
122+
.. list-table::
123+
:widths: 30 70
124+
:header-rows: 1
125+
126+
* - Option
127+
- Description
128+
129+
* - ``collation``
130+
- | The collation to use for the operation.
131+
| **Type**: ``Hash``
132+
133+
* - ``max_time_ms``
134+
- | The maximum amount of time in milliseconds that the operation can run.
135+
| **Type**: ``Integer``
136+
137+
* - ``read``
138+
- | The read preference to use for the operation. To learn more, see
139+
:manual:`Read Preference </core/read-preference/>` in the {+mdb-server+} manual.
140+
| **Type**: ``Hash``
141+
142+
* - ``session``
143+
- | The session to use for the operation.
144+
| **Type**: ``Session``
145+
146+
The following example retrieves the distinct values of the ``name`` field for
147+
all documents that have a ``borough`` field value of ``'Bronx'`` and a
148+
``cuisine`` field value of ``'Pizza'``. It also sets the ``read`` option,
149+
which instructs the operation to use a ``primary_preferred``
150+
read preference:
151+
152+
.. io-code-block::
153+
:copyable:
154+
155+
.. input:: /includes/read/distinct.rb
156+
:start-after: start-distinct-with-opts
157+
:end-before: end-distinct-with-opts
158+
:language: ruby
159+
:dedent:
160+
161+
.. output::
162+
:visible: false
163+
164+
$1.25 Pizza
165+
18 East Gunhill Pizza
166+
2 Bros
167+
Aenos Pizza
168+
Alitalia Pizza Restaurant
169+
Amici Pizza And Pasta
170+
Angie'S Cafe Pizza
171+
Anthony & Joe'S Pizza
172+
Anthony'S Pizza
173+
Antivari Pizza
174+
Arturo'S Pizza
175+
Bartow Pizza
176+
...
177+
178+
API Documentation
179+
-----------------
180+
181+
To learn more about the ``distinct`` method, see the
182+
`API documentation. <{+api-root+}/Mongo/Collection.html#distinct-instance_method>`__

0 commit comments

Comments
 (0)