Retrieve Distinct Values of a Field

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

You can retrieve a list of distinct values for a field across a collection by using the collection.distinct() method. Call the distinct() method on a Collection object with a document field name parameter as a String to produce a list that contains one of each of the different values found in the specified document field as shown below:

const distinctValues = myColl.distinct("countries", query);

You can specify a document field within an embedded document using dot notation. If you call distinct() on an document field that contains an array, the method treats each element as a separate value. See the following example of a method call to the wins field in the awards subdocument:

const distinctValues = myColl.distinct("awards.wins", query);

You can specify additional query options using the options object passed as the third parameter to the distinct() method. For details on the query parameters, see the distinct() method in the API documentation.

If you specify a value for the document field name that is not of type String such as a Document, Array, Number, or null, the method does not execute and returns a TypeMismatch error with a message that resembles the following:

"key" had the wrong type. Expected string, found <non-string type>

Visit Retrieve Distinct Values for more information about the distinct() method.

Example

The following snippet retrieves a list of distinct values for the year document field from the movies collection. It uses a query document to match movies that include "Barbara Streisand" as a director.

Note

You can use this example to connect to an instance of MongoDB and interact with a database that contains sample data. To learn more about connecting to your MongoDB instance and loading a sample dataset, see the Usage Examples guide.

1 import { MongoClient } from "mongodb";
2 
3 // Replace the uri string with your MongoDB deployment's connection string.
4 const uri = "<connection string uri>";
5 
6 const client = new MongoClient(uri);
7 
8 async function run() {
9   try {
10     
11     // Get the database and collection on which to run the operation
12     const database = client.db("sample_mflix");
13     const movies = database.collection("movies");
14 
15     // Specify the document field to find distinct values for
16     const fieldName = "year";
17 
18     // Specify an optional query document to narrow results
19     const query = { directors: "Barbra Streisand" };
20 
21     // Execute the distinct operation
22     const distinctValues = await movies.distinct(fieldName, query);
23 
24     // Print the result
25     console.log(distinctValues);
26   } finally {
27     await client.close();
28   }
29 }
30 run().catch(console.dir);

1 import { MongoClient } from "mongodb";
2 
3 // Replace the uri string with your MongoDB deployment's connection string.
4 const uri = "<connection string uri>";
5 
6 const client = new MongoClient(uri);
7 
8 interface Movie {
9   directors: string;
10   year: number;
11 }
12 
13 async function run() {
14   try {
15     // define a database and collection on which to run the method
16     const database = client.db("sample_mflix");
17     const movies = database.collection<Movie>("movies");
18 
19     const distinctValues = await movies.distinct("year", {
20       directors: "Barbra Streisand",
21     });
22 
23     console.log(distinctValues);
24   } finally {
25     await client.close();
26   }
27 }
28 run().catch(console.dir);

If you run the preceding example, you should see the following output:

[ 1983, 1991, 1996 ]

Back

Count Documents

Run a Command

1	import { MongoClient } from "mongodb";
2
3	// Replace the uri string with your MongoDB deployment's connection string.
4	const uri = "<connection string uri>";
5
6	const client = new MongoClient(uri);
7
8	async function run() {
9	try {
10
11	// Get the database and collection on which to run the operation
12	const database = client.db("sample_mflix");
13	const movies = database.collection("movies");
14
15	// Specify the document field to find distinct values for
16	const fieldName = "year";
17
18	// Specify an optional query document to narrow results
19	const query = { directors: "Barbra Streisand" };
20
21	// Execute the distinct operation
22	const distinctValues = await movies.distinct(fieldName, query);
23
24	// Print the result
25	console.log(distinctValues);
26	} finally {
27	await client.close();
28	}
29	}
30	run().catch(console.dir);