Docs Home → Develop Applications → MongoDB Drivers → Node.js

Retrieve Distinct Values

On this page

Overview

Sample Documents
Distinct
Document Field Parameter
Query Parameter
Options Parameter
Additional Information
API Documentation

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of the MongoDB Node.js driver.

Overview

Use the distinct() method to retrieve all distinct values for a specified field across a collection.

Sample Documents

Consider a collection called restaurants that contains documents with restaurant data. The examples on this page use the following restaurants documents to demonstrate the usage of distinct():

[
   { "_id": 1, "restaurant": "White Bear", "borough": "Queens", "cuisine": "Chinese" },
   { "_id": 2, "restaurant": "Via Carota", "borough": "Manhattan", "cuisine": "Italian" },
   { "_id": 3, "restaurant": "Borgatti's", "borough": "Bronx", "cuisine": "Italian" },
   { "_id": 4, "restaurant": "Tanoreen", "borough": "Brooklyn", "cuisine": "Middle Eastern" },
   { "_id": 5, "restaurant": "Äpfel", "borough": "Queens", "cuisine": "German" },
   { "_id": 6, "restaurant": "Samba Kitchen", "borough": "Manhattan", "cuisine": "Brazilian" },
]

Note

Your query operation may return a reference to a cursor that contains matching documents. To learn how to examine data stored in the cursor, see the Cursor Fundamentals page.

Distinct

The distinct() method requires a document field as a parameter. You can specify the following optional parameters to adjust the method output:

A query parameter to refine your results
An options parameter to set collation rules

Document Field Parameter

Pass the name of the document field to return a list of the field's unique values.

Example

The "Queens" and "Manhattan" borough values each appear more than once in the sample documents. However, the following example retrieves the unique values of the borough field:

// specify "borough" as the field to return values for
const cursor = collection.distinct("borough");
await cursor.forEach(console.dir);

This code outputs the following borough values:

[ "Bronx", "Brooklyn", "Manhattan", "Queens" ]

Query Parameter

You can specify a query parameter to return unique values for documents that match your query.

Visit Specify a Query for more information on constructing a query filter.

Example

The following example outputs the distinct values of the cuisine field but excludes restaurants in "Brooklyn":

// exclude Brooklyn restaurants from the output
const query = { borough: { $ne: "Brooklyn" }};
// find the filtered distinct values of "cuisine"
const cursor = collection.distinct("cuisine", query);
await cursor.forEach(console.dir);

In this case, the query filter matches every borough value except for "Brooklyn". This prevents distinct() from outputting one cuisine value, "Middle Eastern". The code outputs the following values:

[ "Brazilian", "Chinese", "German", "Italian" ]

Options Parameter

You can specify the collation to the distinct() method by defining a collation field as an options parameter. This field allows you to set regional rules for string ordering and comparisons.

See Collations for instructions on applying collations.

Note

When using the options parameter, you must also specify a query parameter. If you don't want to use a query filter, define the query as {}.

Example

The following example uses a collation field to specify German language ordering conventions when outputting the distinct restaurant values:

// define an empty query document
const query = {};
// specify German string ordering conventions
const options = { collation: { locale: "de" }};
const cursor = collection.distinct("restaurant", query, options);
await cursor.forEach(console.dir);

In this case, German string ordering conventions place words beginning with "Ä" before those beginning with "B". The code outputs the following:

[ "Äpfel", "Borgatti's", "Samba Kitchen", "Tanoreen", "Via Carota", "White Bear" ]

Without specifying a collation field, the output order would follow default binary collation rules. These rules place words beginning with "Ä" after the those with unaccented first letters:

[ "Borgatti's", "Samba Kitchen", "Tanoreen", "Via Carota", "White Bear", "Äpfel" ]

Additional Information

For a runnable example of retrieving distinct values, see Retrieve Distinct Values of a Field.

API Documentation

To learn more about the distinct() method and its parameters, you can visit the API documentation.

← Access Data From a Cursor Sort Results →