'\" 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_COLLECTION_AGGREGATE" "3" "May 07, 2024" "1.27.1" "libmongoc" .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .EX mongoc_cursor_t * mongoc_collection_aggregate (mongoc_collection_t *collection, mongoc_query_flags_t flags, 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 \fBcollection\fP: A \fI\%mongoc_collection_t\fP\&. .IP \(bu 2 \fBflags\fP: A \fI\%mongoc_query_flags_t\fP\&. Not all flag values apply. In particular, setting \fBMONGOC_QUERY_EXHAUST\fP results in an error. .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 \fBcollection\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\&. .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 DESCRIPTION .sp This function creates a cursor which sends the aggregate command on the underlying collection 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\&. .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 \fBcollection\fP\&. The write concern is omitted for MongoDB before 3.4. .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{ \fBcollection\fP T} T{ \fBcollection\fP T} T{ \fBcollection\fP T} T{ T} _ .TE .sp \fI\%See the example for transactions\fP and for \fI\%the \(dqdistinct\(dq command with opts\fP\&. .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 * pipeline_query (mongoc_collection_t *collection) { mongoc_cursor_t *cursor; bson_t *pipeline; pipeline = BCON_NEW (\(dqpipeline\(dq, \(dq[\(dq, \(dq{\(dq, \(dq$match\(dq, \(dq{\(dq, \(dqfoo\(dq, BCON_UTF8 (\(dqA\(dq), \(dq}\(dq, \(dq}\(dq, \(dq{\(dq, \(dq$match\(dq, \(dq{\(dq, \(dqbar\(dq, BCON_BOOL (false), \(dq}\(dq, \(dq}\(dq, \(dq]\(dq); cursor = mongoc_collection_aggregate ( collection, MONGOC_QUERY_NONE, pipeline, NULL, NULL); bson_destroy (pipeline); return cursor; } .EE .UNINDENT .UNINDENT .SH OTHER PARAMETERS .sp When using \fB$out\fP, the pipeline stage that writes, the write_concern field of the \fI\%mongoc_cursor_t\fP will be set to the \fI\%mongoc_write_concern_t\fP parameter, if it is valid, and applied to the write command when \fI\%mongoc_cursor_next()\fP is called. Pass any other parameters to the \fBaggregate\fP command, besides \fBpipeline\fP, as fields in \fBopts\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX mongoc_write_concern_t *write_concern = mongoc_write_concern_new (); mongoc_write_concern_set_w (write_concern, 3); pipeline = BCON_NEW (\(dqpipeline\(dq, \(dq[\(dq, \(dq{\(dq, \(dq$out\(dq, BCON_UTF8 (\(dqcollection2\(dq), \(dq}\(dq, \(dq]\(dq); opts = BCON_NEW (\(dqbypassDocumentValidation\(dq, BCON_BOOL (true)); mongoc_write_concern_append (write_concern, opts); cursor = mongoc_collection_aggregate ( collection1, MONGOC_QUERY_NONE, pipeline, opts, NULL); .EE .UNINDENT .UNINDENT .SH AUTHOR MongoDB, Inc .SH COPYRIGHT 2017-present, MongoDB, Inc .\" Generated by docutils manpage writer. .