1MONGOC_COLLECTION_COUNT_DOCUMENTS(3)libmongoMcONGOC_COLLECTION_COUNT_DOCUMENTS(3)
2
3
4

NAME

6       mongoc_collection_count_documents - mongoc_collection_count_documents()
7

SYNOPSIS

9          int64_t
10          mongoc_collection_count_documents (mongoc_collection_t *collection,
11                                             const bson_t *filter,
12                                             const bson_t *opts,
13                                             const mongoc_read_prefs_t *read_prefs,
14                                             bson_t *reply,
15                                             bson_error_t *error);
16

PARAMETERS

18       • collection: A mongoc_collection_t.
19
20       • filter: A bson_t containing the filter.
21
22       • opts: A bson_t, NULL to ignore.
23
24       • read_prefs: A mongoc_read_prefs_t or NULL.
25
26       • reply:  A  location  for an uninitialized bson_t to store the command
27         reply, NULL to ignore. If not NULL, reply will be initialized.
28
29       • error: An optional location for a bson_error_t or NULL.
30
31       opts may be NULL or a BSON document with additional command options:
32
33       • readConcern:    Construct    a    mongoc_read_concern_t    and    use
34         mongoc_read_concern_append() to add the read concern to opts. See the
35         example code for mongoc_client_read_command_with_opts(). Read concern
36         requires MongoDB 3.2 or later, otherwise an error is returned.
37
38       • sessionId:    First,   construct   a   mongoc_client_session_t   with
39         mongoc_client_start_session().  You  can  begin  a  transaction  with
40         mongoc_client_session_start_transaction(),    optionally    with    a
41         mongoc_transaction_opt_t that overrides the  options  inherited  from
42         collection, and use mongoc_client_session_append() to add the session
43         to opts. See the example code for mongoc_client_session_t.
44
45       • collation: Configure textual comparisons. See Setting  Collation  Or‐
46         der,  and  the  MongoDB Manual entry on Collation. Collation requires
47         MongoDB 3.2 or later, otherwise an error is returned.
48
49       • serverId: To target a specific server, include  an  int32  "serverId"
50         field.  Obtain  the id by calling mongoc_client_select_server(), then
51         mongoc_server_description_id() on its return value.
52
53       • skip: An int specifying how many documents matching the query  should
54         be skipped before counting.
55
56       • limit: An int specifying the maximum number of documents to count.
57
58       • comment: A bson_value_t specifying the comment to attach to this com‐
59         mand. The comment will appear in log messages, profiler  output,  and
60         currentOp  output.  Only string values are supported prior to MongoDB
61         4.4.
62
63       • hint: A document or string that specifies the index to use to support
64         the query predicate.
65
66       Other options are included in the sent aggregate command. For a list of
67       all options, see the MongoDB Manual entry on the aggregate command.
68

DESCRIPTION

70       This functions executes a count query on collection. In  contrast  with
71       mongoc_collection_estimated_document_count(),  the  count  returned  is
72       guaranteed to be accurate.
73
74       This function is considered a retryable read operation.  Upon  a  tran‐
75       sient error (a network error, errors due to replica set failover, etc.)
76       the operation is safely retried once.  If retryreads is  false  in  the
77       URI (see mongoc_uri_t) the retry behavior does not apply.
78

ERRORS

80       Errors are propagated via the error parameter.
81

RETURNS

83       -1 on failure, otherwise the number of documents counted.
84

EXAMPLE

86          #include <bson/bson.h>
87          #include <mongoc/mongoc.h>
88          #include <stdio.h>
89
90          static void
91          print_count (mongoc_collection_t *collection, bson_t *filter)
92          {
93             bson_error_t error;
94             int64_t count;
95             bson_t* opts = BCON_NEW ("skip", BCON_INT64(5));
96
97             count = mongoc_collection_count_documents (
98                collection, filter, opts, NULL, NULL, &error);
99             bson_destroy (opts);
100
101             if (count < 0) {
102                fprintf (stderr, "Count failed: %s\n", error.message);
103             } else {
104                printf ("%" PRId64 " documents counted.\n", count);
105             }
106          }
107

MIGRATING FROM DEPRECATED COUNT FUNCTIONS

109       When  migrating  to mongoc_collection_count_documents() from the depre‐
110       cated mongoc_collection_count() or mongoc_collection_count_with_opts(),
111       the following query operators in the filter must be replaced:
112
113                     ┌────────────┬────────────────────────────┐
114                     │Operator    │ Replacement                │
115                     ├────────────┼────────────────────────────┤
116                     │$where      │ $expr                      │
117                     ├────────────┼────────────────────────────┤
118                     │$near       │ $geoWithin with $center    │
119                     ├────────────┼────────────────────────────┤
120                     │$nearSphere │ $geoWithin            with │
121                     │            │ $centerSphere              │
122                     └────────────┴────────────────────────────┘
123
124       $expr requires MongoDB 3.6+
125
126       SEE ALSO:
127          mongoc_collection_estimated_document_count()
128
129

AUTHOR

131       MongoDB, Inc
132

134       2017-present, MongoDB, Inc
135
136
137
138
1391.24.3                           Aug 17, 20M2O3NGOC_COLLECTION_COUNT_DOCUMENTS(3)
Impressum