diff --git a/source/includes/read/distinct.kt b/source/includes/read/distinct.kt new file mode 100644 index 00000000..92f12d9c --- /dev/null +++ b/source/includes/read/distinct.kt @@ -0,0 +1,61 @@ +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.client.model.Filters.and +import com.mongodb.client.model.Filters.eq +import com.mongodb.kotlin.client.MongoClient + +// start-data-class +data class Restaurant( + 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-distinct + val results = collection.distinct(Restaurant::borough.name) + + results.forEach { result -> + println(result) + } + // end-distinct + + // start-distinct-query + val results = collection.distinct( + Restaurant::borough.name, + eq(Restaurant::cuisine.name, "Italian") + ) + + results.forEach { result -> + println(result) + } + // end-distinct-query + + // start-distinct-comment + val results = collection.distinct( + Restaurant::name.name, + and( + eq(Restaurant::borough.name, "Bronx"), + eq(Restaurant::cuisine.name, "Pizza") + ) + ).comment("Bronx pizza restaurants") + + results.forEach { result -> + println(result) + + } + // end-distinct-comment +} + diff --git a/source/read.txt b/source/read.txt index 8433061a..4800b259 100644 --- a/source/read.txt +++ b/source/read.txt @@ -27,6 +27,7 @@ Read Data from MongoDB /read/project /read/specify-documents-to-return /read/count + /read/distinct Overview -------- @@ -133,8 +134,8 @@ collection: :copyable: :dedent: -.. TODO: To learn more about the ``distinct()`` method, see the -.. :ref:`kotlin-sync-distinct` guide. +To learn more about the ``distinct()`` method, see the +:ref:`kotlin-sync-distinct` guide. Monitor Data Changes -------------------- diff --git a/source/read/distinct.txt b/source/read/distinct.txt new file mode 100644 index 00000000..0781bd19 --- /dev/null +++ b/source/read/distinct.txt @@ -0,0 +1,182 @@ +.. _kotlin-sync-distinct: + +============================== +Retrieve Distinct Field Values +============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, unique, code example + +Overview +-------- + +Within a collection, different documents might contain different values for a single field. +For example, one document in the ``restaurant`` collection has a ``borough`` value of ``"Manhattan"``, and +another has a ``borough`` value of ``"Queens"``. With the {+driver-short+}, you can +retrieve all the distinct values that a field contains across multiple documents +in a collection. + +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 following {+language+} data class models the documents in this collection: + +.. literalinclude:: /includes/read/distinct.kt + :start-after: start-data-class + :end-before: end-data-class + :language: kotlin + :copyable: + +``distinct()`` Method +--------------------- + +To retrieve the distinct values for a specified field, call the ``distinct()`` +method and pass in the name of the field you want to find distinct values for. + +Retrieve Distinct Values Across a Collection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example retrieves the distinct values of the ``borough`` field in +the ``restaurants`` collection: + +.. io-code-block:: + + .. input:: /includes/read/distinct.kt + :start-after: start-distinct + :end-before: end-distinct + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Bronx + Brooklyn + Manhattan + Missing + Queens + Staten Island + +The results show every distinct value that appears in the ``borough`` field +across all documents in the collection. Although several documents have the same +value in the ``borough`` field, each value appears in the results only once. + +Retrieve Distinct Values Across Specified Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can provide a **query filter** to the ``distinct()`` method to find the distinct +field values across a subset of documents in a collection. A query filter is an expression that specifies search +criteria used to match documents in an operation. For more information about +creating a query filter, see :ref:`kotlin-sync-specify-query`. + +The following example retrieves the distinct values of the ``borough`` field for +all documents that have a ``cuisine`` field value of ``"Italian"``: + +.. io-code-block:: + + .. input:: /includes/read/distinct.kt + :start-after: start-distinct-query + :end-before: end-distinct-query + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Bronx + Brooklyn + Manhattan + Queens + Staten Island + +Modify Distinct Behavior +~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``distinct()`` method can be modified by chaining methods to the ``distinct()`` method +call. If you don't specify any options, the driver does not customize the operation. + +The following table describes some methods you can use to customize the +``distinct()`` operation: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``batchSize()`` + - | Sets the number of documents to return per batch. + + * - ``collation()`` + - | Specifies the kind of language collation to use when sorting + results. For more information, see :manual:`Collation ` + in the {+mdb-server+} manual. + + * - ``comment()`` + - | Specifies a comment to attach to the operation. + + * - ``filter()`` + - | Sets the query filter to apply to the query. + + * - ``forEach()`` + - | Performs the given action on each element returned by the ``distinct()`` operation. + + * - ``maxTime()`` + - | Sets the maximum amount of time to allow the operation to run, in milliseconds. + +For a complete list of methods you can use to modify the ``distinct()`` method, see +the `DistinctIterable <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-distinct-iterable/index.html>`__ API documentation. + +The following example retrieves the distinct values of the ``name`` field for +all documents that have a ``borough`` field value of ``"Bronx"`` and a +``cuisine`` field value of ``"Pizza"``. It also uses +the ``comment`` option to add a comment to the operation. + +.. io-code-block:: + + .. input:: /includes/read/distinct.kt + :start-after: start-distinct-comment + :end-before: end-distinct-comment + :language: kotlin + :dedent: + + .. output:: + :visible: false + + $1.25 Pizza + 18 East Gunhill Pizza + 2 Bros + Aenos Pizza + Alitalia Pizza Restaurant + ... + +Additional Information +---------------------- + +To learn more about the distinct command, see the :manual:`Distinct 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: + +- `distinct() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/distinct.html>`__ +- `DistinctIterable <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-distinct-iterable/index.html>`__ \ No newline at end of file