From 03bf5c04b4334af040d54be64ac1f7cd694420ba Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 19 Dec 2024 11:00:49 -0500 Subject: [PATCH 1/3] DOCSP-45198: Distinct values --- source/includes/read/distinct.rb | 44 ++++++++ source/read.txt | 1 + source/read/distinct.txt | 182 +++++++++++++++++++++++++++++++ 3 files changed, 227 insertions(+) create mode 100644 source/includes/read/distinct.rb create mode 100644 source/read/distinct.txt diff --git a/source/includes/read/distinct.rb b/source/includes/read/distinct.rb new file mode 100644 index 00000000..7aa64a06 --- /dev/null +++ b/source/includes/read/distinct.rb @@ -0,0 +1,44 @@ +require 'bundler/inline' + +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = '' + +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 diff --git a/source/read.txt b/source/read.txt index 316d2bce..d3b98c6f 100644 --- a/source/read.txt +++ b/source/read.txt @@ -25,3 +25,4 @@ Read Data from MongoDB Retrieve Data Specify Documents to Return Specify Fields to Return + Distinct Field Values diff --git a/source/read/distinct.txt b/source/read/distinct.txt new file mode 100644 index 00000000..279bce6d --- /dev/null +++ b/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 `. 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 ` 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 ` in the 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>`__ \ No newline at end of file From f8d0606c776a28d419b4cf397b0f4f26e8bb7cc1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 19 Dec 2024 11:35:22 -0500 Subject: [PATCH 2/3] edits --- source/read/distinct.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read/distinct.txt b/source/read/distinct.txt index 279bce6d..f23da01e 100644 --- a/source/read/distinct.txt +++ b/source/read/distinct.txt @@ -136,7 +136,7 @@ options you can set to customize the operation: * - ``read`` - | The read preference to use for the operation. To learn more, see - :manual:`Read Preference ` in the Server manual. + :manual:`Read Preference ` in the {+mdb-server+} manual. | **Type**: ``Hash`` * - ``session`` From 86f80df17264a037e3941761bfeb9d5751789599 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 19 Dec 2024 16:11:31 -0500 Subject: [PATCH 3/3] RR feedback --- source/read.txt | 2 +- source/read/distinct.txt | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/read.txt b/source/read.txt index d3b98c6f..92083923 100644 --- a/source/read.txt +++ b/source/read.txt @@ -25,4 +25,4 @@ Read Data from MongoDB Retrieve Data Specify Documents to Return Specify Fields to Return - Distinct Field Values + Distinct Field Values diff --git a/source/read/distinct.txt b/source/read/distinct.txt index f23da01e..d6d142ed 100644 --- a/source/read/distinct.txt +++ b/source/read/distinct.txt @@ -23,10 +23,10 @@ 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 +Within a collection, 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 +``'Queens'``. You can use the {+driver-short+} to retrieve all the unique values that a field contains across multiple documents in a collection. Sample Data @@ -39,10 +39,10 @@ an Atlas cluster and assign the following values to your ``database`` and ``coll variables: .. literalinclude:: /includes/read/distinct.rb - :language: ruby - :dedent: - :start-after: start-db-coll - :end-before: end-db-coll + :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 ` guide.