1MongoDB::ReadPreferenceU(s3e)r Contributed Perl DocumentaMtoinognoDB::ReadPreference(3)
2
3
4

NAME

6       MongoDB::ReadPreference - Encapsulate and validate read preferences
7

VERSION

9       version v2.2.2
10

SYNOPSIS

12           use MongoDB::ReadPreference;
13
14           $rp = MongoDB::ReadPreference->new(); # mode: primary
15
16           $rp = MongoDB::ReadPreference->new(
17               mode     => 'primaryPreferred',
18               tag_sets => [ { dc => 'useast' }, {} ],
19           );
20

DESCRIPTION

22       A read preference indicates which servers should be used for read
23       operations.
24
25       For core documentation on read preference see
26       <http://docs.mongodb.org/manual/core/read-preference/>.
27

USAGE

29       Read preferences work via two attributes: "mode" and "tag_sets".  The
30       "mode" parameter controls the types of servers that are candidates for
31       a read operation as well as the logic for applying the "tag_sets"
32       attribute to further restrict the list.
33
34       The following terminology is used in describing read preferences:
35
36       •   candidates – based on "mode", servers that could be suitable, based
37           on "tag_sets" and other logic
38
39       •   eligible – these are candidates that match "tag_sets"
40
41       •   suitable – servers that meet all criteria for a read operation
42
43   Read preference modes
44       primary
45
46       Only an available primary is suitable.  "tag_sets" do not apply and
47       must not be provided or an exception is thrown.
48
49       secondary
50
51       All secondaries (and only secondaries) are candidates, but only
52       eligible candidates (i.e. after applying "tag_sets") are suitable.
53
54       primaryPreferred
55
56       Try to find a server using mode "primary" (with no "tag_sets").  If
57       that fails, try to find one using mode "secondary" and the "tag_sets"
58       attribute.
59
60       secondaryPreferred
61
62       Try to find a server using mode "secondary" and the "tag_sets"
63       attribute.  If that fails, try to find a server using mode "primary"
64       (with no "tag_sets").
65
66       nearest
67
68       The primary and all secondaries are candidates, but only eligible
69       candidates (i.e. after applying "tag_sets" to all candidates) are
70       suitable.
71
72       NOTE: in retrospect, the name "nearest" is misleading, as it implies a
73       choice based on lowest absolute latency or geographic proximity,
74       neither which are true.
75
76       The "nearest" mode merely includes both primaries and secondaries
77       without any preference between the two.  All are filtered on
78       "tag_sets".  Because of filtering, servers might not be "closest" in
79       any sense.  And if multiple servers are suitable, one is randomly
80       chosen based on the rules for server selection, which again might not
81       be the closest in absolute latency terms.
82
83   Tag set matching
84       The "tag_sets" parameter is a list of tag sets (i.e. key/value pairs)
85       to try in order.  The first tag set in the list to match any candidate
86       server is used as the filter for all candidate servers.  Any subsequent
87       tag sets are ignored.
88
89       A read preference tag set ("T") matches a server tag set ("S") – or
90       equivalently a server tag set ("S") matches a read preference tag set
91       ("T") — if "T" is a subset of "S" (i.e. "T ⊆ S").
92
93       For example, the read preference tag set "{ dc => 'ny', rack => 2 }"
94       matches a secondary server with tag set "{ dc => 'ny', rack => 2, size
95       => 'large' }".
96
97       A tag set that is an empty document – "{}" – matches any server,
98       because the empty tag set is a subset of any tag set.
99

ATTRIBUTES

101   mode
102       The read preference mode determines which server types are candidates
103       for a read operation.  Valid values are:
104
105       •   primary
106
107       •   primaryPreferred
108
109       •   secondary
110
111       •   secondaryPreferred
112
113       •   nearest
114
115   tag_sets
116       The "tag_sets" parameter is an ordered list of tag sets used to
117       restrict the eligibility of servers, such as for data center awareness.
118
119       The application of "tag_sets" varies depending on the "mode" parameter.
120       If the "mode" is 'primary', then "tag_sets" must not be supplied.
121
122   max_staleness_seconds
123       The "max_staleness_seconds" parameter represents the maximum
124       replication lag in seconds (wall clock time) that a secondary can
125       suffer and still be eligible for reads. The default is -1, which
126       disables staleness checks.
127
128       If the "mode" is 'primary', then "max_staleness_seconds" must not be
129       supplied.
130

AUTHORS

132       •   David Golden <david@mongodb.com>
133
134       •   Rassi <rassi@mongodb.com>
135
136       •   Mike Friedman <friedo@friedo.com>
137
138       •   Kristina Chodorow <k.chodorow@gmail.com>
139
140       •   Florian Ragwitz <rafl@debian.org>
141

143       This software is Copyright (c) 2020 by MongoDB, Inc.
144
145       This is free software, licensed under:
146
147         The Apache License, Version 2.0, January 2004
148
149
150
151perl v5.38.0                      2023-07-20        MongoDB::ReadPreference(3)
Impressum