MONGOC_DATABASE_AGGREGATE(3) libmongoc MONGOC_DATABASE_AGGREGATE(3) 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); 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 ex- ample code for mongoc_client_read_command_with_opts(). Read concern re- quires 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 data- base, 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 valida- tion 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 re- turned 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 lan- guage. * 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. * hint: A document or string that specifies the index to use to support the query predicate. 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 un- derlying database upon the first call to mongoc_cursor_next(). For more in- formation on building aggregation pipelines, see the MongoDB Manual entry on the aggregate command. Note that the pipeline must start with a compati- ble stage that does not require an underlying collection (e.g. "$curren- tOp", "$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 pri- mary 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 net- work 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; } AUTHOR MongoDB, Inc COPYRIGHT 2009-present, MongoDB, Inc. 1.30.8 Aug 27, 2026 MONGOC_DATABASE_AGGREGATE(3)
SYNOPSIS | PARAMETERS | DESCRIPTION | RETURNS | EXAMPLE | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mongoc_database_aggregate&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>