Loading...
Searching...
No Matches
mongocxx::v_noabi::client Class Reference

`#include <mongocxx/v_noabi/mongocxx/client.hpp>`

## Description

A client connection to a MongoDB server.

Acts as a logical gateway for working with databases contained within a MongoDB server.

Databases that are created via this client inherit the `read_concern`, `read_preference`, and `write_concern` settings of this client when they are created. The lifetimes of objects created via a client object (databases, collections, cursors, etc...) must be a subset of the lifetime of the client that created them.

Example
  v_noabi::client mongo_client{v_noabi::uri{}};
  v_noabi::client mongo_client{v_noabi::uri{"mongodb://localhost:27017"}};
  mongocxx::v_noabi::client
  A client connection to a MongoDB server.
  Definition client.hpp:77
  mongocxx::v_noabi::uri
  A MongoDB connection string URI.
  Definition uri.hpp:55

Note that client is not thread-safe. See https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/thread-safety/ for more details.

## Public Member Functions

| client () noexcept
| Default constructs a new client. The client is not connected and is equivalent to the state of a moved-from client. The only valid actions to take with a default constructed 'client' are to assign to it, or destroy it.
| client (v1::client client)
| Construct with the mongocxx::v1 equivalent.
| client (v_noabi::uri const &mongodb_uri, options::client const &options=options::client())
| Creates a new client to MongoDB.
v_noabi::database | database (bsoncxx::v_noabi::string::view_or_value name) const &
| Obtains a database that represents a logical grouping of collections on a MongoDB server.
std::vector< std::string > | list_database_names (bsoncxx::v_noabi::document::view_or_value const filter={}) const
| Queries the MongoDB server for a list of known databases.
std::vector< std::string > | list_database_names (v_noabi::client_session const &session, bsoncxx::v_noabi::document::view_or_value const filter={}) const
| Queries the MongoDB server for a list of known databases.
v_noabi::cursor | list_databases () const
| Enumerates the databases in the client.
v_noabi::cursor | list_databases (bsoncxx::v_noabi::document::view_or_value const opts) const
| Enumerates the databases in the client.
v_noabi::cursor | list_databases (v_noabi::client_session const &session) const
| Enumerates the databases in the client.
v_noabi::cursor | list_databases (v_noabi::client_session const &session, bsoncxx::v_noabi::document::view_or_value const opts) const
| Enumerates the databases in the client.
| operator bool () const noexcept
| Returns true if the client is valid, meaning it was not default constructed or moved from.
| operator v1::client () &&
| Convert to the mongocxx::v1 equivalent.
| operator v1::client () const &=delete
| This class is not copyable.
v_noabi::database | operator[] (bsoncxx::v_noabi::string::view_or_value name) const &
| Allows the syntax `client`["db_name"] as a convenient shorthand for the client::database() method by implementing the array subscript operator.
v_noabi::read_concern | read_concern () const
| Returns the current read concern for this client.
void | read_concern (v_noabi::read_concern rc)
| Sets the read concern for this client.
v_noabi::read_preference | read_preference () const
| Returns the current read preference for this client.
void | read_preference (v_noabi::read_preference rp)
| Sets the read preference for this client.
void | reset ()
| Prevents resource cleanup in the child process from interfering with the parent process after forking.
v_noabi::client_session | start_session (v_noabi::options::client_session const &options={})
| Create a client session for a sequence of operations.
v_noabi::uri | uri () const
| Returns the current uri for this client.
v_noabi::change_stream | watch (v_noabi::client_session const &session, v_noabi::options::change_stream const &options={})
| Get a change stream on this client with an empty pipeline.
v_noabi::change_stream | watch (v_noabi::client_session const &session, v_noabi::pipeline const &pipe, v_noabi::options::change_stream const &options={})
| Get a change stream on this client.
v_noabi::change_stream | watch (v_noabi::options::change_stream const &options={})
| Get a change stream on this client with an empty pipeline.
v_noabi::change_stream | watch (v_noabi::pipeline const &pipe, v_noabi::options::change_stream const &options={})
| Get a change stream on this client.
v_noabi::write_concern | write_concern () const
| Returns the current write concern for this client.
void | write_concern (v_noabi::write_concern wc)
| Sets the write concern for this client.
v1::client_bulk_write | create_bulk_write ()
| Return a new client-level bulk write operation for use with this client.
v1::client_bulk_write | create_bulk_write (v_noabi::client_session &session)
| Return a new client-level bulk write operation for use with this client.

## Constructor & Destructor Documentation

## client() [1/3]

mongocxx::v_noabi::client::client | ( |  | ) |

inline noexcept

Default constructs a new client. The client is not connected and is equivalent to the state of a moved-from client. The only valid actions to take with a default constructed 'client' are to assign to it, or destroy it.

## client() [2/3]

mongocxx::v_noabi::client::client | ( | v1::client | client | ) |

inline

Construct with the mongocxx::v1 equivalent.

## client() [3/3]

mongocxx::v_noabi::client::client | ( | v_noabi::uri const & | mongodb_uri,
|  | options::client const & | options = options::client() )

Creates a new client to MongoDB.

Parameters

  mongodb_uri | A MongoDB URI.
  options | Additional URI options.

Exceptions

  mongocxx::v_noabi::exception | if invalid options are provided (whether from the URI or provided client options).

## Member Function Documentation

## create_bulk_write() [1/2]

v1::client_bulk_write mongocxx::v_noabi::client::create_bulk_write | ( |  | ) |

Return a new client-level bulk write operation for use with this client.

## create_bulk_write() [2/2]

v1::client_bulk_write mongocxx::v_noabi::client::create_bulk_write | ( | v_noabi::client_session & | session | ) |

Return a new client-level bulk write operation for use with this client.

## database()

v_noabi::database mongocxx::v_noabi::client::database | ( | bsoncxx::v_noabi::string::view_or_value | name | ) | const &

Obtains a database that represents a logical grouping of collections on a MongoDB server.

Note
  A database cannot be obtained from a temporary client object.

Parameters

  name | The name of the database to get

Returns
  The database

## list_database_names() [1/2]

std::vector< std::string > mongocxx::v_noabi::client::list_database_names | ( | bsoncxx::v_noabi::document::view_or_value const | filter = {} | ) | const

Queries the MongoDB server for a list of known databases.

Parameters

  filter | An optional query expression to filter the returned database names.

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

Exceptions

  mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails.

See also
  - https://www.mongodb.com/docs/manual/reference/command/listDatabases

## list_database_names() [2/2]

std::vector< std::string > mongocxx::v_noabi::client::list_database_names | ( | v_noabi::client_session const & | session,
|  | bsoncxx::v_noabi::document::view_or_value const | filter = {} ) const

Queries the MongoDB server for a list of known databases.

Parameters

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

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

Exceptions

  mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails.

See also
  - https://www.mongodb.com/docs/manual/reference/command/listDatabases

## list_databases() [1/4]

v_noabi::cursor mongocxx::v_noabi::client::list_databases | ( |  | ) | const

Enumerates the databases in the client.

Returns
  A mongocxx::v_noabi::cursor containing a BSON document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.

Exceptions

  mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails.

See also
  - https://www.mongodb.com/docs/manual/reference/command/listDatabases

## list_databases() [2/4]

v_noabi::cursor mongocxx::v_noabi::client::list_databases | ( | bsoncxx::v_noabi::document::view_or_value const | opts | ) | const

Enumerates the databases in the client.

Parameters

  opts | Options passed directly to the 'listDatabases' command.

Returns
  A mongocxx::v_noabi::cursor containing a BSON document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.

Exceptions

  mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails.

See also
  - https://www.mongodb.com/docs/manual/reference/command/listDatabases

## list_databases() [3/4]

v_noabi::cursor mongocxx::v_noabi::client::list_databases | ( | v_noabi::client_session const & | session | ) | const

Enumerates the databases in the client.

Parameters

  session | The mongocxx::v_noabi::client_session with which to perform the aggregation.

Returns
  A mongocxx::v_noabi::cursor containing a BSON document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.

Exceptions

  mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails.

See also
  - https://www.mongodb.com/docs/manual/reference/command/listDatabases

## list_databases() [4/4]

v_noabi::cursor mongocxx::v_noabi::client::list_databases | ( | v_noabi::client_session const & | session,
|  | bsoncxx::v_noabi::document::view_or_value const | opts ) const

Enumerates the databases in the client.

Parameters

  session | The mongocxx::v_noabi::client_session with which to perform the aggregation.
  opts | Options passed directly to the 'listDatabases' command.

Returns
  A mongocxx::v_noabi::cursor containing a BSON document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.

Exceptions

  mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails.

See also
  - https://www.mongodb.com/docs/manual/reference/command/listDatabases

## operator bool()

mongocxx::v_noabi::client::operator bool | ( |  | ) | const

inline explicit noexcept

Returns true if the client is valid, meaning it was not default constructed or moved from.

## operator v1::client() [1/2]

mongocxx::v_noabi::client::operator v1::client | ( |  | ) | &&

inline explicit

Convert to the mongocxx::v1 equivalent.

Postconditions:
  - *this is in an assign-or-destroy-only state.

Warning
  Invalidates all associated objects.

## operator v1::client() [2/2]

mongocxx::v_noabi::client::operator v1::client | ( |  | ) | const &

explicit delete

This class is not copyable.

## operator[]()

v_noabi::database mongocxx::v_noabi::client::operator[] | ( | bsoncxx::v_noabi::string::view_or_value | name | ) | const &

inline

Allows the syntax `client`["db_name"] as a convenient shorthand for the client::database() method by implementing the array subscript operator.

Note
  A database cannot be obtained from a temporary client object.

Parameters

  name | The name of the database.

Returns
  Client side representation of a server side database

## read_concern() [1/2]

v_noabi::read_concern mongocxx::v_noabi::client::read_concern | ( |  | ) | const

Returns the current read concern for this client.

Returns
  The current `read_concern`

## read_concern() [2/2]

void mongocxx::v_noabi::client::read_concern | ( | v_noabi::read_concern | rc | ) |

Sets the read concern for this client.

Modifications at this level do not affect existing database instances that have been created by this client but do affect new ones as databases inherit the `read_concern` settings of their parent upon instantiation.

Deprecated
  This method is deprecated. Read concerns should be set either in the URI or directly on database or collection objects.

Parameters

  rc | The new `read_concern`

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

## read_preference() [1/2]

v_noabi::read_preference mongocxx::v_noabi::client::read_preference | ( |  | ) | const

Returns the current read preference for this client.

Returns
  The current `read_preference`

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

## read_preference() [2/2]

void mongocxx::v_noabi::client::read_preference | ( | v_noabi::read_preference | rp | ) |

Sets the read preference for this client.

Modifications at this level do not affect existing database instances that have been created by this client but do affect new ones as databases inherit the `read_preference` settings of their parent upon instantiation.

Deprecated
  This method is deprecated. Read preferences should be set either in the URI or directly on database or collection objects.

Parameters

  rp | The new `read_preference`

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

## reset()

void mongocxx::v_noabi::client::reset | ( |  | ) |

Prevents resource cleanup in the child process from interfering with the parent process after forking.

Clients should not be reused after forking. Call this method in the child after forking to safely destroy the client. This method should not be used with multi-threaded clients.

This method causes the client to clear its session pool without sending endSessions. It also increments an internal generation counter on the given client. After this method is called, cursors from previous generations will not issue a killCursors command when they are destroyed. Client sessions from previous generations cannot be used and should be destroyed.

## start_session()

v_noabi::client_session mongocxx::v_noabi::client::start_session | ( | v_noabi::options::client_session const & | options = {} | ) |

Create a client session for a sequence of operations.

Returns
  A client_session object. See v_noabi::client_session for more information.

Exceptions

  mongocxx::v_noabi::operation_exception | if the driver is not built with crypto support, if options is misconfigured, or if the session is configured with options that the server does not support.

## uri()

v_noabi::uri mongocxx::v_noabi::client::uri | ( |  | ) | const

Returns the current uri for this client.

Returns
  The `uri` that this client was created with.

## watch() [1/4]

v_noabi::change_stream mongocxx::v_noabi::client::watch | ( | v_noabi::client_session const & | session,
|  | v_noabi::options::change_stream const & | options = {} )

Get a change stream on this client with an empty pipeline.

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

Parameters

  session | The v_noabi::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 client.

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

## watch() [2/4]

v_noabi::change_stream mongocxx::v_noabi::client::watch | ( | v_noabi::client_session const & | session,
|  | v_noabi::pipeline const & | pipe,
|  | v_noabi::options::change_stream const & | options = {} )

Get a change stream on this client.

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

Parameters

  session | The v_noabi::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 client.

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

## watch() [3/4]

v_noabi::change_stream mongocxx::v_noabi::client::watch | ( | v_noabi::options::change_stream const & | options = {} | ) |

Get a change stream on this client 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 client.

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

## watch() [4/4]

v_noabi::change_stream mongocxx::v_noabi::client::watch | ( | v_noabi::pipeline const & | pipe,
|  | v_noabi::options::change_stream const & | options = {} )

Get a change stream on this client.

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

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

## write_concern() [1/2]

v_noabi::write_concern mongocxx::v_noabi::client::write_concern | ( |  | ) | const

Returns the current write concern for this client.

Returns
  the current `write_concern`

## write_concern() [2/2]

void mongocxx::v_noabi::client::write_concern | ( | v_noabi::write_concern | wc | ) |

Sets the write concern for this client.

Note
  Modifications at this level do not affect existing databases or collection instances that have come from this client but do affect new ones as databases will receive a copy of this client's `write_concern` upon instantiation.

Deprecated
  This method is deprecated. Write concerns should be set either in the URI or directly on database or collection objects.

Parameters

  wc | The new write concern

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

- mongocxx/v_noabi/mongocxx/client.hpp