1MONGOC_READ_PREFS_T(3) libmongoc MONGOC_READ_PREFS_T(3)
2
6 mongoc_read_prefs_t - mongoc_read_prefs_t
7 A read preference abstraction
9
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 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
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
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 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 You can specify tag sets with the following read preference modes:
63 • primaryPreferred
65 • secondary
67 • secondaryPreferred
69 • nearest
71 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 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 To specify a list of tag sets, using multiple readPreferenceTags, e.g.
83 readPreferenceTags=dc:ny,rack:1;readPreferenceTags=dc:ny;readPreferenceTags=
85 Note the empty value for the last one, which means "match any secondary
87 as a last resort".
88 Order matters when using multiple readPreferenceTags.
90 Tag Sets can also be configured using mongoc_read_prefs_set_tags.
92 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
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 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 Max Staleness is also supported by sharded clusters of replica sets if
109 all servers run MongoDB 3.4 or later.
110
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 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 {
123 enabled: true
124 }
125 Appropriate values for the enabled key are true or false.
127
129 MongoDB, Inc
130
132 2017-present, MongoDB, Inc
1331.20.0 Nov 18, 2021 MONGOC_READ_PREFS_T(3)