.\" Man page generated from reStructuredText.
.
.TH "MONGOC_COLLECTION_AGGREGATE" "3" "Feb 23, 2019" "1.14.0" "MongoDB C Driver"
.SH NAME
mongoc_collection_aggregate \- mongoc_collection_aggregate()
.
.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
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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;
.ft P
.fi
.UNINDENT
.UNINDENT
.SH PARAMETERS
.INDENT 0.0
.IP \(bu 2
\fBcollection\fP: A \fBmongoc_collection_t\fP\&.
.IP \(bu 2
\fBflags\fP: A \fBmongoc_query_flags_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 "pipeline".
.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 \fBmongoc_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 \fBmongoc_read_concern_t\fP and use \fBmongoc_read_concern_append\fP to add the read concern to \fBopts\fP\&. See the example code for \fBmongoc_client_read_command_with_opts\fP\&. Read concern requires MongoDB 3.2 or later, otherwise an error is returned.
.IP \(bu 2
\fBwriteConcern\fP: For aggregations that include "$out", you can construct a \fBmongoc_write_concern_t\fP and use \fBmongoc_write_concern_append\fP to add the write concern to \fBopts\fP\&. See the example code for \fBmongoc_client_write_command_with_opts\fP\&.
.IP \(bu 2
\fBsessionId\fP: Construct a \fBmongoc_client_session_t\fP with \fBmongoc_client_start_session\fP and use \fBmongoc_client_session_append\fP to add the session to \fBopts\fP\&. See the example code for \fBmongoc_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 Setting Collation Order, 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 "serverId" field. Obtain the id by calling \fBmongoc_client_select_server\fP, then \fBmongoc_server_description_id\fP on its return value.
.IP \(bu 2
\fBbatchSize\fP: To specify the number of documents to return in each batch of a response from the server, include an int "batchSize" field.
.UNINDENT
.sp
For a list of all options, see \fI\%the MongoDB Manual entry on the aggregate command\fP\&.
.SH DESCRIPTION
.sp
This function shall execute an aggregation query on the underlying collection. 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 "$out", 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
See the example for transactions and for the "distinct" command with opts\&.
.SH RETURNS
.sp
This function returns a newly allocated \fBmongoc_cursor_t\fP that should be freed with \fBmongoc_cursor_destroy()\fP when no longer in use. The returned \fBmongoc_cursor_t\fP is never \fBNULL\fP; if the parameters are invalid, the \fI\%bson_error_t\fP in the \fBmongoc_cursor_t\fP is filled out, and the \fBmongoc_cursor_t\fP is returned before the server is selected.
.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
.nf
.ft C
#include <bson/bson.h>
#include <mongoc/mongoc.h>

static mongoc_cursor_t *
pipeline_query (mongoc_collection_t *collection)
{
   mongoc_cursor_t *cursor;
   bson_t *pipeline;

   pipeline = BCON_NEW ("pipeline",
                        "[",
                        "{",
                        "$match",
                        "{",
                        "foo",
                        BCON_UTF8 ("A"),
                        "}",
                        "}",
                        "{",
                        "$match",
                        "{",
                        "bar",
                        BCON_BOOL (false),
                        "}",
                        "}",
                        "]");

   cursor = mongoc_collection_aggregate (
      collection, MONGOC_QUERY_NONE, pipeline, NULL, NULL);

   bson_destroy (pipeline);

   return cursor;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH OTHER PARAMETERS
.sp
When using \fB$out\fP, the pipeline stage that writes, the write_concern field of the \fBmongoc_cursor_t\fP will be set to the \fBmongoc_write_concern_t\fP parameter, if it is valid, and applied to the write command when \fBmongoc_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
.nf
.ft C
mongoc_write_concern_t *write_concern = mongoc_write_concern_new ();
mongoc_write_concern_set_w (write_concern, 3);

pipeline =
   BCON_NEW ("pipeline", "[", "{", "$out", BCON_UTF8 ("collection2"), "}", "]");

opts = BCON_NEW ("bypassDocumentValidation", BCON_BOOL (true));
mongoc_write_concern_append (write_concern, opts);

cursor = mongoc_collection_aggregate (
   collection1, MONGOC_QUERY_NONE, pipeline, opts, NULL);
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.