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.
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, MONGOC_READ_PRIMARY.  All
18       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  to  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
75       select 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 isMaster 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

AUTHOR

112       MongoDB, Inc
113

115       2017-present, MongoDB, Inc
116
117
118
119
1201.16.2                           Feb 25, 2020           MONGOC_READ_PREFS_T(3)
Impressum