DOCSP-36218: builders with dataclass properties

examples/src/test/kotlin/DataClassTest.kt

@@ -1,5 +1,6 @@
 
 import com.mongodb.client.model.Filters
+import com.mongodb.client.model.Filters.eq
 import com.mongodb.client.model.FindOneAndUpdateOptions
 import com.mongodb.client.model.ReturnDocument
 import com.mongodb.client.model.Updates
@@ -92,10 +93,30 @@ internal class DataClassTest {
             .withDocumentClass<NewDataStorage>()
             .findOneAndUpdate(filter, update, options)
 
-        println("Updated document: ${result}")
+        println("Updated document: $result")
         // :snippet-end:
     }
 
+    @Test
+    fun queryDataClassTest() = runBlocking {
+
+        val collection = database.getCollection<DataStorage>("data_storage")
+
+        // :snippet-start: filters-query-data-class
+        val record = DataStorage("SSD", 120.0)
+        // Infixed query
+        DataStorage::productName.eq(record.productName)
+        // Nested query
+        val bson = eq(DataStorage::productName, record.productName)
+        // Kmongo DSL
+        val filter = DataStorage::productName eq record.productName
+        // :snippet-end:
+
+        collection.insertOne(record)
+        val result = collection.find().firstOrNull()
+        assertEquals(record, result)
+    }
+
     // :snippet-start: annotated-data-class
     data class NetworkDevice(
         @BsonId

source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt

@@ -0,0 +1,7 @@
+val record = DataStorage("SSD", 120.0)
+// Infixed query
+DataStorage::productName.eq(record.productName)
+// Nested query
+val bson = eq(DataStorage::productName, record.productName)
+// Kmongo DSL
+val filter = DataStorage::productName eq record.productName

source/examples/generated/DataClassTest.snippet.retrieve-diff-data-class.kt

@@ -14,4 +14,4 @@ val result = collection
     .withDocumentClass<NewDataStorage>()
     .findOneAndUpdate(filter, update, options)
 
-println("Updated document: ${result}")
+println("Updated document: $result")

source/fundamentals/builders/filters.txt

@@ -62,7 +62,8 @@ type, which you can pass to any method that expects a query filter.
 
       import com.mongodb.client.model.Filters.*
 
-Most of the ``Filter`` examples in this guide use the following sample collection ``paints``:
+Most of the ``Filters`` examples in this guide use the following sample
+collection ``paints``:
 
 .. code-block:: json
 
@@ -81,6 +82,13 @@ with the Kotlin driver:
 .. literalinclude:: /examples/generated/FiltersBuildersTest.snippet.paint-order-data-class.kt
     :language: kotlin
 
+.. tip:: Filters and Data Class Properties
+
+   You can use methods from the ``Filters`` class directly with data class
+   properties. To learn more and view examples, see the
+   :ref:`kotlin-data-class-query` section of the Document Data Format:
+   Data Classes guide.
+
 .. _comparison:
 
 Comparison

source/fundamentals/data-formats/document-data-format-data-class.txt

@@ -14,12 +14,12 @@ Overview
 --------
 
 In this guide, you can learn how to store and retrieve data in the
-{+driver-long+} using **Kotlin data classes**.
+{+driver-long+} by using **{+language+} data classes**.
 
 Serialize and Deserialize a Data Class
 --------------------------------------
 
-The driver natively supports encoding and decoding Kotlin data classes for
+The driver natively supports encoding and decoding {+language+} data classes for
 MongoDB read and write operations using the **default codec registry**. The
 default codec registry is a collection of classes called **codecs** that
 define how to encode and decode Kotlin and Java types.
@@ -85,6 +85,30 @@ operation adds the ``releaseDate`` field to the document with a
 For more information about this feature, see :ref:`Specify Return Type
 <db-coll-specify-return-type>` in the Databases and Collections guide.
 
+.. _kotlin-data-class-query:
+
+Querying Data Classes
+---------------------
+
+You can use helpers from the ``Filters`` builders class to query on data
+class properties. To learn more about this class, see the
+:ref:`filters-builders` guide.
+
+The following code uses the ``Filters.eq()`` method to
+construct the same query on the ``DataStorage`` data class in multiple syntaxes:
+
+.. literalinclude:: /examples/generated/DataClassTest.snippet.filters-query-data-class.kt
+   :language: kotlin
+
+.. tip:: Filters and Data Class Annotations
+
+   When you use ``Filters`` class helpers to construct queries on data
+   classes, the methods respect your data class annotations from the
+   ``bson-kotlin`` and ``bson-kotlinx`` packages. To learn more about
+   annotations, see the :ref:`fundamentals-data-class-annotations`
+   section of this guide and the :ref:`kotlin-data-class-annotation`
+   section in the {+language+} Serialization guide.
+
 .. _fundamentals-data-class-annotations:
 
 Specify Component Conversion Using Annotations
@@ -105,7 +129,7 @@ You can use the following annotations on data classes:
      - Description
 
    * - ``BsonId``
-     - Marks a property to serialize as the _id property.
+     - Marks a property to serialize as the ``_id`` property.
 
    * - ``BsonProperty``
      - Specifies a custom document field name when converting the data class

source/usage-examples/updateMany.txt

@@ -56,7 +56,7 @@ bottom of this page.
 Example
 -------
 
-In this example, we use a ``Filter`` builder to filter our query for
+In this example, we use a ``Filters`` builder to filter our query for
 movies in the genre "Frequently Discussed". 
 
 Next, we update documents that match our query in the ``movies`` collection of the

source/usage-examples/updateOne.txt

@@ -54,7 +54,7 @@ bottom of this page.
 Example
 -------
 
-In this example, we use a ``Filter`` builder to query the collection for
+In this example, we use a ``Filters`` builder to query the collection for
 a movie with the title "Cool Runnings 2". 
 
 Next, we perform the following updates to the first match for our query

source/whats-new.txt

@@ -12,6 +12,7 @@ What's New
 
 Learn what's new in:
 
+* :ref:`Version 5.3 <kotlin-coroutine-version-5.3>`
 * :ref:`Version 5.2 <kotlin-coroutine-version-5.2>`
 * :ref:`Version 5.1.3 <kotlin-coroutine-version-5.1.3>`
 * :ref:`Version 5.1.2 <kotlin-coroutine-version-5.1.2>`
@@ -21,6 +22,20 @@ Learn what's new in:
 * :ref:`Version 4.11 <version-4.11>`
 * :ref:`Version 4.10 <version-4.10>`
 
+.. _kotlin-coroutine-version-5.3:
+
+What's New in 5.3
+-----------------
+
+The 5.3 driver release includes the following new features,
+improvements, and fixes:
+
+.. .. sharedinclude:: dbx/jvm/v5.3-wn-items.rst
+
+- Support for using builders class methods directly with data class
+  properties. To learn more, see the :ref:`fundamentals-data-classes`
+  guide and the :ref:`kotlin-builders-landing` guides.
+
 .. _kotlin-coroutine-version-5.2:
 
 What's New in 5.2