diff --git a/source/includes/read/project.kt b/source/includes/read/project.kt new file mode 100644 index 0000000..50a6d37 --- /dev/null +++ b/source/includes/read/project.kt @@ -0,0 +1,68 @@ +package org.example +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.client.model.Filters.eq +import com.mongodb.client.model.Projections +import com.mongodb.kotlin.client.MongoClient +import org.bson.codecs.pojo.annotations.BsonId +import org.bson.types.ObjectId + +// start-data-class +data class Restaurant( + @BsonId + val id: ObjectId? = null, + val name: String, + val borough: String, + val cuisine: String +) +// end-data-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-project + val projection = Projections.fields( + Projections.include( + Restaurant::name.name, + Restaurant::cuisine.name, + Restaurant::borough.name + ) + ) + + val results = collection + .find(eq(Restaurant::name.name, "Emerald Pub")) + .projection(projection) + + results.forEach { result -> + println(result) + } + // end-project + + // start-project-exclude + val projection = Projections.fields( + Projections.excludeId(), + Projections.include( + Restaurant::name.name, + Restaurant::cuisine.name, + Restaurant::borough.name + ) + ) + + val results = collection + .find(eq(Restaurant::name.name, "Emerald Pub")) + .projection(projection) + + results.forEach { result -> + println(result) + } + // end-project-exclude +} diff --git a/source/read.txt b/source/read.txt index 0cdf1f5..f6931cd 100644 --- a/source/read.txt +++ b/source/read.txt @@ -23,6 +23,7 @@ Read Data from MongoDB :maxdepth: 1 /read/count + /read/project Overview -------- diff --git a/source/read/project.txt b/source/read/project.txt new file mode 100644 index 0000000..c77d06c --- /dev/null +++ b/source/read/project.txt @@ -0,0 +1,127 @@ +.. _kotlin-sync-project: + +======================== +Specify Fields To Return +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, filter, project, select + +Overview +-------- + +In this guide, you can learn how to specify which fields to return from a read +operation by using a **projection**. A projection is a document that specifies +which fields MongoDB returns from a query. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +The documents in this collection are modeled by the following {+language+} data class: + +.. literalinclude:: /includes/read/project.kt + :start-after: start-data-class + :end-before: end-data-class + :language: kotlin + :copyable: + +Projection Types +---------------- + +You can use a projection to specify which fields to include in a return +document, or to specify which fields to exclude. + +When specifying certain fields to include in a projection, all other fields are implicitly +excluded (except the ``_id`` field, which is included by default). You cannot combine +inclusion and exclusion statements in a single projection, unless you are excluding the +``_id`` field. + +To remove the ``_id`` field from the returned document, you must +:ref:`explicitly exclude it `. + +Specify Fields to Include +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the following syntax to specify the fields to include in the result: + +.. code-block:: kotlin + + val projection = Projection.fields( + Projections.include(, , ...) + ) + +The following example uses the ``find()`` method to find all restaurants with +the ``name`` field value of ``"Emerald Pub"``. It then uses a projection to +return only the ``name``, ``cuisine``, and ``borough`` fields of the returned +documents. + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/project.kt + :start-after: start-project + :end-before: end-project + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Restaurant(id=5eb3d668b31de5d588f429e2, name=Emerald Pub, borough=Manhattan, cuisine=American) + Restaurant(id=5eb3d668b31de5d588f432dd, name=Emerald Pub, borough=Queens, cuisine=American) + +.. _kotlin-sync-project-exclude-id: + +Exclude the ``_id`` Field +~~~~~~~~~~~~~~~~~~~~~~~~~ + +When specifying fields to include, you can also exclude the ``_id`` field from +the returned document. + +The following example runs the same query as the preceding example, but +excludes the ``_id`` field from the projection: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/project.kt + :start-after: start-project-exclude + :end-before: end-project-exclude + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Restaurant(id=null, name=Emerald Pub, borough=Manhattan, cuisine=American) + Restaurant(id=null, name=Emerald Pub, borough=Queens, cuisine=American) + +Additional Information +---------------------- + +To learn more about projections, see the :manual:`Project Fields guide +` in the MongoDB Server Manual. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API Documentation: + +- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ +- `projection() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/projection.html>`__ \ No newline at end of file