NAME
MongoDB::ReadPreference - Encapsulate and validate read preferences
VERSION
version v2.2.0
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:
candidates – based on
mode
, servers that could be suitable, based ontag_sets
and other logiceligible – these are candidates that match
tag_sets
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 ⊆ 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:
primary
primaryPreferred
secondary
secondaryPreferred
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
David Golden <david@mongodb.com>
Rassi <rassi@mongodb.com>
Mike Friedman <friedo@friedo.com>
Kristina Chodorow <k.chodorow@gmail.com>
Florian Ragwitz <rafl@debian.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2019 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004