1MONGOC_READ_PREFS_T(3)             libmongoc            MONGOC_READ_PREFS_T(3)
2
3
4

NAME

6       mongoc_read_prefs_t - mongoc_read_prefs_t
7
8       A read preference abstraction
9

SYNOPSIS

11       mongoc_read_prefs_t  provides an abstraction on top of the MongoDB con‐
12       nection read preferences. It allows for hinting  to  the  driver  which
13       nodes in a replica set should be accessed first and how.
14
15       You  can specify a read preference mode on connection objects, database
16       objects, collection objects, or per-operation.  Generally, it makes the
17       most  sense to stick with the global default mode, MONGOC_READ_PRIMARY.
18       All of the other modes come with caveats that won't be covered in great
19       detail here.
20

READ MODES

22              ┌───────────────────────────┬────────────────────────────┐
23              │MONGOC_READ_PRIMARY        │ Default  mode.  All opera‐ │
24              │                           │ tions read from  the  cur‐ │
25              │                           │ rent replica set primary.  │
26              ├───────────────────────────┼────────────────────────────┤
27              │MONGOC_READ_SECONDARY      │ All  operations  read from │
28              │                           │ among  the  nearest   sec‐ │
29              │                           │ ondary   members   of  the │
30              │                           │ replica set.               │
31              ├───────────────────────────┼────────────────────────────┤
32              │MONGOC_READ_PRIMARY_PRE‐   │ In most situations, opera‐ │
33              │FERRED                     │ tions read from  the  pri‐ │
34              │                           │ mary but if it is unavail‐ │
35              │                           │ able, operations read from │
36              │                           │ secondary members.         │
37              ├───────────────────────────┼────────────────────────────┤
38              │MONGOC_READ_SECONDARY_PRE‐ │ In most situations, opera‐ │
39              │FERRED                     │ tions  read from among the │
40              │                           │ nearest secondary members, │
41              │                           │ but  if no secondaries are │
42              │                           │ available, operations read │
43              │                           │ from the primary.          │
44              ├───────────────────────────┼────────────────────────────┤
45              │MONGOC_READ_NEAREST        │ Operations read from among │
46              │                           │ the nearest members of the │
47              │                           │ replica  set, irrespective │
48              │                           │ of the member's type.      │
49              └───────────────────────────┴────────────────────────────┘
50

TAG SETS

52       Tag sets allow you to specify custom read preferences  and  write  con‐
53       cerns  so  that your application can target operations to specific mem‐
54       bers.
55
56       Custom read preferences and write concerns evaluate tags sets  in  dif‐
57       ferent  ways: read preferences consider the value of a tag when select‐
58       ing a member to read from, while write concerns ignore the value  of  a
59       tag  when  selecting  a  member,  except to consider whether or not the
60       value is unique.
61
62       You can specify tag sets with the following read preference modes:
63
64       • primaryPreferred
65
66       • secondary
67
68       • secondaryPreferred
69
70       • nearest
71
72       Tags are not compatible with MONGOC_READ_PRIMARY and, in general,  only
73       apply  when selecting a secondary member of a set for a read operation.
74       However, the nearest read mode, when combined with a tag set, will  se‐
75       lect  the  nearest member that matches the specified tag set, which may
76       be a primary or secondary.
77
78       Tag sets are represented as a comma-separated list  of  colon-separated
79       key-value   pairs   when   provided   as   a  connection  string,  e.g.
80       dc:ny,rack:1.
81
82       To specify a list of tag sets, using multiple readPreferenceTags, e.g.
83
84          readPreferenceTags=dc:ny,rack:1;readPreferenceTags=dc:ny;readPreferenceTags=
85
86       Note the empty value for the last one, which means "match any secondary
87       as a last resort".
88
89       Order matters when using multiple readPreferenceTags.
90
91       Tag Sets can also be configured using mongoc_read_prefs_set_tags.
92
93       All interfaces use the same member selection logic to choose the member
94       to which to direct read operations, basing the choice on  read  prefer‐
95       ence mode and tag sets.
96

MAX STALENESS

98       When  connected to replica set running MongoDB 3.4 or later, the driver
99       estimates the staleness of each secondary based on lastWriteDate values
100       provided in server hello responses.
101
102       Max  Staleness  is  the  maximum replication lag in seconds (wall clock
103       time) that a secondary can suffer and still be eligible for reads.  The
104       default  is  MONGOC_NO_MAX_STALENESS,  which disables staleness checks.
105       Otherwise, it  must  be  a  positive  integer  at  least  MONGOC_SMALL‐
106       EST_MAX_STALENESS_SECONDS (90 seconds).
107
108       Max  Staleness is also supported by sharded clusters of replica sets if
109       all servers run MongoDB 3.4 or later.
110

HEDGED READS

112       When connecting to a sharded cluster  running  MongoDB  4.4  or  later,
113       reads can be sent in parallel to the two "best" hosts.  Once one result
114       returns, any other outstanding operations that were part of the  hedged
115       read are cancelled.
116
117       When  the  read  preference mode is MONGOC_READ_NEAREST and the sharded
118       cluster is running MongoDB 4.4 or later, hedged reads  are  enabled  by
119       default.   Additionally, hedged reads may be explicitly enabled or dis‐
120       abled by calling mongoc_read_prefs_set_hedge with a BSON document, e.g.
121
122          {
123             enabled: true
124          }
125
126       Appropriate values for the enabled key are true or false.
127

AUTHOR

129       MongoDB, Inc
130
132       2017-present, MongoDB, Inc
133
134
135
136
1371.20.0                           Nov 18, 2021           MONGOC_READ_PREFS_T(3)
Impressum