Retrieve Distinct Field Values

Sample Data

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

The following Kotlin data class models the documents in this collection:

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String
)

Retrieve Distinct Values Across a Collection

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

val results = collection.distinct<String>(Restaurant::borough.name)
results.forEach { result ->
    println(result)
}

Bronx
Brooklyn
Manhattan
Missing
Queens
Staten Island

The results show every distinct value that appears in the borough field across all documents in the collection. 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 Specify a Query.

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

val results = collection.distinct<String>(
    Restaurant::borough.name,
    eq(Restaurant::cuisine.name, "Italian")
)
results.forEach { result ->
    println(result)
}

Bronx
Brooklyn
Manhattan
Queens
Staten Island

Modify Distinct Behavior

The distinct() method can be modified by chaining methods to the distinct() method call. If you don't specify any options, the driver does not customize the operation.

The following table describes some methods you can use to customize the distinct() operation:

For a complete list of methods you can use to modify the distinct() method, see the DistinctIterable API documentation.

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 uses the comment option to add a comment to the operation.

val results = collection.distinct<String>(
    Restaurant::name.name,
    and(
        eq(Restaurant::borough.name, "Bronx"),
        eq(Restaurant::cuisine.name, "Pizza")
    )
).comment("Bronx pizza restaurants")
results.forEach { result ->
    println(result)
}

$1.25 Pizza
18 East Gunhill Pizza
2 Bros
Aenos Pizza
Alitalia Pizza Restaurant
...

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

• distinct()

• DistinctIterable