Skip to content

Commit 7e0f9be

Browse files
norareidynorareidy
authored
DOCSP-41979: Distinct values (#109)
Adds a Distinct Values guide.
1 parent 09c7be4 commit 7e0f9be

File tree

4 files changed

+213
-2
lines changed

4 files changed

+213
-2
lines changed

‎snooty.toml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,5 +28,4 @@ php-library = "MongoDB PHP Library"
2828
php-library = "MongoDB PHP Library"
2929
driver-short = "PHP library"
3030
mdb-server = "MongoDB Server"
31-
driver-short = "PHP library"
3231
api = "https://www.mongodb.com/docs/php-library/current/reference"

‎source/includes/read/distinct.php

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<?php
2+
require 'vendor/autoload.php';
3+
4+
use MongoDB\BSON\Document;
5+
6+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
7+
$client = new MongoDB\Client($uri);
8+
9+
// start-db-coll
10+
$collection = $client->sample_restaurants->restaurants;
11+
// end-db-coll
12+
13+
// Retrieves distinct values of the "borough" field
14+
// start-distinct
15+
$results = $collection->distinct('borough', []);
16+
foreach ($results as $value) {
17+
echo json_encode($value) . PHP_EOL;
18+
}
19+
// end-distinct
20+
21+
// Retrieves distinct "borough" field values for documents with a "cuisine" value of "Italian"
22+
// start-distinct-with-query
23+
$results = $collection->distinct('borough', ['cuisine' => 'Italian']);
24+
foreach ($results as $value) {
25+
echo json_encode($value) . PHP_EOL;
26+
}
27+
// end-distinct-with-query
28+
29+
// Retrieves distinct "name" field values for documents matching the "borough" and "cuisine" fields query
30+
// and attaches a comment to the operation
31+
// start-distinct-with-comment
32+
$query = ['borough' => 'Bronx', 'cuisine' => 'Pizza'];
33+
$options = ['comment' => 'Bronx pizza restaurants'];
34+
$results = $collection->distinct('name', $query, $options);
35+
36+
foreach ($results as $value) {
37+
echo json_encode($value) . PHP_EOL;
38+
}
39+
// end-distinct-with-comment
40+

‎source/read.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ Read Data from MongoDB
77
.. toctree::
88
:titlesonly:
99
:maxdepth: 1
10-
10+
1111
/read/retrieve
1212
/read/project
1313
/read/count
1414
/read/specify-documents-to-return
1515
/read/specify-a-query
16+
/read/distinct

‎source/read/distinct.txt

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
.. _php-distinct:
2+
3+
==============================
4+
Retrieve Distinct Field Values
5+
==============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: read, unique, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+php-library+} to retrieve the
24+
distinct values of a specified field across a collection.
25+
26+
Within a collection, different documents might contain different values for a
27+
single field. For example, one document in a ``restaurants`` collection has a
28+
``borough`` value of ``'Manhattan'``, and another has a ``borough`` value of
29+
``'Queens'``. By using the {+php-library+}, you can retrieve all the unique values
30+
that a field contains across multiple documents in a collection.
31+
32+
Sample Data
33+
~~~~~~~~~~~
34+
35+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
36+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
37+
from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
38+
and assign the following value to your ``collection`` variable:
39+
40+
.. literalinclude:: /includes/read/distinct.php
41+
:language: php
42+
:dedent:
43+
:start-after: start-db-coll
44+
:end-before: end-db-coll
45+
46+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
47+
:atlas:`Get Started with Atlas </getting-started>` guide.
48+
49+
``MongoDB\Collection::distinct()`` Method
50+
-----------------------------------------
51+
52+
To retrieve the distinct values for a specified field, call the ``MongoDB\Collection::distinct()``
53+
method and pass in the name of the field you want to find distinct values for.
54+
55+
Retrieve Distinct Values Across a Collection
56+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57+
58+
The following example retrieves the distinct values of the ``borough`` field in
59+
the ``restaurants`` collection:
60+
61+
.. io-code-block::
62+
:copyable:
63+
64+
.. input:: /includes/read/distinct.php
65+
:start-after: start-distinct
66+
:end-before: end-distinct
67+
:language: php
68+
:dedent:
69+
70+
.. output::
71+
72+
"Bronx"
73+
"Manhattan"
74+
"Missing"
75+
"Queens"
76+
"Staten Island"
77+
78+
The operation returns an array that stores each distinct ``borough`` field value. Although
79+
several documents have the same value in the ``borough`` field, each value appears in the
80+
results only once.
81+
82+
Retrieve Distinct Values Across Specified Documents
83+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
You can provide a **query filter** to the ``distinct()`` method to find the distinct
86+
field values across a subset of documents in a collection. A query filter is an expression
87+
that specifies search criteria used to match documents in an operation. For more information
88+
about creating a query filter, see the :ref:`php-specify-query` guide.
89+
90+
The following example retrieves the distinct values of the ``borough`` field for
91+
all documents that have a ``cuisine`` field value of ``'Italian'``:
92+
93+
.. io-code-block::
94+
:copyable:
95+
96+
.. input:: /includes/read/distinct.php
97+
:start-after: start-distinct-with-query
98+
:end-before: end-distinct-with-query
99+
:language: php
100+
:dedent:
101+
102+
.. output::
103+
:visible: false
104+
105+
"Bronx"
106+
"Manhattan"
107+
"Queens"
108+
"Staten Island"
109+
110+
Modify Distinct Behavior
111+
~~~~~~~~~~~~~~~~~~~~~~~~
112+
113+
You can modify the behavior of the ``distinct()`` method by passing an
114+
array that specifies option values. The following table describes some
115+
options you can set to customize the operation:
116+
117+
.. list-table::
118+
:widths: 30 70
119+
:header-rows: 1
120+
121+
* - Option
122+
- Description
123+
124+
* - ``collation``
125+
- | The collation to use for the operation.
126+
| **Type**: ``array|object``
127+
128+
* - ``maxTimeMS``
129+
- | The maximum amount of time in milliseconds that the operation can run.
130+
| **Type**: ``integer``
131+
132+
* - ``comment``
133+
- | The comment to attach to the operation.
134+
| **Type**: any valid BSON type
135+
136+
* - ``readPreference``
137+
- | The read preference to use for the operation. To learn more, see
138+
:manual:`Read Preference </core/read-preference/>` in the Server manual.
139+
| **Type**: ``MongoDB\Driver\ReadPreference``
140+
141+
The following example retrieves the distinct values of the ``name`` field for
142+
all documents that have a ``borough`` field value of ``'Bronx'`` and a
143+
``cuisine`` field value of ``'Pizza'``. It also specifies the ``comment`` field
144+
in an options array to add a comment to the operation:
145+
146+
.. io-code-block::
147+
:copyable:
148+
149+
.. input:: /includes/read/distinct.php
150+
:start-after: start-distinct-with-comment
151+
:end-before: end-distinct-with-comment
152+
:language: php
153+
:dedent:
154+
155+
.. output::
156+
:visible: false
157+
158+
"$1.25 Pizza"
159+
"18 East Gunhill Pizza"
160+
"2 Bros"
161+
"Aenos Pizza"
162+
"Alitalia Pizza Restaurant"
163+
"Amici Pizza And Pasta"
164+
"Angie'S Cafe Pizza"
165+
...
166+
167+
API Documentation
168+
-----------------
169+
170+
To learn more about the ``MongoDB\Collection::distinct()`` method, see the
171+
`distinct() API documentation <{+api+}/method/MongoDBCollection-distinct/>`__.

0 commit comments

Comments
 (0)