Retrieve Distinct Values of a Field
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 more 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);
Running the preceding example, you see the following output:
[ 1983, 1991, 1996 ]