[CXX-1059] Add aggregation pipeline class builder methods for new MongoDB 3.4 stages and $geoNear / $indexStats stages Created: 01/Oct/16  Updated: 13/Dec/16  Resolved: 28/Nov/16

Status: Closed
Project: C++ Driver
Component/s: API
Affects Version/s: None
Fix Version/s: 3.1.0

Type: New Feature Priority: Major - P3
Reporter: J Rassi Assignee: J Rassi
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to CXX-1147 Update link to final aggregation page... Closed

 Description   

The pipeline class is currently missing methods associated with the new-in-MongoDB-3.4 pipeline stages:

  • $addFields
  • $bucket
  • $bucketAuto
  • $count
  • $collStats
  • $facet
  • $graphLookup
  • $replaceRoot
  • $sortByCount

It is also missing a method associated with the $indexStats stage (new in MongoDB 3.2), and the $geoNear stage.

In addition, pipeline::unwind() needs a new overload that allows users to specify values for the "includeArrayIndex" and "preserveNullAndEmptyArrays" options (new in MongoDB 3.2).

We should either add new builder methods to the pipeline class for all of these new stages, or we should deprecate the pipeline class entirely and instead have users pass array builders directly to collection::aggregate().



 Comments   
Comment by Githook User [ 29/Nov/16 ]

Author:

{u'username': u'jrassi', u'name': u'J. Rassi', u'email': u'rassi@10gen.com'}

Message: CXX-1059 Add new stage methods to pipeline class

As a result of this work, this pipeline class is now up-to-date with
new functionality available in the aggregation framework as of server
version 3.4.

Complete list of methods added:

pipeline& add_fields(bsoncxx::document::view_or_value fields_to_add);
pipeline& bucket(bsoncxx::document::view_or_value bucket_args);
pipeline& bucket_auto(bsoncxx::document::view_or_value bucket_auto_args);
pipeline& coll_stats(bsoncxx::document::view_or_value coll_stats_args);
pipeline& count(std::string field);
pipeline& facet(bsoncxx::document::view_or_value facet_args);
pipeline& geo_near(bsoncxx::document::view_or_value geo_near_args);
pipeline& graph_lookup(bsoncxx::document::view_or_value graph_lookup_args);
pipeline& index_stats();
pipeline& replace_root(bsoncxx::document::view_or_value replace_root_args);
pipeline& sort_by_count(bsoncxx::document::view_or_value field_expression);
pipeline& sort_by_count(std::string field_expression);
pipeline& unwind(bsoncxx::document::view_or_value unwind_args);
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/764886c4b262aa89f069ae29ed771bb86d542dbf

Comment by Githook User [ 29/Nov/16 ]

Author:

{u'username': u'jrassi', u'name': u'J. Rassi', u'email': u'rassi@10gen.com'}

Message: CXX-1059 Minor cleanup of pipeline.cpp/pipeline.hpp

Simplify implementation, clean up documentation, fix naming of a few
parameters.
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/220ecf828ec96c244e34dc75e20376985107f7b0

Comment by Githook User [ 28/Nov/16 ]

Author:

{u'username': u'jrassi', u'name': u'J. Rassi', u'email': u'rassi@10gen.com'}

Message: CXX-1059 Add new stage methods to pipeline class

As a result of this work, this pipeline class is now up-to-date with
new functionality available in the aggregation framework as of server
version 3.4.

Complete list of methods added:

pipeline& add_fields(bsoncxx::document::view_or_value fields_to_add);
pipeline& bucket(bsoncxx::document::view_or_value bucket_args);
pipeline& bucket_auto(bsoncxx::document::view_or_value bucket_auto_args);
pipeline& coll_stats(bsoncxx::document::view_or_value coll_stats_args);
pipeline& count(std::string field);
pipeline& facet(bsoncxx::document::view_or_value facet_args);
pipeline& geo_near(bsoncxx::document::view_or_value geo_near_args);
pipeline& graph_lookup(bsoncxx::document::view_or_value graph_lookup_args);
pipeline& index_stats();
pipeline& replace_root(bsoncxx::document::view_or_value replace_root_args);
pipeline& sort_by_count(bsoncxx::document::view_or_value field_expression);
pipeline& sort_by_count(std::string field_expression);
pipeline& unwind(bsoncxx::document::view_or_value unwind_args);
Branch: 3.1-dev
https://github.com/mongodb/mongo-cxx-driver/commit/764886c4b262aa89f069ae29ed771bb86d542dbf

Comment by Githook User [ 28/Nov/16 ]

Author:

{u'username': u'jrassi', u'name': u'J. Rassi', u'email': u'rassi@10gen.com'}

Message: CXX-1059 Minor cleanup of pipeline.cpp/pipeline.hpp

Simplify implementation, clean up documentation, fix naming of a few
parameters.
Branch: 3.1-dev
https://github.com/mongodb/mongo-cxx-driver/commit/220ecf828ec96c244e34dc75e20376985107f7b0

Comment by David Golden [ 03/Nov/16 ]

We also considered doing #1 to meet our 3.1 release goal and deferring options 2-4 for a post-3.1 release. (If we are considering dropping/deprecating pipeline builders or making other breaking API changes, we should queue that for 4.0 anyway.)

If we don't get insight into #2 or #3 in the next week or so, I think we should move forward with #1 to close this ticket and open a new ticket for the other options on the table.

Comment by J Rassi [ 03/Nov/16 ]

Me and David spoke in-person today about this. We discussed the following approaches:

  1. Add builder methods for the above stages. This has the advantage of following the existing convention, and deferring further design improvements. It has the disadvantage that 3.1.0 users will not be able to use MongoDB 3.6 with pipeline stages that are new in that release.
  2. Add builder methods for the above stages, and also add a new method that allows users to specify the name of the pipeline stage manually (perhaps with something like "pipeline::append_other(string, document)"). This has the advantage of being a relatively small change to the pipeline class, while providing forwards-compatibility. It has the disadvantage in that this new method is an awkward addition to the pipeline class (which we're not sure yet if we should be maintaining long-term).
  3. Add a collection::aggregate() overload that takes an array::view_or_value instead of a pipeline. This has the advantage of offering a forwards-compatible and familiar API to users, and allows us to consider deprecating the existing overload and the pipeline class. It has the disadvantage of requiring more verbose code to express a pipeline than the existing API. If we take this route, we could optionally add some infrastructure in bsoncxx or mongocxx to make it easier to make building pipelines less verbose, and we could optionally perform the deprecations now (if we decide not to do the deprecations, we should add builder methods for the above stages, too).
  4. Add the new collection::aggregate() method as in #3, and remove the existing method entirely. We could then add an implicit conversion from pipeline to array::view_or_value, to permit existing code to still work. (For academic purposes, note that this approach breaks ABI.)

Further research on what the approaches the other statically-typed languages take here would be useful.

Comment by David Golden [ 07/Oct/16 ]

Also, consider overloading the aggregate command to take an arbitrary user document as the pipeline.

Comment by David Golden [ 07/Oct/16 ]

Per discussions: another possibility is add ability to add arbitrary stage for forward compatibility.

Generated at Wed Feb 07 22:01:16 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.