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.