DOCSP-36218: filters with dataclass properties

source/api.txt

@@ -0,0 +1,26 @@
+.. _kotlin-sync-api-docs:
+
+=================
+API Documentation
+=================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   {+language+} Sync Driver <{+java-api+}/apidocs/mongodb-driver-kotlin-sync/index.html>
+   BSON kotlinx.serialization <{+java-api+}/apidocs/bson-kotlinx/index.html>
+   {+language+} Driver Extensions <{+java-api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>
+   Driver Core <{+core-api+}/index.html>
+
+- `{+language+} Sync Driver <{+java-api+}/apidocs/mongodb-driver-kotlin-sync/index.html>`__ -
+  classes for the current synchronous driver API.
+- `BSON kotlinx.serialization <{+java-api+}/apidocs/bson-kotlinx/index.html>`__ -
+  classes for encoding and decoding between Kotlin data classes and the BSON data
+  format using :github:`kotlinx.serialization <Kotlin/kotlinx.serialization>`.
+- `{+language+} Driver Extensions
+  <{+java-api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ -
+  classes that extend the core builder classes to support :ref:`data
+  classes <kotlin-sync-builders-data-classes>`.
+- `Driver Core <{+core-api+}/index.html>`__ - classes that
+  contain essential driver functionality.

source/builders.txt

@@ -10,7 +10,9 @@ Use Builders Code Pattern
    :depth: 2
    :class: singlecol
 
-.. .. toctree::
+.. toctree::
+
+   Builders & Data Classes </builders/builders-data-classes>
 
 ..    /fundamentals/builders/aggregates
 ..    /fundamentals/builders/filters
@@ -28,6 +30,17 @@ benefits of using the provided builders.
 The {+driver-short+} provides type-safe builder classes and methods that enable developers to
 efficiently build queries and aggregations.
 
+To learn more about the available builder classes and methods, see the
+following API documentation sections:
+
+- `Accumulators <{+core-api+}/com/mongodb/client/model/Accumulators.html>`__
+- `Aggregates <{+core-api+}/com/mongodb/client/model/Aggregates.html>`__
+- `Filters <{+core-api+}/com/mongodb/client/model/Filters.html>`__
+- `Indexes <{+core-api+}/com/mongodb/client/model/Indexes.html>`__
+- `Projections <{+core-api+}/com/mongodb/client/model/Projections.html>`__
+- `Sorts <{+core-api+}/com/mongodb/client/model/Sorts.html>`__
+- `Updates <{+core-api+}/com/mongodb/client/model/Updates.html>`__
+
 Why Use Builders?
 -----------------
 
@@ -53,7 +66,7 @@ The following data class models the documents in the ``users`` collection:
    :copyable:
    :dedent:
 
-The following data class models the results returned by our query:
+The following data class models the results returned by the query:
 
 .. literalinclude:: /includes/builders/builders.kt
    :start-after: start-result-class
@@ -87,8 +100,12 @@ query filter:
    :copyable:
    :dedent:
 
-Builders
-~~~~~~~~
+In this case, you might easily include an error when writing the
+``"\$gt"`` operator in the filter, but your IDE returns the relevant
+error only at runtime.
+
+Builders API
+~~~~~~~~~~~~
 
 The following example performs the query by using the builder helpers:
 
@@ -99,6 +116,14 @@ The following example performs the query by using the builder helpers:
    :copyable:
    :dedent:
 
+Use Builders with Data Classes
+------------------------------
+
+The :ref:`kotlin-sync-builders-data-classes` guide provides examples on
+how to use the preceding builders classes directly with data class
+properties. This guide might help to make your application more type-safe
+and improve {+language+} interoperability.
+
 .. TODO: Uncomment as pages get built
 
 .. Available Builders

source/builders/builders-data-classes.txt

@@ -0,0 +1,262 @@
+.. _kotlin-sync-builders-data-classes:
+
+==============================
+Use Builders with Data Classes
+==============================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, data format, modeling, interoperability
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use your :ref:`Data Class
+<kotlin-sync-data-format-data-classes>` properties directly with the
+builder classes available in the {+driver-short+}.
+
+The {+driver-short+} implements extensions that allow you to reference
+your data class properties when using builder methods instead of using
+string field names. You can structure your code in this way to make your
+code more type-safe and improve your applications {+language+}
+interoperability.
+
+The extensions library also allows you to construct
+queries, update documents, and write other statements by using infix
+notation. To learn more about this notation, see `Infix notation
+<{+kotlin-docs+}/docs/functions.html#infix-notation>`__ in the
+{+language+} reference documentation.
+
+.. note::
+
+   This page provides a limited number of code
+   examples to demonstrate this functionality. To learn more about using
+   builder classes, see the :ref:`kotlin-sync-builders` guide.
+
+Add {+language+} Extensions to Your Project
+-------------------------------------
+
+To implement this functionality, you must add the
+``mongodb-driver-kotlin-extensions`` dependency to your dependencies
+list.
+
+Select from the following tabs to see how to add the extension
+dependency to your project by using the :guilabel:`Gradle` and
+:guilabel:`Maven` package managers:
+
+.. tabs::
+
+   .. tab::
+      :tabid: Gradle
+
+      If you are using `Gradle <https://gradle.org/>`__ to manage your 
+      dependencies, add the following to your ``build.gradle.kts`` dependencies list:
+
+      .. code-block:: kotlin
+         :caption: build.gradle.kts
+
+         implementation("org.mongodb:mongodb-driver-kotlin-extensions:{+full-version+}")
+
+   .. tab::
+      :tabid: Maven
+
+      If you are using `Maven <https://maven.apache.org/>`__ to manage your 
+      dependencies, add the following to your ``pom.xml`` dependencies list:
+
+      .. code-block:: xml
+         :caption: pom.xml
+
+         <dependency>
+             <groupId>org.mongodb</groupId>
+             <artifactId>mongodb-driver-kotlin-extensions</artifactId>
+             <version>{+full-version+}</version>
+         </dependency>
+
+After you install the extensions dependency, you can use the extension
+methods by importing classes and methods from the
+``com.mongodb.kotlin.client.model`` path. You can mix usage of these methods and
+the standard builder methods in the same application, as shown in the
+:ref:`kotlin-sync-data-class-aggregates` example in this guide.
+
+Builders Examples
+-----------------
+
+This section contains examples that demonstrate how to use data class
+properties directly with builder class methods from the extensions
+package.
+
+.. tip:: Data Class Annotations
+
+   When you the extension builder class methods 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:`kotlin-sync-data-class-annotations`
+   section of the Document Data Format: Data Classes guide.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this section use documents in the ``students``
+collection that describe students at a school. Documents in the
+``students`` collection are modeled by the following {+language+} data
+class:
+
+.. literalinclude:: /includes/builders/builders-data-class.kt
+   :language: kotlin
+   :start-after: start-data-class
+   :end-before: end-data-class
+   :dedent:
+
+.. _kotlin-sync-data-class-filters:
+
+Filters
+~~~~~~~
+
+You can use helpers from the ``Filters`` builders class to query on data
+class properties.
+
+The following code shows different ways to use ``Filters`` extension
+methods to perform queries on the ``Student`` data class:
+
+.. code-block:: kotlin
+
+   import com.mongodb.kotlin.client.model.Filters.eq
+   import com.mongodb.kotlin.client.model.Filters.all
+
+.. literalinclude:: /includes/builders/builders-data-class.kt
+   :language: kotlin
+   :start-after: start-filters-data-class
+   :end-before: end-filters-data-class
+   :dedent:
+
+.. _kotlin-sync-data-class-indexes:
+
+Indexes
+~~~~~~~
+
+You can use helpers from the ``Indexes`` builders class to create
+indexes on data class properties.
+
+The following code shows different ways to use ``Indexes`` extension
+methods to create indexes on the ``Student`` data class:
+
+.. code-block:: kotlin
+
+   import com.mongodb.kotlin.client.model.Indexes.ascending
+   import com.mongodb.kotlin.client.model.Indexes.descending
+
+.. literalinclude:: /includes/builders/builders-data-class.kt
+   :language: kotlin
+   :start-after: start-indexes-data-class
+   :end-before: end-indexes-data-class
+   :dedent:
+
+.. _kotlin-sync-data-class-projections:
+
+Projections
+~~~~~~~~~~~
+
+You can use helpers from the ``Projections`` builders class to create
+projections for data class properties.
+
+The following code shows how to use ``Projections`` extension
+methods to create a projection on the ``Student`` data class:
+
+.. code-block:: kotlin
+
+   import com.mongodb.kotlin.client.model.Projections.excludeId
+   import com.mongodb.kotlin.client.model.Projections.fields
+   import com.mongodb.kotlin.client.model.Projections.include
+
+.. literalinclude:: /includes/builders/builders-data-class.kt
+   :language: kotlin
+   :start-after: start-proj-data-class
+   :end-before: end-proj-data-class
+   :dedent:
+
+.. _kotlin-sync-data-class-sorts:
+
+Sorts
+~~~~~
+
+You can use helpers from the ``Sorts`` builders class to sort
+on your data class properties.
+
+The following code shows how to use ``Sorts`` extension
+methods to create different sorts on the ``Student`` data class:
+
+.. code-block:: kotlin
+
+   import com.mongodb.client.model.Sorts.orderBy
+   import com.mongodb.kotlin.client.model.Sorts
+
+.. literalinclude:: /includes/builders/builders-data-class.kt
+   :language: kotlin
+   :start-after: start-sorts-data-class
+   :end-before: end-sorts-data-class
+   :dedent:
+
+.. _kotlin-sync-data-class-updates:
+
+Updates
+~~~~~~~
+
+You can use helpers from the ``Updates`` builders class to perform
+updates by using your data class properties.
+
+The following code shows how to use ``Sorts`` extension
+methods to create different sorts on the ``Student`` data class:
+
+.. code-block:: kotlin
+
+   import com.mongodb.kotlin.client.model.Filters.gte
+   import com.mongodb.kotlin.client.model.Updates.addToSet
+   import com.mongodb.kotlin.client.model.Updates.combine
+   import com.mongodb.kotlin.client.model.Updates.max
+
+.. literalinclude:: /includes/builders/builders-data-class.kt
+   :language: kotlin
+   :start-after: start-updates-data-class
+   :end-before: end-updates-data-class
+   :dedent:
+
+.. _kotlin-sync-data-class-aggregates:
+
+Aggregates
+~~~~~~~~~~
+
+You can use helpers from the ``Aggregates`` and ``Accumulators``
+builders classes to perform aggregations by using you data class
+properties.
+
+The following code shows how to use ``Accumulators`` extension
+methods and ``Aggregates`` helper methods to perform an aggregation on
+the ``Student`` data class:
+
+.. code-block:: kotlin
+
+   import com.mongodb.client.model.Aggregates.group
+   import com.mongodb.client.model.Aggregates.limit
+   import com.mongodb.client.model.Aggregates.sort
+   import com.mongodb.kotlin.client.model.Accumulators.avg
+
+.. literalinclude:: /includes/builders/builders-data-class.kt
+   :language: kotlin
+   :start-after: start-agg-data-class
+   :end-before: end-agg-data-class
+   :dedent:
+
+API Documentation
+-----------------
+
+- `{+driver-short+} Extensions
+  <{+core-api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__

source/data-formats.txt

@@ -21,12 +21,12 @@ Specialized Data Formats
    :titlesonly:
    :maxdepth: 1
 
+   Data Classes </data-formats/data-format-data-class>
    Kotlin Serialization </data-formats/serialization>
    Codecs </data-formats/codecs>
    BSON </data-formats/bson>
    Time Series </data-formats/time-series>
 
-..     TODO: /data-formats/data-class
 ..     TODO: /data-formats/extended-json
 
 Overview
@@ -46,9 +46,10 @@ You can use several types of specialized document data formats in your
 application. To learn how to work with these data formats, see the following
 sections:
 
+- Learn how to model your documents as {+language+} data classes in the
+  :ref:`kotlin-sync-data-format-data-classes` guide.
 - Learn how to work with the BSON data format in the :ref:`kotlin-sync-bson` guide.
 - Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.
 
 .. TODO: Uncomment these as pages get built
-.. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide.
 .. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide.