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

18collection: A mongoc_collection_t.
19
20flags: A mongoc_query_flags_t. Not all flag values apply. In particu‐
21         lar, setting MONGOC_QUERY_EXHAUST results in an error.
22
23pipeline: A bson_t, either a BSON array or a BSON document containing
24         an array field named "pipeline".
25
26opts: A bson_t containing options for the command, or NULL.
27
28read_prefs: A mongoc_read_prefs_t or NULL.
29
30       opts may be NULL or a BSON document with additional command options:
31
32readConcern:   Construct   a   mongoc_read_concern_t   and  use  mon‐
33         goc_read_concern_append to add the read concern to opts. See the  ex‐
34         ample code for mongoc_client_read_command_with_opts. Read concern re‐
35         quires MongoDB 3.2 or later, otherwise an error is returned.
36
37writeConcern:  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
41sessionId:  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
48bypassDocumentValidation: Set to true to skip server-side schema val‐
49         idation of the provided BSON documents.
50
51collation: Configure textual comparisons. See Setting  Collation  Or‐
52         der,  and  the  MongoDB Manual entry on Collation. Collation requires
53         MongoDB 3.2 or later, otherwise an error is returned.
54
55serverId: 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
59batchSize: An int32 representing number of documents requested to  be
60         returned on each call to mongoc_cursor_next
61
62let:  A  BSON  document  consisting of any number of parameter names,
63         each followed by definitions of constants in the  MQL  Aggregate  Ex‐
64         pression language
65
66       For  a  list of all options, see the MongoDB Manual entry on the aggre‐
67       gate command.
68
69       This function is considered a retryable read operation unless the pipe‐
70       line  contains a write stage like $out or $merge.  Upon a transient er‐
71       ror (a network error, errors due to replica set failover, etc.) the op‐
72       eration is safely retried once.  If retryreads is false in the URI (see
73       mongoc_uri_t) the retry behavior does not apply.
74

DESCRIPTION

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

RETURNS

104       This  function returns a newly allocated mongoc_cursor_t that should be
105       freed with mongoc_cursor_destroy() when no longer in use. The  returned
106       mongoc_cursor_t  is  never NULL, even on error. The user must call mon‐
107       goc_cursor_next() on the returned mongoc_cursor_t to execute  the  ini‐
108       tial command.
109
110       Cursor  errors can be checked with mongoc_cursor_error_document. It al‐
111       ways fills out the bson_error_t if an error  occurred,  and  optionally
112       includes a server reply document if the error occurred server-side.
113
114       WARNING:
115          Failure  to  handle the result of this function is a programming er‐
116          ror.
117

EXAMPLE

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

OTHER PARAMETERS

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

AUTHOR

174       MongoDB, Inc
175
177       2017-present, MongoDB, Inc
178
179
180
181
1821.20.0                           Nov 18, 2021   MONGOC_COLLECTION_AGGREGATE(3)
Impressum