Retrieve Distinct Field Values

On this page

Overview

Sample Data
Distinct Command
Retrieve Distinct Values Across a Collection
Retrieve Distinct Values Across Specified Documents
Modify Distinct Behavior
Additional Information
API Documentation

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 the restaurant 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 distinct 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 learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

Distinct Command

To retrieve the distinct values for a specified field, call the mongoc_collection_read_command_with_opts() function and direct it to use the distinct command. You must also specify the collection and field to retrieve data from.

Retrieve Distinct Values Across a Collection

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

bson_t reply;
bson_error_t error;
bson_t *command = BCON_NEW ("distinct",
                    BCON_UTF8 ("restaurants"),
                    "key",
                    BCON_UTF8 ("borough"));
if (!mongoc_collection_read_command_with_opts (collection, command, NULL, NULL, &reply, &error)) {
    fprintf (stderr, "An error occurred: %s\n", error.message);
} else {
    char *str = bson_as_canonical_extended_json (&reply, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (&reply);
bson_destroy (command);

{ "values" : [ "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 command 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.

To learn more about creating query filters, 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":

bson_t reply;
bson_error_t error;
bson_t *query = BCON_NEW ("cuisine", BCON_UTF8 ("Italian"));
bson_t *command = BCON_NEW ("distinct", BCON_UTF8 ("restaurants"),
                    "key", BCON_UTF8 ("borough"),
                    "query", BCON_DOCUMENT (query));
if (!mongoc_collection_read_command_with_opts (collection, command, NULL, NULL, &reply, &error)) {
    fprintf (stderr, "An error occurred: %s\n", error.message);
} else {
    char *str = bson_as_canonical_extended_json (&reply, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (&reply);
bson_destroy (command);
bson_destroy (query);

{ "values" : [ "Bronx", "Brooklyn", "Manhattan", "Queens", "Staten Island" ], ... }

Modify Distinct Behavior

The distinct command can be modified by passing options to the mongoc_collection_read_command_with_opts() function. If you don't specify any options, the driver does not customize the operation.

The following table describes some options you can use to customize the distinct operation:

Option	Description
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`comment`	Specifies a comment to attach to the operation.

For a complete list of options you can use to modify the distinct operation, see the Distinct documentation in the MongoDB Server manual.

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.

bson_t reply;
bson_error_t error;
bson_t *query = BCON_NEW ("borough", BCON_UTF8 ("Bronx"),
                          "cuisine", BCON_UTF8 ("Pizza"));
bson_t *command = BCON_NEW ("distinct", BCON_UTF8 ("restaurants"),
                    "key", BCON_UTF8 ("name"),
                    "query", BCON_DOCUMENT (query));
bson_t *opts = BCON_NEW ("comment", BCON_UTF8 ("Bronx pizza restaurants"));
if (!mongoc_collection_read_command_with_opts (collection, command, NULL, opts, &reply, &error)) {
    fprintf (stderr, "An error occurred: %s\n", error.message);
} else {
    char *str = bson_as_canonical_extended_json (&reply, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (&reply);
bson_destroy (command);
bson_destroy (query);
bson_destroy (opts);

{ "values" : [ "$1.25 Pizza", "18 East Gunhill Pizza", "2 Bros", "Aenos Pizza", "Alitalia Pizza Restaurant", ... ], ... }

Additional Information

To learn more about the distinct command, see the Distinct page in the MongoDB Server Manual.

API Documentation

To learn more about the mongoc_collection_read_command_with_opts() function, see the API documentation.

Back

Count Documents

Access Data from a Cursor