[CXX-763] Overload methods that take options classes to take bson documents instead Created: 04/Dec/15  Updated: 08/Feb/23

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

Type: New Feature Priority: Major - P3
Reporter: Samantha Ritter (Inactive) Assignee: Unassigned
Resolution: Unresolved Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Epic Link: CXX ABI
Quarter: FY24Q1

 Description   

For some users and use cases, it is tedious/impractical to create options objects when calling driver methods that take them. We should provide overloads taking bsoncxx::document::view_or_value objects to make the driver more versatile and usable.

Consider a case where the user has a bson document that they have stored options in, either generated from some config file or read out of the database:

// aggregate options
{ "maxTimeMS" : 100, "explain" : true, "allowDiskUse" : false }

In order to run an aggregation query, these options must first be converted to an options::aggregate object:

bsoncxx::document::value agg_options_bson{some existing bson};
 
options::aggregate opts{};
opts.max_time_ms(agg_options_bson["maxTimeMS"].get_int64());
opts.explain(agg_options_bson["explain"].get_bool());
opts.allow_disk_use(agg_options_bson["allowDiskUse"].get_bool());
 
collection.aggregate(pipeline, opts);

If we provided an overload we could skip the options-building steps here and just pass in the original document:

bsoncxx::document::value agg_options_bson{some existing bson};
collection.aggregate(pipeline, agg_options_bson);

Edit:

Other methods that we should consider changing, in addition to collection::aggregate():

  • collection::create_index()


 Comments   
Comment by Andrew Morrow (Inactive) [ 06/Jan/16 ]

Kicking this out to 3.1.0. Since we aren't planning to set an ABI until then anyway, I'm more comfortable deferring this work, and I don't want it to hold up rc0 or the GA.

Comment by Andrew Morrow (Inactive) [ 17/Dec/15 ]

I've thought about this and decided that we should do something here. I'm leaning towards providing a basic framework for objects to describe their serialization into a builder, and their deserialization from an object.

I'd prefer this to overloading.

Comment by Andrew Morrow (Inactive) [ 04/Dec/15 ]

Another way to approach this would be to have options classes be able to serialize to and de-serialize from BSON, rather than having the methods taking options be overloaded to als take BSON. There are some trade-offs, so we should consider this carefully, and probably check in with other drivers to see what they are doing.

Taking the BSON has the advantage that if there is an option that emerges in the server that is not yet reflected in the driver you can use it by bypassing the option class. Making the options serializable to/from BSON avoids the need to overload every single method that takes an option class.

I'm going to put this in 3.0.0/features-we-aren't-sure-of to indicate that we need to make a decision about it before we ship.

Comment by Andrew Morrow (Inactive) [ 04/Dec/15 ]

And I guess the proposed solution as well?

Comment by Andrew Morrow (Inactive) [ 04/Dec/15 ]

Can you update the description with an example showing the problem?

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