'\" 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_COUNT_DOCUMENTS" "3" "May 07, 2024" "1.27.1" "libmongoc"
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
int64_t
mongoc_collection_count_documents (mongoc_collection_t *collection,
                                   const bson_t *filter,
                                   const bson_t *opts,
                                   const mongoc_read_prefs_t *read_prefs,
                                   bson_t *reply,
                                   bson_error_t *error);
.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 filter.
.IP \(bu 2
\fBopts\fP: A \fI\%bson_t\fP, \fBNULL\fP to ignore.
.IP \(bu 2
\fBread_prefs\fP: A \fI\%mongoc_read_prefs_t\fP or \fBNULL\fP\&.
.IP \(bu 2
\fBreply\fP: A maybe\-\fBNULL\fP pointer to \fI\%overwritable storage\fP for a \fI\%bson_t\fP to contain the results.
.IP \(bu 2
\fBerror\fP: An optional location for a \fI\%bson_error_t\fP or \fBNULL\fP\&.
.UNINDENT
.sp
\fBopts\fP may be NULL or a BSON document with additional command options:
.INDENT 0.0
.IP \(bu 2
\fBreadConcern\fP: Construct a \fI\%mongoc_read_concern_t\fP and use \fI\%mongoc_read_concern_append()\fP to add the read concern to \fBopts\fP\&. See the example code for \fI\%mongoc_client_read_command_with_opts()\fP\&. Read concern requires MongoDB 3.2 or later, otherwise an error is returned.
.IP \(bu 2
\fBsessionId\fP: First, 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, and 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\&.
.IP \(bu 2
\fBcollation\fP: Configure textual comparisons. See \fI\%Setting Collation Order\fP, and \fI\%the MongoDB Manual entry on Collation\fP\&. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
.IP \(bu 2
\fBserverId\fP: To target a specific server, include an int32 \(dqserverId\(dq field. Obtain the id by calling \fI\%mongoc_client_select_server()\fP, then \fI\%mongoc_server_description_id()\fP on its return value.
.IP \(bu 2
\fBskip\fP: An int specifying how many documents matching the \fBquery\fP should be skipped before counting.
.IP \(bu 2
\fBlimit\fP: An int specifying the maximum number of documents to count.
.IP \(bu 2
\fBcomment\fP: A \fI\%bson_value_t\fP specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Only string values are supported prior to MongoDB 4.4.
.IP \(bu 2
\fBhint\fP: A document or string that specifies the index to use to support the query predicate.
.UNINDENT
.sp
Other options are included in the sent \fBaggregate\fP command. For a list of all options, see \fI\%the MongoDB Manual entry on the aggregate command\fP\&.
.SH DESCRIPTION
.sp
This functions executes a count query on \fBcollection\fP\&. In contrast with \fI\%mongoc_collection_estimated_document_count()\fP, the count returned is guaranteed to be accurate.
.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 ERRORS
.sp
Errors are propagated via the \fBerror\fP parameter.
.SH RETURNS
.sp
\-1 on failure, otherwise the number of documents counted.
.SH EXAMPLE
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#include <bson/bson.h>
#include <mongoc/mongoc.h>
#include <stdio.h>

static void
print_count (mongoc_collection_t *collection, bson_t *filter)
{
   bson_error_t error;
   int64_t count;
   bson_t* opts = BCON_NEW (\(dqskip\(dq, BCON_INT64(5));

   count = mongoc_collection_count_documents (
      collection, filter, opts, NULL, NULL, &error);
   bson_destroy (opts);

   if (count < 0) {
      fprintf (stderr, \(dqCount failed: %s\en\(dq, error.message);
   } else {
      printf (\(dq%\(dq PRId64 \(dq documents counted.\en\(dq, count);
   }
}
.EE
.UNINDENT
.UNINDENT
.SH MIGRATING FROM DEPRECATED COUNT FUNCTIONS
.sp
When migrating to \fI\%mongoc_collection_count_documents()\fP from the deprecated \fI\%mongoc_collection_count()\fP or \fI\%mongoc_collection_count_with_opts()\fP, the following query operators in the filter must be replaced:
.TS
center;
|l|l|.
_
T{
Operator
T}	T{
Replacement
T}
_
T{
$where
T}	T{
\fI\%$expr\fP
T}
_
T{
$near
T}	T{
\fI\%$geoWithin\fP with \fI\%$center\fP
T}
_
T{
$nearSphere
T}	T{
\fI\%$geoWithin\fP with \fI\%$centerSphere\fP
T}
_
.TE
.sp
$expr requires MongoDB 3.6+
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%mongoc_collection_estimated_document_count()\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.