1MONGOC_COLLECTION_AGGREGATE(3) MongoDB C Driver MONGOC_COLLECTION_AGGREGATE(3)
2
3
4

NAME

6       mongoc_collection_aggregate - mongoc_collection_aggregate()
7

SYNOPSIS

9          mongoc_cursor_t *
10          mongoc_collection_aggregate (mongoc_collection_t *collection,
11                                       mongoc_query_flags_t flags,
12                                       const bson_t *pipeline,
13                                       const bson_t *opts,
14                                       const mongoc_read_prefs_t *read_prefs)
15             BSON_GNUC_WARN_UNUSED_RESULT;
16

PARAMETERS

18       · collection: A mongoc_collection_t.
19
20       · flags: A mongoc_query_flags_t.
21
22       · pipeline: A bson_t, either a BSON array or a BSON document containing
23         an array field named "pipeline".
24
25       · opts: A bson_t containing options for the command, or NULL.
26
27       · read_prefs: A mongoc_read_prefs_t or NULL.
28
29       opts may be NULL or a BSON document with additional command options:
30
31       · readConcern:  Construct  a   mongoc_read_concern_t   and   use   mon‐
32         goc_read_concern_append  to  add  the  read  concern to opts. See the
33         example code for mongoc_client_read_command_with_opts.  Read  concern
34         requires MongoDB 3.2 or later, otherwise an error is returned.
35
36       · writeConcern: For aggregations that include "$out", you can construct
37         a mongoc_write_concern_t and use mongoc_write_concern_append  to  add
38         the   write   concern   to  opts.  See  the  example  code  for  mon‐
39         goc_client_write_command_with_opts.
40
41       · sessionId:   Construct   a    mongoc_client_session_t    with    mon‐
42         goc_client_start_session  and use mongoc_client_session_append to add
43         the session to opts. See  the  example  code  for  mongoc_client_ses‐
44         sion_t.
45
46       · bypassDocumentValidation: Set to true to skip server-side schema val‐
47         idation of the provided BSON documents.
48
49       · collation:  Configure  textual  comparisons.  See  Setting  Collation
50         Order,  and the MongoDB Manual entry on Collation. Collation requires
51         MongoDB 3.2 or later, otherwise an error is returned.
52
53       · serverId: To target a specific server, include  an  int32  "serverId"
54         field.  Obtain  the  id  by calling mongoc_client_select_server, then
55         mongoc_server_description_id on its return value.
56
57       · batchSize: To specify the number of documents to return in each batch
58         of a response from the server, include an int "batchSize" field.
59
60       For  a  list of all options, see the MongoDB Manual entry on the aggre‐
61       gate command.
62

DESCRIPTION

64       This function shall execute an aggregation query on the underlying col‐
65       lection.  For  more  information on building aggregation pipelines, see
66       the MongoDB Manual entry on the aggregate command.
67
68       Read preferences, read and write concern, and collation can be overrid‐
69       den  by various sources. The highest-priority sources for these options
70       are listed first in the following table. In a transaction, read concern
71       and  write  concern are prohibited in opts and the read preference must
72       be primary or NULL. Write concern is applied from opts, or if opts  has
73       no  write  concern  and  the  aggregation pipeline includes "$out", the
74       write concern is applied from collection. The write concern is  omitted
75       for MongoDB before 3.4.
76
77            ┌─────────────────┬──────────────┬───────────────┬───────────┐
78            │Read Preferences │ Read Concern │ Write Concern │ Collation │
79            ├─────────────────┼──────────────┼───────────────┼───────────┤
80read_prefs       opts         opts          opts      
81            ├─────────────────┼──────────────┼───────────────┼───────────┤
82            │Transaction      │ Transaction  │ Transaction   │           │
83            ├─────────────────┼──────────────┼───────────────┼───────────┤
84collection       collection   collection    │           │
85            └─────────────────┴──────────────┴───────────────┴───────────┘
86
87       See  the  example  for transactions and for the "distinct" command with
88       opts.
89

RETURNS

91       This function returns a newly allocated mongoc_cursor_t that should  be
92       freed  with mongoc_cursor_destroy() when no longer in use. The returned
93       mongoc_cursor_t is never NULL;  if  the  parameters  are  invalid,  the
94       bson_error_t  in the mongoc_cursor_t is filled out, and the mongoc_cur‐
95       sor_t is returned before the server is selected.
96
97       WARNING:
98          Failure to handle the result  of  this  function  is  a  programming
99          error.
100

EXAMPLE

102          #include <bson/bson.h>
103          #include <mongoc/mongoc.h>
104
105          static mongoc_cursor_t *
106          pipeline_query (mongoc_collection_t *collection)
107          {
108             mongoc_cursor_t *cursor;
109             bson_t *pipeline;
110
111             pipeline = BCON_NEW ("pipeline",
112                                  "[",
113                                  "{",
114                                  "$match",
115                                  "{",
116                                  "foo",
117                                  BCON_UTF8 ("A"),
118                                  "}",
119                                  "}",
120                                  "{",
121                                  "$match",
122                                  "{",
123                                  "bar",
124                                  BCON_BOOL (false),
125                                  "}",
126                                  "}",
127                                  "]");
128
129             cursor = mongoc_collection_aggregate (
130                collection, MONGOC_QUERY_NONE, pipeline, NULL, NULL);
131
132             bson_destroy (pipeline);
133
134             return cursor;
135          }
136

OTHER PARAMETERS

138       When  using  $out,  the  pipeline  stage that writes, the write_concern
139       field of the mongoc_cursor_t will be set to the  mongoc_write_concern_t
140       parameter,  if  it is valid, and applied to the write command when mon‐
141       goc_cursor_next() is called. Pass any other parameters to the aggregate
142       command, besides pipeline, as fields in opts:
143
144          mongoc_write_concern_t *write_concern = mongoc_write_concern_new ();
145          mongoc_write_concern_set_w (write_concern, 3);
146
147          pipeline =
148             BCON_NEW ("pipeline", "[", "{", "$out", BCON_UTF8 ("collection2"), "}", "]");
149
150          opts = BCON_NEW ("bypassDocumentValidation", BCON_BOOL (true));
151          mongoc_write_concern_append (write_concern, opts);
152
153          cursor = mongoc_collection_aggregate (
154             collection1, MONGOC_QUERY_NONE, pipeline, opts, NULL);
155

AUTHOR

157       MongoDB, Inc
158
160       2017-present, MongoDB, Inc
161
162
163
164
1651.13.1                           Jan 24, 2019   MONGOC_COLLECTION_AGGREGATE(3)
Impressum