Retrieve Distinct Values of a Field

Overview

In this guide, you can learn how to 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 use for the results 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.

// 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");
            // 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());
            }
        }
    }
}

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:

1992
1995
1998
...

For more information about 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