Specify a Query

Overview

In this guide, you can learn how to specify a query by using the C driver.

You can define a query filter to retrieve specific documents from a collection when performing a query. A query filter is an expression that specifies the search criteria MongoDB uses to match documents in a read or write operation. By defining a query filter, you can direct the driver to search for documents with an exact match to your query, or you can compose query filters to express more complex matching criteria.

Exact Match

Literal value queries return documents with an exact match to your query filter.

The following example specifies a query filter as a parameter to the mongoc_collection_find_with_opts() function. The code returns all documents in which the value of the type field is "movie".

const bson_t *doc;
bson_t *filter = BCON_NEW ("type", BCON_UTF8 ("movie"));
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
mongoc_cursor_destroy (results);
bson_destroy (filter);

{ "_id" : { "$oid" : "..." }, "title" : "Wild and Woolly", "type" : "movie", ... }
{ "_id" : { "$oid" : "..." }, "title" : "The Devil to Pay!", "type" : "movie", ... }
{ "_id" : { "$oid" : "..." }, "title" : "Traffic in Souls", "type" : "movie", ... }
{ "_id" : { "$oid" : "..." }, "title" : "Now or Never", "type" : "movie", ... }
{ "_id" : { "$oid" : "..." }, "title" : "High and Dizzy", "type" : "movie", ... }
...

Comparison Operators

Comparison operators evaluate a document field value against a specified value in your query filter. The following is a list of common comparison operators:

• $gt: Greater than

• $lte: Less than or equal

• $ne: Not equal

To view a full list of comparison operators, see the Comparison Query Operators guide in the MongoDB Server manual.

The following example specifies a comparison operator in a query filter as a parameter to the mongoc_collection_find_with_opts() function. The code returns all documents in which the value of the year field is greater than 2015.

const bson_t *doc;
bson_t *filter = BCON_NEW ("year", "{", "$gt", BCON_INT32 (2015), "}");
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
mongoc_cursor_destroy (results);
bson_destroy (filter);

{ "_id" : ..., "title" : "The Masked Saint", "year" : { "$numberInt" : "2016" }, ... }

Logical Operators

Logical operators match documents by using logic applied to the results of two or more sets of expressions. The following is a list of logical operators:

• $and, which returns all documents that match the conditions of all clauses

• $or, which returns all documents that match the conditions of one clause

• $nor, which returns all documents that do not match the conditions of any clause

• $not, which returns all documents that do not match the expression

To learn more about logical operators, see the Logical Query Operators guide in the MongoDB Server manual.

The following example specifies a logical operator in a query filter as a parameter to the mongoc_collection_find_with_opts() function. The code returns all documents in which the value of the year field is 1983 or 1985.

const bson_t *doc;
bson_t *filter = BCON_NEW (
    "$or", "[",
        "{", "year", BCON_INT64 (1983), "}",
        "{", "year", BCON_INT64 (1985), "}",
    "]"
);
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
mongoc_cursor_destroy (results);
bson_destroy (filter);

{ "_id" : ..., "title" : "Amityville 3-D", "year" : { "$numberInt" : "1983" }, ... }
{ "_id" : ..., "title" : "Barefoot Gen", "year" : { "$numberInt" : "1983" }, ... }
{ "_id" : ..., "title" : "Betrayal", "year" : { "$numberInt" : "1983" }, ... }
{ "_id" : ..., "title" : "You're a Good Man, Charlie Brown", "year" : { "$numberInt" : "1985" }, ... }
{ "_id" : ..., "title" : "Yes: 9012 Live", "year" : { "$numberInt" : "1985" }, ... }
...

Array Operators

Array operators match documents based on the value or quantity of elements in an array field. The following is a list of available array operators:

• $all, which returns documents with arrays that contain all elements in the query

• $elemMatch, which returns documents if an element in their array field matches all conditions in the query

• $size, which returns all documents with arrays of a specified size

To learn more about array operators, see the Array Query Operators guide in the MongoDB Server manual.

The following example specifies an array operator in a query filter as a parameter to the mongoc_collection_find_with_opts() function. The code returns all documents in which the value of the genres array field contains exactly 2 elements.

const bson_t *doc;
bson_t *filter = BCON_NEW ("genres", "{", "$size", BCON_INT32 (2), "}");
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
mongoc_cursor_destroy (results);
bson_destroy (filter);

{ "_id" : ..., "genres" : [ "Comedy", "Romance" ], "title" : "The Devil to Pay!", ... }
{ "_id" : ..., "genres" : [ "Crime", "Drama" ], "title" : "Traffic in Souls", ... }
{ "_id" : ..., "genres" : [ "Comedy", "Short" ], "title" : "High and Dizzy", ... }
{ "_id" : ..., "genres" : [ "Comedy", "Short" ], "title" : "Now or Never", ... }
{ "_id" : ..., "genres" : [ "Drama", "Romance" ], "title" : "A Woman of Paris: A Drama of Fate", ... }
...

Element Operators

Element operators query data based on the presence or type of a field.

To learn more about element operators, see the Element Query Operators guide in the MongoDB Server manual.

The following example specifies the $exists operator in a query filter as a parameter to the mongoc_collection_find_with_opts() function. The code returns all documents that have a num_mflix_comments field.

const bson_t *doc;
bson_t *filter = BCON_NEW ("num_mflix_comments", "{", "$exists", BCON_BOOL (true), "}");
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
mongoc_cursor_destroy (results);
bson_destroy (filter);

{ "_id" : ..., "num_mflix_comments" : { "$numberInt" : "0" }, "title" : "The Park Is Mine", ...}
{ "_id" : ..., "num_mflix_comments" : { "$numberInt" : "1" }, "title" : "The Good Father", ... }
{ "_id" : ..., "num_mflix_comments" : { "$numberInt" : "0" }, "title" : "Alpine Fire", ... }
{ "_id" : ..., "num_mflix_comments" : { "$numberInt" : "1" }, "title" : "Huang jia shi jie", ... }
{ "_id" : ..., "num_mflix_comments" : { "$numberInt" : "0" }, "title" : "Twenty Years Later", ... }
...

Evaluation Operators

Evaluation operators return data based on evaluations of either individual fields or the entire collection's documents.

The following is a list of common evaluation operators:

• $text, which performs a text search on the documents

• $regex, which returns documents that match a specified regular expression

• $mod, which performs a modulo operation on the value of a field and returns documents where the remainder is a specified value

To view a full list of evaluation operators, see the Evaluation Query Operators guide in the MongoDB Server manual.

The following example specifies an evaluation operator in a query filter as a parameter to the mongoc_collection_find_with_opts() function. The code uses a regular expression to return all documents in which the value of the title field has at least two consecutive "p" characters.

const bson_t *doc;
bson_t *filter = BCON_NEW("title", "{", "$regex", BCON_UTF8("p{2,}"), "}");
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
mongoc_cursor_destroy (results);
bson_destroy (filter);

{ "_id" : ..., "title" : "He Who Gets Slapped", ... }
{ "_id" : ..., "title" : "David Copperfield", ... }
{ "_id" : ..., "title" : "Applause", ... }
{ "_id" : ..., "title" : "Skippy", ... }
{ "_id" : ..., "title" : "This Happy Breed", ... }
...

Additional Information

To learn more about querying documents, see the Query Documents guide in the MongoDB Server manual.

To learn more about using the C driver to retrieve documents, see Retrieve Data.