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

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.
 
databaseoperator= (database &&) noexcept
 Move assigns a database.
 
 database (const database &)
 Copy constructs a database.
 
databaseoperator= (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
sessionThe mongocxx::client_session with which to perform the aggregation.
pipelineThe pipeline of aggregation operations to perform.
optionsOptional arguments, see mongocxx::options::aggregate.
Returns
A mongocxx::cursor with the results. If the query fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
See also
https://docs.mongodb.com/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
pipelineThe pipeline of aggregation operations to perform.
optionsOptional arguments, see mongocxx::options::aggregate.
Returns
A mongocxx::cursor with the results. If the query fails, the cursor throws mongocxx::query_exception when the returned cursor is iterated.
See also
https://docs.mongodb.com/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
namethe 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
namethe new collection's name.
collection_optionsthe options for the new collection.
write_concernthe write concern to use for this operation. Will default to database set write concern if none passed here.
Exceptions
mongocxx::operation_exceptionif 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
sessionThe mongocxx::client_session with which to perform the create operation.
namethe new collection's name.
collection_optionsthe options for the new collection.
write_concernthe write concern to use for this operation. Will default to database set write concern if none passed here.
Exceptions
mongocxx::operation_exceptionif 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
sessionThe mongocxx::client_session with which to perform the create operation.
namethe new collection's name.
collection_optionsthe options for the new collection.
write_concernthe write concern to use for this operation. Will default to database set write concern if none passed here.
Exceptions
mongocxx::operation_exceptionif 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
namethe new collection's name.
collection_optionsthe options for the new collection.
write_concernthe write concern to use for this operation. Will default to database set write concern if none passed here.
Exceptions
mongocxx::operation_exceptionif 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
namethe new collection's name.
collection_optionsthe options for the new collection.
write_concernthe write concern to use for this operation. Will default to database set write concern if none passed here.
Exceptions
mongocxx::operation_exceptionif 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
sessionThe mongocxx::client_session with which to perform the create operation.
namethe new collection's name.
collection_optionsthe options for the new collection.
write_concernthe write concern to use for this operation. Will default to database set write concern if none passed here.
Exceptions
mongocxx::operation_exceptionif 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_exceptionif 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
sessionThe 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_exceptionif 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
optionsThe options for the bucket.
Returns
The GridFS bucket.
Note
See the class comment for gridfs::bucket for more information about GridFS.
Exceptions
mongocxx::logic_errorif 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
namethe name of the collection.
Returns
bool whether the collection exists in this database.
Exceptions
mongocxx::operation_exceptionif 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
filterAn optional query expression to filter the returned collection names.
Returns
std::vector<std::string> containing the collection names.
Exceptions
mongocxx::operation_exceptionif 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
sessionThe mongocxx::client_session with which to perform the aggregation.
filterAn optional query expression to filter the returned collection names.
Returns
std::vector<std::string> containing the collection names.
Exceptions
mongocxx::operation_exceptionif 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
filterAn 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
sessionThe mongocxx::client_session with which to perform the aggregation.
filterAn 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
namethe 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
rcThe 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
rpthe 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
commanddocument representing the command to be run.
Returns
the result of executing the command.
Exceptions
mongocxx::operation_exceptionif 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
commanddocument representing the command to be run.
server_idspecifying which server to use.
Returns
the result of executing the command.
Exceptions
mongocxx::operation_exceptionif 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
sessionThe mongocxx::client_session with which to run the command.
commanddocument representing the command to be run.
Returns
the result of executing the command.
Exceptions
mongocxx::operation_exceptionif the operation fails.

◆ watch() [1/4]

change_stream mongocxx::database::watch ( const client_session session,
const options::change_stream options = {} 
)
Parameters
sessionThe mongocxx::client_session with which to perform the watch operation.
optionsThe options to use when creating the change stream.
Returns
A change stream on this 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
sessionThe mongocxx::client_session with which to perform the watch operation.
pipeThe aggregation pipeline to be used on the change notifications.
optionsThe options to use when creating the change stream.
Returns
A change stream on this 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
optionsThe 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
pipeThe aggregation pipeline to be used on the change notifications. Only a subset of pipeline operations are supported for change streams. For more information see the change streams documentation.
optionsThe options to use when creating the change stream.
Returns
A change stream on this 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: