Skip to content

Commit e6ac23f

Browse files
rustagirrustagir
authored
DOCSP-36218: filters with dataclass properties (#63)
* DOCSP-36218: filters with dataclass properties WIP * wip * vale fix * cross links
1 parent dc019b9 commit e6ac23f

File tree

10 files changed

+826
-13
lines changed

10 files changed

+826
-13
lines changed

‎source/api.txt

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. _kotlin-sync-api-docs:
2+
3+
=================
4+
API Documentation
5+
=================
6+
7+
.. toctree::
8+
:titlesonly:
9+
:maxdepth: 1
10+
11+
{+language+} Sync Driver <{+java-api+}/apidocs/mongodb-driver-kotlin-sync/index.html>
12+
BSON kotlinx.serialization <{+java-api+}/apidocs/bson-kotlinx/index.html>
13+
{+language+} Driver Extensions <{+java-api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>
14+
Driver Core <{+core-api+}/index.html>
15+
16+
- `{+language+} Sync Driver <{+java-api+}/apidocs/mongodb-driver-kotlin-sync/index.html>`__ -
17+
classes for the current synchronous driver API.
18+
- `BSON kotlinx.serialization <{+java-api+}/apidocs/bson-kotlinx/index.html>`__ -
19+
classes for encoding and decoding between Kotlin data classes and the BSON data
20+
format using :github:`kotlinx.serialization <Kotlin/kotlinx.serialization>`.
21+
- `{+language+} Driver Extensions
22+
<{+java-api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ -
23+
classes that extend the core builder classes to support :ref:`data
24+
classes <kotlin-sync-builders-data-classes>`.
25+
- `Driver Core <{+core-api+}/index.html>`__ - classes that
26+
contain essential driver functionality.

‎source/builders.txt

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,9 @@ Use Builders Code Pattern
1010
:depth: 2
1111
:class: singlecol
1212

13-
.. .. toctree::
13+
.. toctree::
14+
15+
Builders & Data Classes </builders/builders-data-classes>
1416

1517
.. /fundamentals/builders/aggregates
1618
.. /fundamentals/builders/filters
@@ -28,6 +30,17 @@ benefits of using the provided builders.
2830
The {+driver-short+} provides type-safe builder classes and methods that enable developers to
2931
efficiently build queries and aggregations.
3032

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+
3144
Why Use Builders?
3245
-----------------
3346

@@ -53,7 +66,7 @@ The following data class models the documents in the ``users`` collection:
5366
:copyable:
5467
:dedent:
5568

56-
The following data class models the results returned by our query:
69+
The following data class models the results returned by the query:
5770

5871
.. literalinclude:: /includes/builders/builders.kt
5972
:start-after: start-result-class
@@ -87,8 +100,12 @@ query filter:
87100
:copyable:
88101
:dedent:
89102

90-
Builders
91-
~~~~~~~~
103+
In this case, you might easily include an error when writing the
104+
``"\$gt"`` operator in the filter, but your IDE returns the relevant
105+
error only at runtime.
106+
107+
Builders API
108+
~~~~~~~~~~~~
92109

93110
The following example performs the query by using the builder helpers:
94111

@@ -99,6 +116,14 @@ The following example performs the query by using the builder helpers:
99116
:copyable:
100117
:dedent:
101118

119+
Use Builders with Data Classes
120+
------------------------------
121+
122+
The :ref:`kotlin-sync-builders-data-classes` guide provides examples on
123+
how to use the preceding builders classes directly with data class
124+
properties. This guide might help to make your application more type-safe
125+
and improve {+language+} interoperability.
126+
102127
.. TODO: Uncomment as pages get built
103128

104129
.. Available Builders

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

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
.. _kotlin-sync-builders-data-classes:
2+
3+
==============================
4+
Use Builders with Data Classes
5+
==============================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, data format, modeling, interoperability
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use your :ref:`Data Class
24+
<kotlin-sync-data-format-data-classes>` properties directly with the
25+
builder classes available in the {+driver-short+}.
26+
27+
The {+driver-short+} implements extensions that allow you to reference
28+
your data class properties when using builder methods instead of using
29+
string field names. You can structure your code in this way to make your
30+
code more type-safe and improve your applications {+language+}
31+
interoperability.
32+
33+
The extensions library also allows you to construct
34+
queries, update documents, and write other statements by using infix
35+
notation. To learn more about this notation, see `Infix notation
36+
<{+kotlin-docs+}/docs/functions.html#infix-notation>`__ in the
37+
{+language+} reference documentation.
38+
39+
.. note::
40+
41+
This page provides a limited number of code
42+
examples to demonstrate this functionality. To learn more about using
43+
builder classes, see the :ref:`kotlin-sync-builders` guide.
44+
45+
Add {+language+} Extensions to Your Project
46+
-------------------------------------
47+
48+
To implement this functionality, you must add the
49+
``mongodb-driver-kotlin-extensions`` dependency to your dependencies
50+
list.
51+
52+
Select from the following tabs to see how to add the extension
53+
dependency to your project by using the :guilabel:`Gradle` and
54+
:guilabel:`Maven` package managers:
55+
56+
.. tabs::
57+
58+
.. tab::
59+
:tabid: Gradle
60+
61+
If you are using `Gradle <https://gradle.org/>`__ to manage your
62+
dependencies, add the following to your ``build.gradle.kts`` dependencies list:
63+
64+
.. code-block:: kotlin
65+
:caption: build.gradle.kts
66+
67+
implementation("org.mongodb:mongodb-driver-kotlin-extensions:{+full-version+}")
68+
69+
.. tab::
70+
:tabid: Maven
71+
72+
If you are using `Maven <https://maven.apache.org/>`__ to manage your
73+
dependencies, add the following to your ``pom.xml`` dependencies list:
74+
75+
.. code-block:: xml
76+
:caption: pom.xml
77+
78+
<dependency>
79+
<groupId>org.mongodb</groupId>
80+
<artifactId>mongodb-driver-kotlin-extensions</artifactId>
81+
<version>{+full-version+}</version>
82+
</dependency>
83+
84+
After you install the extensions dependency, you can use the extension
85+
methods by importing classes and methods from the
86+
``com.mongodb.kotlin.client.model`` path. You can mix usage of these methods and
87+
the standard builder methods in the same application, as shown in the
88+
:ref:`kotlin-sync-data-class-aggregates` example in this guide.
89+
90+
Builders Examples
91+
-----------------
92+
93+
This section contains examples that demonstrate how to use data class
94+
properties directly with builder class methods from the extensions
95+
package.
96+
97+
.. tip:: Data Class Annotations
98+
99+
When you the extension builder class methods data
100+
classes, the methods respect your data class annotations from the
101+
``bson-kotlin`` and ``bson-kotlinx`` packages. To learn more about
102+
annotations, see the :ref:`kotlin-sync-data-class-annotations`
103+
section of the Document Data Format: Data Classes guide.
104+
105+
Sample Data
106+
~~~~~~~~~~~
107+
108+
The examples in this section use documents in the ``students``
109+
collection that describe students at a school. Documents in the
110+
``students`` collection are modeled by the following {+language+} data
111+
class:
112+
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:
118+
119+
.. _kotlin-sync-data-class-filters:
120+
121+
Filters
122+
~~~~~~~
123+
124+
You can use helpers from the ``Filters`` builders class to query on data
125+
class properties.
126+
127+
The following code shows different ways to use ``Filters`` extension
128+
methods to perform queries on the ``Student`` data class:
129+
130+
.. code-block:: kotlin
131+
132+
import com.mongodb.kotlin.client.model.Filters.eq
133+
import com.mongodb.kotlin.client.model.Filters.all
134+
135+
.. literalinclude:: /includes/builders/builders-data-class.kt
136+
:language: kotlin
137+
:start-after: start-filters-data-class
138+
:end-before: end-filters-data-class
139+
:dedent:
140+
141+
.. _kotlin-sync-data-class-indexes:
142+
143+
Indexes
144+
~~~~~~~
145+
146+
You can use helpers from the ``Indexes`` builders class to create
147+
indexes on data class properties.
148+
149+
The following code shows different ways to use ``Indexes`` extension
150+
methods to create indexes on the ``Student`` data class:
151+
152+
.. code-block:: kotlin
153+
154+
import com.mongodb.kotlin.client.model.Indexes.ascending
155+
import com.mongodb.kotlin.client.model.Indexes.descending
156+
157+
.. literalinclude:: /includes/builders/builders-data-class.kt
158+
:language: kotlin
159+
:start-after: start-indexes-data-class
160+
:end-before: end-indexes-data-class
161+
:dedent:
162+
163+
.. _kotlin-sync-data-class-projections:
164+
165+
Projections
166+
~~~~~~~~~~~
167+
168+
You can use helpers from the ``Projections`` builders class to create
169+
projections for data class properties.
170+
171+
The following code shows how to use ``Projections`` extension
172+
methods to create a projection on the ``Student`` data class:
173+
174+
.. code-block:: kotlin
175+
176+
import com.mongodb.kotlin.client.model.Projections.excludeId
177+
import com.mongodb.kotlin.client.model.Projections.fields
178+
import com.mongodb.kotlin.client.model.Projections.include
179+
180+
.. literalinclude:: /includes/builders/builders-data-class.kt
181+
:language: kotlin
182+
:start-after: start-proj-data-class
183+
:end-before: end-proj-data-class
184+
:dedent:
185+
186+
.. _kotlin-sync-data-class-sorts:
187+
188+
Sorts
189+
~~~~~
190+
191+
You can use helpers from the ``Sorts`` builders class to sort
192+
on your data class properties.
193+
194+
The following code shows how to use ``Sorts`` extension
195+
methods to create different sorts on the ``Student`` data class:
196+
197+
.. code-block:: kotlin
198+
199+
import com.mongodb.client.model.Sorts.orderBy
200+
import com.mongodb.kotlin.client.model.Sorts
201+
202+
.. literalinclude:: /includes/builders/builders-data-class.kt
203+
:language: kotlin
204+
:start-after: start-sorts-data-class
205+
:end-before: end-sorts-data-class
206+
:dedent:
207+
208+
.. _kotlin-sync-data-class-updates:
209+
210+
Updates
211+
~~~~~~~
212+
213+
You can use helpers from the ``Updates`` builders class to perform
214+
updates by using your data class properties.
215+
216+
The following code shows how to use ``Sorts`` extension
217+
methods to create different sorts on the ``Student`` data class:
218+
219+
.. code-block:: kotlin
220+
221+
import com.mongodb.kotlin.client.model.Filters.gte
222+
import com.mongodb.kotlin.client.model.Updates.addToSet
223+
import com.mongodb.kotlin.client.model.Updates.combine
224+
import com.mongodb.kotlin.client.model.Updates.max
225+
226+
.. literalinclude:: /includes/builders/builders-data-class.kt
227+
:language: kotlin
228+
:start-after: start-updates-data-class
229+
:end-before: end-updates-data-class
230+
:dedent:
231+
232+
.. _kotlin-sync-data-class-aggregates:
233+
234+
Aggregates
235+
~~~~~~~~~~
236+
237+
You can use helpers from the ``Aggregates`` and ``Accumulators``
238+
builders classes to perform aggregations by using you data class
239+
properties.
240+
241+
The following code shows how to use ``Accumulators`` extension
242+
methods and ``Aggregates`` helper methods to perform an aggregation on
243+
the ``Student`` data class:
244+
245+
.. code-block:: kotlin
246+
247+
import com.mongodb.client.model.Aggregates.group
248+
import com.mongodb.client.model.Aggregates.limit
249+
import com.mongodb.client.model.Aggregates.sort
250+
import com.mongodb.kotlin.client.model.Accumulators.avg
251+
252+
.. literalinclude:: /includes/builders/builders-data-class.kt
253+
:language: kotlin
254+
:start-after: start-agg-data-class
255+
:end-before: end-agg-data-class
256+
:dedent:
257+
258+
API Documentation
259+
-----------------
260+
261+
- `{+driver-short+} Extensions
262+
<{+core-api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__

‎source/data-formats.txt

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,12 @@ Specialized Data Formats
2121
:titlesonly:
2222
:maxdepth: 1
2323

24+
Data Classes </data-formats/data-format-data-class>
2425
Kotlin Serialization </data-formats/serialization>
2526
Codecs </data-formats/codecs>
2627
BSON </data-formats/bson>
2728
Time Series </data-formats/time-series>
2829

29-
.. TODO: /data-formats/data-class
3030
.. TODO: /data-formats/extended-json
3131

3232
Overview
@@ -46,9 +46,10 @@ You can use several types of specialized document data formats in your
4646
application. To learn how to work with these data formats, see the following
4747
sections:
4848

49+
- Learn how to model your documents as {+language+} data classes in the
50+
:ref:`kotlin-sync-data-format-data-classes` guide.
4951
- Learn how to work with the BSON data format in the :ref:`kotlin-sync-bson` guide.
5052
- Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.
5153

5254
.. TODO: Uncomment these as pages get built
53-
.. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide.
5455
.. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide.

0 commit comments

Comments
 (0)