This is something I realized while implementing the db-level aggregate helper in CDRIVER-2899. The current documentation leads users to believe that the pipeline is executed by the helper itself, which is not correct since the returned command cursor is lazy. This is especially pertinent for piplines using an $out stage, as there is typically no reason to advance the cursor (no results are ever returned).

I intend to update the doc blocks for both the db and collection helpers as part of CDRIVER-2899, but this issue can be used to revise mongoc_collection_aggregate.rst.