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

SYNOPSIS

6          int64_t
7          mongoc_collection_count_documents (mongoc_collection_t *collection,
8                                             const bson_t *filter,
9                                             const bson_t *opts,
10                                             const mongoc_read_prefs_t *read_prefs,
11                                             bson_t *reply,
12                                             bson_error_t *error);
13

PARAMETERS

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

DESCRIPTION

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

ERRORS

77       Errors are propagated via the error parameter.
78

RETURNS

80       -1 on failure, otherwise the number of documents counted.
81

EXAMPLE

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

MIGRATING FROM DEPRECATED COUNT FUNCTIONS

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

AUTHOR

128       MongoDB, Inc
129

131       2017-present, MongoDB, Inc
132
133
134
135
1361.25.1                           Nov 08, 20M2O3NGOC_COLLECTION_COUNT_DOCUMENTS(3)
Impressum