.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MongoDB::ReadPreference 3pm"
.TH MongoDB::ReadPreference 3pm "2020-08-15" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::ReadPreference \- Encapsulate and validate read preferences
.SH "VERSION"
.IX Header "VERSION"
version v2.2.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use MongoDB::ReadPreference;
\&
\&    $rp = MongoDB::ReadPreference\->new(); # mode: primary
\&
\&    $rp = MongoDB::ReadPreference\->new(
\&        mode     => \*(AqprimaryPreferred\*(Aq,
\&        tag_sets => [ { dc => \*(Aquseast\*(Aq }, {} ],
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A read preference indicates which servers should be used for read operations.
.PP
For core documentation on read preference see
<http://docs.mongodb.org/manual/core/read\-preference/>.
.SH "USAGE"
.IX Header "USAGE"
Read preferences work via two attributes: \f(CW\*(C`mode\*(C'\fR and \f(CW\*(C`tag_sets\*(C'\fR.  The \f(CW\*(C`mode\*(C'\fR
parameter controls the types of servers that are candidates for a read
operation as well as the logic for applying the \f(CW\*(C`tag_sets\*(C'\fR attribute to
further restrict the list.
.PP
The following terminology is used in describing read preferences:
.IP "\(bu" 4
candidates – based on \f(CW\*(C`mode\*(C'\fR, servers that could be suitable, based on \f(CW\*(C`tag_sets\*(C'\fR and other logic
.IP "\(bu" 4
eligible – these are candidates that match \f(CW\*(C`tag_sets\*(C'\fR
.IP "\(bu" 4
suitable – servers that meet all criteria for a read operation
.SS "Read preference modes"
.IX Subsection "Read preference modes"
\fIprimary\fR
.IX Subsection "primary"
.PP
Only an available primary is suitable.  \f(CW\*(C`tag_sets\*(C'\fR do not apply and must not
be provided or an exception is thrown.
.PP
\fIsecondary\fR
.IX Subsection "secondary"
.PP
All secondaries (and \fBonly\fR secondaries) are candidates, but only eligible
candidates (i.e. after applying \f(CW\*(C`tag_sets\*(C'\fR) are suitable.
.PP
\fIprimaryPreferred\fR
.IX Subsection "primaryPreferred"
.PP
Try to find a server using mode \*(L"primary\*(R" (with no \f(CW\*(C`tag_sets\*(C'\fR).  If that
fails, try to find one using mode \*(L"secondary\*(R" and the \f(CW\*(C`tag_sets\*(C'\fR attribute.
.PP
\fIsecondaryPreferred\fR
.IX Subsection "secondaryPreferred"
.PP
Try to find a server using mode \*(L"secondary\*(R" and the \f(CW\*(C`tag_sets\*(C'\fR attribute.  If
that fails, try to find a server using mode \*(L"primary\*(R" (with no \f(CW\*(C`tag_sets\*(C'\fR).
.PP
\fInearest\fR
.IX Subsection "nearest"
.PP
The primary and all secondaries are candidates, but only eligible candidates
(i.e. after applying \f(CW\*(C`tag_sets\*(C'\fR to all candidates) are suitable.
.PP
\&\fB\s-1NOTE\s0\fR: in retrospect, the name \*(L"nearest\*(R" is misleading, as it implies a
choice based on lowest absolute latency or geographic proximity, neither which
are true.
.PP
The \*(L"nearest\*(R" mode merely includes both primaries and secondaries without any
preference between the two.  All are filtered on \f(CW\*(C`tag_sets\*(C'\fR.  Because of
filtering, servers might not be \*(L"closest\*(R" 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.
.SS "Tag set matching"
.IX Subsection "Tag set matching"
The \f(CW\*(C`tag_sets\*(C'\fR 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 \fBany\fR candidate server is
used as the filter for all candidate servers.  Any subsequent tag sets are
ignored.
.PP
A read preference tag set (\f(CW\*(C`T\*(C'\fR) matches a server tag set (\f(CW\*(C`S\*(C'\fR) – or
equivalently a server tag set (\f(CW\*(C`S\*(C'\fR) matches a read preference tag set (\f(CW\*(C`T\*(C'\fR) —
if \f(CW\*(C`T\*(C'\fR is a subset of \f(CW\*(C`S\*(C'\fR (i.e. \f(CW\*(C`T ⊆ S\*(C'\fR).
.PP
For example, the read preference tag set \f(CW\*(C`{ dc => \*(Aqny\*(Aq, rack => 2 }\*(C'\fR
matches a secondary server with tag set \f(CW\*(C`{ dc => \*(Aqny\*(Aq, rack => 2, size =>
\&\*(Aqlarge\*(Aq }\*(C'\fR.
.PP
A tag set that is an empty document – \f(CW\*(C`{}\*(C'\fR – matches any server, because
the empty tag set is a subset of any tag set.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "mode"
.IX Subsection "mode"
The read preference mode determines which server types are candidates
for a read operation.  Valid values are:
.IP "\(bu" 4
primary
.IP "\(bu" 4
primaryPreferred
.IP "\(bu" 4
secondary
.IP "\(bu" 4
secondaryPreferred
.IP "\(bu" 4
nearest
.SS "tag_sets"
.IX Subsection "tag_sets"
The \f(CW\*(C`tag_sets\*(C'\fR parameter is an ordered list of tag sets used to restrict the
eligibility of servers, such as for data center awareness.
.PP
The application of \f(CW\*(C`tag_sets\*(C'\fR varies depending on the \f(CW\*(C`mode\*(C'\fR parameter.  If
the \f(CW\*(C`mode\*(C'\fR is 'primary', then \f(CW\*(C`tag_sets\*(C'\fR must not be supplied.
.SS "max_staleness_seconds"
.IX Subsection "max_staleness_seconds"
The \f(CW\*(C`max_staleness_seconds\*(C'\fR 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.
.PP
If the \f(CW\*(C`mode\*(C'\fR is 'primary', then \f(CW\*(C`max_staleness_seconds\*(C'\fR must not be supplied.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve