NAME

       mongoc_collection_aggregate()  -  This  function  shall  execute  an  aggregation query on the underlying
       'collection'. The bson 'pipeline' is not validated, simply passed along as appropriate to the server.  As
       such, compatibility and errors should be validated in the appropriate server documentation.

SYNOPSIS

       mongoc_cursor_t *
       mongoc_collection_aggregate (mongoc_collection_t       *collection,
                                    mongoc_query_flags_t       flags,
                                    const bson_t              *pipeline,
                                    const bson_t              *options,
                                    const mongoc_read_prefs_t *read_prefs)
          BSON_GNUC_WARN_UNUSED_RESULT;

PARAMETERS

       collection
              A mongoc_collection_t \&.

       flags  A mongoc_query_flags_t \&.

       pipeline
              A bson_t containing the pipeline array.

       options
              A bson_t containing options for the pipeline, or NULL \&.

       read_prefs
              A mongoc_read_prefs_t or NULL \&.

DESCRIPTION

       This function shall execute an aggregation query on the underlying 'collection'. The bson  'pipeline'  is
       not  validated,  simply  passed  along  as  appropriate to the server.  As such, compatibility and errors
       should be validated in the appropriate server documentation.

       In the case of older server versions, < v2.5, the returned cursor is a synthetic iterator over the result
       set. This provides a limitation insofar as returned documents can be no larger than 16MB. When connecting
       to newer servers this limitation doesn't exist. The specific test is for wire_version > 0.

       For more information on building MongoDB pipelines,  see  MongoDB  Aggregation  Command  on  the  MongoDB
       website.

       NOTE
              The  pipeline  parameter should contain a field named pipeline containing a BSON array of pipeline
              stages.

       NOTE
              The mongoc_read_concern_t specified on the mongoc_collection_t will be used, if any.

RETURNS

       This   function   returns   a   newly   allocated   mongoc_cursor_t   that   should   be    freed    with
       mongoc_cursor_destroy(3) when no longer in use.  NULL may be returned if parameters are invalid.

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

EXAMPLE

       #include <bcon.h>
       #include <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;
       }

OTHER PARAMETERS

       Pass any parameters to the aggregate command, besides pipeline , as fields in options :

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

       options = BCON_NEW ("bypassDocumentValidation", BCON_BOOL (true));
       cursor = mongoc_collection_aggregate (collection1,
                                             MONGOC_QUERY_NONE,
                                             pipeline,
                                             options,
                                             NULL);

COLOPHON

       This     page     is     part     of    MongoDB    C    Driver.     Please    report    any    bugs    at
       https://jira.mongodb.org/browse/CDRIVER.

MongoDB C Driver                                   2016‐01‐18                     MONGOC_COLLECTION_AGGREGATE(3)