DOCSP-41138: Distinct

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 = "<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<Restaurant>("restaurants")
+
+    // start-distinct
+    val results = collection.distinct<String>(Restaurant::borough.name)
+
+    results.forEach { result ->
+        println(result)
+    }
+    // end-distinct
+
+    // start-distinct-query
+    val results = collection.distinct<String>(
+        Restaurant::borough.name,
+        eq(Restaurant::cuisine.name, "Italian")
+    )
+
+    results.forEach { result ->
+        println(result)
+    }
+    // end-distinct-query
+
+    // start-distinct-comment
+    val results = collection.distinct<String>(
+        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
+}
+

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
 --------------------

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 </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` 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 </reference/collation/#std-label-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
+</reference/command/distinct/>` 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>`__