DOCSP-41161: Builders landing page (mongodb#28)

Author: mcmorisi

snooty.toml

@@ -14,6 +14,7 @@ toc_landing_pages = [
     "/indexes",
     "work-with-indexes",
     "/data-formats",
+    "/builders",
     "/aggregation"
 ]
 

source/builders.txt

@@ -0,0 +1,115 @@
+.. _kotlin-sync-builders:
+
+=========================
+Use Builders Code Pattern
+=========================
+
+.. 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 various available builders in your code and describes
+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.
+
+Why Use Builders?
+-----------------
+
+If you use only plain {+language+} to construct BSON query documents, you are not
+able to identify syntax errors until runtime. The builders help ensure the corretness of
+syntax and can be less verbose than constructing BSON documents.
+
+Example
+-------
+
+This section provides three equivalent ways to fetch the ``email`` field values of documents
+in the ``users`` collection that meet the following criteria:
+
+- ``gender`` value is ``"female"``
+- ``age`` value is greater 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:
+
+MongoDB Query API
+~~~~~~~~~~~~~~~~~
+
+The following sample performs the query by using the MongoDB Query API:
+
+.. code-block:: js
+
+   collection.find(
+       { "gender": "female", "age" : { "$gt": 29 }},
+       { "_id": 0, "email": 1 }
+   )
+
+Document Class Filter
+~~~~~~~~~~~~~~~~~~~~~
+
+The following example performs the query by using the ``Document`` class to construct the
+query filter:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-find
+   :end-before: end-find
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Builders
+~~~~~~~~
+
+The following example performs the query by using the builder helpers:
+
+.. 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
+.. ------------------
+
+.. The following pages describe how to implement the different classes of builders
+.. available in the {+driver-short+}.
+
+.. - :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,57 @@
+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 Email(
+    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<Email>(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<Email>(filter).projection(projection)
+    // end-find-builders
+}
+

source/index.txt

@@ -21,6 +21,7 @@
    /aggregation
    Use Aggregation Expression Operations </agg-exp-ops>
    /data-formats
+   /builders
    /faq
    /connection-troubleshooting
    /issues-and-help
@@ -96,6 +97,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 builder operation helpers in the :ref:`kotlin-sync-builders` section.
+
 FAQ
 ---