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:

       •   candidates – based on "mode", servers that could be suitable, based on "tag_sets" and other logic

       •   eligible – 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) 2020 by MongoDB, Inc.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004

perl v5.34.0                                       2022-06-30                       MongoDB::ReadPreference(3pm)