Skip to content

Commit f875dec

Browse files
rustagirrustagir
committed
wip
1 parent c6352b4 commit f875dec

File tree

4 files changed

+215
-34
lines changed

4 files changed

+215
-34
lines changed

‎source/builders.txt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,17 @@ benefits of using the provided builders.
3030
The {+driver-short+} provides type-safe builder classes and methods that enable developers to
3131
efficiently build queries and aggregations.
3232

33+
To learn more about the available builder classes and methods, see the
34+
following API documentation sections:
35+
36+
- `Accumulators <{+core-api+}/com/mongodb/client/model/Accumulators.html>`__
37+
- `Aggregates <{+core-api+}/com/mongodb/client/model/Aggregates.html>`__
38+
- `Filters <{+core-api+}/com/mongodb/client/model/Filters.html>`__
39+
- `Indexes <{+core-api+}/com/mongodb/client/model/Indexes.html>`__
40+
- `Projections <{+core-api+}/com/mongodb/client/model/Projections.html>`__
41+
- `Sorts <{+core-api+}/com/mongodb/client/model/Sorts.html>`__
42+
- `Updates <{+core-api+}/com/mongodb/client/model/Updates.html>`__
43+
3344
Why Use Builders?
3445
-----------------
3546

‎source/builders/builders-data-classes.txt

Lines changed: 47 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@ notation. To learn more about this notation, see `Infix notation
3939
.. note::
4040

4141
This page provides a limited number of code
42-
examples to demonstrate this functionality. To view examples for all
43-
the builder classes, see the :ref:`kotlin-builders-landing` guides.
42+
examples to demonstrate this functionality. To learn more about using
43+
builder classes, see the :ref:`kotlin-sync-builders` guide.
4444

4545
Add {+language+} Extensions to Your Project
4646
-------------------------------------
@@ -85,7 +85,7 @@ After you install the extensions dependency, you can use the extension
8585
methods by importing classes and methods from the
8686
``com.mongodb.kotlin.client.model`` path. You can mix usage of these methods and
8787
the standard builder methods in the same application, as shown in the
88-
:ref:`kotlin-data-class-aggregates` example in this guide.
88+
:ref:`kotlin-sync-data-class-aggregates` example in this guide.
8989

9090
Builders Examples
9191
-----------------
@@ -99,10 +99,8 @@ package.
9999
When you the extension builder class methods data
100100
classes, the methods respect your data class annotations from the
101101
``bson-kotlin`` and ``bson-kotlinx`` packages. To learn more about
102-
annotations, see the :ref:`fundamentals-data-class-annotations`
103-
section of the Document Data Format: Data Classes guide and the
104-
:ref:`kotlin-data-class-annotation` section in the {+language+}
105-
Serialization guide.
102+
annotations, see the :ref:`kotlin-sync-data-class-annotations`
103+
section of the Document Data Format: Data Classes guide.
106104

107105
Sample Data
108106
~~~~~~~~~~~
@@ -112,17 +110,19 @@ collection that describe students at a school. Documents in the
112110
``students`` collection are modeled by the following {+language+} data
113111
class:
114112

115-
.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.data-class.kt
116-
:language: kotlin
113+
.. literalinclude:: /includes/builders/builders-data-class.kt
114+
:language: kotlin
115+
:start-after: start-data-class
116+
:end-before: end-data-class
117+
:dedent:
117118

118-
.. _kotlin-data-class-filters:
119+
.. _kotlin-sync-data-class-filters:
119120

120121
Filters
121122
~~~~~~~
122123

123124
You can use helpers from the ``Filters`` builders class to query on data
124-
class properties. To learn more about this class, see the
125-
:ref:`filters-builders` guide.
125+
class properties.
126126

127127
The following code shows different ways to use ``Filters`` extension
128128
methods to perform queries on the ``Student`` data class:
@@ -132,17 +132,19 @@ methods to perform queries on the ``Student`` data class:
132132
import com.mongodb.kotlin.client.model.Filters.eq
133133
import com.mongodb.kotlin.client.model.Filters.all
134134

135-
.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.filters-data-class.kt
135+
.. literalinclude:: /includes/builders/builders-data-class.kt
136136
:language: kotlin
137+
:start-after: start-filters-data-class
138+
:end-before: end-filters-data-class
139+
:dedent:
137140

138-
.. _kotlin-data-class-indexes:
141+
.. _kotlin-sync-data-class-indexes:
139142

140143
Indexes
141144
~~~~~~~
142145

143146
You can use helpers from the ``Indexes`` builders class to create
144-
indexes on data class properties. To learn more about this class, see the
145-
:ref:`indexes-builders` guide.
147+
indexes on data class properties.
146148

147149
The following code shows different ways to use ``Indexes`` extension
148150
methods to create indexes on the ``Student`` data class:
@@ -152,17 +154,19 @@ methods to create indexes on the ``Student`` data class:
152154
import com.mongodb.kotlin.client.model.Indexes.ascending
153155
import com.mongodb.kotlin.client.model.Indexes.descending
154156

155-
.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.indexes-data-class.kt
157+
.. literalinclude:: /includes/builders/builders-data-class.kt
156158
:language: kotlin
159+
:start-after: start-indexes-data-class
160+
:end-before: end-indexes-data-class
161+
:dedent:
157162

158-
.. _kotlin-data-class-projections:
163+
.. _kotlin-sync-data-class-projections:
159164

160165
Projections
161166
~~~~~~~~~~~
162167

163168
You can use helpers from the ``Projections`` builders class to create
164-
projections for data class properties. To learn more about this class, see the
165-
:ref:`projections-builders` guide.
169+
projections for data class properties.
166170

167171
The following code shows how to use ``Projections`` extension
168172
methods to create a projection on the ``Student`` data class:
@@ -173,17 +177,19 @@ methods to create a projection on the ``Student`` data class:
173177
import com.mongodb.kotlin.client.model.Projections.fields
174178
import com.mongodb.kotlin.client.model.Projections.include
175179

176-
.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.projections-data-class.kt
180+
.. literalinclude:: /includes/builders/builders-data-class.kt
177181
:language: kotlin
182+
:start-after: start-proj-data-class
183+
:end-before: end-proj-data-class
184+
:dedent:
178185

179-
.. _kotlin-data-class-sorts:
186+
.. _kotlin-sync-data-class-sorts:
180187

181188
Sorts
182189
~~~~~
183190

184191
You can use helpers from the ``Sorts`` builders class to sort
185-
on your data class properties. To learn more about this class, see the
186-
:ref:`sorts-builders` guide.
192+
on your data class properties.
187193

188194
The following code shows how to use ``Sorts`` extension
189195
methods to create different sorts on the ``Student`` data class:
@@ -193,17 +199,19 @@ methods to create different sorts on the ``Student`` data class:
193199
import com.mongodb.client.model.Sorts.orderBy
194200
import com.mongodb.kotlin.client.model.Sorts
195201

196-
.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.sorts-data-class.kt
202+
.. literalinclude:: /includes/builders/builders-data-class.kt
197203
:language: kotlin
204+
:start-after: start-sorts-data-class
205+
:end-before: end-sorts-data-class
206+
:dedent:
198207

199-
.. _kotlin-data-class-updates:
208+
.. _kotlin-sync-data-class-updates:
200209

201210
Updates
202211
~~~~~~~
203212

204213
You can use helpers from the ``Updates`` builders class to perform
205-
updates by using your data class properties. To learn more about this
206-
class, see the :ref:`updates-builders` guide.
214+
updates by using your data class properties.
207215

208216
The following code shows how to use ``Sorts`` extension
209217
methods to create different sorts on the ``Student`` data class:
@@ -215,18 +223,20 @@ methods to create different sorts on the ``Student`` data class:
215223
import com.mongodb.kotlin.client.model.Updates.combine
216224
import com.mongodb.kotlin.client.model.Updates.max
217225

218-
.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.updates-data-class.kt
226+
.. literalinclude:: /includes/builders/builders-data-class.kt
219227
:language: kotlin
228+
:start-after: start-updates-data-class
229+
:end-before: end-updates-data-class
230+
:dedent:
220231

221-
.. _kotlin-data-class-aggregates:
232+
.. _kotlin-sync-data-class-aggregates:
222233

223234
Aggregates
224235
~~~~~~~~~~
225236

226237
You can use helpers from the ``Aggregates`` and ``Accumulators``
227238
builders classes to perform aggregations by using you data class
228-
properties. To learn more about these classes, see the
229-
:ref:`aggregates-builders` guide.
239+
properties.
230240

231241
The following code shows how to use ``Accumulators`` extension
232242
methods and ``Aggregates`` helper methods to perform an aggregation on
@@ -239,11 +249,14 @@ the ``Student`` data class:
239249
import com.mongodb.client.model.Aggregates.sort
240250
import com.mongodb.kotlin.client.model.Accumulators.avg
241251

242-
.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.aggregates-data-class.kt
252+
.. literalinclude:: /includes/builders/builders-data-class.kt
243253
:language: kotlin
254+
:start-after: start-agg-data-class
255+
:end-before: end-agg-data-class
256+
:dedent:
244257

245258
API Documentation
246259
-----------------
247260

248261
- `{+driver-short+} Extensions
249-
<{+api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__
262+
<{+core-api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__

‎source/includes/builders/builders-data-class.kt

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
import com.mongodb.client.model.Aggregates.group
2+
import com.mongodb.client.model.Aggregates.limit
3+
import com.mongodb.client.model.Aggregates.sort
4+
5+
import com.mongodb.kotlin.client.model.Filters.eq
6+
import com.mongodb.kotlin.client.model.Filters.all
7+
import com.mongodb.kotlin.client.model.Indexes
8+
import com.mongodb.kotlin.client.model.Projections.excludeId
9+
import com.mongodb.kotlin.client.model.Projections.fields
10+
import com.mongodb.kotlin.client.model.Projections.include
11+
import com.mongodb.client.model.Sorts.orderBy
12+
import com.mongodb.kotlin.client.MongoClient
13+
import com.mongodb.kotlin.client.model.Accumulators.avg
14+
import com.mongodb.kotlin.client.model.Sorts
15+
16+
import com.mongodb.kotlin.client.model.Filters.gte
17+
import com.mongodb.kotlin.client.model.Updates.addToSet
18+
import com.mongodb.kotlin.client.model.Updates.combine
19+
import com.mongodb.kotlin.client.model.Updates.max
20+
21+
internal class BuildersDataClassTest {
22+
23+
// start-data-class
24+
data class Student(
25+
val name: String,
26+
val teachers: List<String>,
27+
val gradeAverage: Double
28+
)
29+
// end-data-class
30+
31+
fun main() {
32+
val uri = "<connection string>"
33+
34+
val mongoClient = MongoClient.create(uri)
35+
val database = mongoClient.getDatabase("school")
36+
val collection = database.getCollection<Student>("students")
37+
38+
// start-filters-data-class
39+
val student = Student(
40+
"Sandra Nook",
41+
listOf("Alvarez", "Gruber"),
42+
85.7
43+
)
44+
45+
// Equivalent equality queries
46+
Student::name.eq(student.name)
47+
eq(Student::name, student.name)
48+
Student::name eq student.name // Infix notation
49+
50+
// Equivalent array queries
51+
all(Student::teachers, student.teachers)
52+
Student::teachers.all(student.teachers)
53+
Student::teachers all student.teachers // Infix notation
54+
// end-filters-data-class
55+
56+
collection.insertOne(student)
57+
val filter = eq(Student::name, student.name)
58+
val result = collection.find(filter).firstOrNull()
59+
60+
// start-indexes-data-class
61+
val ascendingIdx = Indexes.ascending(Student::name)
62+
val descendingIdx = Indexes.descending(Student::teachers)
63+
64+
val ascIdxName = collection.createIndex(ascendingIdx)
65+
val descIdxName = collection.createIndex(descendingIdx)
66+
// end-indexes-data-class
67+
68+
val student = Student(
69+
"Sandra Nook",
70+
listOf("Alvarez", "Gruber"),
71+
85.7
72+
)
73+
collection.insertOne(student)
74+
75+
// start-proj-data-class
76+
val combinedProj = fields(
77+
include(Student::name, Student::gradeAverage),
78+
excludeId()
79+
)
80+
81+
collection.find().projection(combinedProj)
82+
// end-proj-data-class
83+
84+
data class Result(val name: String, val gradeAverage: Double)
85+
val result = collection.find<Result>().projection(combinedProj).firstOrNull()
86+
87+
val student1 = Student(
88+
"Sandra Nook",
89+
listOf("Alvarez", "Gruber"),
90+
85.7
91+
)
92+
val student2 = Student(
93+
"Paolo Sanchez",
94+
listOf("Gruber", "Piselli"),
95+
89.3
96+
)
97+
collection.insertMany(listOf(student1, student2))
98+
99+
// start-sorts-data-class
100+
val sort = orderBy(
101+
Sorts.descending(Student::gradeAverage),
102+
Sorts.ascending(Student::name)
103+
)
104+
105+
collection.find().sort(sort)
106+
// end-sorts-data-class
107+
108+
val students = listOf(
109+
Student("Sandra Nook", listOf("Alvarez", "Gruber"),85.7),
110+
Student("Paolo Sanchez", listOf("Gruber", "Piselli"),89.3)
111+
)
112+
collection.insertMany(students)
113+
114+
// start-updates-data-class
115+
val filter = Student::gradeAverage gte 85.0
116+
val update = combine(
117+
addToSet(Student::teachers, "Soto"),
118+
Student::gradeAverage.max(90.0)
119+
)
120+
collection.updateMany(filter, update)
121+
// end-updates-data-class
122+
123+
val result = collection.find().firstOrNull()
124+
125+
val students = listOf(
126+
Student("Sandra Nook", listOf("Alvarez", "Gruber"),85.7),
127+
Student("Paolo Sanchez", listOf("Gruber", "Piselli"),89.3),
128+
Student("Katerina Jakobsen", listOf("Alvarez", "Ender"),97.3),
129+
Student("Emma Frank", listOf("Piselli", "Harbour"),93.4),
130+
Student("Qasim Haq", listOf("Gruber", "Harbour"),80.6)
131+
)
132+
collection.insertMany(students)
133+
134+
// start-agg-data-class
135+
// Data class to store aggregation result
136+
data class Summary ( val average: Double )
137+
138+
val pipeline = listOf(
139+
// Sorts grades from high to low
140+
sort(Sorts.descending(Student::gradeAverage)),
141+
// Selects the top 3 students
142+
limit(3),
143+
// Calculates the average of their grades and stores value in a Summary instance
144+
group(null, avg(Summary::average, "\$${Student::gradeAverage.name}"))
145+
)
146+
147+
val result = collection.aggregate<Summary>(pipeline)
148+
// end-agg-data-class
149+
150+
}
151+
}

‎source/whats-new.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ improvements, and fixes:
4242
:ref:`kotlin-sync-write-replace`, and
4343
:ref:`kotlin-sync-bulk-write` guides
4444

45+
- Support for using builders class methods directly with data class
46+
properties. To learn more, see the :ref:`kotlin-sync-builders-data-classes`
47+
guide. This functionality is supported by the `{+driver-short+}
48+
Extensions package <{+java-api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__
49+
published with this release.
50+
4551
- Implements a *client* bulk write API that allows you to perform write
4652
operations on multiple databases and collections in the same call. To learn
4753
more about this feature, see the :ref:`kotlin-sync-client-bulk-write`

0 commit comments

Comments
 (0)