Skip to content

Commit 6891133

Browse files
mcmorisimcmorisi
committed
DOCSP-41138: Distinct (#24)
(cherry picked from commit ae8646c)
1 parent a564eea commit 6891133

File tree

3 files changed

+246
-2
lines changed

3 files changed

+246
-2
lines changed

‎source/includes/read/distinct.kt

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import com.mongodb.ConnectionString
2+
import com.mongodb.MongoClientSettings
3+
import com.mongodb.client.model.Filters.and
4+
import com.mongodb.client.model.Filters.eq
5+
import com.mongodb.kotlin.client.MongoClient
6+
7+
// start-data-class
8+
data class Restaurant(
9+
val name: String,
10+
val borough: String,
11+
val cuisine: String
12+
)
13+
// end-data-class
14+
15+
fun main() {
16+
val uri = "<connection string URI>"
17+
18+
val settings = MongoClientSettings.builder()
19+
.applyConnectionString(ConnectionString(uri))
20+
.retryWrites(true)
21+
.build()
22+
23+
val mongoClient = MongoClient.create(settings)
24+
val database = mongoClient.getDatabase("sample_restaurants")
25+
val collection = database.getCollection<Restaurant>("restaurants")
26+
27+
// start-distinct
28+
val results = collection.distinct<String>(Restaurant::borough.name)
29+
30+
results.forEach { result ->
31+
println(result)
32+
}
33+
// end-distinct
34+
35+
// start-distinct-query
36+
val results = collection.distinct<String>(
37+
Restaurant::borough.name,
38+
eq(Restaurant::cuisine.name, "Italian")
39+
)
40+
41+
results.forEach { result ->
42+
println(result)
43+
}
44+
// end-distinct-query
45+
46+
// start-distinct-comment
47+
val results = collection.distinct<String>(
48+
Restaurant::name.name,
49+
and(
50+
eq(Restaurant::borough.name, "Bronx"),
51+
eq(Restaurant::cuisine.name, "Pizza")
52+
)
53+
).comment("Bronx pizza restaurants")
54+
55+
results.forEach { result ->
56+
println(result)
57+
58+
}
59+
// end-distinct-comment
60+
}
61+

‎source/read.txt

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Read Data from MongoDB
2727
/read/project
2828
/read/specify-documents-to-return
2929
/read/count
30+
/read/distinct
3031

3132
Overview
3233
--------
@@ -133,8 +134,8 @@ collection:
133134
:copyable:
134135
:dedent:
135136

136-
.. TODO: To learn more about the ``distinct()`` method, see the
137-
.. :ref:`kotlin-sync-distinct` guide.
137+
To learn more about the ``distinct()`` method, see the
138+
:ref:`kotlin-sync-distinct` guide.
138139

139140
Monitor Data Changes
140141
--------------------

‎source/read/distinct.txt

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
.. _kotlin-sync-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+
Within a collection, different documents might contain different values for a single field.
24+
For example, one document in the ``restaurant`` collection has a ``borough`` value of ``"Manhattan"``, and
25+
another has a ``borough`` value of ``"Queens"``. With the {+driver-short+}, you can
26+
retrieve all the distinct values that a field contains across multiple documents
27+
in a collection.
28+
29+
Sample Data
30+
~~~~~~~~~~~
31+
32+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
33+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
34+
free MongoDB Atlas cluster and load the sample datasets, see the
35+
:atlas:`Get Started with Atlas </getting-started>` guide.
36+
37+
The following {+language+} data class models the documents in this collection:
38+
39+
.. literalinclude:: /includes/read/distinct.kt
40+
:start-after: start-data-class
41+
:end-before: end-data-class
42+
:language: kotlin
43+
:copyable:
44+
45+
``distinct()`` Method
46+
---------------------
47+
48+
To retrieve the distinct values for a specified field, call the ``distinct()``
49+
method and pass in the name of the field you want to find distinct values for.
50+
51+
Retrieve Distinct Values Across a Collection
52+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53+
54+
The following example retrieves the distinct values of the ``borough`` field in
55+
the ``restaurants`` collection:
56+
57+
.. io-code-block::
58+
59+
.. input:: /includes/read/distinct.kt
60+
:start-after: start-distinct
61+
:end-before: end-distinct
62+
:language: kotlin
63+
:dedent:
64+
65+
.. output::
66+
:visible: false
67+
68+
Bronx
69+
Brooklyn
70+
Manhattan
71+
Missing
72+
Queens
73+
Staten Island
74+
75+
The results show every distinct value that appears in the ``borough`` field
76+
across all documents in the collection. Although several documents have the same
77+
value in the ``borough`` field, each value appears in the results only once.
78+
79+
Retrieve Distinct Values Across Specified Documents
80+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81+
82+
You can provide a **query filter** to the ``distinct()`` method to find the distinct
83+
field values across a subset of documents in a collection. A query filter is an expression that specifies search
84+
criteria used to match documents in an operation. For more information about
85+
creating a query filter, see :ref:`kotlin-sync-specify-query`.
86+
87+
The following example retrieves the distinct values of the ``borough`` field for
88+
all documents that have a ``cuisine`` field value of ``"Italian"``:
89+
90+
.. io-code-block::
91+
92+
.. input:: /includes/read/distinct.kt
93+
:start-after: start-distinct-query
94+
:end-before: end-distinct-query
95+
:language: kotlin
96+
:dedent:
97+
98+
.. output::
99+
:visible: false
100+
101+
Bronx
102+
Brooklyn
103+
Manhattan
104+
Queens
105+
Staten Island
106+
107+
Modify Distinct Behavior
108+
~~~~~~~~~~~~~~~~~~~~~~~~
109+
110+
The ``distinct()`` method can be modified by chaining methods to the ``distinct()`` method
111+
call. If you don't specify any options, the driver does not customize the operation.
112+
113+
The following table describes some methods you can use to customize the
114+
``distinct()`` operation:
115+
116+
.. list-table::
117+
:widths: 30 70
118+
:header-rows: 1
119+
120+
* - Method
121+
- Description
122+
123+
* - ``batchSize()``
124+
- | Sets the number of documents to return per batch.
125+
126+
* - ``collation()``
127+
- | Specifies the kind of language collation to use when sorting
128+
results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
129+
in the {+mdb-server+} manual.
130+
131+
* - ``comment()``
132+
- | Specifies a comment to attach to the operation.
133+
134+
* - ``filter()``
135+
- | Sets the query filter to apply to the query.
136+
137+
* - ``forEach()``
138+
- | Performs the given action on each element returned by the ``distinct()`` operation.
139+
140+
* - ``maxTime()``
141+
- | Sets the maximum amount of time to allow the operation to run, in milliseconds.
142+
143+
For a complete list of methods you can use to modify the ``distinct()`` method, see
144+
the `DistinctIterable <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-distinct-iterable/index.html>`__ API documentation.
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 uses
149+
the ``comment`` option to add a comment to the operation.
150+
151+
.. io-code-block::
152+
153+
.. input:: /includes/read/distinct.kt
154+
:start-after: start-distinct-comment
155+
:end-before: end-distinct-comment
156+
:language: kotlin
157+
:dedent:
158+
159+
.. output::
160+
:visible: false
161+
162+
$1.25 Pizza
163+
18 East Gunhill Pizza
164+
2 Bros
165+
Aenos Pizza
166+
Alitalia Pizza Restaurant
167+
...
168+
169+
Additional Information
170+
----------------------
171+
172+
To learn more about the distinct command, see the :manual:`Distinct guide
173+
</reference/command/distinct/>` in the MongoDB Server Manual.
174+
175+
API Documentation
176+
~~~~~~~~~~~~~~~~~
177+
178+
To learn more about any of the methods or types discussed in this
179+
guide, see the following API documentation:
180+
181+
- `distinct() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/distinct.html>`__
182+
- `DistinctIterable <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-distinct-iterable/index.html>`__

0 commit comments

Comments
 (0)