DOCSP-41979: Distinct values

source/includes/read/distinct.php

@@ -0,0 +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
+$collection = $client->sample_restaurants->restaurants;
+// end-db-coll
+
+// 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-distinct-with-query
+
+// 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']]];
+$options = ['comment' => 'Bronx pizza restaurants'];
+$results = $collection->distinct('name', $query, $options);
+
+foreach ($results as $value) {
+    echo json_encode($value) . PHP_EOL;
+}
+// end-distinct-with-comment
+

source/read.txt

@@ -8,4 +8,5 @@ Read Data from MongoDB
    :titlesonly:
    :maxdepth: 1
 
-   /read/retrieve
+   /read/retrieve
+   /read/distinct

source/read/distinct.txt

@@ -0,0 +1,174 @@
+.. _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::
+   :copyable:
+
+   .. input:: /includes/read/distinct.php
+      :start-after: start-distinct
+      :end-before: end-distinct
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      "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
+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::
+   :copyable:
+
+   .. input:: /includes/read/distinct.php
+      :start-after: start-distinct-with-query
+      :end-before: end-distinct-with-query
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      "Bronx"
+      "Manhattan"
+      "Queens"
+      "Staten Island"
+
+Modify Distinct Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+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::
+   :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::
+   :copyable:
+
+   .. input:: /includes/read/distinct.php
+      :start-after: start-distinct-with-comment
+      :end-before: end-distinct-with-comment
+      :language: php
+      :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"
+      ...
+
+API Documentation
+-----------------
+
+To learn more about the ``MongoDB\Collection::distinct()`` method, see the following
+API documentation:
+
+- `distinct() <{+api+}/method/MongoDBCollection-distinct/>`__