Skip to content

Commit 10dae4f

Browse files
mcmorisimcmorisi
committed
DOCSP-41138: Distict
1 parent 6bb165f commit 10dae4f

File tree

3 files changed

+240
-2
lines changed

3 files changed

+240
-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: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
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 ``restaurant`` document 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 document 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+
64+
.. output::
65+
66+
Bronx
67+
Brooklyn
68+
Manhattan
69+
Missing
70+
Queens
71+
Staten Island
72+
73+
The results show every distinct value that appears in the ``borough`` field
74+
across all documents in the collection. Although several documents have the same
75+
value in the ``borough`` field, each value appears in the results only once.
76+
77+
Retrieve Distinct Values Across Specified Documents
78+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79+
80+
You can provide a **query filter** to the ``distinct()`` method to find the distinct
81+
field values across a subset of documents in a collection. A query filter is an expression that specifies search
82+
criteria used to match documents in an operation. For more information about
83+
creating a query filter, see :ref:`kotlin-sync-specify-query`.
84+
85+
The following example retrieves the distinct values of the ``borough`` field for
86+
all documents that have a ``cuisine`` field value of ``"Italian"``:
87+
88+
.. io-code-block::
89+
90+
.. input:: /includes/read/distinct.kt
91+
:start-after: start-distinct-query
92+
:end-before: end-distinct-query
93+
:language: kotlin
94+
95+
.. output::
96+
97+
Bronx
98+
Brooklyn
99+
Manhattan
100+
Queens
101+
Staten Island
102+
103+
Modify Distinct Behavior
104+
~~~~~~~~~~~~~~~~~~~~~~~~
105+
106+
The ``distinct()`` method can be modified by chaining methods to the ``distinct()`` method
107+
call. If you don't specify any options, the driver does not customize the operation.
108+
109+
The following table describes some methods you can use to customize the
110+
``distinct()`` operation:
111+
112+
.. list-table::
113+
:widths: 30 70
114+
:header-rows: 1
115+
116+
* - Method
117+
- Description
118+
119+
* - ``batchSize()``
120+
- | Sets the number of documents to return per batch.
121+
122+
* - ``collation()``
123+
- | Specifies the kind of language collation to use when sorting
124+
results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
125+
in the {+mdb-server+} manual.
126+
127+
* - ``comment()``
128+
- | Specifies a comment to attach to the operation.
129+
130+
* - ``filter()``
131+
- | Sets the query filter to apply to the query.
132+
133+
* - ``forEach()``
134+
- | Performs the given action on each element returned by the ``distinct()`` operation.
135+
136+
* - ``maxTime()``
137+
- | Sets the maximum amount of time to allow the operation to run, in milliseconds.
138+
139+
For a complete list of methods you can use to modify the ``distinct()`` method, see
140+
the `DistinctIterable <{+api}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-distinct-iterable/index.html>`__ API documentation.
141+
142+
The following example retrieves the distinct values of the ``name`` field for
143+
all documents that have a ``borough`` field value of ``"Bronx"`` and a
144+
``cuisine`` field value of ``"Pizza"``. It also uses
145+
the ``comment`` option to add a comment to the operation.
146+
147+
.. io-code-block::
148+
149+
.. input:: /includes/read/distinct.kt
150+
:start-after: start-distinct-comment
151+
:end-before: end-distinct-comment
152+
:language: kotlin
153+
154+
.. output::
155+
156+
$1.25 Pizza
157+
18 East Gunhill Pizza
158+
2 Bros
159+
Aenos Pizza
160+
Alitalia Pizza Restaurant
161+
...
162+
163+
Additional Information
164+
----------------------
165+
166+
To learn more about the distinct command, see the :manual:`Distinct guide
167+
</reference/command/distinct/>` in the MongoDB Server Manual.
168+
169+
API Documentation
170+
~~~~~~~~~~~~~~~~~
171+
172+
To learn more about any of the methods or types discussed in this
173+
guide, see the following API documentation:
174+
175+
- `distinct() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/distinct.html>`__
176+
- `DistinctIterable <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-distinct-iterable/index.html>`__

0 commit comments

Comments
 (0)