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.

collection &	operator= (collection &&) noexcept
	Move assigns a collection.

	collection (const collection &)
	Copy constructs a collection.

collection &	operator= (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.

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_write >	write (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_write >	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. More...


template<typename container_type >
stdx::optional< result::bulk_write >	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. More...

template<typename container_type >
stdx::optional< result::bulk_write >	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. More...


template<typename write_model_iterator_type >
stdx::optional< result::bulk_write >	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. More...

template<typename write_model_iterator_type >
stdx::optional< result::bulk_write >	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. More...


std::int64_t	count_documents (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_documents (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...


std::int64_t	estimated_document_count (const options::estimated_document_count &options=options::estimated_document_count())
	Returns an estimate of the number of documents in the collection. 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_result >	delete_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_result >	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. More...


stdx::optional< result::delete_result >	delete_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_result >	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. 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::value >	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. More...

stdx::optional< bsoncxx::document::value >	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. More...


stdx::optional< bsoncxx::document::value >	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. More...

stdx::optional< bsoncxx::document::value >	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. More...


stdx::optional< bsoncxx::document::value >	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. More...

stdx::optional< bsoncxx::document::value >	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. More...


stdx::optional< bsoncxx::document::value >	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. More...

stdx::optional< bsoncxx::document::value >	find_one_and_update (bsoncxx::document::view_or_value filter, const pipeline &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::value >	find_one_and_update (bsoncxx::document::view_or_value filter, std::initializer_list< _empty_doc_tag > 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::value >	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. More...

stdx::optional< bsoncxx::document::value >	find_one_and_update (const client_session &session, bsoncxx::document::view_or_value filter, const pipeline &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::value >	find_one_and_update (const client_session &session, bsoncxx::document::view_or_value filter, std::initializer_list< _empty_doc_tag > 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_one >	insert_one (bsoncxx::document::view_or_value document, const options::insert &options={})
	Inserts a single document into the collection. More...

stdx::optional< result::insert_one >	insert_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_many >	insert_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_many >	insert_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_many >	insert_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_many >	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. 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_one >	replace_one (bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value replacement, const options::replace &options=options::replace{})
	Replaces a single document matching the provided filter in this collection. More...

stdx::optional< result::replace_one >	replace_one (const client_session &session, bsoncxx::document::view_or_value filter, bsoncxx::document::view_or_value replacement, const options::replace &options=options::replace{})
	Replaces a single document matching the provided filter in this collection. More...

stdx::optional< result::update >	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. More...

stdx::optional< result::update >	update_many (bsoncxx::document::view_or_value filter, const pipeline &update, const options::update &options=options::update())
	Updates multiple documents matching the provided filter in this collection. More...

stdx::optional< result::update >	update_many (bsoncxx::document::view_or_value filter, std::initializer_list< _empty_doc_tag > update, const options::update &options=options::update())
	Updates multiple documents matching the provided filter in this collection. More...

stdx::optional< result::update >	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. More...

stdx::optional< result::update >	update_many (const client_session &session, bsoncxx::document::view_or_value filter, const pipeline &update, const options::update &options=options::update())
	Updates multiple documents matching the provided filter in this collection. More...

stdx::optional< result::update >	update_many (const client_session &session, bsoncxx::document::view_or_value filter, std::initializer_list< _empty_doc_tag > update, const options::update &options=options::update())
	Updates multiple documents matching the provided filter in this collection. More...


stdx::optional< result::update >	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. More...

stdx::optional< result::update >	update_one (bsoncxx::document::view_or_value filter, const pipeline &update, const options::update &options=options::update())
	Updates a single document matching the provided filter in this collection. More...

stdx::optional< result::update >	update_one (bsoncxx::document::view_or_value filter, std::initializer_list< _empty_doc_tag > update, const options::update &options=options::update())
	Updates a single document matching the provided filter in this collection. More...

stdx::optional< result::update >	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. More...

stdx::optional< result::update >	update_one (const client_session &session, bsoncxx::document::view_or_value filter, const pipeline &update, const options::update &options=options::update())
	Updates a single document matching the provided filter in this collection. More...

stdx::optional< result::update >	update_one (const client_session &session, bsoncxx::document::view_or_value filter, std::initializer_list< _empty_doc_tag > 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.
mongocxx::client mongo_client{mongocxx::uri{}};
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 client_session &	session,
		const pipeline &	pipeline,
		const options::aggregate &	options = `options::aggregate()`
	)

Runs an aggregation framework pipeline against this collection.

Parameters

session	The mongocxx::client_session with which to perform the aggregation.
pipeline	The pipeline of aggregation operations to perform.
options	Optional 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/manual/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 pipeline &	pipeline,
		const options::aggregate &	options = `options::aggregate()`
	)

Runs an aggregation framework pipeline against this collection.

Parameters

pipeline	The pipeline of aggregation operations to perform.
options	Optional 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/manual/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/4]

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_type The container type. Must meet the requirements for the container concept with a value type of model::write.

Parameters

session	The mongocxx::client_session with which to perform the bulk operation.
writes	A container of model::write.
options	Optional 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_exception when there are errors processing the writes.

See also: mongocxx::bulk_write; https://docs.mongodb.com/manual/core/bulk-write-operations/

◆ bulk_write() [2/4]

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_type The container type. Must meet the requirements for the input iterator concept with a value type of model::write.

Parameters

session	The mongocxx::client_session with which to perform the bulk operation.
begin	Iterator pointing to the first model::write to send.
end	Iterator pointing to the end of the writes to send.
options	Optional arguments, see options::bulk_write.

Returns: The optional result of the bulk operation execution, a result::bulk_write.

Exceptions

mongocxx::bulk_write_exception when there are errors processing the writes.

See also: mongocxx::bulk_write; https://docs.mongodb.com/manual/core/bulk-write-operations/

◆ bulk_write() [3/4]

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_type The container type. Must meet the requirements for the container concept with a value type of model::write.

Parameters

writes	A container of model::write.
options	Optional 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_exception when there are errors processing the writes.

See also: mongocxx::bulk_write; https://docs.mongodb.com/manual/core/bulk-write-operations/

◆ bulk_write() [4/4]

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_type The container type. Must meet the requirements for the input iterator concept with a value type of model::write.

Parameters

begin	Iterator pointing to the first model::write to send.
end	Iterator pointing to the end of the writes to send.
options	Optional arguments, see options::bulk_write.

Returns: The optional result of the bulk operation execution, a result::bulk_write.

Exceptions

mongocxx::bulk_write_exception when there are errors processing the writes.

See also: mongocxx::bulk_write; https://docs.mongodb.com/manual/core/bulk-write-operations/

◆ count_documents() [1/2]

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

Counts the number of documents matching the provided filter.

Parameters

filter	The filter that documents must match in order to be counted.
options	Optional arguments, see mongocxx::options::count.

Returns: The count of the documents that matched the filter.

Exceptions

mongocxx::query_exception if the count operation fails.

Note: For a fast count of the total documents in a collection, see estimated_document_count().; Due to an oversight in MongoDB server versions 5.0.0 through 5.0.7, the count command was not included in Stable API v1. Users of the Stable API with estimatedDocumentCount are recommended to upgrade their server version to 5.0.8 or newer, or set apiStrict: false to avoid encountering errors.

See also: mongocxx::estimated_document_count

◆ count_documents() [2/2]

std::int64_t mongocxx::collection::count_documents	(	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

session	The mongocxx::client_session with which to perform the count.
filter	The filter that documents must match in order to be counted.
options	Optional arguments, see mongocxx::options::count.

Returns: The count of the documents that matched the filter.

Exceptions

mongocxx::query_exception if the count operation fails.

Note: Due to an oversight in MongoDB server versions 5.0.0 through 5.0.7, the count command was not included in Stable API v1. Users of the Stable API with estimatedDocumentCount are recommended to upgrade their server version to 5.0.8 or newer, or set apiStrict: false to avoid encountering errors.

See also: mongocxx::estimated_document_count

◆ create_bulk_write() [1/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

session	The mongocxx::client_session with which to perform the bulk operation.
options	Optional 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 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

options Optional 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

keys	The keys for the index: `{a:` 1, b: -1}
index_options	A document containing optional arguments for creating the index.
operation_options	Optional arguments for the overall operation, see mongocxx::options::index_view.

Exceptions

mongocxx::operation_exception if index creation fails.

See also: https://docs.mongodb.com/manual/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

session	The mongocxx::client_session with which to perform the index creation.
keys	The keys for the index: `{a:` 1, b: -1}
index_options	A document containing optional arguments for creating the index.
operation_options	Optional arguments for the overall operation, see mongocxx::options::index_view.

Exceptions

mongocxx::operation_exception if index creation fails.

See also: https://docs.mongodb.com/manual/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

filter	Document view representing the data to be deleted.
options	Optional 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_exception if the delete fails.

See also: https://docs.mongodb.com/manual/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

session	The mongocxx::client_session with which to perform the deletion.
filter	Document view representing the data to be deleted.
options	Optional 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_exception if the delete fails.

See also: https://docs.mongodb.com/manual/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

filter	Document view representing the data to be deleted.
options	Optional 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_exception if the delete fails.

See also: https://docs.mongodb.com/manual/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

session	The mongocxx::client_session with which to perform the deletion.
filter	Document view representing the data to be deleted.
options	Optional 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_exception if the delete fails.

See also: https://docs.mongodb.com/manual/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

name	The field for which the distinct values will be found.
filter	Document view representing the documents for which the distinct operation will apply.
options	Optional 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/manual/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

session	The mongocxx::client_session with which to perform the operation.
name	The field for which the distinct values will be found.
filter	Document view representing the documents for which the distinct operation will apply.
options	Optional 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/manual/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_exception if the operation fails.

See also: https://docs.mongodb.com/manual/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

session	The 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_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/drop/

Note: Write concern supported only for MongoDB 3.4+.

◆ estimated_document_count()

std::int64_t mongocxx::collection::estimated_document_count ( const options::estimated_document_count & options = options::estimated_document_count() )

Returns an estimate of the number of documents in the collection.

Parameters

options Optional arguments, see mongocxx::options::count.

Returns: The count of the documents that matched the filter.

Exceptions

mongocxx::query_exception if the count operation fails.

Note: This function is implemented in terms of the count server command. See: https://www.mongodb.com/docs/manual/reference/command/count/#behavior for more information.

See also: mongocxx::count_documents

◆ 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

filter	Document view representing a document that should match the query.
options	Optional 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_error if the options are invalid, or if the unsupported option modifiers "$query" or "$explain" are used.

See also: https://docs.mongodb.com/manual/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

session	The mongocxx::client_session with which to perform the query.
filter	Document view representing a document that should match the query.
options	Optional 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_error if the options are invalid, or if the unsupported option modifiers "$query" or "$explain" are used.

See also: https://docs.mongodb.com/manual/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

filter	Document view representing a document that should match the query.
options	Optional arguments, see options::find

Returns: An optional document that matched the filter.

Exceptions

mongocxx::query_exception if the operation fails.

See also: https://docs.mongodb.com/manual/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

session	The mongocxx::client_session with which to perform the query.
filter	Document view representing a document that should match the query.
options	Optional arguments, see options::find

Returns: An optional document that matched the filter.

Exceptions

mongocxx::query_exception if the operation fails.

See also: https://docs.mongodb.com/manual/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

filter	Document view representing a document that should be deleted.
options	Optional arguments, see options::find_one_and_delete

Returns: The document that was deleted.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::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

session	The mongocxx::client_session with which to perform the operation.
filter	Document view representing a document that should be deleted.
options	Optional arguments, see options::find_one_and_delete

Returns: The document that was deleted.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::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

filter	Document view representing a document that should be replaced.
replacement	Document view representing the replacement for a matching document.
options	Optional arguments, see options::find_one_and_replace.

Returns: The original or replaced document.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::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

session	The mongocxx::client_session with which to perform the operation.
filter	Document view representing a document that should be replaced.
replacement	Document view representing the replacement for a matching document.
options	Optional arguments, see options::find_one_and_replace.

Returns: The original or replaced document.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::write_exception if the operation fails.

◆ find_one_and_update() [1/6]

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

filter	Document view representing a document that should be updated.
update	Document view representing the update to apply to a matching document.
options	Optional arguments, see options::find_one_and_update.

Returns: The original or updated document.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::write_exception if the operation fails.

◆ find_one_and_update() [2/6]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_update	(	bsoncxx::document::view_or_value	filter,
		const pipeline &	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

filter	Document view representing a document that should be updated.
update	Pipeline representing the update to apply to a matching document.
options	Optional arguments, see options::find_one_and_update.

Returns: The original or updated document.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::write_exception if the operation fails.

◆ find_one_and_update() [3/6]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_update	(	bsoncxx::document::view_or_value	filter,
		std::initializer_list< _empty_doc_tag >	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

filter	Document view representing a document that should be updated.
update	Supports the empty update {}.
options	Optional arguments, see options::find_one_and_update.

Returns: The original or updated document.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::write_exception if the operation fails.

◆ find_one_and_update() [4/6]

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

session	The mongocxx::client_session with which to perform the operation.
filter	Document view representing a document that should be updated.
update	Document view representing the update to apply to a matching document.
options	Optional arguments, see options::find_one_and_update.

Returns: The original or updated document.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::write_exception if the operation fails.

◆ find_one_and_update() [5/6]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_update	(	const client_session &	session,
		bsoncxx::document::view_or_value	filter,
		const pipeline &	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

session	The mongocxx::client_session with which to perform the operation.
filter	Document view representing a document that should be updated.
update	Pipeline representing the update to apply to a matching document.
options	Optional arguments, see options::find_one_and_update.

Returns: The original or updated document.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::write_exception if the operation fails.

◆ find_one_and_update() [6/6]

stdx::optional<bsoncxx::document::value> mongocxx::collection::find_one_and_update	(	const client_session &	session,
		bsoncxx::document::view_or_value	filter,
		std::initializer_list< _empty_doc_tag >	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

session	The mongocxx::client_session with which to perform the operation.
filter	Document view representing a document that should be updated.
update	Supports the empty update {}.
options	Optional arguments, see options::find_one_and_update.

Returns: The original or updated document.

Exceptions

Throws	mongocxx::logic_error if the collation option is specified and an unacknowledged write concern is used.
Throws	mongocxx::write_exception if the operation fails.

◆ insert_many() [1/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_type The container type. Must meet the requirements for the container concept with a value type of model::write.

Parameters

session	The mongocxx::client_session with which to perform the inserts.
container	Container of a documents to insert.
options	Optional 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_exception when the operation fails.

◆ insert_many() [2/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_type The iterator type. Must meet the requirements for the input iterator concept with a value type of bsoncxx::document::view.

Parameters

session	The mongocxx::client_session with which to perform the inserts.
begin	Iterator pointing to the first document to be inserted.
end	Iterator pointing to the end of the documents to be inserted.
options	Optional arguments, see options::insert.

Returns: The result of attempting to performing the insert.

Exceptions

mongocxx::bulk_write_exception if the operation fails.

◆ insert_many() [3/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_type The container type. Must meet the requirements for the container concept with a value type of model::write.

Parameters

container	Container of a documents to insert.
options	Optional 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_exception when the operation fails.

◆ insert_many() [4/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_type The iterator type. Must meet the requirements for the input iterator concept with a value type of bsoncxx::document::view.

Parameters

begin	Iterator pointing to the first document to be inserted.
end	Iterator pointing to the end of the documents to be inserted.
options	Optional arguments, see options::insert.

Returns: The result of attempting to performing the insert.

Exceptions

mongocxx::bulk_write_exception if 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

document	The document to insert.
options	Optional 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_exception if 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

session	The mongocxx::client_session with which to perform the insert.
document	The document to insert.
options	Optional 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_exception if 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_exception if the operation fails.

See also: https://docs.mongodb.com/manual/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

session The mongocxx::client_session with which to perform the operation.

Returns: Cursor yielding the index specifications.

Exceptions

mongocxx::operation_exception if the operation fails.

See also: https://docs.mongodb.com/manual/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]

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_concern() [2/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

rc	The new `read_concern`

See also: https://docs.mongodb.com/manual/reference/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/manual/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

rp	The read_preference to set.

See also: https://docs.mongodb.com/manual/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_name	The new name to assign to the collection.
drop_target_before_rename	Whether 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_exception if the operation fails.

See also: https://docs.mongodb.com/manual/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

session	The mongocxx::client_session with which to perform the rename.
new_name	The new name to assign to the collection.
drop_target_before_rename	Whether 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_exception if the operation fails.

See also: https://docs.mongodb.com/manual/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::replace &	options = `options::replace{}`
	)

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

Parameters

filter	Document representing the match criteria.
replacement	The replacement document.
options	Optional arguments, see options::replace.

Returns: The optional result of attempting to replace a document. If the write concern is unacknowledged, the optional will be disengaged.

Exceptions

mongocxx::logic_error if the replacement is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/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::replace &	options = `options::replace{}`
	)

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

Parameters

session	The mongocxx::client_session with which to perform the replace.
filter	Document representing the match criteria.
replacement	The replacement document.
options	Optional arguments, see options::replace.

Returns: The optional result of attempting to replace a document. If the write concern is unacknowledged, the optional will be disengaged.

Exceptions

mongocxx::logic_error if the replacement is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_many() [1/6]

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

filter	Document representing the match criteria.
update	Document representing the update to be applied to matching documents.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_many() [2/6]

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

Updates multiple documents matching the provided filter in this collection.

Parameters

filter	Document representing the match criteria.
update	Pipeline representing the update to be applied to matching documents.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_many() [3/6]

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

Updates multiple documents matching the provided filter in this collection.

Parameters

filter	Document representing the match criteria.
update	Supports the empty update {}.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_many() [4/6]

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

session	The mongocxx::client_session with which to perform the update.
filter	Document representing the match criteria.
update	Document representing the update to be applied to matching documents.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_many() [5/6]

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

Updates multiple documents matching the provided filter in this collection.

Parameters

session	The mongocxx::client_session with which to perform the update.
filter	Document representing the match criteria.
update	Pipeline representing the update to be applied to matching documents.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_many() [6/6]

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

Updates multiple documents matching the provided filter in this collection.

Parameters

session	The mongocxx::client_session with which to perform the update.
filter	Document representing the match criteria.
update	Supports the empty update {}.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_one() [1/6]

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

filter	Document representing the match criteria.
update	Document representing the update to be applied to a matching document.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_one() [2/6]

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

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

Parameters

filter	Document representing the match criteria.
update	Pipeline representing the update to be applied to a matching document.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_one() [3/6]

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

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

Parameters

filter	Document representing the match criteria.
update	Supports the empty update {}.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_one() [4/6]

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

session	The mongocxx::client_session with which to perform the update.
filter	Document representing the match criteria.
update	Document representing the update to be applied to a matching document.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_one() [5/6]

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

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

Parameters

session	The mongocxx::client_session with which to perform the update.
filter	Document representing the match criteria.
update	Pipeline representing the update to be applied to a matching document.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ update_one() [6/6]

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

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

Parameters

session	The mongocxx::client_session with which to perform the update.
filter	Document representing the match criteria.
update	Supports the empty update {}.
options	Optional 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_error if the update is invalid, or mongocxx::bulk_write_exception if the operation fails.

See also: https://docs.mongodb.com/manual/reference/command/update/

◆ watch() [1/4]

change_stream mongocxx::collection::watch	(	const client_session &	session,
		const options::change_stream &	options = `{}`
	)

Parameters

session	The mongocxx::client_session with which to perform the watch operation.
options	The 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 pipeline &	pipe,
		const options::change_stream &	options = `{}`
	)

Gets a change stream on this collection.

Parameters

session	The mongocxx::client_session with which to perform the watch operation.
pipe	The aggregation pipeline to be used on the change notifications.
options	The 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 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

options The 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 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

pipe	The 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.
options	The 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 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

session	The mongocxx::client_session with which to perform the bulk operation.
write	A model::write.
options	Optional 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_exception when there are errors processing the writes.

See also: mongocxx::bulk_write; https://docs.mongodb.com/manual/core/bulk-write-operations/

◆ write() [2/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

write	A model::write.
options	Optional 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_exception when there are errors processing the writes.

See also: mongocxx::bulk_write; https://docs.mongodb.com/manual/core/bulk-write-operations/

◆ write_concern() [1/2]

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

Gets the write_concern for the collection.

Returns: The current write_concern.

◆ write_concern() [2/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

wc	The new write_concern to use.

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

src/mongocxx/collection.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ collection()

Member Function Documentation

◆ aggregate() [1/2]

◆ aggregate() [2/2]

◆ bulk_write() [1/4]

◆ bulk_write() [2/4]

◆ bulk_write() [3/4]

◆ bulk_write() [4/4]

◆ count_documents() [1/2]

◆ count_documents() [2/2]

◆ create_bulk_write() [1/2]

◆ create_bulk_write() [2/2]

◆ create_index() [1/2]

◆ create_index() [2/2]

◆ delete_many() [1/2]

◆ delete_many() [2/2]

◆ delete_one() [1/2]

◆ delete_one() [2/2]

◆ distinct() [1/2]

◆ distinct() [2/2]

◆ drop() [1/2]

◆ drop() [2/2]

◆ estimated_document_count()

◆ find() [1/2]

◆ find() [2/2]

◆ find_one() [1/2]

◆ find_one() [2/2]

◆ find_one_and_delete() [1/2]

◆ find_one_and_delete() [2/2]

◆ find_one_and_replace() [1/2]

◆ find_one_and_replace() [2/2]

◆ find_one_and_update() [1/6]

◆ find_one_and_update() [2/6]

◆ find_one_and_update() [3/6]

◆ find_one_and_update() [4/6]

◆ find_one_and_update() [5/6]

◆ find_one_and_update() [6/6]

◆ insert_many() [1/4]

◆ insert_many() [2/4]

◆ insert_many() [3/4]

◆ insert_many() [4/4]

◆ insert_one() [1/2]

◆ insert_one() [2/2]

◆ list_indexes() [1/2]

◆ list_indexes() [2/2]

◆ name()

◆ read_concern() [1/2]

◆ read_concern() [2/2]

◆ read_preference() [1/2]

◆ read_preference() [2/2]

◆ rename() [1/2]

◆ rename() [2/2]

◆ replace_one() [1/2]

◆ replace_one() [2/2]

◆ update_many() [1/6]

◆ update_many() [2/6]

◆ update_many() [3/6]

◆ update_many() [4/6]

◆ update_many() [5/6]

◆ update_many() [6/6]

◆ update_one() [1/6]

◆ update_one() [2/6]

◆ update_one() [3/6]

◆ update_one() [4/6]

◆ update_one() [5/6]

◆ update_one() [6/6]

◆ watch() [1/4]

◆ watch() [2/4]

◆ watch() [3/4]

◆ watch() [4/4]

◆ write() [1/2]

◆ write() [2/2]

◆ write_concern() [1/2]

◆ write_concern() [2/2]