'\" t .\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "MONGOC_DATABASE_AGGREGATE" "3" "May 07, 2024" "1.27.1" "libmongoc" .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .EX 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; .EE .UNINDENT .UNINDENT .SH PARAMETERS .INDENT 0.0 .IP \(bu 2 \fBdatabase\fP: A \fI\%mongoc_database_t\fP\&. .IP \(bu 2 \fBpipeline\fP: A \fI\%bson_t\fP, either a BSON array or a BSON document containing an array field named \(dqpipeline\(dq. .IP \(bu 2 \fBopts\fP: A \fI\%bson_t\fP containing options for the command, or \fBNULL\fP\&. .IP \(bu 2 \fBread_prefs\fP: A \fI\%mongoc_read_prefs_t\fP or \fBNULL\fP\&. .UNINDENT .sp \fBopts\fP may be NULL or a BSON document with additional command options: .INDENT 0.0 .IP \(bu 2 \fBreadConcern\fP: Construct a \fI\%mongoc_read_concern_t\fP and use \fI\%mongoc_read_concern_append()\fP to add the read concern to \fBopts\fP\&. See the example code for \fI\%mongoc_client_read_command_with_opts()\fP\&. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. .IP \(bu 2 \fBwriteConcern\fP: Construct a \fI\%mongoc_write_concern_t\fP and use \fI\%mongoc_write_concern_append()\fP to add the write concern to \fBopts\fP\&. See the example code for \fI\%mongoc_client_write_command_with_opts()\fP\&. .IP \(bu 2 \fBsessionId\fP: First, construct a \fI\%mongoc_client_session_t\fP with \fI\%mongoc_client_start_session()\fP\&. You can begin a transaction with \fI\%mongoc_client_session_start_transaction()\fP, optionally with a \fI\%mongoc_transaction_opt_t\fP that overrides the options inherited from \fBdatabase\fP, and use \fI\%mongoc_client_session_append()\fP to add the session to \fBopts\fP\&. See the example code for \fI\%mongoc_client_session_t\fP\&. .IP \(bu 2 \fBbypassDocumentValidation\fP: Set to \fBtrue\fP to skip server\-side schema validation of the provided BSON documents. .IP \(bu 2 \fBcollation\fP: Configure textual comparisons. See \fI\%Setting Collation Order\fP, and \fI\%the MongoDB Manual entry on Collation\fP\&. Collation requires MongoDB 3.2 or later, otherwise an error is returned. .IP \(bu 2 \fBserverId\fP: To target a specific server, include an int32 \(dqserverId\(dq field. Obtain the id by calling \fI\%mongoc_client_select_server()\fP, then \fI\%mongoc_server_description_id()\fP on its return value. .IP \(bu 2 \fBbatchSize\fP: An \fBint32\fP representing number of documents requested to be returned on each call to \fI\%mongoc_cursor_next()\fP .IP \(bu 2 \fBlet\fP: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. .IP \(bu 2 \fBcomment\fP: A \fI\%bson_value_t\fP 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. .IP \(bu 2 \fBhint\fP: A document or string that specifies the index to use to support the query predicate. .UNINDENT .sp For a list of all options, see \fI\%the MongoDB Manual entry on the aggregate command\fP\&. .SH DESCRIPTION .sp This function creates a cursor which sends the aggregate command on the underlying database upon the first call to \fI\%mongoc_cursor_next()\fP\&. For more information on building aggregation pipelines, see \fI\%the MongoDB Manual entry on the aggregate command\fP\&. Note that the pipeline must start with a compatible stage that does not require an underlying collection (e.g. \(dq$currentOp\(dq, \(dq$listLocalSessions\(dq). .sp 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 \fBopts\fP and the read preference must be primary or NULL. Write concern is applied from \fBopts\fP, or if \fBopts\fP has no write concern and the aggregation pipeline includes \(dq$out\(dq, the write concern is applied from \fBdatabase\fP\&. .TS center; |l|l|l|l|. _ T{ Read Preferences T} T{ Read Concern T} T{ Write Concern T} T{ Collation T} _ T{ \fBread_prefs\fP T} T{ \fBopts\fP T} T{ \fBopts\fP T} T{ \fBopts\fP T} _ T{ Transaction T} T{ Transaction T} T{ Transaction T} T{ T} _ T{ \fBdatabase\fP T} T{ \fBdatabase\fP T} T{ \fBdatabase\fP T} T{ T} _ .TE .sp \fI\%See the example for transactions\fP and for \fI\%the \(dqdistinct\(dq command with opts\fP\&. .sp 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 \fBretryreads\fP is false in the URI (see \fI\%mongoc_uri_t\fP) the retry behavior does not apply. .SH RETURNS .sp This function returns a newly allocated \fI\%mongoc_cursor_t\fP that should be freed with \fI\%mongoc_cursor_destroy()\fP when no longer in use. The returned \fI\%mongoc_cursor_t\fP is never \fBNULL\fP, even on error. The user must call \fI\%mongoc_cursor_next()\fP on the returned \fI\%mongoc_cursor_t\fP to execute the initial command. .sp Cursor errors can be checked with \fI\%mongoc_cursor_error_document()\fP\&. It always fills out the \fI\%bson_error_t\fP if an error occurred, and optionally includes a server reply document if the error occurred server\-side. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Failure to handle the result of this function is a programming error. .UNINDENT .UNINDENT .SH EXAMPLE .INDENT 0.0 .INDENT 3.5 .sp .EX #include #include 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 (\(dqpipeline\(dq, \(dq[\(dq, \(dq{\(dq, \(dq$currentOp\(dq, \(dq{\(dq, \(dq}\(dq, \(dq}\(dq, \(dq]\(dq); /* $currentOp must be run on the admin database */ database = mongoc_client_get_database (client, \(dqadmin\(dq); cursor = mongoc_database_aggregate ( database, pipeline, NULL, NULL); bson_destroy (pipeline); mongoc_database_destroy (database); return cursor; } .EE .UNINDENT .UNINDENT .SH AUTHOR MongoDB, Inc .SH COPYRIGHT 2017-present, MongoDB, Inc .\" Generated by docutils manpage writer. .