From 1a32205613319a80fd826d0e865b656ff57c3578 Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Tue, 20 Aug 2024 14:00:23 -0400
Subject: [PATCH 1/6] DOCSP-41979: Distinct values

---
 source/includes/read/distinct.php |  40 ++++++++
 source/read.txt                   |   3 +-
 source/read/distinct.txt          | 159 ++++++++++++++++++++++++++++++
 3 files changed, 201 insertions(+), 1 deletion(-)
 create mode 100644 source/includes/read/distinct.php
 create mode 100644 source/read/distinct.txt

diff --git a/source/includes/read/distinct.php b/source/includes/read/distinct.php
new file mode 100644
index 00000000..a6ee53b5
--- /dev/null
+++ b/source/includes/read/distinct.php
@@ -0,0 +1,40 @@
+<?php
+require 'vendor/autoload.php';
+
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
+$client = new MongoDB\Client($uri);
+
+// start-db-coll
+$db = $client->sample_training;
+$collection = $db->companies;
+// end-db-coll
+
+// Finds one document with a "name" value of "LinkedIn"
+// start-find-one
+$document = $collection->findOne(['name' => 'LinkedIn']);
+echo json_encode($document) . "\n";
+// end-find-one
+
+// Finds documents with a "founded_year" value of 1970
+// start-find-many
+$results = $collection->find(['founded_year' => 1970]);
+// end-find-many
+
+// Prints documents with a "founded_year" value of 1970
+// start-cursor
+foreach ($results as $doc) {
+    echo json_encode($doc) . "\n";
+}
+// end-cursor
+
+// Finds and prints up to 5 documents with a "number_of_employees" value of 1000
+// start-modify
+$results = $collection->find(
+    ['number_of_employees' => 1000],
+    ['limit' => 5]
+);
+
+foreach ($results as $doc) {
+    echo json_encode($doc) . "\n";
+}
+// end-modify
diff --git a/source/read.txt b/source/read.txt
index eb974b7f..004375ca 100644
--- a/source/read.txt
+++ b/source/read.txt
@@ -8,4 +8,5 @@ Read Data from MongoDB
    :titlesonly:
    :maxdepth: 1
 
-   /read/retrieve
\ No newline at end of file
+   /read/retrieve
+   /read/distint
\ No newline at end of file
diff --git a/source/read/distinct.txt b/source/read/distinct.txt
new file mode 100644
index 00000000..889b3e36
--- /dev/null
+++ b/source/read/distinct.txt
@@ -0,0 +1,159 @@
+.. _php-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 {+php-library+} 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 {+php-library+}, 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 PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
+and assign the following value to your ``collection`` variable:
+
+.. literalinclude:: /includes/read/distinct.php
+    :language: php
+    :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.
+
+``MongoDB\\Collection::distinct()`` Method
+------------------------------------------
+
+To retrieve the distinct values for a specified field, call the ``MongoDB\Collection::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.php
+      :start-after: start-distinct
+      :end-before: end-distinct
+      :language: php
+      :dedent:
+
+   .. output:: 
+
+      { "values" : [ "Bronx", "Brooklyn", "Manhattan", "Missing", "Queens", "Staten Island" ],
+      "ok" : 1.0, "$clusterTime" : { "clusterTime" : { "$timestamp" : { ... } },
+      "signature" : { "hash" : { ... }, "keyId" : ... } }, "operationTime" : { "$timestamp" : { ... } }
+
+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 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 the :ref:`php-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::
+
+   .. input:: /includes/read/distinct.php
+      :start-after: start-distinct-with-query
+      :end-before: end-distinct-with-query
+      :language: php
+      :dedent:
+
+   .. output:: 
+
+      { "values" : [ "Bronx", "Brooklyn", "Manhattan", "Queens", "Staten Island" ],
+      "ok" : 1.0, "$clusterTime" : { "clusterTime" : { "$timestamp" : { ... },
+      "signature" : { "hash" : { ... }, "keyId" : ... } }, "operationTime" : { "$timestamp" : { ... } }
+
+Modify Distinct Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can modify the behavior of the ``MongoDB\Collection::distinct()`` method by
+passing an array that specifies option values. The following table describes some
+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**: ``array|object``
+
+   * - ``maxTimeMS``
+     - | The maximum amount of time in milliseconds that the operation can run.
+       | **Type**: ``integer``
+
+   * - ``comment`` 
+     - | The comment to attach to the operation.
+       | **Type**: any valid BSON type
+
+   * - ``readPreference``
+     - | The read preference to use for the operation. To learn more, see
+         :manual:`Read Preference </core/read-preference/>` in the Server manual.
+       | **Type**: ``MongoDB\Driver\ReadPreference``
+
+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 specifies the ``comment`` field
+in an options array to add a comment to the operation:
+
+.. io-code-block::
+
+   .. input:: /includes/read/distinct.php
+      :start-after: start-distinct-with-comment
+      :end-before: end-distinct-with-comment
+      :language: php
+      :dedent:
+
+   .. output:: 
+
+      { "values" : [ "$1.25 Pizza", "18 East Gunhill Pizza", "2 Bros", "Aenos Pizza", "Alitalia Pizza Restaurant", … ], 
+        "ok" : 1.0, "$clusterTime" : { "clusterTime" : { … }, "signature" : { … }, "keyId" : … } }, "operationTime" : { … } }
+
+API Documentation
+-----------------
+
+To learn more about the ``MongoDB\Collection::distinct()`` method, see the following
+API documentation:
+
+- `distinct() <{+api+}/method/MongoDBCollection-distinct/>`__
\ No newline at end of file

From 4dd9f25fedc5172f5f893bc163b09b099bbff65d Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Tue, 20 Aug 2024 14:25:01 -0400
Subject: [PATCH 2/6] edits

---
 source/includes/read/distinct.php | 54 +++++++++++++++----------------
 source/read.txt                   |  2 +-
 source/read/distinct.txt          | 37 ++++++++++++++-------
 3 files changed, 54 insertions(+), 39 deletions(-)

diff --git a/source/includes/read/distinct.php b/source/includes/read/distinct.php
index a6ee53b5..f04c23aa 100644
--- a/source/includes/read/distinct.php
+++ b/source/includes/read/distinct.php
@@ -1,40 +1,40 @@
 <?php
 require 'vendor/autoload.php';
 
+use MongoDB\BSON\Document;
+
 $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
 $client = new MongoDB\Client($uri);
 
 // start-db-coll
-$db = $client->sample_training;
-$collection = $db->companies;
+$collection = $client->sample_restaurants->restaurants;
 // end-db-coll
 
-// Finds one document with a "name" value of "LinkedIn"
-// start-find-one
-$document = $collection->findOne(['name' => 'LinkedIn']);
-echo json_encode($document) . "\n";
-// end-find-one
-
-// Finds documents with a "founded_year" value of 1970
-// start-find-many
-$results = $collection->find(['founded_year' => 1970]);
-// end-find-many
-
-// Prints documents with a "founded_year" value of 1970
-// start-cursor
-foreach ($results as $doc) {
-    echo json_encode($doc) . "\n";
+// Retrieves distinct values of the "borough" field
+// start-distinct
+$results = $collection->distinct('borough', []);
+foreach ($results as $value) {
+    echo json_encode($value) . PHP_EOL;
+}
+// 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']);
+foreach ($results as $value) {
+    echo json_encode($value) . PHP_EOL;
 }
-// end-cursor
+// end-distinct-with-query
 
-// Finds and prints up to 5 documents with a "number_of_employees" value of 1000
-// start-modify
-$results = $collection->find(
-    ['number_of_employees' => 1000],
-    ['limit' => 5]
-);
+// Retrieves distinct "name" field values for documents matching the "borough" and "cuisine" fields query
+// and attaches a comment to the operation
+// start-distinct-with-comment
+$options = ['comment' => 'Bronx pizza restaurants'];
+$query = ['$and' => [['borough' => 'Bronx'], ['cuisine' => 'Pizza']]];
+$results = $collection->distinct('name', $query, $options);
 
-foreach ($results as $doc) {
-    echo json_encode($doc) . "\n";
+foreach ($results as $value) {
+    echo json_encode($value) . PHP_EOL;
 }
-// end-modify
+// end-distinct-with-comment
+
diff --git a/source/read.txt b/source/read.txt
index 004375ca..4876ecce 100644
--- a/source/read.txt
+++ b/source/read.txt
@@ -9,4 +9,4 @@ Read Data from MongoDB
    :maxdepth: 1
 
    /read/retrieve
-   /read/distint
\ No newline at end of file
+   /read/distinct
\ No newline at end of file
diff --git a/source/read/distinct.txt b/source/read/distinct.txt
index 889b3e36..85c45ce8 100644
--- a/source/read/distinct.txt
+++ b/source/read/distinct.txt
@@ -25,8 +25,8 @@ 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 {+php-library+}, you can retrieve all the unique values
+``borough`` value of ``'Manhattan'``, and another has a ``borough`` value of
+``'Queens'``. By using the {+php-library+}, you can retrieve all the unique values
 that a field contains across multiple documents in a collection.
 
 Sample Data
@@ -59,6 +59,7 @@ The following example retrieves the distinct values of the ``borough`` field in
 the ``restaurants`` collection:
 
 .. io-code-block::
+   :copyable:
 
    .. input:: /includes/read/distinct.php
       :start-after: start-distinct
@@ -67,10 +68,13 @@ the ``restaurants`` collection:
       :dedent:
 
    .. output:: 
+      :visible: false
 
-      { "values" : [ "Bronx", "Brooklyn", "Manhattan", "Missing", "Queens", "Staten Island" ],
-      "ok" : 1.0, "$clusterTime" : { "clusterTime" : { "$timestamp" : { ... } },
-      "signature" : { "hash" : { ... }, "keyId" : ... } }, "operationTime" : { "$timestamp" : { ... } }
+      "Bronx"
+      "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
@@ -88,6 +92,7 @@ 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.php
       :start-after: start-distinct-with-query
@@ -96,10 +101,12 @@ all documents that have a ``cuisine`` field value of ``'Italian'``:
       :dedent:
 
    .. output:: 
+      :visible: false
 
-      { "values" : [ "Bronx", "Brooklyn", "Manhattan", "Queens", "Staten Island" ],
-      "ok" : 1.0, "$clusterTime" : { "clusterTime" : { "$timestamp" : { ... },
-      "signature" : { "hash" : { ... }, "keyId" : ... } }, "operationTime" : { "$timestamp" : { ... } }
+      "Bronx"
+      "Manhattan"
+      "Queens"
+      "Staten Island"
 
 Modify Distinct Behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -138,6 +145,7 @@ all documents that have a ``borough`` field value of ``'Bronx'`` and a
 in an options array to add a comment to the operation:
 
 .. io-code-block::
+   :copyable:
 
    .. input:: /includes/read/distinct.php
       :start-after: start-distinct-with-comment
@@ -146,9 +154,16 @@ in an options array to add a comment to the operation:
       :dedent:
 
    .. output:: 
-
-      { "values" : [ "$1.25 Pizza", "18 East Gunhill Pizza", "2 Bros", "Aenos Pizza", "Alitalia Pizza Restaurant", … ], 
-        "ok" : 1.0, "$clusterTime" : { "clusterTime" : { … }, "signature" : { … }, "keyId" : … } }, "operationTime" : { … } }
+      :visible: false
+
+      "$1.25 Pizza"
+      "18 East Gunhill Pizza"
+      "2 Bros"
+      "Aenos Pizza"
+      "Alitalia Pizza Restaurant"
+      "Amici Pizza And Pasta"
+      "Angie'S Cafe Pizza"
+      ...
 
 API Documentation
 -----------------

From 509c146406f2b543ba40ece6ffc74a78b0b0b2a8 Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Tue, 20 Aug 2024 14:28:08 -0400
Subject: [PATCH 3/6] more edits

---
 source/includes/read/distinct.php | 2 +-
 source/read/distinct.txt          | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/includes/read/distinct.php b/source/includes/read/distinct.php
index f04c23aa..b9cffaab 100644
--- a/source/includes/read/distinct.php
+++ b/source/includes/read/distinct.php
@@ -29,8 +29,8 @@
 // Retrieves distinct "name" field values for documents matching the "borough" and "cuisine" fields query
 // and attaches a comment to the operation
 // start-distinct-with-comment
-$options = ['comment' => 'Bronx pizza restaurants'];
 $query = ['$and' => [['borough' => 'Bronx'], ['cuisine' => 'Pizza']]];
+$options = ['comment' => 'Bronx pizza restaurants'];
 $results = $collection->distinct('name', $query, $options);
 
 foreach ($results as $value) {
diff --git a/source/read/distinct.txt b/source/read/distinct.txt
index 85c45ce8..9b6bdc22 100644
--- a/source/read/distinct.txt
+++ b/source/read/distinct.txt
@@ -46,8 +46,8 @@ and assign the following value to your ``collection`` variable:
 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.
 
-``MongoDB\\Collection::distinct()`` Method
-------------------------------------------
+``MongoDB\Collection::distinct()`` Method
+-----------------------------------------
 
 To retrieve the distinct values for a specified field, call the ``MongoDB\Collection::distinct()``
 method and pass in the name of the field you want to find distinct values for.
@@ -111,8 +111,8 @@ all documents that have a ``cuisine`` field value of ``'Italian'``:
 Modify Distinct Behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can modify the behavior of the ``MongoDB\Collection::distinct()`` method by
-passing an array that specifies option values. The following table describes some
+You can modify the behavior of the ``distinct()`` method by passing an
+array that specifies option values. The following table describes some
 options you can set to customize the operation:
 
 .. list-table::

From 6241c8a399ceb9e2b14d170d410cdf8e82405860 Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Wed, 21 Aug 2024 10:55:37 -0400
Subject: [PATCH 4/6] JS feedback

---
 source/read/distinct.txt | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/source/read/distinct.txt b/source/read/distinct.txt
index 9b6bdc22..18b9de2f 100644
--- a/source/read/distinct.txt
+++ b/source/read/distinct.txt
@@ -67,8 +67,7 @@ the ``restaurants`` collection:
       :language: php
       :dedent:
 
-   .. output:: 
-      :visible: false
+   .. output::
 
       "Bronx"
       "Manhattan"
@@ -168,7 +167,5 @@ in an options array to add a comment to the operation:
 API Documentation
 -----------------
 
-To learn more about the ``MongoDB\Collection::distinct()`` method, see the following
-API documentation:
-
-- `distinct() <{+api+}/method/MongoDBCollection-distinct/>`__
\ No newline at end of file
+To learn more about the ``MongoDB\Collection::distinct()`` method, see the
+`distinct() API documentation <{+api+}/method/MongoDBCollection-distinct/>`__.
\ No newline at end of file

From 0ec7b6aed24e5ad1c953758e60f3dd97548fa01b Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Wed, 28 Aug 2024 11:03:35 -0400
Subject: [PATCH 5/6] AB feedback

---
 source/includes/read/distinct.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/includes/read/distinct.php b/source/includes/read/distinct.php
index b9cffaab..5ac02f97 100644
--- a/source/includes/read/distinct.php
+++ b/source/includes/read/distinct.php
@@ -29,7 +29,7 @@
 // Retrieves distinct "name" field values for documents matching the "borough" and "cuisine" fields query
 // and attaches a comment to the operation
 // start-distinct-with-comment
-$query = ['$and' => [['borough' => 'Bronx'], ['cuisine' => 'Pizza']]];
+$query = ['borough' => 'Bronx', 'cuisine' => 'Pizza'];
 $options = ['comment' => 'Bronx pizza restaurants'];
 $results = $collection->distinct('name', $query, $options);
 

From e6294077f4b16c4ea8a90034b000227598f085f7 Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Tue, 3 Sep 2024 13:30:46 -0400
Subject: [PATCH 6/6] fix

---
 snooty.toml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/snooty.toml b/snooty.toml
index e30bbbc3..a77d00d6 100644
--- a/snooty.toml
+++ b/snooty.toml
@@ -28,5 +28,4 @@ php-library = "MongoDB PHP Library"
 php-library = "MongoDB PHP Library"
 driver-short = "PHP library"
 mdb-server = "MongoDB Server"
-driver-short = "PHP library"
 api = "https://www.mongodb.com/docs/php-library/current/reference"