Retrieve Distinct Values of a Field

You can retrieve a list of distinct values for a field across a collection by calling the distinct() method on a MongoCollection object. Pass the document field name as the first parameter and the class you want to cast the results to as the second parameter as shown below:

collection.distinct("countries", String.class);

You can specify a field on the document or one within an embedded document using dot notation. The following method call returns each distinct value of the wins field in the awards embedded document:

collection.distinct("awards.wins", Integer.class);

You can optionally pass a query filter to the method to limit the set of documents from which your MongoDB instance retrieves distinct values as follows:

collection.distinct("type", Filters.eq("languages", "French"), String.class);

The distinct() method returns an object that implements the DistinctIterable interface. This interface contains methods to access, organize, and traverse the results. It also inherits methods from its parent interface, MongoIterable, such as first() which returns the first result and cursor() which returns an instance of a MongoCursor.

Example

The following snippet retrieves a list of distinct values for the year document field from the movies collection. It uses a query filter to match movies that include "Carl Franklin" as one of the values in the directors array.

Note

This example connects to an instance of MongoDB using a connection URI. To learn more about connecting to your MongoDB instance, see the connection guide.

// Retrieves distinct values of a field by using the Java driver
package usage.examples;
import org.bson.Document;
import com.mongodb.MongoException;
import com.mongodb.client.DistinctIterable;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoCursor;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.Filters;
public class Distinct {
    public static void main(String[] args) {
        // Replace the uri string with your MongoDB deployment's connection string
        String uri = "<connection string uri>";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
            MongoCollection<Document> collection = database.getCollection("movies");
            try {
                // Retrieves the distinct values of the "year" field present in documents that match the filter
                DistinctIterable<Integer> docs = collection.distinct("year", Filters.eq("directors", "Carl Franklin"), Integer.class);
                MongoCursor<Integer> results = docs.iterator();
                // Prints the distinct "year" values
                while(results.hasNext()) {
                    System.out.println(results.next());
                }
            // Prints a message if any exceptions occur during the operation
            } catch (MongoException me) {
                System.err.println("An error occurred: " + me);
            }
        }
    }
}

When you run the example, you should see output that reports each distinct year for all the movies that Carl Franklin was included as a director, which resembles the following:

Tip

Legacy API

If you are using the legacy API, see our FAQ page to learn what changes you need to make to this code example.

For additional information on the classes and methods mentioned on this page, see the following resources:

distinct() API Documentation
DistinctIterable API Documentation
Dot Notation Server Manual Entry
MongoIterable API Documentation

Back

Count Documents

Run a Command