MongoDB C++ Driver  mongocxx-3.3.1
Public Member Functions | List of all members
mongocxx::collection Class Reference

Class representing server side document groupings within a MongoDB database. More...

#include <collection.hpp>

Public Member Functions

 collection () noexcept
 Default constructs a collection object. More...
 
 collection (collection &&) noexcept
 Move constructs a collection.
 
collectionoperator= (collection &&) noexcept
 Move assigns a collection.
 
 collection (const collection &)
 Copy constructs a collection.
 
collectionoperator= (const collection &)
 Copy assigns a collection.
 
 ~collection ()
 Destroys a collection.
 
 operator bool () const noexcept
 Returns true if the collection is valid, meaning it was not default constructed or moved from.
 
MONGOCXX_DEPRECATED stdx::optional< result::bulk_writebulk_write (const class bulk_write &bulk_write)
 Sends a batch of writes represented by the bulk_write to the server. More...
 
stdx::string_view name () const
 Returns the name of this collection. More...
 
void rename (bsoncxx::string::view_or_value new_name, bool drop_target_before_rename=false, const bsoncxx::stdx::optional< write_concern > &write_concern={})
 Rename this collection. More...
 
void rename (const client_session &session, bsoncxx::string::view_or_value new_name, bool drop_target_before_rename=false, const bsoncxx::stdx::optional< write_concern > &write_concern={})
 Rename this collection. More...
 
void read_concern (class read_concern rc)
 Sets the read_concern for this collection. More...
 
class read_concern read_concern () const
 Gets the read_concern for the collection. More...
 
void read_preference (class read_preference rp)
 Sets the read_preference for this collection. More...
 
class read_preference read_preference () const
 Gets the read_preference for the collection. More...
 
void write_concern (class write_concern wc)
 Sets the write_concern for this collection. More...
 
class write_concern write_concern () const
 Gets the write_concern for the collection. More...
 
index_view indexes ()
 
Gets an index_view to the collection.
 
cursor aggregate (const pipeline &pipeline, const options::aggregate &options=options::aggregate())
 Runs an aggregation framework pipeline against this collection. More...
 
cursor aggregate (const client_session &session, const pipeline &pipeline, const options::aggregate &options=options::aggregate())
 Runs an aggregation framework pipeline against this collection. More...
 
class bulk_write create_bulk_write (const options::bulk_write &options={})
 Creates a new bulk operation to be executed against this collection. More...
 
class bulk_write create_bulk_write (const client_session &session, const options::bulk_write &options={})
 Creates a new bulk operation to be executed against this collection. More...
 
stdx::optional< result::bulk_writewrite (const model::write &write, const options::bulk_write &options=options::bulk_write())
 Sends a write to the server as a bulk write operation. More...
 
stdx::optional< result::bulk_writewrite (const client_session &session, const model::write &write, const options::bulk_write &options=options::bulk_write())
 Sends a write to the server as a bulk write operation. More...
 
template<typename container_type >
stdx::optional< result::bulk_writebulk_write (const container_type &writes, const options::bulk_write &options=options::bulk_write())
 Sends a container of writes to the server as a bulk write operation. More...
 
template<typename container_type >
stdx::optional< result::bulk_writebulk_write (const client_session &session, const container_type &writes, const options::bulk_write &options=options::bulk_write())
 Sends a container of writes to the server as a bulk write operation. More...
 
template<typename write_model_iterator_type >
stdx::optional< result::bulk_writebulk_write (write_model_iterator_type begin, write_model_iterator_type end, const options::bulk_write &options=options::bulk_write())
 Sends writes starting at begin and ending at end to the server as a bulk write operation. More...
 
template<typename write_model_iterator_type >
stdx::optional< result::bulk_writebulk_write (const client_session &session, write_model_iterator_type begin, write_model_iterator_type end, const options::bulk_write &options=options::bulk_write())
 Sends writes starting at begin and ending at end to the server as a bulk write operation. More...
 
std::int64_t count (bsoncxx::document::view_or_value filter, const options::count &options=options::count())
 Counts the number of documents matching the provided filter. More...
 
std::int64_t count (const client_session &session, bsoncxx::document::view_or_value filter, const options::count &options=options::count())
 Counts the number of documents matching the provided filter. More...
 
bsoncxx::document::value create_index (bsoncxx::document::view_or_value keys, bsoncxx::document::view_or_value index_options={}, options::index_view operation_options=options::index_view{})
 Creates an index over the collection for the provided keys with the provided options. More...
 
bsoncxx::document::value create_index (const client_session &session, bsoncxx::document::view_or_value keys, bsoncxx::document::view_or_value index_options={}, options::index_view operation_options=options::index_view{})
 Creates an index over the collection for the provided keys with the provided options. More...
 
stdx::optional< result::delete_resultdelete_many (bsoncxx::document::view_or_value filter, const options::delete_options &options=options::delete_options())
 Deletes all matching documents from the collection. More...
 
stdx::optional< result::delete_resultdelete_many (const client_session &session, bsoncxx::document::view_or_value filter, const options::delete_options &options=options::delete_options())
 Deletes all matching documents from the collection. More...
 
stdx::optional< result::delete_resultdelete_one (bsoncxx::document::view_or_value filter, const options::delete_options &options=options::delete_options())
 Deletes a single matching document from the collection. More...
 
stdx::optional< result::delete_resultdelete_one (const client_session &session, bsoncxx::document::view_or_value filter, const options::delete_options &options=options::delete_options())
 Deletes a single matching document from the collection. More...
 
cursor distinct (bsoncxx::string::view_or_value name, bsoncxx::document::view_or_value filter, const options::distinct &options=options::distinct())
 Finds the distinct values for a specified field across the collection. More...
 
cursor distinct (const client_session &session, bsoncxx::string::view_or_value name, bsoncxx::document::view_or_value filter, const options::distinct &options=options::distinct())
 Finds the distinct values for a specified field across the collection. More...
 
void drop (const bsoncxx::stdx::optional< mongocxx::write_concern > &write_concern={})
 Drops this collection and all its contained documents from the database. More...
 
void drop (const client_session &session, const bsoncxx::stdx::optional< mongocxx::write_concern > &write_concern={})
 Drops this collection and all its contained documents from the database. More...
 
cursor find (bsoncxx::document::view_or_value filter, const options::find &options=options::find())
 Finds the documents in this collection which match the provided filter. More...
 
cursor find (const client_session &session, bsoncxx::document::view_or_value filter, const options::find &options=options::find())
 Finds the documents in this collection which match the provided filter. More...
 
stdx::optional< bsoncxx::document::valuefind_one (bsoncxx::document::view_or_value filter, const options::find &options=options::find())
 Finds a single document in this collection that match the provided filter. More...
 
stdx::optional< bsoncxx::document::valuefind_one (const client_session &session, bsoncxx::document::view_or_value filter, const options::find &options=options::find())
 Finds a single document in this collection that match the provided filter. More...
 
stdx::optional< bsoncxx::document::valuefind_one_and_delete (bsoncxx::document::view_or_value filter, const options::find_one_and_delete &options=options::find_one_and_delete())
 Finds a single document matching the filter, deletes it, and returns the original. More...
 
stdx::optional< bsoncxx::document::valuefind_one_and_delete (const client_session &session, bsoncxx::document::view_or_value filter, const options::find_one_and_delete &options=options::find_one_and_delete())
 Finds a single document matching the filter, deletes it, and returns the original. More...
 
stdx::optional< bsoncxx::document::valuefind_one_and_replace (bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value replacement, const options::find_one_and_replace &options=options::find_one_and_replace())
 Finds a single document matching the filter, replaces it, and returns either the original or the replacement document. More...
 
stdx::optional< bsoncxx::document::valuefind_one_and_replace (const client_session &session, bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value replacement, const options::find_one_and_replace &options=options::find_one_and_replace())
 Finds a single document matching the filter, replaces it, and returns either the original or the replacement document. More...
 
stdx::optional< bsoncxx::document::valuefind_one_and_update (bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value update, const options::find_one_and_update &options=options::find_one_and_update())
 Finds a single document matching the filter, updates it, and returns either the original or the newly-updated document. More...
 
stdx::optional< bsoncxx::document::valuefind_one_and_update (const client_session &session, bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value update, const options::find_one_and_update &options=options::find_one_and_update())
 Finds a single document matching the filter, updates it, and returns either the original or the newly-updated document. More...
 
stdx::optional< result::insert_oneinsert_one (bsoncxx::document::view_or_value document, const options::insert &options={})
 Inserts a single document into the collection. More...
 
stdx::optional< result::insert_oneinsert_one (const client_session &session, bsoncxx::document::view_or_value document, const options::insert &options={})
 Inserts a single document into the collection. More...
 
template<typename container_type >
stdx::optional< result::insert_manyinsert_many (const container_type &container, const options::insert &options=options::insert())
 Inserts multiple documents into the collection. More...
 
template<typename container_type >
stdx::optional< result::insert_manyinsert_many (const client_session &session, const container_type &container, const options::insert &options=options::insert())
 Inserts multiple documents into the collection. More...
 
template<typename document_view_iterator_type >
stdx::optional< result::insert_manyinsert_many (document_view_iterator_type begin, document_view_iterator_type end, const options::insert &options=options::insert())
 Inserts multiple documents into the collection. More...
 
template<typename document_view_iterator_type >
stdx::optional< result::insert_manyinsert_many (const client_session &session, document_view_iterator_type begin, document_view_iterator_type end, const options::insert &options=options::insert())
 Inserts multiple documents into the collection. More...
 
cursor list_indexes () const
 Returns a list of the indexes currently on this collection. More...
 
cursor list_indexes (const client_session &session) const
 Returns a list of the indexes currently on this collection. More...
 
stdx::optional< result::replace_onereplace_one (bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value replacement, const options::update &options=options::update())
 Replaces a single document matching the provided filter in this collection. More...
 
stdx::optional< result::replace_onereplace_one (const client_session &session, bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value replacement, const options::update &options=options::update())
 Replaces a single document matching the provided filter in this collection. More...
 
stdx::optional< result::updateupdate_many (bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value update, const options::update &options=options::update())
 Updates multiple documents matching the provided filter in this collection. More...
 
stdx::optional< result::updateupdate_many (const client_session &session, bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value update, const options::update &options=options::update())
 Updates multiple documents matching the provided filter in this collection. More...
 
stdx::optional< result::updateupdate_one (bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value update, const options::update &options=options::update())
 Updates a single document matching the provided filter in this collection. More...
 
stdx::optional< result::updateupdate_one (const client_session &session, bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value update, const options::update &options=options::update())
 Updates a single document matching the provided filter in this collection. More...
 
change_stream watch (const options::change_stream &options={})
 Gets a change stream on this collection with an empty pipeline. More...
 
change_stream watch (const client_session &session, const options::change_stream &options={})
 
change_stream watch (const pipeline &pipe, const options::change_stream &options={})
 Gets a change stream on this collection. More...
 
change_stream watch (const client_session &session, const pipeline &pipe, const options::change_stream &options={})
 Gets a change stream on this collection. More...
 

Detailed Description

Class representing server side document groupings within a MongoDB database.

Collections do not require or enforce a schema and documents inside of a collection can have different fields. While not a requirement, typically documents in a collection have a similar shape or related purpose.

Example:

// Connect and get a collection.
auto coll = mongo_client["database"]["collection"];

Constructor & Destructor Documentation

◆ collection()

mongocxx::collection::collection ( )
noexcept

Default constructs a collection object.

The collection is equivalent to the state of a moved from collection. The only valid actions to take with a default constructed collection are to assign to it, or destroy it.

Member Function Documentation

◆ aggregate() [1/2]

cursor mongocxx::collection::aggregate ( const pipeline pipeline,
const options::aggregate options = options::aggregate() 
)

Runs an aggregation framework pipeline against this collection.

Parameters
pipelineThe pipeline of aggregation operations to perform.
optionsOptional arguments, see mongocxx::options::aggregate.
Returns
A mongocxx::cursor with the results. If the query fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
See also
https://docs.mongodb.com/master/reference/command/aggregate/
Note
In order to pass a read concern to this, you must use the collection level set read concern - collection::read_concern(rc). (Write concern supported only for MongoDB 3.4+).

◆ aggregate() [2/2]

cursor mongocxx::collection::aggregate ( const client_session session,
const pipeline pipeline,
const options::aggregate options = options::aggregate() 
)

Runs an aggregation framework pipeline against this collection.

Parameters
sessionThe mongocxx::client_session with which to perform the aggregation.
pipelineThe pipeline of aggregation operations to perform.
optionsOptional arguments, see mongocxx::options::aggregate.
Returns
A mongocxx::cursor with the results. If the query fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
See also
https://docs.mongodb.com/master/reference/command/aggregate/
Note
In order to pass a read concern to this, you must use the collection level set read concern - collection::read_concern(rc). (Write concern supported only for MongoDB 3.4+).

◆ bulk_write() [1/5]

template<typename container_type >
stdx::optional< result::bulk_write > mongocxx::collection::bulk_write ( const container_type &  writes,
const options::bulk_write options = options::bulk_write() 
)

Sends a container of writes to the server as a bulk write operation.

Template Parameters
container_typeThe container type. Must meet the requirements for the container concept with a value type of model::write.
Parameters
writesA container of model::write.
optionsOptional arguments, see options::bulk_write.
Returns
The optional result of the bulk operation execution. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionwhen there are errors processing the writes.
See also
mongocxx::bulk_write
https://docs.mongodb.com/master/core/bulk-write-operations/

◆ bulk_write() [2/5]

template<typename container_type >
stdx::optional< result::bulk_write > mongocxx::collection::bulk_write ( const client_session session,
const container_type &  writes,
const options::bulk_write options = options::bulk_write() 
)

Sends a container of writes to the server as a bulk write operation.

Template Parameters
container_typeThe container type. Must meet the requirements for the container concept with a value type of model::write.
Parameters
sessionThe mongocxx::client_session with which to perform the bulk operation.
writesA container of model::write.
optionsOptional arguments, see options::bulk_write.
Returns
The optional result of the bulk operation execution. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionwhen there are errors processing the writes.
See also
mongocxx::bulk_write
https://docs.mongodb.com/master/core/bulk-write-operations/

◆ bulk_write() [3/5]

template<typename write_model_iterator_type >
stdx::optional< result::bulk_write > mongocxx::collection::bulk_write ( write_model_iterator_type  begin,
write_model_iterator_type  end,
const options::bulk_write options = options::bulk_write() 
)

Sends writes starting at begin and ending at end to the server as a bulk write operation.

Template Parameters
write_model_iterator_typeThe container type. Must meet the requirements for the input iterator concept with a value type of model::write.
Parameters
beginIterator pointing to the first model::write to send.
endIterator pointing to the end of the writes to send.
optionsOptional arguments, see options::bulk_write.
Returns
The optional result of the bulk operation execution, a result::bulk_write.
Exceptions
mongocxx::bulk_write_exceptionwhen there are errors processing the writes.
See also
mongocxx::bulk_write
https://docs.mongodb.com/master/core/bulk-write-operations/

◆ bulk_write() [4/5]

template<typename write_model_iterator_type >
stdx::optional< result::bulk_write > mongocxx::collection::bulk_write ( const client_session session,
write_model_iterator_type  begin,
write_model_iterator_type  end,
const options::bulk_write options = options::bulk_write() 
)

Sends writes starting at begin and ending at end to the server as a bulk write operation.

Template Parameters
write_model_iterator_typeThe container type. Must meet the requirements for the input iterator concept with a value type of model::write.
Parameters
sessionThe mongocxx::client_session with which to perform the bulk operation.
beginIterator pointing to the first model::write to send.
endIterator pointing to the end of the writes to send.
optionsOptional arguments, see options::bulk_write.
Returns
The optional result of the bulk operation execution, a result::bulk_write.
Exceptions
mongocxx::bulk_write_exceptionwhen there are errors processing the writes.
See also
mongocxx::bulk_write
https://docs.mongodb.com/master/core/bulk-write-operations/

◆ bulk_write() [5/5]

MONGOCXX_DEPRECATED stdx::optional<result::bulk_write> mongocxx::collection::bulk_write ( const class bulk_write bulk_write)

Sends a batch of writes represented by the bulk_write to the server.

Deprecated:
Use mongocxx::bulk_write::execute instead.
Parameters
bulk_writeA bulk write which contains multiple write operations.
Returns
The optional result of the bulk operation execution, a result::bulk_write.
Exceptions
mongocxx::bulk_write_exceptionwhen there are errors processing the writes.
See also
https://docs.mongodb.com/master/core/bulk-write-operations/

◆ count() [1/2]

std::int64_t mongocxx::collection::count ( bsoncxx::document::view_or_value  filter,
const options::count options = options::count() 
)

Counts the number of documents matching the provided filter.

Parameters
filterThe filter that documents must match in order to be counted.
optionsOptional arguments, see mongocxx::options::count.
Returns
The count of the documents that matched the filter.
Exceptions
mongocxx::query_exceptionif the count operation fails.
See also
https://docs.mongodb.com/master/reference/command/count/

◆ count() [2/2]

std::int64_t mongocxx::collection::count ( const client_session session,
bsoncxx::document::view_or_value  filter,
const options::count options = options::count() 
)

Counts the number of documents matching the provided filter.

Parameters
sessionThe mongocxx::client_session with which to perform the count.
filterThe filter that documents must match in order to be counted.
optionsOptional arguments, see mongocxx::options::count.
Returns
The count of the documents that matched the filter.
Exceptions
mongocxx::query_exceptionif the count operation fails.
See also
https://docs.mongodb.com/master/reference/command/count/

◆ create_bulk_write() [1/2]

class bulk_write mongocxx::collection::create_bulk_write ( const options::bulk_write options = {})

Creates a new bulk operation to be executed against this collection.

The lifetime of the bulk_write is independent of the collection.

Parameters
optionsOptional arguments; see mongocxx::options::bulk_write.
Returns
The newly-created bulk write.

◆ create_bulk_write() [2/2]

class bulk_write mongocxx::collection::create_bulk_write ( const client_session session,
const options::bulk_write options = {} 
)

Creates a new bulk operation to be executed against this collection.

The lifetime of the bulk_write is independent of the collection.

Parameters
sessionThe mongocxx::client_session with which to perform the bulk operation.
optionsOptional arguments; see mongocxx::options::bulk_write.
Returns
The newly-created bulk write.

◆ create_index() [1/2]

bsoncxx::document::value mongocxx::collection::create_index ( bsoncxx::document::view_or_value  keys,
bsoncxx::document::view_or_value  index_options = {},
options::index_view  operation_options = options::index_view{} 
)

Creates an index over the collection for the provided keys with the provided options.

Parameters
keysThe keys for the index: {a: 1, b: -1}
index_optionsA document containing optional arguments for creating the index.
operation_optionsOptional arguments for the overall operation, see mongocxx::options::index_view.
Exceptions
mongocxx::operation_exceptionif index creation fails.
See also
https://docs.mongodb.com/master/reference/command/createIndexes/
Note
Write concern supported only for MongoDB 3.4+.

◆ create_index() [2/2]

bsoncxx::document::value mongocxx::collection::create_index ( const client_session session,
bsoncxx::document::view_or_value  keys,
bsoncxx::document::view_or_value  index_options = {},
options::index_view  operation_options = options::index_view{} 
)

Creates an index over the collection for the provided keys with the provided options.

Parameters
sessionThe mongocxx::client_session with which to perform the index creation.
keysThe keys for the index: {a: 1, b: -1}
index_optionsA document containing optional arguments for creating the index.
operation_optionsOptional arguments for the overall operation, see mongocxx::options::index_view.
Exceptions
mongocxx::operation_exceptionif index creation fails.
See also
https://docs.mongodb.com/master/reference/command/createIndexes/
Note
Write concern supported only for MongoDB 3.4+.

◆ delete_many() [1/2]

stdx::optional<result::delete_result> mongocxx::collection::delete_many ( bsoncxx::document::view_or_value  filter,
const options::delete_options options = options::delete_options() 
)

Deletes all matching documents from the collection.

Parameters
filterDocument view representing the data to be deleted.
optionsOptional arguments, see mongocxx::options::delete_options.
Returns
The optional result of performing the deletion. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionif the delete fails.
See also
https://docs.mongodb.com/master/reference/command/delete/

◆ delete_many() [2/2]

stdx::optional<result::delete_result> mongocxx::collection::delete_many ( const client_session session,
bsoncxx::document::view_or_value  filter,
const options::delete_options options = options::delete_options() 
)

Deletes all matching documents from the collection.

Parameters
sessionThe mongocxx::client_session with which to perform the deletion.
filterDocument view representing the data to be deleted.
optionsOptional arguments, see mongocxx::options::delete_options.
Returns
The optional result of performing the deletion. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionif the delete fails.
See also
https://docs.mongodb.com/master/reference/command/delete/

◆ delete_one() [1/2]

stdx::optional<result::delete_result> mongocxx::collection::delete_one ( bsoncxx::document::view_or_value  filter,
const options::delete_options options = options::delete_options() 
)

Deletes a single matching document from the collection.

Parameters
filterDocument view representing the data to be deleted.
optionsOptional arguments, see mongocxx::options::delete_options.
Returns
The optional result of performing the deletion. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionif the delete fails.
See also
https://docs.mongodb.com/master/reference/command/delete/

◆ delete_one() [2/2]

stdx::optional<result::delete_result> mongocxx::collection::delete_one ( const client_session session,
bsoncxx::document::view_or_value  filter,
const options::delete_options options = options::delete_options() 
)

Deletes a single matching document from the collection.

Parameters
sessionThe mongocxx::client_session with which to perform the deletion.
filterDocument view representing the data to be deleted.
optionsOptional arguments, see mongocxx::options::delete_options.
Returns
The optional result of performing the deletion. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionif the delete fails.
See also
https://docs.mongodb.com/master/reference/command/delete/

◆ distinct() [1/2]

cursor mongocxx::collection::distinct ( bsoncxx::string::view_or_value  name,
bsoncxx::document::view_or_value  filter,
const options::distinct options = options::distinct() 
)

Finds the distinct values for a specified field across the collection.

Parameters
nameThe field for which the distinct values will be found.
filterDocument view representing the documents for which the distinct operation will apply.
optionsOptional arguments, see options::distinct.
Returns
mongocxx::cursor having the distinct values for the specified field. If the operation fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
See also
https://docs.mongodb.com/master/reference/command/distinct/

◆ distinct() [2/2]

cursor mongocxx::collection::distinct ( const client_session session,
bsoncxx::string::view_or_value  name,
bsoncxx::document::view_or_value  filter,
const options::distinct options = options::distinct() 
)

Finds the distinct values for a specified field across the collection.

Parameters
sessionThe mongocxx::client_session with which to perform the operation.
nameThe field for which the distinct values will be found.
filterDocument view representing the documents for which the distinct operation will apply.
optionsOptional arguments, see options::distinct.
Returns
mongocxx::cursor having the distinct values for the specified field. If the operation fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
See also
https://docs.mongodb.com/master/reference/command/distinct/

◆ drop() [1/2]

void mongocxx::collection::drop ( const bsoncxx::stdx::optional< mongocxx::write_concern > &  write_concern = {})

Drops this collection and all its contained documents from the database.

Parameters
write_concern(optional) The write concern to use for this operation. Defaults to the collection wide write concern if none is provided.
Exceptions
mongocxx::operation_exceptionif the operation fails.
See also
https://docs.mongodb.com/master/reference/command/drop/
Note
Write concern supported only for MongoDB 3.4+.

◆ drop() [2/2]

void mongocxx::collection::drop ( const client_session session,
const bsoncxx::stdx::optional< mongocxx::write_concern > &  write_concern = {} 
)

Drops this collection and all its contained documents from the database.

Parameters
sessionThe mongocxx::client_session with which to perform the drop.
write_concern(optional) The write concern to use for this operation. Defaults to the collection wide write concern if none is provided.
Exceptions
mongocxx::operation_exceptionif the operation fails.
See also
https://docs.mongodb.com/master/reference/command/drop/
Note
Write concern supported only for MongoDB 3.4+.

◆ find() [1/2]

cursor mongocxx::collection::find ( bsoncxx::document::view_or_value  filter,
const options::find options = options::find() 
)

Finds the documents in this collection which match the provided filter.

Parameters
filterDocument view representing a document that should match the query.
optionsOptional arguments, see options::find
Returns
A mongocxx::cursor with the results. If the query fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
Exceptions
mongocxx::logic_errorif the options are invalid, or if the unsupported option modifiers "$query" or "$explain" are used.
See also
https://docs.mongodb.com/master/core/read-operations-introduction/

◆ find() [2/2]

cursor mongocxx::collection::find ( const client_session session,
bsoncxx::document::view_or_value  filter,
const options::find options = options::find() 
)

Finds the documents in this collection which match the provided filter.

Parameters
sessionThe mongocxx::client_session with which to perform the query.
filterDocument view representing a document that should match the query.
optionsOptional arguments, see options::find
Returns
A mongocxx::cursor with the results. If the query fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
Exceptions
mongocxx::logic_errorif the options are invalid, or if the unsupported option modifiers "$query" or "$explain" are used.
See also
https://docs.mongodb.com/master/core/read-operations-introduction/

◆ find_one() [1/2]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one ( bsoncxx::document::view_or_value  filter,
const options::find options = options::find() 
)

Finds a single document in this collection that match the provided filter.

Parameters
filterDocument view representing a document that should match the query.
optionsOptional arguments, see options::find
Returns
An optional document that matched the filter.
Exceptions
mongocxx::query_exceptionif the operation fails.
See also
https://docs.mongodb.com/master/core/read-operations-introduction/

◆ find_one() [2/2]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one ( const client_session session,
bsoncxx::document::view_or_value  filter,
const options::find options = options::find() 
)

Finds a single document in this collection that match the provided filter.

Parameters
sessionThe mongocxx::client_session with which to perform the query.
filterDocument view representing a document that should match the query.
optionsOptional arguments, see options::find
Returns
An optional document that matched the filter.
Exceptions
mongocxx::query_exceptionif the operation fails.
See also
https://docs.mongodb.com/master/core/read-operations-introduction/

◆ find_one_and_delete() [1/2]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_delete ( bsoncxx::document::view_or_value  filter,
const options::find_one_and_delete options = options::find_one_and_delete() 
)

Finds a single document matching the filter, deletes it, and returns the original.

Parameters
filterDocument view representing a document that should be deleted.
optionsOptional arguments, see options::find_one_and_delete
Returns
The document that was deleted.
Exceptions
Throwsmongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throwsmongocxx::write_exception if the operation fails.

◆ find_one_and_delete() [2/2]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_delete ( const client_session session,
bsoncxx::document::view_or_value  filter,
const options::find_one_and_delete options = options::find_one_and_delete() 
)

Finds a single document matching the filter, deletes it, and returns the original.

Parameters
sessionThe mongocxx::client_session with which to perform the operation.
filterDocument view representing a document that should be deleted.
optionsOptional arguments, see options::find_one_and_delete
Returns
The document that was deleted.
Exceptions
Throwsmongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throwsmongocxx::write_exception if the operation fails.

◆ find_one_and_replace() [1/2]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_replace ( bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  replacement,
const options::find_one_and_replace options = options::find_one_and_replace() 
)

Finds a single document matching the filter, replaces it, and returns either the original or the replacement document.

Parameters
filterDocument view representing a document that should be replaced.
replacementDocument view representing the replacement for a matching document.
optionsOptional arguments, see options::find_one_and_replace.
Returns
The original or replaced document.
Exceptions
Throwsmongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throwsmongocxx::write_exception if the operation fails.

◆ find_one_and_replace() [2/2]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_replace ( const client_session session,
bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  replacement,
const options::find_one_and_replace options = options::find_one_and_replace() 
)

Finds a single document matching the filter, replaces it, and returns either the original or the replacement document.

Parameters
sessionThe mongocxx::client_session with which to perform the operation.
filterDocument view representing a document that should be replaced.
replacementDocument view representing the replacement for a matching document.
optionsOptional arguments, see options::find_one_and_replace.
Returns
The original or replaced document.
Exceptions
Throwsmongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throwsmongocxx::write_exception if the operation fails.

◆ find_one_and_update() [1/2]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_update ( bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  update,
const options::find_one_and_update options = options::find_one_and_update() 
)

Finds a single document matching the filter, updates it, and returns either the original or the newly-updated document.

Parameters
filterDocument view representing a document that should be updated.
updateDocument view representing the update to apply to a matching document.
optionsOptional arguments, see options::find_one_and_update.
Returns
The original or updated document.
Exceptions
Throwsmongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throwsmongocxx::write_exception if the operation fails.

◆ find_one_and_update() [2/2]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_update ( const client_session session,
bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  update,
const options::find_one_and_update options = options::find_one_and_update() 
)

Finds a single document matching the filter, updates it, and returns either the original or the newly-updated document.

Parameters
sessionThe mongocxx::client_session with which to perform the operation.
filterDocument view representing a document that should be updated.
updateDocument view representing the update to apply to a matching document.
optionsOptional arguments, see options::find_one_and_update.
Returns
The original or updated document.
Exceptions
Throwsmongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throwsmongocxx::write_exception if the operation fails.

◆ insert_many() [1/4]

template<typename container_type >
stdx::optional< result::insert_many > mongocxx::collection::insert_many ( const container_type &  container,
const options::insert options = options::insert() 
)

Inserts multiple documents into the collection.

If any of the documents are missing identifiers the driver will generate them.

Warning
This method uses the bulk insert command to execute the insertion as opposed to the legacy OP_INSERT wire protocol message. As a result, using this method to insert many documents on MongoDB < 2.6 will be slow.
Template Parameters
container_typeThe container type. Must meet the requirements for the container concept with a value type of model::write.
Parameters
containerContainer of a documents to insert.
optionsOptional arguments, see options::insert.
Returns
The optional result of attempting to performing the insert. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionwhen the operation fails.

◆ insert_many() [2/4]

template<typename container_type >
stdx::optional< result::insert_many > mongocxx::collection::insert_many ( const client_session session,
const container_type &  container,
const options::insert options = options::insert() 
)

Inserts multiple documents into the collection.

If any of the documents are missing identifiers the driver will generate them.

Template Parameters
container_typeThe container type. Must meet the requirements for the container concept with a value type of model::write.
Parameters
sessionThe mongocxx::client_session with which to perform the inserts.
containerContainer of a documents to insert.
optionsOptional arguments, see options::insert.
Returns
The optional result of attempting to performing the insert. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionwhen the operation fails.

◆ insert_many() [3/4]

template<typename document_view_iterator_type >
stdx::optional< result::insert_many > mongocxx::collection::insert_many ( document_view_iterator_type  begin,
document_view_iterator_type  end,
const options::insert options = options::insert() 
)

Inserts multiple documents into the collection.

If any of the documents are missing identifiers the driver will generate them.

Warning
This method uses the bulk insert command to execute the insertion as opposed to the legacy OP_INSERT wire protocol message. As a result, using this method to insert many documents on MongoDB < 2.6 will be slow.
Template Parameters
document_view_iterator_typeThe iterator type. Must meet the requirements for the input iterator concept with a value type of bsoncxx::document::view.
Parameters
beginIterator pointing to the first document to be inserted.
endIterator pointing to the end of the documents to be inserted.
optionsOptional arguments, see options::insert.
Returns
The result of attempting to performing the insert.
Exceptions
mongocxx::bulk_write_exceptionif the operation fails.

◆ insert_many() [4/4]

template<typename document_view_iterator_type >
stdx::optional< result::insert_many > mongocxx::collection::insert_many ( const client_session session,
document_view_iterator_type  begin,
document_view_iterator_type  end,
const options::insert options = options::insert() 
)

Inserts multiple documents into the collection.

If any of the documents are missing identifiers the driver will generate them.

Template Parameters
document_view_iterator_typeThe iterator type. Must meet the requirements for the input iterator concept with a value type of bsoncxx::document::view.
Parameters
sessionThe mongocxx::client_session with which to perform the inserts.
beginIterator pointing to the first document to be inserted.
endIterator pointing to the end of the documents to be inserted.
optionsOptional arguments, see options::insert.
Returns
The result of attempting to performing the insert.
Exceptions
mongocxx::bulk_write_exceptionif the operation fails.

◆ insert_one() [1/2]

stdx::optional<result::insert_one> mongocxx::collection::insert_one ( bsoncxx::document::view_or_value  document,
const options::insert options = {} 
)

Inserts a single document into the collection.

If the document is missing an identifier (_id field) one will be generated for it.

Parameters
documentThe document to insert.
optionsOptional arguments, see options::insert.
Returns
The optional result of attempting to perform the insert. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionif the operation fails.

◆ insert_one() [2/2]

stdx::optional<result::insert_one> mongocxx::collection::insert_one ( const client_session session,
bsoncxx::document::view_or_value  document,
const options::insert options = {} 
)

Inserts a single document into the collection.

If the document is missing an identifier (_id field) one will be generated for it.

Parameters
sessionThe mongocxx::client_session with which to perform the insert.
documentThe document to insert.
optionsOptional arguments, see options::insert.
Returns
The optional result of attempting to perform the insert. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionif the operation fails.

◆ list_indexes() [1/2]

cursor mongocxx::collection::list_indexes ( ) const

Returns a list of the indexes currently on this collection.

Returns
Cursor yielding the index specifications.
Exceptions
mongocxx::operation_exceptionif the operation fails.
See also
https://docs.mongodb.com/master/reference/command/listIndexes/

◆ list_indexes() [2/2]

cursor mongocxx::collection::list_indexes ( const client_session session) const

Returns a list of the indexes currently on this collection.

Parameters
sessionThe mongocxx::client_session with which to perform the operation.
Returns
Cursor yielding the index specifications.
Exceptions
mongocxx::operation_exceptionif the operation fails.
See also
https://docs.mongodb.com/master/reference/command/listIndexes/

◆ name()

stdx::string_view mongocxx::collection::name ( ) const

Returns the name of this collection.

Returns
The name of the collection. The return value of this method is invalidated by any subsequent call to collection::rename() on this collection object.

◆ read_concern() [1/2]

void mongocxx::collection::read_concern ( class read_concern  rc)

Sets the read_concern for this collection.

Changes will not have any effect on existing cursors or other read operations which use the previously-set read concern.

Parameters
rcThe new read_concern
See also
https://docs.mongodb.com/master/reference/read-concern/

◆ read_concern() [2/2]

class read_concern mongocxx::collection::read_concern ( ) const

Gets the read_concern for the collection.

If a read_concern has not been explicitly set for this collection object, it inherits the read_concern from its parent database or client object.

Returns
The current read_concern.

◆ read_preference() [1/2]

class read_preference mongocxx::collection::read_preference ( ) const

Gets the read_preference for the collection.

Returns
The current read_preference.
See also
https://docs.mongodb.com/master/core/read-preference/

◆ read_preference() [2/2]

void mongocxx::collection::read_preference ( class read_preference  rp)

Sets the read_preference for this collection.

Changes will not have any effect on existing cursors or other read operations which use the read preference.

Parameters
rpThe read_preference to set.
See also
https://docs.mongodb.com/master/core/read-preference/

◆ rename() [1/2]

void mongocxx::collection::rename ( bsoncxx::string::view_or_value  new_name,
bool  drop_target_before_rename = false,
const bsoncxx::stdx::optional< write_concern > &  write_concern = {} 
)

Rename this collection.

Parameters
new_nameThe new name to assign to the collection.
drop_target_before_renameWhether to overwrite any existing collections called new_name. The default is false.
write_concern(optional) The write concern to use for this operation. Defaults to the collection wide write concern if none is provided.
Exceptions
mongocxx::operation_exceptionif the operation fails.
See also
https://docs.mongodb.com/master/reference/command/renameCollection/
Note
Write concern supported only for MongoDB 3.4+.

◆ rename() [2/2]

void mongocxx::collection::rename ( const client_session session,
bsoncxx::string::view_or_value  new_name,
bool  drop_target_before_rename = false,
const bsoncxx::stdx::optional< write_concern > &  write_concern = {} 
)

Rename this collection.

Parameters
sessionThe mongocxx::client_session with which to perform the rename.
new_nameThe new name to assign to the collection.
drop_target_before_renameWhether to overwrite any existing collections called new_name. The default is false.
write_concern(optional) The write concern to use for this operation. Defaults to the collection wide write concern if none is provided.
Exceptions
mongocxx::operation_exceptionif the operation fails.
See also
https://docs.mongodb.com/master/reference/command/renameCollection/
Note
Write concern supported only for MongoDB 3.4+.

◆ replace_one() [1/2]

stdx::optional<result::replace_one> mongocxx::collection::replace_one ( bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  replacement,
const options::update options = options::update() 
)

Replaces a single document matching the provided filter in this collection.

Parameters
filterDocument representing the match criteria.
replacementThe replacement document.
optionsOptional arguments, see options::update.
Returns
The optional result of attempting to replace a document. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::logic_errorif the replacement is invalid, or mongocxx::bulk_write_exception if the operation fails.
See also
https://docs.mongodb.com/master/reference/command/update/

◆ replace_one() [2/2]

stdx::optional<result::replace_one> mongocxx::collection::replace_one ( const client_session session,
bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  replacement,
const options::update options = options::update() 
)

Replaces a single document matching the provided filter in this collection.

Parameters
sessionThe mongocxx::client_session with which to perform the replace.
filterDocument representing the match criteria.
replacementThe replacement document.
optionsOptional arguments, see options::update.
Returns
The optional result of attempting to replace a document. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::logic_errorif the replacement is invalid, or mongocxx::bulk_write_exception if the operation fails.
See also
https://docs.mongodb.com/master/reference/command/update/

◆ update_many() [1/2]

stdx::optional<result::update> mongocxx::collection::update_many ( bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  update,
const options::update options = options::update() 
)

Updates multiple documents matching the provided filter in this collection.

Parameters
filterDocument representing the match criteria.
updateDocument representing the update to be applied to matching documents.
optionsOptional arguments, see options::update.
Returns
The optional result of attempting to update multiple documents. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::logic_errorif the update is invalid, or mongocxx::bulk_write_exception if the operation fails.
See also
https://docs.mongodb.com/master/reference/command/update/

◆ update_many() [2/2]

stdx::optional<result::update> mongocxx::collection::update_many ( const client_session session,
bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  update,
const options::update options = options::update() 
)

Updates multiple documents matching the provided filter in this collection.

Parameters
sessionThe mongocxx::client_session with which to perform the update.
filterDocument representing the match criteria.
updateDocument representing the update to be applied to matching documents.
optionsOptional arguments, see options::update.
Returns
The optional result of attempting to update multiple documents. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::logic_errorif the update is invalid, or mongocxx::bulk_write_exception if the operation fails.
See also
https://docs.mongodb.com/master/reference/command/update/

◆ update_one() [1/2]

stdx::optional<result::update> mongocxx::collection::update_one ( bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  update,
const options::update options = options::update() 
)

Updates a single document matching the provided filter in this collection.

Parameters
filterDocument representing the match criteria.
updateDocument representing the update to be applied to a matching document.
optionsOptional arguments, see options::update.
Returns
The optional result of attempting to update a document. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::logic_errorif the update is invalid, or mongocxx::bulk_write_exception if the operation fails.
See also
https://docs.mongodb.com/master/reference/command/update/

◆ update_one() [2/2]

stdx::optional<result::update> mongocxx::collection::update_one ( const client_session session,
bsoncxx::document::view_or_value  filter,
bsoncxx::document::view_or_value  update,
const options::update options = options::update() 
)

Updates a single document matching the provided filter in this collection.

Parameters
sessionThe mongocxx::client_session with which to perform the update.
filterDocument representing the match criteria.
updateDocument representing the update to be applied to a matching document.
optionsOptional arguments, see options::update.
Returns
The optional result of attempting to update a document. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::logic_errorif the update is invalid, or mongocxx::bulk_write_exception if the operation fails.
See also
https://docs.mongodb.com/master/reference/command/update/

◆ watch() [1/4]

change_stream mongocxx::collection::watch ( const options::change_stream options = {})

Gets a change stream on this collection with an empty pipeline.

Change streams are only supported with a "majority" read concern or no read concern.

Parameters
optionsThe options to use when creating the change stream.
Returns
A change stream on this collection.
See also
https://docs.mongodb.com/manual/changeStreams/

◆ watch() [2/4]

change_stream mongocxx::collection::watch ( const client_session session,
const options::change_stream options = {} 
)
Parameters
sessionThe mongocxx::client_session with which to perform the watch operation.
optionsThe options to use when creating the change stream.
Returns
A change stream on this collection.
See also
https://docs.mongodb.com/manual/changeStreams/

◆ watch() [3/4]

change_stream mongocxx::collection::watch ( const pipeline pipe,
const options::change_stream options = {} 
)

Gets a change stream on this collection.

Change streams are only supported with a "majority" read concern or no read concern.

Parameters
pipeThe aggregation pipeline to be used on the change notifications. Only a subset of pipeline operations are supported for change streams. For more information see the change streams documentation.
optionsThe options to use when creating the change stream.
Returns
A change stream on this collection.
See also
https://docs.mongodb.com/manual/changeStreams/

◆ watch() [4/4]

change_stream mongocxx::collection::watch ( const client_session session,
const pipeline pipe,
const options::change_stream options = {} 
)

Gets a change stream on this collection.

Parameters
sessionThe mongocxx::client_session with which to perform the watch operation.
pipeThe aggregation pipeline to be used on the change notifications.
optionsThe options to use when creating the change stream.
Returns
A change stream on this collection.
See also
https://docs.mongodb.com/manual/changeStreams/

◆ write() [1/2]

stdx::optional< result::bulk_write > mongocxx::collection::write ( const model::write write,
const options::bulk_write options = options::bulk_write() 
)

Sends a write to the server as a bulk write operation.

Parameters
writeA model::write.
optionsOptional arguments, see options::bulk_write.
Returns
The optional result of the bulk operation execution. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionwhen there are errors processing the writes.
See also
mongocxx::bulk_write
https://docs.mongodb.com/master/core/bulk-write-operations/

◆ write() [2/2]

stdx::optional< result::bulk_write > mongocxx::collection::write ( const client_session session,
const model::write write,
const options::bulk_write options = options::bulk_write() 
)

Sends a write to the server as a bulk write operation.

Parameters
sessionThe mongocxx::client_session with which to perform the bulk operation.
writeA model::write.
optionsOptional arguments, see options::bulk_write.
Returns
The optional result of the bulk operation execution. If the write concern is unacknowledged, the optional will be disengaged.
Exceptions
mongocxx::bulk_write_exceptionwhen there are errors processing the writes.
See also
mongocxx::bulk_write
https://docs.mongodb.com/master/core/bulk-write-operations/

◆ write_concern() [1/2]

void mongocxx::collection::write_concern ( class write_concern  wc)

Sets the write_concern for this collection.

Changes will not have any effect on existing write operations.

Parameters
wcThe new write_concern to use.

◆ write_concern() [2/2]

class write_concern mongocxx::collection::write_concern ( ) const

Gets the write_concern for the collection.

Returns
The current write_concern.

The documentation for this class was generated from the following file: