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_preference &	operator= (const read_preference &)
	Copy assigns a read_preference.

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

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

	~read_preference ()
	Destroys a read_preference.

read_preference &	mode (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_preference &	tags (bsoncxx::document::view_or_value tag_set_list)
	Sets or updates the tag set list for this read_preference. More...

read_preference &	tags (bsoncxx::array::view_or_value tag_set_list)
	Sets or updates the tag set list for this read_preference. More...

stdx::optional< bsoncxx::document::view >	tags () const
	Sets or updates the tag set list for this read_preference. More...

read_preference &	max_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_preference &	hedge (bsoncxx::document::view_or_value hedge)
	Sets the hedge document to be used for the read preference. More...

const stdx::optional< bsoncxx::document::view >	hedge () 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

mode	Specifies 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

mode	A read_preference read_mode.
tags	A 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

hedge The 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_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::logic_error if 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

mode	The 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

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

Sets or updates the tag set list for this read_preference.

Parameters

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

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

src/mongocxx/read_preference.hpp

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ read_mode

Constructor & Destructor Documentation

◆ read_preference() [1/2]

◆ read_preference() [2/2]

Member Function Documentation

◆ hedge() [1/2]

◆ hedge() [2/2]

◆ max_staleness() [1/2]

◆ max_staleness() [2/2]

◆ mode() [1/2]

◆ mode() [2/2]

◆ tags() [1/3]

◆ tags() [2/3]

◆ tags() [3/3]