Retrieve Distinct Field Values
On this page
Overview
In this guide, you can learn how to use the C++ driver to retrieve the distinct values of a specified field across a collection.
Within a collection, different documents might contain different values for a
single field. For example, one document in a restaurants
collection has a
borough
value of "Manhattan"
, and another has a borough
value of
"Queens"
. By using the C++ driver, you can retrieve all the unique values
that a field contains across multiple documents in a collection.
Sample Data
The examples in this guide use the restaurants
collection in the sample_restaurants
database from the Atlas sample datasets. To access this collection
from your C++ application, instantiate a mongocxx::client
that connects to an Atlas cluster
and assign the following values to your db
and collection
variables:
auto db = client["sample_restaurants"]; auto collection = db["restaurants"];
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.
distinct()
Method
To retrieve the distinct values for a specified field, call the distinct()
method and pass in the name of the field you want to find distinct values for.
Retrieve Distinct Values Across a Collection
The following example retrieves the distinct values of the borough
field in
the restaurants
collection:
auto cursor = collection.distinct("borough", {}); for(auto&& doc : cursor) { std::cout << bsoncxx::to_json(doc) << std::endl; }
{ "values" : [ "Bronx", "Brooklyn", "Manhattan", "Missing", "Queens", "Staten Island" ], "ok" : 1.0, "$clusterTime" : { "clusterTime" : { "$timestamp" : { ... } }, "signature" : { "hash" : { ... }, "keyId" : ... } }, "operationTime" : { "$timestamp" : { ... } }
The operation returns a cursor that contains a single document. The document includes a list
of distinct borough
field values and metadata about the operation. 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 the Specify a Query guide.
The following example retrieves the distinct values of the borough
field for
all documents that have a cuisine
field value of "Italian"
:
auto cursor = collection.distinct("borough", make_document(kvp("cuisine", "Italian"))); for(auto&& doc : cursor) { std::cout << bsoncxx::to_json(doc) << std::endl; }
{ "values" : [ "Bronx", "Brooklyn", "Manhattan", "Queens", "Staten Island" ], "ok" : 1.0, "$clusterTime" : { "clusterTime" : { "$timestamp" : { ... }, "signature" : { "hash" : { ... }, "keyId" : ... } }, "operationTime" : { "$timestamp" : { ... } }
Modify Distinct Behavior
You can modify the behavior of the distinct()
method by passing an instance
of the mongocxx::options::distinct
class as an argument. The following table
describes the fields you can set in a mongocxx::options::distinct
instance:
Field | Description |
---|---|
collation | The collation to use for the operation. Type: bsoncxx::document::view_or_value |
max_time | The maximum amount of time in milliseconds that the operation can run. Type: std::chrono::milliseconds |
comment | The comment to attach to the operation. Type: bsoncxx::types::bson_value::view_or_value |
read_preference | The read preference to use for the operation. Type: mongocxx::read_preference |
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 specifies the comment
field
of an options instance to add a comment to the operation:
mongocxx::options::distinct opts{}; opts.comment(bsoncxx::types::bson_value::view_or_value{"Bronx pizza restaurants"}); auto cursor = collection.distinct("name", make_document(kvp("$and", make_array(make_document(kvp("borough", "Bronx")), make_document(kvp("cuisine", "Pizza"))))), opts ); for (auto&& doc : cursor) { std::cout << bsoncxx::to_json(doc) << std::endl; }
{ "values" : [ "$1.25 Pizza", "18 East Gunhill Pizza", "2 Bros", "Aenos Pizza", "Alitalia Pizza Restaurant", … ], "ok" : 1.0, "$clusterTime" : { "clusterTime" : { … }, "signature" : { … }, "keyId" : … } }, "operationTime" : { … } }
API Documentation
To learn more about any of the methods or types discussed in this guide, see the following API documentation: