NAME

       mongoc_collection_find()  -  This  function  shall  execute  a  query  on  the  underlying
       collection.

SYNOPSIS

       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;

PARAMETERS

       collection
              A mongoc_collection_t \&.

       flags  A mongoc_query_flags_t \&.

       skip   A uint32_t of number of documents to skip or 0.

       limit  A uint32_t of max number of documents to return or 0.

       batch_size
              A uint32_t containing batch size of document result sets or 0 for default.  Default
              is 100.

       query  A bson_t containing the query and options to execute.

       fields A bson_t containing fields to return or NULL \&.

       read_prefs
              A mongoc_read_prefs_t or NULL for default read preferences.

DESCRIPTION

       This function shall execute a query on the underlying collection \&.

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

RETURNS

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

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

EXAMPLE

       #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 (‐1), "}");
          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\n", str);
             bson_free (str);
          }

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

          mongoc_cursor_destroy (cursor);
          bson_destroy (query);
       }

THE FIND" COMMAND"

       Queries  have  historically been sent as OP_QUERY wire protocol messages, but beginning in
       MongoDB 3.2 queries use 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:

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

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

       Query  $query filter

       Sort   $orderby sort

       Show record location
              $showDiskLoc showRecordId

       Other $‐options
              $<option name> <option name>

       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.

SEE ALSO

       The find command in the MongoDB Manual.

FINDING A DOCUMENT BY A KEY NAMED FILTER""

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

       /* 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);

       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":

       /* 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);

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

       { filter : { filter : value } }

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:

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

THE EXPLAIN" COMMAND"

       With  MongoDB before 3.2, a query with option $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:

       /* MongoDB 3.2+, "explain" command syntax */
       command = BCON_NEW ("explain", "{",
                           "find", BCON_UTF8 ("collection_name"),
                           "filter", "{",
                           "foo", BCON_INT32 (1), "}",
                           "}", "}");
       cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);

SEE ALSO

       The explain command in the MongoDB Manual.

COLOPHON

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