Class representing a MongoDB database. More...

#include <database.hpp>

Public Member Functions
	database () noexcept
	Default constructs a new database. More...

	database (database &&) noexcept
	Move constructs a database.

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

	database (const database &)
	Copy constructs a database.

database &	operator= (const database &)
	Copy assigns a database.

	~database ()
	Destroys a database.

	operator bool () const noexcept
	Returns true if the client is valid, meaning it was not default constructed or moved from.

bool	has_collection (bsoncxx::string::view_or_value name) const
	Checks whether this database contains a collection having the given name. More...

stdx::string_view	name () const
	Get the name of this database. More...

void	read_concern (class read_concern rc)
	Sets the read_concern for this database. More...

class read_concern	read_concern () const
	The current read concern for this database. More...

void	read_preference (class read_preference rp)
	Sets the read_preference for this database. More...

class read_preference	read_preference () const
	The current read preference for this database. More...

void	write_concern (class write_concern wc)
	Sets the write_concern for this database. More...

class write_concern	write_concern () const
	The current write_concern for this database. More...

class collection	collection (bsoncxx::string::view_or_value name) const
	Access a collection (logical grouping of documents) within this database. More...

class collection	operator[] (bsoncxx::string::view_or_value name) const
	Allows the db["collection_name"] syntax to be used to access a collection within this database. More...

class gridfs::bucket	gridfs_bucket (const options::gridfs::bucket &options=options::gridfs::bucket()) const
	Access a GridFS bucket within this database. More...


cursor	aggregate (const pipeline &pipeline, const options::aggregate &options=options::aggregate())
	Runs an aggregation framework pipeline against this database for pipeline stages that do not require an underlying collection, such as $currentOp and $listLocalSessions. More...

cursor	aggregate (const client_session &session, const pipeline &pipeline, const options::aggregate &options=options::aggregate())
	Runs an aggregation framework pipeline against this database for pipeline stages that do not require an underlying collection, such as $currentOp and $listLocalSessions. More...


bsoncxx::document::value	run_command (bsoncxx::document::view_or_value command)
	Runs a command against this database. More...

bsoncxx::document::value	run_command (const client_session &session, bsoncxx::document::view_or_value command)
	Runs a command against this database. More...

bsoncxx::document::value	run_command (bsoncxx::document::view_or_value command, uint32_t server_id)
	Executes a command on a specific server using this database. More...


class collection	create_collection (stdx::string_view name, bsoncxx::document::view_or_value collection_options={}, const stdx::optional< write_concern > &write_concern={})
	Explicitly creates a collection in this database with the specified options. More...

class collection	create_collection (const client_session &session, stdx::string_view name, bsoncxx::document::view_or_value collection_options={}, const stdx::optional< write_concern > &write_concern={})
	Explicitly creates a collection in this database with the specified options. More...

MONGOCXX_DEPRECATED class collection	create_collection (bsoncxx::string::view_or_value name, const options::create_collection_deprecated &collection_options, const stdx::optional< write_concern > &write_concern={})
	Explicitly creates a collection in this database with the specified options. More...

class collection	create_collection_deprecated (bsoncxx::string::view_or_value name, const options::create_collection_deprecated &collection_options, const stdx::optional< write_concern > &write_concern={})
	Explicitly creates a collection in this database with the specified options. More...

MONGOCXX_DEPRECATED class collection	create_collection (const client_session &session, bsoncxx::string::view_or_value name, const options::create_collection_deprecated &collection_options, const stdx::optional< write_concern > &write_concern={})
	Explicitly creates a collection in this database with the specified options. More...

class collection	create_collection_deprecated (const client_session &session, bsoncxx::string::view_or_value name, const options::create_collection_deprecated &collection_options, const stdx::optional< write_concern > &write_concern={})
	Explicitly creates a collection in this database with the specified options. More...


void	drop (const bsoncxx::stdx::optional< mongocxx::write_concern > &write_concern={})
	Drops the database and all its collections. More...

void	drop (const client_session &session, const bsoncxx::stdx::optional< mongocxx::write_concern > &write_concern={})
	Drops the database and all its collections. More...


cursor	list_collections (bsoncxx::document::view_or_value filter={})
	Enumerates the collections in this database. More...

cursor	list_collections (const client_session &session, bsoncxx::document::view_or_value filter={})
	Enumerates the collections in this database. More...

std::vector< std::string >	list_collection_names (bsoncxx::document::view_or_value filter={})
	Enumerates the collection names in this database. More...

std::vector< std::string >	list_collection_names (const client_session &session, bsoncxx::document::view_or_value filter={})
	Enumerates the collection names in this database. More...


change_stream	watch (const options::change_stream &options={})
	Gets a change stream on this database 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 database. More...

change_stream	watch (const client_session &session, const pipeline &pipe, const options::change_stream &options={})
	Gets a change stream on this database. More...

Detailed Description

Class representing a MongoDB database.

Acts as a gateway for accessing collections that are contained within a database. It inherits all of its default settings from the client that creates it.

Constructor & Destructor Documentation

◆ database()

mongocxx::database::database ( )

noexcept

Default constructs a new database.

The database is not valid for use and is equivalent to the state of a moved-from database. The only valid actions to take with a default constructed database are to assign to it, or destroy it.

Member Function Documentation

◆ aggregate() [1/2]

cursor mongocxx::database::aggregate	(	const client_session &	session,
		const pipeline &	pipeline,
		const options::aggregate &	options = `options::aggregate()`
	)

Runs an aggregation framework pipeline against this database for pipeline stages that do not require an underlying collection, such as $currentOp and $listLocalSessions.

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/#dbcmd.aggregate

Note: In order to pass a read concern to this, you must use the database level set read concern - database::read_concern(rc). (Write concern supported only for MongoDB 3.4+).

◆ aggregate() [2/2]

cursor mongocxx::database::aggregate	(	const pipeline &	pipeline,
		const options::aggregate &	options = `options::aggregate()`
	)

Runs an aggregation framework pipeline against this database for pipeline stages that do not require an underlying collection, such as $currentOp and $listLocalSessions.

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/#dbcmd.aggregate

Note: In order to pass a read concern to this, you must use the database level set read concern - database::read_concern(rc). (Write concern supported only for MongoDB 3.4+).

◆ collection()

class collection mongocxx::database::collection ( bsoncxx::string::view_or_value name ) const

Access a collection (logical grouping of documents) within this database.

Parameters

name	the name of the collection to get.

Returns: the collection.

◆ create_collection() [1/4]

MONGOCXX_DEPRECATED class collection mongocxx::database::create_collection	(	bsoncxx::string::view_or_value	name,
		const options::create_collection_deprecated &	collection_options,
		const stdx::optional< write_concern > &	write_concern = `{}`
	)

inline

Explicitly creates a collection in this database with the specified options.

Deprecated:: This overload is deprecated. Call database::create_collection with a bsoncxx::document::view_or_value collection_options instead.

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

Parameters

name	the new collection's name.
collection_options	the options for the new collection.
write_concern	the write concern to use for this operation. Will default to database set write concern if none passed here.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ create_collection() [2/4]

MONGOCXX_DEPRECATED class collection mongocxx::database::create_collection	(	const client_session &	session,
		bsoncxx::string::view_or_value	name,
		const options::create_collection_deprecated &	collection_options,
		const stdx::optional< write_concern > &	write_concern = `{}`
	)

inline

Explicitly creates a collection in this database with the specified options.

Deprecated:: This overload is deprecated. Call database::create_collection with a bsoncxx::document::view_or_value collection_options instead.

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

Parameters

session	The mongocxx::client_session with which to perform the create operation.
name	the new collection's name.
collection_options	the options for the new collection.
write_concern	the write concern to use for this operation. Will default to database set write concern if none passed here.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ create_collection() [3/4]

class collection mongocxx::database::create_collection	(	const client_session &	session,
		stdx::string_view	name,
		bsoncxx::document::view_or_value	collection_options = `{}`,
		const stdx::optional< write_concern > &	write_concern = `{}`
	)

Explicitly creates a collection in this database with the specified options.

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

Note: This function can also be used to create a Time Series Collection. See: https://docs.mongodb.com/manual/core/timeseries-collections/

Parameters

session	The mongocxx::client_session with which to perform the create operation.
name	the new collection's name.
collection_options	the options for the new collection.
write_concern	the write concern to use for this operation. Will default to database set write concern if none passed here.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ create_collection() [4/4]

class collection mongocxx::database::create_collection	(	stdx::string_view	name,
		bsoncxx::document::view_or_value	collection_options = `{}`,
		const stdx::optional< write_concern > &	write_concern = `{}`
	)

Explicitly creates a collection in this database with the specified options.

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

Note: This function can also be used to create a Time Series Collection. See: https://docs.mongodb.com/manual/core/timeseries-collections/

Parameters

name	the new collection's name.
collection_options	the options for the new collection.
write_concern	the write concern to use for this operation. Will default to database set write concern if none passed here.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ create_collection_deprecated() [1/2]

class collection mongocxx::database::create_collection_deprecated	(	bsoncxx::string::view_or_value	name,
		const options::create_collection_deprecated &	collection_options,
		const stdx::optional< write_concern > &	write_concern = `{}`
	)

Explicitly creates a collection in this database with the specified options.

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

Note: This function can also be used to create a Time Series Collection. See: https://docs.mongodb.com/manual/core/timeseries-collections/

Parameters

name	the new collection's name.
collection_options	the options for the new collection.
write_concern	the write concern to use for this operation. Will default to database set write concern if none passed here.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ create_collection_deprecated() [2/2]

class collection mongocxx::database::create_collection_deprecated	(	const client_session &	session,
		bsoncxx::string::view_or_value	name,
		const options::create_collection_deprecated &	collection_options,
		const stdx::optional< write_concern > &	write_concern = `{}`
	)

Explicitly creates a collection in this database with the specified options.

Deprecated:: This overload is deprecated. Call database::create_collection with a bsoncxx::document::view_or_value collection_options instead.

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

Parameters

session	The mongocxx::client_session with which to perform the create operation.
name	the new collection's name.
collection_options	the options for the new collection.
write_concern	the write concern to use for this operation. Will default to database set write concern if none passed here.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ drop() [1/2]

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

Drops the database and all its collections.

Parameters

write_concern (optional) The write concern to be used for this operation. If not passed here, the write concern set on the database will be used.

Exceptions

mongocxx::operation_exception if the operation fails.

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

◆ drop() [2/2]

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

Drops the database and all its collections.

Parameters

session	The mongocxx::client_session with which to perform the aggregation.
write_concern	(optional) The write concern to be used for this operation. If not passed here, the write concern set on the database will be used.

Exceptions

mongocxx::operation_exception if the operation fails.

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

◆ gridfs_bucket()

class gridfs::bucket mongocxx::database::gridfs_bucket ( const options::gridfs::bucket & options = options::gridfs::bucket() ) const

Access a GridFS bucket within this database.

Parameters

options The options for the bucket.

Returns: The GridFS bucket.

Note: See the class comment for gridfs::bucket for more information about GridFS.

Exceptions

mongocxx::logic_error if options are invalid.

◆ has_collection()

bool mongocxx::database::has_collection ( bsoncxx::string::view_or_value name ) const

Checks whether this database contains a collection having the given name.

Parameters

name	the name of the collection.

Returns: bool whether the collection exists in this database.

Exceptions

mongocxx::operation_exception if the underlying 'listCollections' command fails.

◆ list_collection_names() [1/2]

std::vector<std::string> mongocxx::database::list_collection_names ( bsoncxx::document::view_or_value filter = {} )

Enumerates the collection names in this database.

Parameters

filter An optional query expression to filter the returned collection names.

Returns: std::vector<std::string> containing the collection names.

Exceptions

mongocxx::operation_exception if the underlying 'listCollections' command fails.

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

◆ list_collection_names() [2/2]

std::vector<std::string> mongocxx::database::list_collection_names	(	const client_session &	session,
		bsoncxx::document::view_or_value	filter = `{}`
	)

Enumerates the collection names in this database.

Parameters

session	The mongocxx::client_session with which to perform the aggregation.
filter	An optional query expression to filter the returned collection names.

Returns: std::vector<std::string> containing the collection names.

Exceptions

mongocxx::operation_exception if the underlying 'listCollections' command fails.

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

◆ list_collections() [1/2]

cursor mongocxx::database::list_collections ( bsoncxx::document::view_or_value filter = {} )

Enumerates the collections in this database.

Parameters

filter An optional query expression to filter the returned collections.

Returns: mongocxx::cursor containing the collection information.

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

◆ list_collections() [2/2]

cursor mongocxx::database::list_collections	(	const client_session &	session,
		bsoncxx::document::view_or_value	filter = `{}`
	)

Enumerates the collections in this database.

Parameters

session	The mongocxx::client_session with which to perform the aggregation.
filter	An optional query expression to filter the returned collections.

Returns: mongocxx::cursor containing the collection information.

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

◆ name()

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

Get the name of this database.

Returns: the name of this database.

◆ operator[]()

collection mongocxx::database::operator[] ( bsoncxx::string::view_or_value name ) const

Allows the db["collection_name"] syntax to be used to access a collection within this database.

Parameters

name	the name of the collection to get.

Returns: the collection.

◆ read_concern() [1/2]

class read_concern mongocxx::database::read_concern ( ) const

The current read concern for this database.

If the read_concern is not explicitly set on this database object, it inherits the read_concern from its parent client object.

Returns: the current read_concern

◆ read_concern() [2/2]

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

Sets the read_concern for this database.

Note: Modifications at this level do not affect existing collection instances that have come from this database, but do affect new ones. New collections will receive a copy of the new read_concern for this database upon instantiation.

Parameters

rc	The new `read_concern`

See also: https://docs.mongodb.com/manual/reference/read-concern/

◆ read_preference() [1/2]

class read_preference mongocxx::database::read_preference ( ) const

The current read preference for this database.

See also: https://docs.mongodb.com/manual/core/read-preference/

Returns: the current read_preference

◆ read_preference() [2/2]

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

Sets the read_preference for this database.

Note: Modifications at this level do not affect existing collection instances that have come from this database, but do affect new ones. New collections will receive a copy of the new read_preference for this database upon instantiation.

See also: https://docs.mongodb.com/manual/core/read-preference/

Parameters

rp	the new read_preference.

◆ run_command() [1/3]

bsoncxx::document::value mongocxx::database::run_command ( bsoncxx::document::view_or_value command )

Runs a command against this database.

See also: https://docs.mongodb.com/manual/reference/method/db.runCommand/

Parameters

command document representing the command to be run.

Returns: the result of executing the command.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ run_command() [2/3]

bsoncxx::document::value mongocxx::database::run_command	(	bsoncxx::document::view_or_value	command,
		uint32_t	server_id
	)

Executes a command on a specific server using this database.

See also: https://docs.mongodb.com/manual/reference/method/db.runCommand/

Parameters

command	document representing the command to be run.
server_id	specifying which server to use.

Returns: the result of executing the command.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ run_command() [3/3]

bsoncxx::document::value mongocxx::database::run_command	(	const client_session &	session,
		bsoncxx::document::view_or_value	command
	)

Runs a command against this database.

See also: https://docs.mongodb.com/manual/reference/method/db.runCommand/

Parameters

session	The mongocxx::client_session with which to run the command.
command	document representing the command to be run.

Returns: the result of executing the command.

Exceptions

mongocxx::operation_exception if the operation fails.

◆ watch() [1/4]

change_stream mongocxx::database::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 database.

See also: https://docs.mongodb.com/manual/changeStreams/

◆ watch() [2/4]

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

Gets a change stream on this database.

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 database.

See also: https://docs.mongodb.com/manual/changeStreams/

◆ watch() [3/4]

change_stream mongocxx::database::watch ( const options::change_stream & options = {} )

Gets a change stream on this database 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 database.

See also: https://docs.mongodb.com/manual/changeStreams/

◆ watch() [4/4]

change_stream mongocxx::database::watch	(	const pipeline &	pipe,
		const options::change_stream &	options = `{}`
	)

Gets a change stream on this database.

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 database.

See also: https://docs.mongodb.com/manual/changeStreams/

◆ write_concern() [1/2]

class write_concern mongocxx::database::write_concern ( ) const

The current write_concern for this database.

Returns: the current write_concern

◆ write_concern() [2/2]

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

Sets the write_concern for this database.

Note: Modifications at this level do not affect existing collection instances that have come from this database, but do affect new ones as new collections will receive a copy of the write_concern of this database upon instantiation.

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

src/mongocxx/database.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ database()

Member Function Documentation

◆ aggregate() [1/2]

◆ aggregate() [2/2]

◆ collection()

◆ create_collection() [1/4]

◆ create_collection() [2/4]

◆ create_collection() [3/4]

◆ create_collection() [4/4]

◆ create_collection_deprecated() [1/2]

◆ create_collection_deprecated() [2/2]

◆ drop() [1/2]

◆ drop() [2/2]

◆ gridfs_bucket()

◆ has_collection()

◆ list_collection_names() [1/2]

◆ list_collection_names() [2/2]

◆ list_collections() [1/2]

◆ list_collections() [2/2]

◆ name()

◆ operator[]()

◆ read_concern() [1/2]

◆ read_concern() [2/2]

◆ read_preference() [1/2]

◆ read_preference() [2/2]

◆ run_command() [1/3]

◆ run_command() [2/3]

◆ run_command() [3/3]

◆ watch() [1/4]

◆ watch() [2/4]

◆ watch() [3/4]

◆ watch() [4/4]

◆ write_concern() [1/2]

◆ write_concern() [2/2]