/ /

Retrieve Distinct Field Values

Overview

In this guide, you can learn how to use the Ruby driver to retrieve the distinct values of a specified field across a collection.

Within a collection, 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'. You can use the Ruby driver to 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 Ruby application, create a Mongo::Client object that connects to an Atlas cluster and assign the following values to your database and collection variables:

database = client.use('sample_restaurants')
collection = database[:restaurants]

To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the MongoDB Get Started guide.

Retrieve Distinct Values

To retrieve the distinct values for a specified field, call the distinct method and pass in the name of the field you want to find distinct values for.

Retrieve Values Across a Collection

The following example retrieves the distinct values of the borough field in the restaurants collection:

results = collection.distinct('borough')
results.each do |value|
  puts value
end

Bronx
Brooklyn
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 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.

Tip

To learn more 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' })
results.each do |value|
  puts value
end

Bronx
Brooklyn
Manhattan
Queens
Staten Island

Modify Distinct Behavior

You can modify the behavior of the distinct method by passing a Hash object that specifies option values. The following table describes the options you can set to customize the operation:

Option	Description
`collation`	The collation to use for the operation. Type: `Hash`
`max_time_ms`	The maximum amount of time in milliseconds that the operation can run. Type: `Integer`
`read`	The read preference to use for the operation. To learn more, see Read Preference in the MongoDB Server manual. Type: `Hash`
`session`	The session to use for the operation. Type: `Session`

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 sets the read option, which instructs the operation to use a primary_preferred read preference:

filter = { borough: 'Bronx', cuisine: 'Pizza' }
options = { read: { mode: :primary_preferred } }
results = collection.distinct('name', filter, options)
results.each do |value|
  puts value
end

$1.25 Pizza
18 East Gunhill Pizza
2 Bros
Aenos Pizza
Alitalia Pizza Restaurant
Amici Pizza And Pasta
Angie'S Cafe Pizza
Anthony & Joe'S Pizza
Anthony'S Pizza
Antivari Pizza
Arturo'S Pizza
Bartow Pizza
...

API Documentation

To learn more about the distinct method, see the API documentation.

Back

Specify Fields to Return

Count Documents