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.

MongoDB C Driver                                   2016‐01‐18                          MONGOC_COLLECTION_FIND(3)