mongocxx::read_preference Class Reference

#include <mongocxx/v_noabi/mongocxx/read_preference.hpp>

Description

Describes how MongoDB clients route read operations to the members of a replica set or sharded cluster.

See also

• Read Preference (MongoDB Manual)

Public Types
enum class	read_mode : std::uint8_t
	Determines which members in a replica set are acceptable to read from. More...

Public Member Functions
	read_preference ()=default
	Constructs a new read_preference with read_mode set to k_primary.
	read_preference (read_mode mode)
	Constructs a new read_preference.
	read_preference (read_mode mode, bsoncxx::v_noabi::document::view_or_value tags)
	Constructs a new read_preference with tags.
	read_preference (v1::read_preference rp)
	Construct with the mongocxx::v1 equivalent.
bsoncxx::v_noabi::stdx::optional< bsoncxx::v_noabi::document::view > const	hedge () const
	Gets the current hedge document to be used for the read preference.
read_preference &	hedge (bsoncxx::v_noabi::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.
bsoncxx::v_noabi::stdx::optional< std::chrono::seconds >	max_staleness () const
	Returns the current max staleness setting for this read_preference.
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.
read_mode	mode () const
	Returns the current read_mode for this read_preference.
read_preference &	mode (read_mode mode)
	Sets a new mode for this read_preference.
	operator v1::read_preference () &&
	Convert to the mongocxx::v1 equivalent.
	operator v1::read_preference () const &
	Convert to the mongocxx::v1 equivalent.
bsoncxx::v_noabi::stdx::optional< bsoncxx::v_noabi::document::view >	tags () const
	Returns the current tag set list for this read_preference.
read_preference &	tags (bsoncxx::v_noabi::array::view_or_value tag_set_list)
	Sets or updates the tag set list for this read_preference.
read_preference &	tags (bsoncxx::v_noabi::document::view_or_value tag_set_list)
	Sets or updates the tag set list for this read_preference.

Related Symbols
(Note that these are not member symbols.)
bool	operator== (read_preference const &lhs, read_preference const &rhs)
	Compares two read_preference objects for (in)-equality.
bool	operator!= (read_preference const &lhs, read_preference const &rhs)
	Compares two read_preference objects for (in)-equality.

Member Enumeration Documentation

read_mode

enum class mongocxx::v_noabi::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://www.mongodb.com/docs/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/4]

mongocxx::v_noabi::read_preference::read_preference ( )

default

Constructs a new read_preference with read_mode set to k_primary.

read_preference() [2/4]

mongocxx::v_noabi::read_preference::read_preference ( v1::read_preference rp )

inline

Construct with the mongocxx::v1 equivalent.

read_preference() [3/4]

mongocxx::v_noabi::read_preference::read_preference ( read_mode mode )

inline

Constructs a new read_preference.

Parameters

mode	Specifies the read_mode.

Deprecated

Use mode instead.

read_preference() [4/4]

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

inline

Constructs a new read_preference with tags.

Parameters

mode	A read_preference read_mode.
tags	A document representing tags to use for the read_preference.

See also

• https://www.mongodb.com/docs/manual/core/read-preference/#tag-sets

Deprecated

Use tags instead.

Member Function Documentation

hedge() [1/2]

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

inline

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

Deprecated

Hedged reads are deprecated in MongoDB Server version 8.0.

Returns

A hedge document if one was set.

hedge() [2/2]

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

inline

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

hedge

The hedge document to set. For example, the document { enabled: true }.

Deprecated

Hedged reads are deprecated in MongoDB Server version 8.0.

Returns

A reference to the object on which this member function is being called. This facilitates method chaining.

max_staleness() [1/2]

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

inline

Returns the current max staleness setting for this read_preference.

Returns

The optionally current max staleness setting.

max_staleness() [2/2]

read_preference & mongocxx::v_noabi::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_staleness

The 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::v_noabi::logic_error

if the argument is invalid.

mode() [1/2]

read_mode mongocxx::v_noabi::read_preference::mode ( ) const

inline

Returns the current read_mode for this read_preference.

Returns

The current read_mode.

mode() [2/2]

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

inline

Sets a new mode for this read_preference.

Parameters

mode	The new read preference mode.

Returns

A reference to the object on which this member function is being called. This facilitates method chaining.

operator v1::read_preference() [1/2]

mongocxx::v_noabi::read_preference::operator v1::read_preference ( ) &&

inlineexplicit

Convert to the mongocxx::v1 equivalent.

Postconditions:

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

Warning

Invalidates all associated views.

operator v1::read_preference() [2/2]

mongocxx::v_noabi::read_preference::operator v1::read_preference ( ) const &

inlineexplicit

Convert to the mongocxx::v1 equivalent.

tags() [1/3]

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

inline

Returns the current 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::v_noabi::read_preference::tags ( bsoncxx::v_noabi::array::view_or_value tag_set_list )

inline

Sets or updates the tag set list for this read_preference.

Parameters

tag_set_list

Array 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::v_noabi::read_preference::tags ( bsoncxx::v_noabi::document::view_or_value tag_set_list )

inline

Sets or updates the tag set list for this read_preference.

Parameters

tag_set_list

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

Friends And Related Symbol Documentation

operator!=

bool operator!= ( read_preference const & lhs, read_preference const & rhs )

friend

Compares two read_preference objects for (in)-equality.

operator==

bool operator== ( read_preference const & lhs, read_preference const & rhs )

friend

Compares two read_preference objects for (in)-equality.

---

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

• mongocxx/v_noabi/mongocxx/read_preference.hpp