On Apache
Under GNU General Public License
2025-11-21 16:55 @216.73.216.57 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
MongoDB::ReadPreference(3pm) User Contributed Perl Documentation MongoDB::ReadPreference(3pm)
NAME
MongoDB::ReadPreference - Encapsulate and validate read preferences
VERSION
version v2.2.2
SYNOPSIS
use MongoDB::ReadPreference;
$rp = MongoDB::ReadPreference->new(); # mode: primary
$rp = MongoDB::ReadPreference->new(
mode => 'primaryPreferred',
tag_sets => [ { dc => 'useast' }, {} ],
);
DESCRIPTION
A read preference indicates which servers should be used for read operations.
For core documentation on read preference see
<http://docs.mongodb.org/manual/core/read-preference/>.
USAGE
Read preferences work via two attributes: "mode" and "tag_sets". The "mode" parameter
controls the types of servers that are candidates for a read operation as well as the
logic for applying the "tag_sets" attribute to further restrict the list.
The following terminology is used in describing read preferences:
o candidates - based on "mode", servers that could be suitable, based on "tag_sets" and
other logic
o eligible -these are candidates that match "tag_sets"
o suitable -servers that meet all criteria for a read operation
Read preference modes
primary
Only an available primary is suitable. "tag_sets" do not apply and must not be provided
or an exception is thrown.
secondary
All secondaries (and only secondaries) are candidates, but only eligible candidates (i.e.
after applying "tag_sets") are suitable.
primaryPreferred
Try to find a server using mode "primary" (with no "tag_sets"). If that fails, try to
find one using mode "secondary" and the "tag_sets" attribute.
secondaryPreferred
Try to find a server using mode "secondary" and the "tag_sets" attribute. If that fails,
try to find a server using mode "primary" (with no "tag_sets").
nearest
The primary and all secondaries are candidates, but only eligible candidates (i.e. after
applying "tag_sets" to all candidates) are suitable.
NOTE: in retrospect, the name "nearest" is misleading, as it implies a choice based on
lowest absolute latency or geographic proximity, neither which are true.
The "nearest" mode merely includes both primaries and secondaries without any preference
between the two. All are filtered on "tag_sets". Because of filtering, servers might not
be "closest" in any sense. And if multiple servers are suitable, one is randomly chosen
based on the rules for server selection, which again might not be the closest in absolute
latency terms.
Tag set matching
The "tag_sets" parameter is a list of tag sets (i.e. key/value pairs) to try in order.
The first tag set in the list to match any candidate server is used as the filter for all
candidate servers. Any subsequent tag sets are ignored.
A read preference tag set ("T") matches a server tag set ("S") - or equivalently a server
tag set ("S") matches a read preference tag set ("T") -- if "T" is a subset of "S" (i.e.
"T <subset or equal> S").
For example, the read preference tag set "{ dc => 'ny', rack => 2 }" matches a secondary
server with tag set "{ dc => 'ny', rack => 2, size => 'large' }".
A tag set that is an empty document - "{}" - matches any server, because the empty tag set
is a subset of any tag set.
ATTRIBUTES
mode
The read preference mode determines which server types are candidates for a read
operation. Valid values are:
o primary
o primaryPreferred
o secondary
o secondaryPreferred
o nearest
tag_sets
The "tag_sets" parameter is an ordered list of tag sets used to restrict the eligibility
of servers, such as for data center awareness.
The application of "tag_sets" varies depending on the "mode" parameter. If the "mode" is
'primary', then "tag_sets" must not be supplied.
max_staleness_seconds
The "max_staleness_seconds" parameter represents the maximum replication lag in seconds
(wall clock time) that a secondary can suffer and still be eligible for reads. The default
is -1, which disables staleness checks.
If the "mode" is 'primary', then "max_staleness_seconds" must not be supplied.
AUTHORS
o David Golden <david AT mongodb.com>
o Rassi <rassi AT mongodb.com>
o Mike Friedman <friedo AT friedo.com>
o Kristina Chodorow <k.chodorow AT gmail.com>
o Florian Ragwitz <rafl AT debian.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2020 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
perl v5.30.3 2020-08-15 MongoDB::ReadPreference(3pm)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2025-11-21 16:55 @216.73.216.57 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)