.\" This manpage is Copyright (C) 2016 MongoDB, Inc.
.\" 
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.3
.\" or any later version published by the Free Software Foundation;
.\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the section entitled "GNU
.\" Free Documentation License".
.\" 
.TH "MONGOC_COLLECTION_FIND" "3" "2016\(hy10\(hy12" "MongoDB C Driver"
.SH NAME
mongoc_collection_find() \- This function shall execute a query on the underlying collection.
.SH "SYNOPSIS"

.nf
.nf
mongoc_cursor_t *
mongoc_collection_find (mongoc_collection_t       *collection,
                        mongoc_query_flags_t       flags,
                        uint32_t                   skip,
                        uint32_t                   limit,
                        uint32_t                   batch_size,
                        const bson_t              *query,
                        const bson_t              *fields,
                        const mongoc_read_prefs_t *read_prefs)
   BSON_GNUC_WARN_UNUSED_RESULT;
.fi
.fi

.SH "PARAMETERS"

.TP
.B
collection
A
.B mongoc_collection_t
.
.LP
.TP
.B
flags
A
.B mongoc_query_flags_t
.
.LP
.TP
.B
skip
A uint32_t of number of documents to skip or 0.
.LP
.TP
.B
limit
A uint32_t of max number of documents to return or 0.
.LP
.TP
.B
batch_size
A uint32_t containing batch size of document result sets or 0 for default. Default is 100.
.LP
.TP
.B
query
A
.B bson_t
containing the query and options to execute.
.LP
.TP
.B
fields
A
.B bson_t
containing fields to return or
.B NULL
.
.LP
.TP
.B
read_prefs
A
.B mongoc_read_prefs_t
or
.B NULL
for default read preferences.
.LP

.SH "DESCRIPTION"

This function shall execute a query on the underlying
.B collection
.

If no options are necessary,
.B query
can simply contain a query such as
.B {a:1}
. If you would like to specify options such as a sort order, the query must be placed inside of
.B {"$query": {}}
as specified by the server documentation. See the example below for how to properly specify additional options to
.B query
.

.SH "RETURNS"

A newly allocated
.B mongoc_cursor_t
that should be freed with
.B mongoc_cursor_destroy(3)
when no longer in use. If invalid parameters are supplied,
.B NULL
may be returned.

.B NOTE
.RS
Failure to handle the result of this function is a programming error.
.RE

.SH "EXAMPLE"

.nf
#include <mongoc.h>
#include <stdio.h>

static void
print_all_documents (mongoc_collection_t *collection)
{
   mongoc_cursor_t *cursor;
   bson_error_t error;
   const bson_t *doc;
   char *str;
   bson_t *query;

   query = BCON_NEW ("$query", "{", "foo", BCON_INT32 (1), "}",
                     "$orderby", "{", "bar", BCON_INT32 (\(hy1), "}");
   cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);

   while (mongoc_cursor_more (cursor) && mongoc_cursor_next (cursor, &doc)) {
      str = bson_as_json (doc, NULL);
      printf ("%s\en", str);
      bson_free (str);
   }

   if (mongoc_cursor_error (cursor, &error)) {
      fprintf (stderr, "An error occurred: %s\en", error.message);
   }

   mongoc_cursor_destroy (cursor);
   bson_destroy (query);
}
.fi

.SH "THE FIND COMMAND"

Queries have historically been sent as OP_QUERY wire protocol messages, but beginning in MongoDB 3.2 queries use
.B the "find" command
instead.

The driver automatically converts queries to the new "find" command syntax if needed, so this change is typically invisible to C Driver users. However, an application written exclusively for MongoDB 3.2 and later can choose to use the new syntax directly instead of relying on the driver to convert from the old syntax:

.nf
/* MongoDB 3.2+ "find" command syntax */
query = BCON_NEW ("filter", "{", "foo", BCON_INT32 (1), "}",
                  "sort": "{", "bar", BCON_INT32 (\(hy1), "}");
cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
.fi

The "find" command takes different options from the traditional OP_QUERY message.

.TP
.B
Query
.B $query
.B filter
.LP
.TP
.B
Sort
.B $orderby
.B sort
.LP
.TP
.B
Show record location
.B $showDiskLoc
.B showRecordId
.LP
.TP
.B
Other $\(hyoptions
.B $<option name>
.B <option name>
.LP

Most applications should use the OP_QUERY syntax, with "$query", "$orderby", and so on, and rely on the driver to convert to the new syntax if needed. There are two caveats: querying documents by a key named "filter", and using new "find" command options that OP_QUERY does not support.

.SH "SEE ALSO"

.B The "find" command
in the MongoDB Manual.


.SH "FINDING A DOCUMENT BY A KEY NAMED FILTER"

To find a document like
.B { "_id": 1, "filter": "value" }
, this query works in MongoDB before 3.2:

.nf
/* Fails with MongoDB 3.2+ */
query = BCON_NEW ("filter", BCON_UTF8 ("value"));
cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
.fi

Beginning in MongoDB 3.2, the "filter" option has special meaning, and it is no longer assumed to be a field in a document you are querying for. To execute this query on any MongoDB version, wrap it in "$query":

.nf
/* Works in all MongoDB versions */
query = BCON_NEW ("$query", "{", "filter", BCON_UTF8 ("value"), "}");
cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
.fi

This code works for any MongoDB version. The driver sends it as\(hyis to a MongoDB server older than 3.2, and before sending to MongoDB 3.2 or later converts it to the following:

.B { "filter": { "filter": "value" } }


.SH "OPTIONS SPECIFIC TO THE FIND COMMAND"

The "find" command has new options like "singleBatch" not supported by OP_QUERY. Applications should use the new "find" syntax directly to take advantage of them:

.nf
/* MongoDB 3.2+ "find" command syntax */
query = BCON_NEW ("filter", "{", "foo", BCON_INT32 (1), "}",
                  "sort": "{", "bar", BCON_INT32 (\(hy1), "}",
                  "singleBatch", BCON_BOOL (true));
cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
.fi


.SH "THE EXPLAIN COMMAND"

With MongoDB before 3.2, a query with option
.B $explain: true
returns information about the query plan, instead of the query results. Beginning in MongoDB 3.2, there is a separate "explain" command. The driver will not convert "$explain" queries to "explain" commands, you must call the "explain" command explicitly:

.nf
/* MongoDB 3.2+, "explain" command syntax */
 command = BCON_NEW ("explain", "{",
                     "find", BCON_UTF8 ("collection_name"),
                     "filter", "{", "foo", BCON_INT32 (1), "}",
                     "}");
mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
.fi

.SH "SEE ALSO"

.B The "explain" command
in the MongoDB Manual.


.B
.SH COLOPHON
This page is part of MongoDB C Driver.
Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.