1MONGOC_DATABASE_AGGREGATE(3)       libmongoc      MONGOC_DATABASE_AGGREGATE(3)
2
3
4

NAME

6       mongoc_database_aggregate - mongoc_database_aggregate()
7

SYNOPSIS

9          mongoc_cursor_t *
10          mongoc_database_aggregate (mongoc_database_t *database,
11                                     const bson_t *pipeline,
12                                     const bson_t *opts,
13                                     const mongoc_read_prefs_t *read_prefs)
14             BSON_GNUC_WARN_UNUSED_RESULT;
15

PARAMETERS

17database: A mongoc_database_t.
18
19pipeline: A bson_t, either a BSON array or a BSON document containing
20         an array field named "pipeline".
21
22opts: A bson_t containing options for the command, or NULL.
23
24read_prefs: A mongoc_read_prefs_t or NULL.
25
26       opts may be NULL or a BSON document with additional command options:
27
28readConcern:  Construct  a   mongoc_read_concern_t   and   use   mon‐
29         goc_read_concern_append  to add the read concern to opts. See the ex‐
30         ample code for mongoc_client_read_command_with_opts. Read concern re‐
31         quires MongoDB 3.2 or later, otherwise an error is returned.
32
33writeConcern:   Construct   a  mongoc_write_concern_t  and  use  mon‐
34         goc_write_concern_append to add the write concern to  opts.  See  the
35         example code for mongoc_client_write_command_with_opts.
36
37sessionId:  First,  construct  a  mongoc_client_session_t  with  mon‐
38         goc_client_start_session. You  can  begin  a  transaction  with  mon‐
39         goc_client_session_start_transaction, optionally with a mongoc_trans‐
40         action_opt_t that overrides the options inherited from database,  and
41         use  mongoc_client_session_append to add the session to opts. See the
42         example code for mongoc_client_session_t.
43
44bypassDocumentValidation: Set to true to skip server-side schema val‐
45         idation of the provided BSON documents.
46
47collation:  Configure  textual comparisons. See Setting Collation Or‐
48         der, and the MongoDB Manual entry on  Collation.  Collation  requires
49         MongoDB 3.2 or later, otherwise an error is returned.
50
51serverId:  To  target  a specific server, include an int32 "serverId"
52         field. Obtain the id  by  calling  mongoc_client_select_server,  then
53         mongoc_server_description_id on its return value.
54
55batchSize:  An int32 representing number of documents requested to be
56         returned on each call to mongoc_cursor_next
57
58let: A BSON document consisting of any  number  of  parameter  names,
59         each  followed  by  definitions of constants in the MQL Aggregate Ex‐
60         pression language
61
62       For a list of all options, see the MongoDB Manual entry on  the  aggre‐
63       gate command.
64

DESCRIPTION

66       This function creates a cursor which sends the aggregate command on the
67       underlying database upon the first call  to  mongoc_cursor_next().  For
68       more  information  on  building  aggregation pipelines, see the MongoDB
69       Manual entry on the aggregate command.  Note  that  the  pipeline  must
70       start  with a compatible stage that does not require an underlying col‐
71       lection (e.g. "$currentOp", "$listLocalSessions").
72
73       Read preferences, read and write concern, and collation can be overrid‐
74       den  by various sources. The highest-priority sources for these options
75       are listed first in the following table. In a transaction, read concern
76       and  write  concern are prohibited in opts and the read preference must
77       be primary or NULL. Write concern is applied from opts, or if opts  has
78       no  write  concern  and  the  aggregation pipeline includes "$out", the
79       write concern is applied from database.
80
81            ┌─────────────────┬──────────────┬───────────────┬───────────┐
82            │Read Preferences │ Read Concern │ Write Concern │ Collation │
83            ├─────────────────┼──────────────┼───────────────┼───────────┤
84read_prefs       opts         opts          opts      
85            ├─────────────────┼──────────────┼───────────────┼───────────┤
86            │Transaction      │ Transaction  │ Transaction   │           │
87            ├─────────────────┼──────────────┼───────────────┼───────────┤
88database         database     database      │           │
89            └─────────────────┴──────────────┴───────────────┴───────────┘
90
91       See the example for transactions and for the  "distinct"  command  with
92       opts.
93
94       This function is considered a retryable read operation unless the pipe‐
95       line contains a write stage like $out or $merge.  Upon a transient  er‐
96       ror (a network error, errors due to replica set failover, etc.) the op‐
97       eration is safely retried once.  If retryreads is false in the URI (see
98       mongoc_uri_t) the retry behavior does not apply.
99

RETURNS

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

EXAMPLE

116          #include <bson/bson.h>
117          #include <mongoc/mongoc.h>
118
119          static mongoc_cursor_t *
120          current_op_query (mongoc_client_t *client)
121          {
122             mongoc_cursor_t *cursor;
123             mongoc_database_t *database;
124             bson_t *pipeline;
125
126             pipeline = BCON_NEW ("pipeline",
127                                  "[",
128                                  "{",
129                                  "$currentOp",
130                                  "{",
131                                  "}",
132                                  "}",
133                                  "]");
134
135             /* $currentOp must be run on the admin database */
136             database = mongoc_client_get_database (client, "admin");
137
138             cursor = mongoc_database_aggregate (
139                database, pipeline, NULL, NULL);
140
141             bson_destroy (pipeline);
142             mongoc_database_destroy (database);
143
144             return cursor;
145          }
146

AUTHOR

148       MongoDB, Inc
149
151       2017-present, MongoDB, Inc
152
153
154
155
1561.20.0                           Nov 18, 2021     MONGOC_DATABASE_AGGREGATE(3)
Impressum