NAME

       mongoc_collection_aggregate - mongoc_collection_aggregate()

SYNOPSIS

          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;

PARAMETERS

       • collection: A mongoc_collection_t.

       • flags: A mongoc_query_flags_t.

       • pipeline: A bson_t containing the pipeline array.

       • opts: A bson_t containing options for the command, or NULL.

       • read_prefs: A mongoc_read_prefs_t or NULL.

       opts may be NULL or a BSON document with additional command options:

       • readConcern: Construct a mongoc_read_concern_t and use mongoc_read_concern_append to add
         the read concern to opts. See the example code for mongoc_client_read_command_with_opts.
         Read concern requires MongoDB 3.2 or later, otherwise an error is returned.

       • writeConcern:   For   aggregations   that   include   "$out",   you   can   construct  a
         mongoc_write_concern_t and use mongoc_write_concern_append to add the write  concern  to
         opts. See the example code for mongoc_client_write_command_with_opts.

       • sessionId:  Construct a mongoc_client_session_t with mongoc_client_start_session and use
         mongoc_client_session_append to add the session  to  opts.  See  the  example  code  for
         mongoc_client_session_t.

       • bypassDocumentValidation:  Set  to  true  to  skip  server-side schema validation of the
         provided BSON documents.

       • collation: Configure textual comparisons. See Setting Collation Order, and  the  MongoDB
         Manual  entry  on Collation. Collation requires MongoDB 3.2 or later, otherwise an error
         is returned.

       • serverId: To target a specific server, include an int32 "serverId" field. Obtain the  id
         by  calling mongoc_client_select_server, then mongoc_server_description_id on its return
         value.

       For a list of all options, see the MongoDB Manual entry on the aggregate command.

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.

       For more information on building MongoDB pipelines, see the MongoDB Manual  entry  on  the
       aggregate command.

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

       Read concern is applied from opts or else from collection. Collation is applied from  opts
       (see  example  for  the  "distinct"  command with opts). Read preferences are applied from
       read_prefs or else from collection. Write concern is applied from opts, or if opts has  no
       write  concern  and the aggregation pipeline includes "$out", the write concern is applied
       from collection. The write concern is omitted for MongoDB before 3.4.

RETURNS

       This function returns  a  newly  allocated  mongoc_cursor_t  that  should  be  freed  with
       mongoc_cursor_destroy() when no longer in use. The returned mongoc_cursor_t is never NULL;
       if the parameters are invalid, the bson_error_t in the mongoc_cursor_t is filled out,  and
       the mongoc_cursor_t is returned before the server is selected.

       WARNING:
          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

       When  using  $out,  the  pipeline  stage  that  writes,  the  write_concern  field  of the
       mongoc_cursor_t will be set to the mongoc_write_concern_t parameter, if it is  valid,  and
       applied  to  the  write  command  when  mongoc_cursor_next()  is  called.  Pass  any other
       parameters to the aggregate command, besides pipeline, as fields in opts:

          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);

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2018, MongoDB, Inc