'\" 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_WITH_OPTS" "3" "May 07, 2024" "1.27.1" "libmongoc"
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
mongoc_cursor_t *
mongoc_collection_find_with_opts (mongoc_collection_t *collection,
                                  const bson_t *filter,
                                  const bson_t *opts,
                                  const mongoc_read_prefs_t *read_prefs)
   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
\fBfilter\fP: A \fI\%bson_t\fP containing the query to execute.
.IP \(bu 2
\fBopts\fP: A \fI\%bson_t\fP query options, including sort order and which fields to return. Can be \fBNULL\fP\&.
.IP \(bu 2
\fBread_prefs\fP: A \fI\%mongoc_read_prefs_t\fP or \fBNULL\fP\&.
.UNINDENT
.SH DESCRIPTION
.sp
Query on \fBcollection\fP, passing arbitrary query options to the server in \fBopts\fP\&.
.sp
To target a specific server, include an integer \(dqserverId\(dq field in \fBopts\fP with an id obtained first by calling \fI\%mongoc_client_select_server()\fP, then \fI\%mongoc_server_description_id()\fP on its return value.
.sp
Read preferences, read concern, and collation can be overridden by various sources. In a transaction, read concern and write concern are prohibited in \fBopts\fP and the read preference must be primary or NULL. The highest\-priority sources for these options are listed first in the following table. No write concern is applied.
.TS
center;
|l|l|l|.
_
T{
Read Preferences
T}	T{
Read Concern
T}	T{
Collation
T}
_
T{
\fBread_prefs\fP
T}	T{
\fBopts\fP
T}	T{
\fBopts\fP
T}
_
T{
Transaction
T}	T{
Transaction
T}	T{
T}
_
T{
\fBcollection\fP
T}	T{
T}	T{
T}
_
.TE
.sp
\fI\%See the example for transactions\fP and for \fI\%the \(dqdistinct\(dq command with opts\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 EXAMPLES
.sp
Print First Ten 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_ten_documents (mongoc_collection_t *collection)
{
   bson_t *filter;
   bson_t *opts;
   mongoc_cursor_t *cursor;
   bson_error_t error;
   const bson_t *doc;
   char *str;

   /* filter by \(dqfoo\(dq: 1, order by \(dqbar\(dq descending */
   filter = BCON_NEW (\(dqfoo\(dq, BCON_INT32 (1));
   opts = BCON_NEW (
      \(dqlimit\(dq, BCON_INT64 (10), \(dqsort\(dq, \(dq{\(dq, \(dqbar\(dq, BCON_INT32 (\-1), \(dq}\(dq);

   cursor = mongoc_collection_find_with_opts (collection, filter, opts, 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 (filter);
   bson_destroy (opts);
}
.EE
.UNINDENT
.UNINDENT
.sp
More examples of modifying the query with \fBopts\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *filter;
bson_t *opts;
mongoc_read_prefs_t *read_prefs;

filter = BCON_NEW (\(dqfoo\(dq, BCON_INT32 (1));

/* Include \(dqfield_name_one\(dq and \(dqfield_name_two\(dq in \(dqprojection\(dq, omit
 * others. \(dq_id\(dq must be specifically removed or it is included by default.
 */
opts = BCON_NEW (\(dqprojection\(dq, \(dq{\(dq,
                    \(dqfield_name_one\(dq, BCON_BOOL (true),
                    \(dqfield_name_two\(dq, BCON_BOOL (true),
                    \(dq_id\(dq, BCON_BOOL (false),
                 \(dq}\(dq,
                 \(dqtailable\(dq, BCON_BOOL (true),
                 \(dqawaitData\(dq, BCON_BOOL (true),
                 \(dqsort\(dq, \(dq{\(dq, \(dqbar\(dq, BCON_INT32 (\-1), \(dq}\(dq,
                 \(dqcollation\(dq, \(dq{\(dq,
                    \(dqlocale\(dq, BCON_UTF8(\(dqen_US\(dq),
                    \(dqcaseFirst\(dq, BCON_UTF8 (\(dqlower\(dq),
                 \(dq}\(dq);

read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);

cursor =
   mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
.EE
.UNINDENT
.UNINDENT
.sp
The following options are supported.
.TS
center;
|l|l|l|l|.
_
T{
Option
T}	T{
BSON type
T}	T{
Option
T}	T{
BSON type
T}
_
T{
\fBprojection\fP
T}	T{
document
T}	T{
\fBmax\fP
T}	T{
document
T}
_
T{
\fBsort\fP
T}	T{
document
T}	T{
\fBmaxTimeMS\fP
T}	T{
non\-negative int64
T}
_
T{
\fBskip\fP
T}	T{
non\-negative int64
T}	T{
\fBmaxAwaitTimeMS\fP
T}	T{
non\-negative int64
T}
_
T{
\fBlimit\fP
T}	T{
non\-negative int64
T}	T{
\fBmin\fP
T}	T{
document
T}
_
T{
\fBbatchSize\fP
T}	T{
non\-negative int64
T}	T{
\fBnoCursorTimeout\fP
T}	T{
bool
T}
_
T{
\fBexhaust\fP
T}	T{
bool
T}	T{
\fBoplogReplay\fP
T}	T{
bool
T}
_
T{
\fBhint\fP
T}	T{
string or document
T}	T{
\fBreadConcern\fP
T}	T{
document
T}
_
T{
\fBallowPartialResults\fP
T}	T{
bool
T}	T{
\fBreturnKey\fP
T}	T{
bool
T}
_
T{
\fBawaitData\fP
T}	T{
bool
T}	T{
\fBsessionId\fP
T}	T{
(none)
T}
_
T{
\fBcollation\fP
T}	T{
document
T}	T{
\fBshowRecordId\fP
T}	T{
bool
T}
_
T{
\fBcomment\fP
T}	T{
any
T}	T{
\fBsingleBatch\fP
T}	T{
bool
T}
_
T{
\fBallowDiskUse\fP
T}	T{
bool
T}	T{
\fBlet\fP
T}	T{
document
T}
_
.TE
.sp
All options are documented in the reference page for \fI\%the \(dqfind\(dq command\fP in the MongoDB server manual, except for \(dqmaxAwaitTimeMS\(dq, \(dqsessionId\(dq, and \(dqexhaust\(dq.
.sp
\(dqmaxAwaitTimeMS\(dq is the maximum amount of time for the server to wait on new documents to satisfy a query, if \(dqtailable\(dq and \(dqawaitData\(dq are both true.
If no new documents are found, the tailable cursor receives an empty batch. The \(dqmaxAwaitTimeMS\(dq option is ignored for MongoDB older than 3.4.
.sp
To add a \(dqsessionId\(dq, construct a \fI\%mongoc_client_session_t\fP with \fI\%mongoc_client_start_session()\fP\&. You can begin a transaction with \fI\%mongoc_client_session_start_transaction()\fP, optionally with a \fI\%mongoc_transaction_opt_t\fP that overrides the options inherited from \fBcollection\fP\&. Then use \fI\%mongoc_client_session_append()\fP to add the session to \fBopts\fP\&. See the example code for \fI\%mongoc_client_session_t\fP\&.
.sp
To add a \(dqreadConcern\(dq, construct a \fI\%mongoc_read_concern_t\fP with \fI\%mongoc_read_concern_new()\fP and configure it with \fI\%mongoc_read_concern_set_level()\fP\&. Then use \fI\%mongoc_read_concern_append()\fP to add the read concern to \fBopts\fP\&.
.sp
\(dqexhaust\(dq requests the construction of an exhaust cursor.
.sp
For some options like \(dqcollation\(dq, the driver returns an error if the server version is too old to support the feature.
Any fields in \fBopts\fP that are not listed here are passed to the server unmodified.
.sp
\fBallowDiskUse\fP is only supported in MongoDB 4.4+.
.sp
\fBcomment\fP only supports string values prior to MongoDB 4.4.
.SH DEPRECATED OPTIONS
.sp
The \fBsnapshot\fP boolean option is removed in MongoDB 4.0. The \fBmaxScan\fP option, a non\-negative int64, is deprecated in MongoDB 4.0 and will be removed in a future MongoDB version. The \fBoplogReplay\fP boolean option is deprecated in MongoDB 4.4. All of these options are supported by the C Driver with older MongoDB versions.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%The \(dqfind\(dq command\fP in the MongoDB Manual. All options listed there are supported by the C Driver.  For MongoDB servers before 3.2, the driver transparently converts the query to a legacy OP_QUERY message.
.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.
.