'\" t
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MONGOC_COLLECTION_FIND" "3" "May 07, 2024" "1.27.1" "libmongoc"
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Deprecated since version 1.5.0: This function is deprecated and should not be used in new code.

.UNINDENT
.UNINDENT
.sp
Use the more convenient \fI\%mongoc_collection_find_with_opts()\fP instead.
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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_DEPRECATED_FOR (mongoc_collection_find_with_opts)
      BSON_GNUC_WARN_UNUSED_RESULT;
.EE
.UNINDENT
.UNINDENT
.SH PARAMETERS
.INDENT 0.0
.IP \(bu 2
\fBcollection\fP: A \fI\%mongoc_collection_t\fP\&.
.IP \(bu 2
\fBflags\fP: A \fI\%mongoc_query_flags_t\fP\&.
.IP \(bu 2
\fBskip\fP: A uint32_t of number of documents to skip or 0.
.IP \(bu 2
\fBlimit\fP: A uint32_t of max number of documents to return or 0.
.IP \(bu 2
\fBbatch_size\fP: A uint32_t containing batch size of document result sets or 0 for default. Default is 100.
.IP \(bu 2
\fBquery\fP: A \fI\%bson_t\fP containing the query and options to execute.
.IP \(bu 2
\fBfields\fP: A \fI\%bson_t\fP containing fields to return or \fBNULL\fP\&.
.IP \(bu 2
\fBread_prefs\fP: A \fI\%mongoc_read_prefs_t\fP or \fBNULL\fP for default read preferences.
.UNINDENT
.SH DESCRIPTION
.sp
This function shall execute a query on the underlying \fBcollection\fP\&.
.sp
If no options are necessary, \fBquery\fP can simply contain a query such as \fB{a:1}\fP\&. If you would like to specify options such as a sort order, the query must be placed inside of \fB{\(dq$query\(dq: {}}\fP\&. See the example below for how to properly specify additional options to \fBquery\fP\&.
.sp
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 \fBretryreads\fP is false in the URI (see \fI\%mongoc_uri_t\fP) the retry behavior does not apply.
.SH RETURNS
.sp
This function returns a newly allocated \fI\%mongoc_cursor_t\fP that should be freed with \fI\%mongoc_cursor_destroy()\fP when no longer in use. The returned \fI\%mongoc_cursor_t\fP is never \fBNULL\fP, even on error. The user must call \fI\%mongoc_cursor_next()\fP on the returned \fI\%mongoc_cursor_t\fP to execute the initial command.
.sp
Cursor errors can be checked with \fI\%mongoc_cursor_error_document()\fP\&. It always fills out the \fI\%bson_error_t\fP if an error occurred, and optionally includes a server reply document if the error occurred server\-side.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Failure to handle the result of this function is a programming error.
.UNINDENT
.UNINDENT
.SH EXAMPLE
.sp
Print All Documents in a Collection
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#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 (\(dq$query\(dq,
                     \(dq{\(dq,
                     \(dqfoo\(dq,
                     BCON_INT32 (1),
                     \(dq}\(dq,
                     \(dq$orderby\(dq,
                     \(dq{\(dq,
                     \(dqbar\(dq,
                     BCON_INT32 (\-1),
                     \(dq}\(dq);
   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 (\(dq%s\en\(dq, str);
      bson_free (str);
   }

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

   mongoc_cursor_destroy (cursor);
   bson_destroy (query);
}
.EE
.UNINDENT
.UNINDENT
.SH THE "FIND" COMMAND
.sp
Queries have historically been sent as OP_QUERY wire protocol messages, but beginning in MongoDB 3.2 queries use \fI\%the \(dqfind\(dq command\fP instead.
.sp
The driver automatically converts queries to the new \(dqfind\(dq 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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/* MongoDB 3.2+ \(dqfind\(dq command syntax */
query = BCON_NEW (\(dqfilter\(dq,
                  \(dq{\(dq,
                  \(dqfoo\(dq,
                  BCON_INT32 (1),
                  \(dq}\(dq,
                  \(dqsort\(dq,
                  \(dq{\(dq,
                  \(dqbar\(dq,
                  BCON_INT32 (\-1),
                  \(dq}\(dq);
cursor = mongoc_collection_find (
   collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
.EE
.UNINDENT
.UNINDENT
.sp
The \(dqfind\(dq command takes different options from the traditional OP_QUERY message.
.TS
center;
|l|l|l|.
_
T{
Query
T}	T{
\fB$query\fP
T}	T{
\fBfilter\fP
T}
_
T{
Sort
T}	T{
\fB$orderby\fP
T}	T{
\fBsort\fP
T}
_
T{
Show record location
T}	T{
\fB$showDiskLoc\fP
T}	T{
\fBshowRecordId\fP
T}
_
T{
Other $\-options
T}	T{
\fB$<option name>\fP
T}	T{
\fB<option name>\fP
T}
_
.TE
.sp
Most applications should use the OP_QUERY syntax, with \(dq$query\(dq, \(dq$orderby\(dq, and so on, and rely on the driver to convert to the new syntax if needed.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%The \(dqfind\(dq command\fP in the MongoDB Manual.
.fi
.sp
.UNINDENT
.UNINDENT
.SH THE "EXPLAIN" COMMAND
.sp
With MongoDB before 3.2, a query with option \fB$explain: true\fP returns information about the query plan, instead of the query results. Beginning in MongoDB 3.2, there is a separate \(dqexplain\(dq command. The driver will not convert \(dq$explain\(dq queries to \(dqexplain\(dq commands, you must call the \(dqexplain\(dq command explicitly:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/* MongoDB 3.2+, \(dqexplain\(dq command syntax */
command = BCON_NEW (\(dqexplain\(dq,
                    \(dq{\(dq,
                    \(dqfind\(dq,
                    BCON_UTF8 (\(dqcollection_name\(dq),
                    \(dqfilter\(dq,
                    \(dq{\(dq,
                    \(dqfoo\(dq,
                    BCON_INT32 (1),
                    \(dq}\(dq,
                    \(dq}\(dq);
mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
.EE
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%The \(dqexplain\(dq command\fP in the MongoDB Manual.
.fi
.sp
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.