# mongoc_database_aggregate()

## Synopsis

    mongoc_cursor_t *
    mongoc_database_aggregate (mongoc_database_t *database,
                               const bson_t *pipeline,
                               const bson_t *opts,
                               const mongoc_read_prefs_t *read_prefs)
       BSON_GNUC_WARN_UNUSED_RESULT;

## Parameters

- `database`: A mongoc_database_t.

- `pipeline`: A `bson_t`, either a BSON array or a BSON document containing an array field named “pipeline”.

- `opts`: A `bson_t` containing options for the command, or `NULL`.

- `read_prefs`: A mongoc_read_prefs_t or `NULL`.

`opts` may be NULL or a BSON document with additional command options:

- `readConcern`: Construct a mongoc_read_concern_t and use mongoc_read_concern_append() to add the read concern to `opts`. See the example code for mongoc_client_read_command_with_opts(). Read concern requires MongoDB 3.2 or later, otherwise an error is returned.

- `writeConcern`: Construct a mongoc_write_concern_t and use mongoc_write_concern_append() to add the write concern to `opts`. See the example code for mongoc_client_write_command_with_opts().

- `sessionId`: First, construct a mongoc_client_session_t with mongoc_client_start_session(). You can begin a transaction with mongoc_client_session_start_transaction(), optionally with a mongoc_transaction_opt_t that overrides the options inherited from `database`, and use mongoc_client_session_append() to add the session to `opts`. See the example code for mongoc_client_session_t.

- `bypassDocumentValidation`: Set to `true` to skip server-side schema validation of the provided BSON documents.

- `collation`: Configure textual comparisons. See Setting Collation Order, and the MongoDB Manual entry on Collation. Collation requires MongoDB 3.2 or later, otherwise an error is returned.

- `serverId`: To target a specific server, include an int32 “serverId” field. Obtain the id by calling mongoc_client_select_server(), then mongoc_server_description_id() on its return value.

- `batchSize`: An `int32` representing number of documents requested to be returned on each call to mongoc_cursor_next()

- `let`: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.

- `comment`: A `bson_value_t` specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Only string values are supported prior to MongoDB 4.4.

For a list of all options, see the MongoDB Manual entry on the aggregate command.

## Description

This function creates a cursor which sends the aggregate command on the underlying database upon the first call to mongoc_cursor_next(). For more information on building aggregation pipelines, see the MongoDB Manual entry on the aggregate command. Note that the pipeline must start with a compatible stage that does not require an underlying collection (e.g. “$currentOp”, “$listLocalSessions”).

Read preferences, read and write concern, and collation can be overridden by various sources. The highest-priority sources for these options are listed first in the following table. In a transaction, read concern and write concern are prohibited in `opts` and the read preference must be primary or NULL. Write concern is applied from `opts`, or if `opts` has no write concern and the aggregation pipeline includes “$out”, the write concern is applied from `database`.

Read Preferences | Read Concern | Write Concern | Collation
--- | --- | --- | ---
`read_prefs` | `opts` | `opts` | `opts`
Transaction | Transaction | Transaction |
`database` | `database` | `database` |

See the example for transactions and for the “distinct” command with opts.

This function is considered a retryable read operation unless the pipeline contains a write stage like $out or $merge. Upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once. If `retryreads` is false in the URI (see mongoc_uri_t) the retry behavior does not apply.

## Returns

This function returns a newly allocated mongoc_cursor_t that should be freed with mongoc_cursor_destroy() when no longer in use. The returned mongoc_cursor_t is never `NULL`, even on error. The user must call mongoc_cursor_next() on the returned mongoc_cursor_t to execute the initial command.

Cursor errors can be checked with mongoc_cursor_error_document(). It always fills out the `bson_error_t` if an error occurred, and optionally includes a server reply document if the error occurred server-side.

Warning

Failure to handle the result of this function is a programming error.

## Example

    #include <bson/bson.h>
    #include <mongoc/mongoc.h>

    static mongoc_cursor_t *
    current_op_query (mongoc_client_t *client)
    {
       mongoc_cursor_t *cursor;
       mongoc_database_t *database;
       bson_t *pipeline;

       pipeline = BCON_NEW ("pipeline",
                            "[",
                            "{",
                            "$currentOp",
                            "{",
                            "}",
                            "}",
                            "]");

       /* $currentOp must be run on the admin database */
       database = mongoc_client_get_database (client, "admin");

       cursor = mongoc_database_aggregate (
          database, pipeline, NULL, NULL);

       bson_destroy (pipeline);
       mongoc_database_destroy (database);

       return cursor;
    }