CXX-3235 add mongocxx::v1 forward headers and component files #1462
Conversation
| /// | ||
| /// @attention This feature is experimental! It is not ready for use! | ||
| /// | ||
| class options {}; |
There was a problem hiding this comment.
v_noabi::options::index seems to be nearly-completely obsoleted by v_noabi::options::index_view. It's only current usage is in:
- Isolated test and example code: easily replaceable.
v_noabi::gridfs::bucket::create_indexes_if_nonexistent: private API, easily replaceable.v_noabi::options::index::operator bsoncxx::v_noabi::document::view_or_value: to support the deprecated*_storage_optionsAPI (not included inv1).
Therefore, v1::indexes::options will merge and fulfill the role of both the old index and index_view options classes.
| /// | ||
| /// Support for MongoDB indexes. | ||
| /// | ||
| /// @note Not to be confused with Atlas Search indexes or Atlas Vector Search indexes. |
There was a problem hiding this comment.
The distinction between index and index_view does not seem valuable (perhaps it might have been when CXX-1360 was resolved in Jun 2017...?). Besides the unnecessary "view" vs. "value" terminology (a la bsoncxx API), it may also be confused with MongoDB standard or on-demand materialized views as pertains to aggregation pipelines, which this class is not directly related to:
Standard views use the indexes of the underlying collection. As a result, you cannot create, drop or re-build indexes on a standard view directly, nor get a list of indexes on the view. You can create indexes directly on on-demand materialized views because they are stored on disk.
There was a problem hiding this comment.
The Index Management spec defines two APIs:
All drivers MUST offer at least one of the sections of operations, the Standard API or the Index View API. The driver MAY elect to have both.
The v_noabi API appears to only partially implement the Standard API (e.g. no collection::drop_index). I expect v1::indexes will serve as the Index View API.
I would also like to avoid the overloaded "view". The spec says this about naming:
When deviating from a defined name, an author should consider if the altered name is recognizable and discoverable to the user of another driver.
However, surveying other drivers found C#, Go, and Ruby implement the Index View API. C# uses a similarly named Indexes method to get the Index View. I expect "Indexes" is a discoverable API name for wanting to manage indexes, and I expect the distinction between the two APIs would not matter to most users.
There was a problem hiding this comment.
Do we want to leave a note/ticket to split v1::indexes::options (IndexOptions) into command-specific options classes for better accuracy with the Index View API specification (v1::indexes::create_one_options, v1::indexes::create_many_options, etc.) as done for the regular database command option classes (insert_one_options, insert_many_options, etc.)?
There was a problem hiding this comment.
No strong opinion. I am slightly in favor to split the options for spec and CRUD API consistency. But arguably, there is not much need since the options do not-yet differ from the combined options:
interface CreateOneIndexOptions {
// same as CreateIndexOptions in the Standard API
}
interface CreateManyIndexesOptions {
// same as CreateIndexesOptions in the Standard API
}| /// | ||
| /// `returnDocument` from the CRUD API specification. | ||
| /// | ||
| /// @see | ||
| /// - [CRUD API (MongoDB Specifications)](https://www.mongodb.com/docs/manual/reference/command/return_document/) | ||
| /// | ||
| enum class return_document {}; |
There was a problem hiding this comment.
This replaces v_noabi::options::find_one_common_options as a more specific and direct component+class name describing its actual purpose (representing the returnDocument field option).
| /// | ||
| /// A connection to a MongoDB deployment. | ||
| /// | ||
| /// @important This interface does NOT fully conform to the CMAP specification! | ||
| /// | ||
| /// @see | ||
| /// - [Connection Monitoring and Pooling (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/connection-monitoring-and-pooling/connection-monitoring-and-pooling/) | ||
| /// - [Connection Strings (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/connection-string/) |
There was a problem hiding this comment.
This PR proposes deferring as much documentation as possible into "See Also" links to MongoDB Manual or MongoDB Specification pages (+ occasionally mongoc API docs). C++ Driver API documentation is and should be specific to behaviors specific to the C++ Driver, not the MongoDB server behavior or other libraries.
Also added the "Important" note to several API docs clarifying that these are not CMAP-compliant, which can be relevant for certain APM event-handling, (unstructured) logging, and error handling behavior.
| /// | ||
| /// Options related to field encryption for CSFLE and Queryable Encryption. | ||
| /// | ||
| /// @see | ||
| /// - [Fields and Encryption Types (MongoDB Manual)](https://www.mongodb.com/docs/manual/core/csfle/fundamentals/encryption-algorithms/) | ||
| /// - [Encrypted Fields and Enabled Queries (MongoDB Manual)](https://mongodb.com/docs/manual/core/queryable-encryption/fundamentals/encrypt-and-query/) | ||
| /// - [Encryption Schemas](https://www.mongodb.com/docs/manual/core/csfle/fundamentals/create-schema/) | ||
| /// | ||
| /// @attention This feature is experimental! It is not ready for use! | ||
| /// | ||
| class encrypt {}; |
There was a problem hiding this comment.
The "encrypt" options class is overloaded in usage with both the .encrypt() database command as well as options pertaining to encrypted field configuration for CSFLE and Queryable Encryption. Unlike the <command>_one vs. <command>_many splits, this one was too complicated to attempt to split up by refined purpose as part of the v_noabi -> v1 migration effort. Perhaps it may be revisited in the future.
There was a problem hiding this comment.
I expect v_noabi::options::encrypt model EncryptOpts from the spec. I expect these are only used for explicit encryption (client_encryption.encrypt()).
| /// | ||
| /// Support for MongoDB indexes. | ||
| /// | ||
| /// @note Not to be confused with Atlas Search indexes or Atlas Vector Search indexes. |
There was a problem hiding this comment.
The Index Management spec defines two APIs:
All drivers MUST offer at least one of the sections of operations, the Standard API or the Index View API. The driver MAY elect to have both.
The v_noabi API appears to only partially implement the Standard API (e.g. no collection::drop_index). I expect v1::indexes will serve as the Index View API.
I would also like to avoid the overloaded "view". The spec says this about naming:
When deviating from a defined name, an author should consider if the altered name is recognizable and discoverable to the user of another driver.
However, surveying other drivers found C#, Go, and Ruby implement the Index View API. C# uses a similarly named Indexes method to get the Index View. I expect "Indexes" is a discoverable API name for wanting to manage indexes, and I expect the distinction between the two APIs would not matter to most users.
eramongodb
force-pushed
the
cxx-3235
branch
from
a14a3f6 to
38cb4e0
Compare
| /// | ||
| /// Support for MongoDB indexes. | ||
| /// | ||
| /// @note Not to be confused with Atlas Search indexes or Atlas Vector Search indexes. |
There was a problem hiding this comment.
Do we want to leave a note/ticket to split v1::indexes::options (IndexOptions) into command-specific options classes for better accuracy with the Index View API specification (v1::indexes::create_one_options, v1::indexes::create_many_options, etc.) as done for the regular database command option classes (insert_one_options, insert_many_options, etc.)?
Summary
Followup to #1447 and analogous to #1401 for bsoncxx.
As in #1401, this PR is a "lightweight" preview of the
mongocxx::v1interface, file structure, and class (+ some enumeration) API documentation. Unlike #1401, this PR includes declarations of some member classes and enumerations in advance to clarify relocated equivalents to v_noabi non-member classes and enumerations.Most of the proposed v_noabi -> v1 relative changes are due to relocations and renaming of types to address CXX-1826:
and CXX-1836
To address both of these issues, the
v_noabi::optionsandv_noabi::resultnamespaces+components are removed in favor of*_optionsand*_resultsuffixes instead. Options and result types specific to an existing class are made members of that class (e.g.v_noabi::options::*->v1::*::options). The only nested namespaces remaining arev1::gridfsandv1::events.Relative Changelog (v_noabi -> v1)
v1::source_errcandv1::type_errc(same pattern as forbsoncxx::v1).v_noabi::operation_exception->v1::server_error*_errorsuffix pattern.v1::source_errcandv1::type_errc. User's responsibility to compare theintagainst library-specific error codes.v_noabi::result::<command>->v1::<command>_resultdelete->delete_one+delete_manyinsert_oneinsert_manyreplace_onerewrap_many_datakeyupdate->update_one+update_many*_resultsuffix pattern.v_noabi::options::<command>->v1::<command>_optionsaggregatecountdelete->delete_one+delete_manydistinctencryptestimated_document_countfind+find_one_and_*find_one_common_options->return_documentoptions::gridfs::upload->gridfs::upload_optionsinsert->insert_one+insert_manyreplace->replace_oneupdate->update_one+update_many*_resultpattern:<command>():<command>_options+<command>_result..count()vs.count_options). The_optionssuffix is not used for options-only types for non-commands (e.g..apm_opts()vs.apm)."Options" classes which do not have the
*_optionssuffix and are not nested in another class:hintapmauto_encryptionrangeserver_apitlsread_concernread_preferencewrite_concernv_noabi::events::<name>_event->v_noabi::events::<name>heartbeat_*_event->server_heartbeat_*topology_changed_event->topology_description_changedserver_changed_event->server_description_changedevents::*_eventredundancy without possibility of conflation or confusion with overloaded terminology (unlikeview,<command>, etc.).v_noabi::index_view->v1::indexesv_noabi::index_model->v1::indexes::modelv_noabi::options::index_view->v1::indexes::optionsv_noabi::options::index->v1::indexes::options(merge index-related options into a single class; no clear reason to keep separate).v_noabi::search_index_view->v1::search_indexesv_noabi::search_index_model->v1::search_indexes::modelv1::indexes.v_noabi::model::<command>->v1::bulk_write::<command>(bulk write commands)v_noabi::model::write->v1::bulk_write::singlev_noabi::options::bulk_write->v1::bulk_write::optionsv_noabi::write_type->v1::bulk_write::typev1::bulk_writeas members.v_noabi::server_api->v1::stable_apiv1::exceptionorv1::server_error:authentication_exceptionbulk_write_exceptionv1::server_errorwithv1::bulk_write::errcerror codes.gridfs_exceptionv1::exceptionwithv1::gridfs::*::errc(bucket, downloader, uploader).logic_errorquery_exceptionv1::exceptionwith an unspecified error code that compares equal tov1::source_errc::mongocorv1::source_errc::crypt.v1::server_errorwith an unspecified error code that compares equal tov1::source_errc::server.write_exceptionv1::server_errorwith an unspecified error code that compares equal tov1::source_errc::server.v_noabi::events::topology_description::server_descriptionsstd::vector<server_description>instead. The intermediate owning array returned bymongoc_client_get_server_descriptions()does not need to be preserved.v_noabi::validation_criteriav_noabi::options::index::*_storage_options.storage_engine()in CDRIVER-5946 remove deprecated index management API #1360.v_noabi::options::ssltls.