DOCSP-45198: Distinct values

source/includes/read/distinct.rb

@@ -0,0 +1,44 @@
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'mongo'
+end
+
+uri = '<connection string>'
+
+Mongo::Client.new(uri) do |client|
+  # Access the database and collection
+  # start-db-coll
+  database = client.use('sample_restaurants')
+  collection = database[:restaurants]
+  # end-db-coll
+
+  # Retrieves distinct values of the "borough" field
+  # start-distinct
+  results = collection.distinct('borough')
+  results.each do |value|
+    puts value
+  end
+  # end-distinct
+
+  # Retrieves distinct "borough" field values for documents with a "cuisine" value of "Italian"
+  # start-distinct-with-query
+  results = collection.distinct('borough', { cuisine: 'Italian' })
+  results.each do |value|
+    puts value
+  end
+  # end-distinct-with-query
+
+  # Retrieves distinct "name" field values for documents matching the "borough" and "cuisine" fields query
+  # and uses primary preferred read preference
+  # start-distinct-with-opts
+  filter = { borough: 'Bronx', cuisine: 'Pizza' }
+  options = { read: { mode: :primary_preferred } }
+  results = collection.distinct('name', filter, options)
+
+  results.each do |value|
+    puts value
+  end
+  # end-distinct-with-opts
+end

source/read.txt

@@ -25,3 +25,4 @@ Read Data from MongoDB
    Retrieve Data </read/retrieve>
    Specify Documents to Return </read/specify-documents-to-return>
    Specify Fields to Return </read/project>
+   Distinct Field Values </read/project>

source/read/distinct.txt

@@ -0,0 +1,182 @@
+.. _ruby-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
+--------
+
+In this guide, you can learn how to use the {+driver-short+} to retrieve the
+distinct values of a specified field across a collection.
+
+Within a collection, different documents might contain different values for a
+single field. For example, one document in a ``restaurants`` collection has a
+``borough`` value of ``'Manhattan'``, and another has a ``borough`` value of
+``'Queens'``. By using the {+driver-short+}, you can retrieve all the unique 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 access this collection
+from your {+language+} application, create a ``Mongo::Client`` object that connects to
+an Atlas cluster and assign the following values to your ``database`` and ``collection``
+variables:
+
+.. literalinclude:: /includes/read/distinct.rb
+    :language: ruby
+    :dedent:
+    :start-after: start-db-coll
+    :end-before: end-db-coll
+
+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.
+
+Retrieve Distinct Values
+------------------------
+
+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 Values Across a Collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following example retrieves the distinct values of the ``borough`` field in
+the ``restaurants`` collection:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/distinct.rb
+      :start-after: start-distinct
+      :end-before: end-distinct
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Bronx
+      Brooklyn
+      Manhattan
+      Missing
+      Queens
+      Staten Island
+
+The operation returns an array that stores each distinct ``borough`` field value. Although
+several documents have the same value in the ``borough`` field, each value appears in the
+results only once.
+
+Retrieve 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. 
+
+.. TODO: To learn more about creating a query filter, see the :ref:`ruby-specify-query` guide.
+
+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::
+   :copyable:
+
+   .. input:: /includes/read/distinct.rb
+      :start-after: start-distinct-with-query
+      :end-before: end-distinct-with-query
+      :language: ruby
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      Bronx
+      Brooklyn
+      Manhattan
+      Queens
+      Staten Island
+
+Modify Distinct Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can modify the behavior of the ``distinct`` method by passing a
+``Hash`` object that specifies option values. The following table describes the
+options you can set to customize the operation:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+
+   * - ``collation`` 
+     - | The collation to use for the operation.
+       | **Type**: ``Hash``
+
+   * - ``max_time_ms``
+     - | The maximum amount of time in milliseconds that the operation can run.
+       | **Type**: ``Integer``
+
+   * - ``read``
+     - | The read preference to use for the operation. To learn more, see
+         :manual:`Read Preference </core/read-preference/>` in the {+mdb-server+} manual.
+       | **Type**: ``Hash``
+
+   * - ``session``
+     - | The session to use for the operation.
+       | **Type**: ``Session``
+
+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 sets the ``read`` option,
+which instructs the operation to use a ``primary_preferred``
+read preference:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/distinct.rb
+      :start-after: start-distinct-with-opts
+      :end-before: end-distinct-with-opts
+      :language: ruby
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      $1.25 Pizza
+      18 East Gunhill Pizza
+      2 Bros
+      Aenos Pizza
+      Alitalia Pizza Restaurant
+      Amici Pizza And Pasta
+      Angie'S Cafe Pizza
+      Anthony & Joe'S Pizza
+      Anthony'S Pizza
+      Antivari Pizza
+      Arturo'S Pizza
+      Bartow Pizza
+      ...
+
+API Documentation
+-----------------
+
+To learn more about the ``distinct`` method, see the
+`API documentation. <{+api-root+}/Mongo/Collection.html#distinct-instance_method>`__