diff --git a/snooty.toml b/snooty.toml index 301fa399..314aed4f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -14,6 +14,7 @@ toc_landing_pages = [ "/indexes", "work-with-indexes", "/data-formats", + "/builders", "/aggregation" ] diff --git a/source/builders.txt b/source/builders.txt new file mode 100644 index 00000000..11c66f95 --- /dev/null +++ b/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 ` for building aggregation pipelines. +.. - :ref:`Filters ` for building query filters. +.. - :ref:`Indexes ` for creating index keys. +.. - :ref:`Projections ` for building projections. +.. - :ref:`Sorts ` for building sort criteria. +.. - :ref:`Updates ` for building updates. \ No newline at end of file diff --git a/source/includes/builders/builders.kt b/source/includes/builders/builders.kt new file mode 100644 index 00000000..24aeb2f5 --- /dev/null +++ b/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 = "" + + 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("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(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(filter).projection(projection) + // end-find-builders +} + diff --git a/source/index.txt b/source/index.txt index 46f78670..e4159fb5 100644 --- a/source/index.txt +++ b/source/index.txt @@ -21,6 +21,7 @@ /aggregation Use Aggregation Expression Operations /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 ---