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

Class representing a preference for how the driver routes read operations to members of a replica set or to a sharded cluster. More...

#include <read_preference.hpp>

Classes

struct  deprecated_tag
 

Public Types

enum  read_mode : std::uint8_t {
  read_mode::k_primary, read_mode::k_primary_preferred, read_mode::k_secondary, read_mode::k_secondary_preferred,
  read_mode::k_nearest
}
 Determines which members in a replica set are acceptable to read from. More...
 

Public Member Functions

 read_preference ()
 Constructs a new read_preference with read_mode set to k_primary.
 
MONGOCXX_DEPRECATED read_preference (read_mode mode)
 Constructs a new read_preference. More...
 
MONGOCXX_DEPRECATED read_preference (read_mode mode, bsoncxx::document::view_or_value tags)
 Constructs a new read_preference with tags. More...
 
 read_preference (const read_preference &)
 Copy constructs a read_preference.
 
read_preferenceoperator= (const read_preference &)
 Copy assigns a read_preference.
 
 read_preference (read_preference &&) noexcept
 Move constructs a read_preference.
 
read_preferenceoperator= (read_preference &&) noexcept
 Move assigns a read_preference.
 
 ~read_preference ()
 Destroys a read_preference.
 
read_preferencemode (read_mode mode)
 Sets a new mode for this read_preference. More...
 
read_mode mode () const
 Returns the current read_mode for this read_preference. More...
 
read_preferencetags (bsoncxx::document::view_or_value tag_set_list)
 Sets or updates the tag set list for this read_preference. More...
 
read_preferencetags (bsoncxx::array::view_or_value tag_set_list)
 Sets or updates the tag set list for this read_preference. More...
 
stdx::optional< bsoncxx::document::viewtags () const
 Sets or updates the tag set list for this read_preference. More...
 
read_preferencemax_staleness (std::chrono::seconds max_staleness)
 Sets the max staleness setting for this read_preference. More...
 
stdx::optional< std::chrono::seconds > max_staleness () const
 Returns the current max staleness setting for this read_preference. More...
 
read_preferencehedge (bsoncxx::document::view_or_value hedge)
 Sets the hedge document to be used for the read preference. More...
 
const stdx::optional< bsoncxx::document::viewhedge () const
 Gets the current hedge document to be used for the read preference. More...
 

Friends

bool operator== (const read_preference &, const read_preference &)
 Compares two read_preference objects for (in)-equality.
 
bool operator!= (const read_preference &, const read_preference &)
 Compares two read_preference objects for (in)-equality.
 

Detailed Description

Class representing a preference for how the driver routes read operations to members of a replica set or to a sharded cluster.

By default read operations are directed to the primary member in a replica set. Reading from the primary guarantees that read operations reflect the latest version of a document. However, by distributing some or all reads to secondary members of the replica set, you can improve read throughput or reduce latency for an application that does not require fully up-to-date data.

Read preference can be broadly specified by setting a mode. It is also possible to set tags in the read preference for more granular control, and to target specific members of a replica set via attributes other than their current state as a primary or secondary node. Furthermore, it is also possible to set a staleness threshold, such that the read is limited to targeting secondaries whose staleness is less than or equal to the given threshold.

Read preferences are ignored for direct connections to a single mongod instance. However, in order to perform read operations on a direct connection to a secondary member of a replica set, you must set a read preference that allows reading from secondaries.

See also
https://docs.mongodb.com/manual/core/read-preference/
Examples
examples/mongocxx/client_session.cpp.

Member Enumeration Documentation

◆ read_mode

enum mongocxx::read_preference::read_mode : std::uint8_t
strong

Determines which members in a replica set are acceptable to read from.

Warning
Read preference tags are not respected when the mode is set to primary.
All read preference modes except primary may return stale data because secondaries replicate operations from the primary with some delay. Ensure that your application can tolerate stale data if you choose to use a non-primary mode.
See also
https://docs.mongodb.com/manual/core/read-preference/#read-preference-modes
Enumerator
k_primary 

Only read from a primary node.

k_primary_preferred 

Prefer to read from a primary node.

k_secondary 

Only read from secondary nodes.

k_secondary_preferred 

Prefer to read from secondary nodes.

k_nearest 

Read from the node with the lowest latency irrespective of state.

Constructor & Destructor Documentation

◆ read_preference() [1/2]

MONGOCXX_DEPRECATED mongocxx::read_preference::read_preference ( read_mode  mode)

Constructs a new read_preference.

Parameters
modeSpecifies the read_mode.
Deprecated:
The constructor with no arguments and the method mode() should be used.

◆ read_preference() [2/2]

MONGOCXX_DEPRECATED mongocxx::read_preference::read_preference ( read_mode  mode,
bsoncxx::document::view_or_value  tags 
)

Constructs a new read_preference with tags.

Parameters
modeA read_preference read_mode.
tagsA document representing tags to use for the read_preference.
See also
https://docs.mongodb.com/manual/core/read-preference/#tag-sets
Deprecated:
The tags() method should be used instead.

Member Function Documentation

◆ hedge() [1/2]

const stdx::optional<bsoncxx::document::view> mongocxx::read_preference::hedge ( ) const

Gets the current hedge document to be used for the read preference.

Returns
A hedge document if one was set.

◆ hedge() [2/2]

read_preference& mongocxx::read_preference::hedge ( bsoncxx::document::view_or_value  hedge)

Sets the hedge document to be used for the read preference.

Sharded clusters running MongoDB 4.4 or later can dispatch read operations in parallel, returning the result from the fastest host and cancelling the unfinished operations.

This may be an empty document or a document of the form { enabled: <boolean> }.

Hedged reads are automatically enabled in MongoDB 4.4+ when using a nearest read preference. To explicitly enable or disable hedging, the hedge document must be passed. An empty document uses server defaults to control hedging, but the enabled key may be set to true or false to explicitly enable or disable hedged reads.

Parameters
hedgeThe hedge document to set. For example, the document { enabled: true }.
Returns
A reference to the object on which this member function is being called. This facilitates method chaining.

◆ max_staleness() [1/2]

stdx::optional<std::chrono::seconds> mongocxx::read_preference::max_staleness ( ) const

Returns the current max staleness setting for this read_preference.

Returns
The optionally current max staleness setting.

◆ max_staleness() [2/2]

read_preference& mongocxx::read_preference::max_staleness ( std::chrono::seconds  max_staleness)

Sets the max staleness setting for this read_preference.

Secondary servers with an estimated lag greater than this value will be excluded from selection under modes that allow secondaries.

Max staleness must be at least 90 seconds, and also at least the sum (in seconds) of the client's heartbeatFrequencyMS and the server's idle write period, which is 10 seconds. For general use, 90 seconds is the effective minimum. If less, an exception will be thrown when an operation is attempted.

Max staleness may only be used with MongoDB version 3.4 or later. If used with an earlier version, an exception will be thrown when an operation is attempted.

Note
The max-staleness feature is designed to prevent badly-lagging servers from being selected. The staleness estimate is imprecise and shouldn't be used to try to select "up-to-date" secondaries.
Parameters
max_stalenessThe new max staleness setting. It must be positive.
Returns
A reference to the object on which this member function is being called. This facilitates method chaining.
Exceptions
mongocxx::logic_errorif the argument is invalid.

◆ mode() [1/2]

read_mode mongocxx::read_preference::mode ( ) const

Returns the current read_mode for this read_preference.

Returns
The current read_mode.

◆ mode() [2/2]

read_preference& mongocxx::read_preference::mode ( read_mode  mode)

Sets a new mode for this read_preference.

Parameters
modeThe new read preference mode.
Returns
A reference to the object on which this member function is being called. This facilitates method chaining.
Examples
examples/mongocxx/client_session.cpp.

◆ tags() [1/3]

stdx::optional<bsoncxx::document::view> mongocxx::read_preference::tags ( ) const

Sets or updates the tag set list for this read_preference.

Returns
The optionally set current tag set list.
See also
https://www.mongodb.com/docs/manual/core/read-preference-tags/

◆ tags() [2/3]

read_preference& mongocxx::read_preference::tags ( bsoncxx::array::view_or_value  tag_set_list)

Sets or updates the tag set list for this read_preference.

Parameters
tagsArray of tag sets.
See also
https://www.mongodb.com/docs/manual/core/read-preference-tags/
Returns
A reference to the object on which this member function is being called. This facilitates method chaining.

◆ tags() [3/3]

read_preference& mongocxx::read_preference::tags ( bsoncxx::document::view_or_value  tag_set_list)

Sets or updates the tag set list for this read_preference.

Parameters
tagsDocument representing the tag set list.
See also
https://www.mongodb.com/docs/manual/core/read-preference-tags/
Returns
A reference to the object on which this member function is being called. This facilitates method chaining.

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