DOCSP-41161: Builders landing page

snooty.toml

@@ -13,7 +13,8 @@ toc_landing_pages = [
     "/connect",
     "/indexes",
     "work-with-indexes",
-    "/data-formats"
+    "/data-formats",
+    "/builders"
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/builders.txt

@@ -0,0 +1,110 @@
+.. _kotlin-sync-builders:
+
+================
+Use Builders API
+================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. .. toctree::
+
+..    /fundamentals/builders/aggregates
+..    /fundamentals/builders/filters
+..    /fundamentals/builders/indexes
+..    /fundamentals/builders/projections
+..    /fundamentals/builders/sort
+..    /fundamentals/builders/updates
+
+Overview
+--------
+
+This page describes how to use the builders API and demonstrates the utility provided by
+builder classes.
+
+The {+driver-short+} provides type-safe classes and methods that enable developers to
+efficiently build queries and aggregations.
+
+Why Use Builders?
+-----------------
+
+When using the MongoDB shell or plain Kotlin to construct BSON query documents, you are not
+able to identify errors in your code until runtime.
+
+With builder classes, you can write operators as methods and any syntax errors will be
+caught at compile time.
+
+Example
+-------
+
+This section describes three methods of fetching the ``email`` field values of documents
+in the ``users`` collection that meet the following criteria:
+
+- Users that identify as ``female``
+- Users that are older than ``29``
+
+The following data class models the documents in the ``users`` collection:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-user-class
+   :end-before: end-user-class
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+The following data class models the results returned by our query:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-result-class
+   :end-before: end-result-class
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Using the MongoDB Shell
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The following sample executes the previously defined query using the MongoDB shell:
+
+.. code-block:: js
+
+   collection.find({ "gender": "female", "age" : { "$gt": 29 }}, { "_id": 0, "email": 1 })
+
+Without Using Builders
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following example executes the previously defined query using plain {+language+}:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-find
+   :end-before: end-find
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Using Builders
+~~~~~~~~~~~~~~
+
+The following example executes the previously defined query using the builders API:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-find-builders
+   :end-before: end-find-builders
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. TODO: Uncomment as pages get built
+
+.. Available Builders
+.. ------------------
+
+.. - :ref:`Aggregates <aggregates-builders>` for building aggregation pipelines.
+.. - :ref:`Filters <filters-builders>` for building query filters.
+.. - :ref:`Indexes <indexes-builders>` for creating index keys.
+.. - :ref:`Projections <projections-builders>` for building projections. 
+.. - :ref:`Sorts <sorts-builders>` for building sort criteria.
+.. - :ref:`Updates <updates-builders>` for building updates.

source/includes/builders/builders.kt

@@ -0,0 +1,58 @@
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.client.model.Filters
+import com.mongodb.client.model.Projections
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.Document
+import org.bson.codecs.pojo.annotations.BsonId
+import org.bson.types.ObjectId
+
+// start-user-class
+data class User(
+    @BsonId
+    val id: ObjectId,
+    val gender: String,
+    val age: Int,
+    val email: String
+)
+// end-user-class
+
+// start-result-class
+data class Result(
+    val email: String
+)
+// end-result-class
+
+fun main() {
+    val uri = "<connection string URI>"
+
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .retryWrites(true)
+        .build()
+
+    val mongoClient = MongoClient.create(settings)
+    val database = mongoClient.getDatabase("sample_restaurants")
+    val collection = database.getCollection<User>("restaurants")
+
+    // start-find
+    val filter = Document("gender", "female").append("age", Document("\$gt", 29))
+    val projection = Document("_id", 0).append("email", 1)
+    val results = collection.find<Result>(filter).projection(projection)
+    // end-find
+
+    // start-find-builders
+    val filter = Filters.and(
+        Filters.eq(User::gender.name, "female"),
+        Filters.gt(User::age.name, 29)
+    )
+
+    val projection = Projections.fields(
+        Projections.excludeId(),
+        Projections.include("email")
+    )
+
+    val results = collection.find<Result>(filter).projection(projection)
+    // end-find-builders
+}
+

source/index.txt

@@ -19,6 +19,7 @@
    /read
    /indexes
    /data-formats
+   /builders
    /faq
    /connection-troubleshooting
    /issues-and-help
@@ -84,6 +85,11 @@ Specialized Data Formats
 Learn how to work with specialized data formats and custom types in the
 :ref:`kotlin-sync-data-formats` section.
 
+Use Builders API
+----------------
+
+Learn how to work with the builders pattern in the :ref:`kotlin-sync-builders` section.
+
 FAQ
 ---