1MONGOC_COLLECTION_AGGREGATE(3)     libmongoc    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. Not all flag values apply. In particu‐
21         lar, setting MONGOC_QUERY_EXHAUST results in an error.
22
23       · pipeline: A bson_t, either a BSON array or a BSON document containing
24         an array field named "pipeline".
25
26       · opts: A bson_t containing options for the command, or NULL.
27
28       · read_prefs: A mongoc_read_prefs_t or NULL.
29
30       opts may be NULL or a BSON document with additional command options:
31
32       · readConcern:   Construct   a   mongoc_read_concern_t   and  use  mon‐
33         goc_read_concern_append to add the read  concern  to  opts.  See  the
34         example  code  for mongoc_client_read_command_with_opts. Read concern
35         requires MongoDB 3.2 or later, otherwise an error is returned.
36
37       · writeConcern:  Construct  a  mongoc_write_concern_t  and   use   mon‐
38         goc_write_concern_append  to  add  the write concern to opts. See the
39         example code for mongoc_client_write_command_with_opts.
40
41       · sessionId:  First,  construct  a  mongoc_client_session_t  with  mon‐
42         goc_client_start_session.  You  can  begin  a  transaction  with mon‐
43         goc_client_session_start_transaction, optionally with a mongoc_trans‐
44         action_opt_t  that  overrides  the options inherited from collection,
45         and use mongoc_client_session_append to add the session to opts.  See
46         the example code for mongoc_client_session_t.
47
48       · bypassDocumentValidation: Set to true to skip server-side schema val‐
49         idation of the provided BSON documents.
50
51       · collation:  Configure  textual  comparisons.  See  Setting  Collation
52         Order,  and the MongoDB Manual entry on Collation. Collation requires
53         MongoDB 3.2 or later, otherwise an error is returned.
54
55       · serverId: To target a specific server, include  an  int32  "serverId"
56         field.  Obtain  the  id  by calling mongoc_client_select_server, then
57         mongoc_server_description_id on its return value.
58
59       · batchSize: An int32 representing number of documents requested to  be
60         returned on each call to mongoc_cursor_next
61
62       For  a  list of all options, see the MongoDB Manual entry on the aggre‐
63       gate command.
64
65       This function is considered a retryable read operation unless the pipe‐
66       line  contains  a  write  stage  like $out or $merge.  Upon a transient
67       error (a network error, errors due to replica set failover,  etc.)  the
68       operation  is  safely  retried once.  If retryreads is false in the URI
69       (see mongoc_uri_t) the retry behavior does not apply.
70

DESCRIPTION

72       This function creates a cursor which sends the aggregate command on the
73       underlying  collection upon the first call to mongoc_cursor_next(). For
74       more information on building aggregation  pipelines,  see  the  MongoDB
75       Manual entry on the aggregate command.
76
77       Read preferences, read and write concern, and collation can be overrid‐
78       den by various sources. The highest-priority sources for these  options
79       are listed first in the following table. In a transaction, read concern
80       and write concern are prohibited in opts and the read  preference  must
81       be  primary or NULL. Write concern is applied from opts, or if opts has
82       no write concern and the  aggregation  pipeline  includes  "$out",  the
83       write  concern is applied from collection. The write concern is omitted
84       for MongoDB before 3.4.
85
86            ┌─────────────────┬──────────────┬───────────────┬───────────┐
87            │Read Preferences │ Read Concern │ Write Concern │ Collation │
88            ├─────────────────┼──────────────┼───────────────┼───────────┤
89read_prefs       opts         opts          opts      
90            ├─────────────────┼──────────────┼───────────────┼───────────┤
91            │Transaction      │ Transaction  │ Transaction   │           │
92            ├─────────────────┼──────────────┼───────────────┼───────────┤
93collection       collection   collection    │           │
94            └─────────────────┴──────────────┴───────────────┴───────────┘
95
96       See the example for transactions and for the  "distinct"  command  with
97       opts.
98

RETURNS

100       This  function returns a newly allocated mongoc_cursor_t that should be
101       freed with mongoc_cursor_destroy() when no longer in use. The  returned
102       mongoc_cursor_t  is  never  NULL;  if  the  parameters are invalid, the
103       bson_error_t in the mongoc_cursor_t is filled out, and the  mongoc_cur‐
104       sor_t  is  returned  before  the server is selected. The user must call
105       mongoc_cursor_next() on the returned  mongoc_cursor_t  to  execute  the
106       aggregation pipeline.
107
108       WARNING:
109          Failure  to  handle  the  result  of  this function is a programming
110          error.
111

EXAMPLE

113          #include <bson/bson.h>
114          #include <mongoc/mongoc.h>
115
116          static mongoc_cursor_t *
117          pipeline_query (mongoc_collection_t *collection)
118          {
119             mongoc_cursor_t *cursor;
120             bson_t *pipeline;
121
122             pipeline = BCON_NEW ("pipeline",
123                                  "[",
124                                  "{",
125                                  "$match",
126                                  "{",
127                                  "foo",
128                                  BCON_UTF8 ("A"),
129                                  "}",
130                                  "}",
131                                  "{",
132                                  "$match",
133                                  "{",
134                                  "bar",
135                                  BCON_BOOL (false),
136                                  "}",
137                                  "}",
138                                  "]");
139
140             cursor = mongoc_collection_aggregate (
141                collection, MONGOC_QUERY_NONE, pipeline, NULL, NULL);
142
143             bson_destroy (pipeline);
144
145             return cursor;
146          }
147

OTHER PARAMETERS

149       When using $out, the pipeline  stage  that  writes,  the  write_concern
150       field  of the mongoc_cursor_t will be set to the mongoc_write_concern_t
151       parameter, if it is valid, and applied to the write command  when  mon‐
152       goc_cursor_next() is called. Pass any other parameters to the aggregate
153       command, besides pipeline, as fields in opts:
154
155          mongoc_write_concern_t *write_concern = mongoc_write_concern_new ();
156          mongoc_write_concern_set_w (write_concern, 3);
157
158          pipeline =
159             BCON_NEW ("pipeline", "[", "{", "$out", BCON_UTF8 ("collection2"), "}", "]");
160
161          opts = BCON_NEW ("bypassDocumentValidation", BCON_BOOL (true));
162          mongoc_write_concern_append (write_concern, opts);
163
164          cursor = mongoc_collection_aggregate (
165             collection1, MONGOC_QUERY_NONE, pipeline, opts, NULL);
166

AUTHOR

168       MongoDB, Inc
169
171       2017-present, MongoDB, Inc
172
173
174
175
1761.17.4                           Feb 04, 2021   MONGOC_COLLECTION_AGGREGATE(3)
Impressum