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" diff --git a/source/includes/read/distinct.php b/source/includes/read/distinct.php new file mode 100644 index 00000000..5ac02f97 --- /dev/null +++ b/source/includes/read/distinct.php @@ -0,0 +1,40 @@ +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 = ['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 + diff --git a/source/read.txt b/source/read.txt index be850609..d0299830 100644 --- a/source/read.txt +++ b/source/read.txt @@ -7,9 +7,10 @@ Read Data from MongoDB .. toctree:: :titlesonly: :maxdepth: 1 - + /read/retrieve /read/project /read/count /read/specify-documents-to-return /read/specify-a-query + /read/distinct diff --git a/source/read/distinct.txt b/source/read/distinct.txt new file mode 100644 index 00000000..18b9de2f --- /dev/null +++ b/source/read/distinct.txt @@ -0,0 +1,171 @@ +.. _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 `. 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 ` 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:: + + "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 ` 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 +`distinct() API documentation <{+api+}/method/MongoDBCollection-distinct/>`__. \ No newline at end of file