Docs Menu
Docs Home
/
Languages
/
PHP
/
PHP Library Manual
/
Read Data

Retrieve Distinct Field Values

On this page

  • Overview
  • Sample Data
  • MongoDB\Collection::distinct() Method
  • Retrieve Distinct Values Across a Collection
  • Retrieve Distinct Values Across Specified Documents
  • Modify Distinct Behavior
  • API Documentation

Overview

In this guide, you can learn how to use the MongoDB 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 MongoDB 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 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:

$collection = $client->sample_restaurants->restaurants;

To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the 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:

$results = $collection->distinct('borough', []);
foreach ($results as $value) {
    echo json_encode($value), PHP_EOL;
}
"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 Specify a Query guide.

The following example retrieves the distinct values of the borough field for all documents that have a cuisine field value of 'Italian':

$results = $collection->distinct('borough', ['cuisine' => 'Italian']);
foreach ($results as $value) {
    echo json_encode($value), PHP_EOL;
}
"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:

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 Read Preference in the Server manual.
Type: MongoDB\Driver\ReadPreference

hint

The index to use for the operation.
Type: string|object

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:

$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;
}
"$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 distinct() method, see MongoDB\Collection::distinct() in the API documentation.

Back

Specify a Query

Next

Monitor Changes