plucky (3) mongoc_collection_find.3.gz

Provided by: libmongoc-doc_1.30.0-1_all bug

WARNING:

          Deprecated since version 1.5.0: Use mongoc_collection_find_with_opts() instead.

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

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": {}}. See  the  example  below
       for how to properly specify additional options to query.

       This  function is considered a retryable read operation.  Upon a transient error (a network error, errors
       due to replica set failover, etc.) the operation is safely retried once.  If retryreads is false  in  the
       URI (see mongoc_uri_t) the retry behavior does not apply.

RETURNS

       This function returns a newly allocated mongoc_cursor_t that should be freed with mongoc_cursor_destroy()
       when no longer in use. The returned mongoc_cursor_t is never NULL, even on  error.  The  user  must  call
       mongoc_cursor_next() on the returned mongoc_cursor_t to execute the initial command.

       Cursor errors can be checked with mongoc_cursor_error_document(). It always fills out the bson_error_t if
       an error occurred, and optionally includes a server reply document if the error occurred server-side.

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

EXAMPLE

       Print All Documents in a Collection

          #include <bson/bson.h>
          #include <mongoc/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_next (cursor, &doc)) {
                str = bson_as_canonical_extended_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                │ $queryfilter        │
                                ├─────────────────────┼────────────────┼───────────────┤
                                │Sort                 │ $orderbysort          │
                                ├─────────────────────┼────────────────┼───────────────┤
                                │Show record location │ $showDiskLocshowRecordId  │
                                ├─────────────────────┼────────────────┼───────────────┤
                                │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.

       SEE ALSO:
          The "find" command in the MongoDB Manual.

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),
                              "}",
                              "}");
          mongoc_collection_command_simple (collection, command, NULL, &reply, &error);

       SEE ALSO:
          The "explain" command in the MongoDB Manual.

AUTHOR

       MongoDB, Inc

       2009-present, MongoDB, Inc.