SYNOPSIS

       mongoc_read_prefs_t  provides  an  abstraction  on  top  of  the  MongoDB  connection read
       preferences. It allows for hinting to the driver which nodes in a replica  set  should  be
       accessed first and how.

       You can specify a read preference mode on connection objects, database objects, collection
       objects, or per-operation.  Generally, it makes the most sense to stick  with  the  global
       default mode, MONGOC_READ_PRIMARY.  All of the other modes come with caveats that won't be
       covered in great detail here.

READ MODES

                  ┌────────────────────────────────┬──────────────────────────────────┐
                  │MONGOC_READ_PRIMARY             │ Default  mode.  All   operations │
                  │                                │ read  from  the  current replica │
                  │                                │ set primary.                     │
                  ├────────────────────────────────┼──────────────────────────────────┤
                  │MONGOC_READ_SECONDARY           │ All operations read  from  among │
                  │                                │ the nearest secondary members of │
                  │                                │ the replica set.                 │
                  ├────────────────────────────────┼──────────────────────────────────┤
                  │MONGOC_READ_PRIMARY_PREFERRED   │ In most  situations,  operations │
                  │                                │ read  from the primary but if it │
                  │                                │ is unavailable, operations  read │
                  │                                │ from secondary members.          │
                  ├────────────────────────────────┼──────────────────────────────────┤
                  │MONGOC_READ_SECONDARY_PREFERRED │ In  most  situations, operations │
                  │                                │ read  from  among  the   nearest │
                  │                                │ secondary  members,  but  if  no │
                  │                                │ secondaries    are    available, │
                  │                                │ operations    read    from   the │
                  │                                │ primary.                         │
                  ├────────────────────────────────┼──────────────────────────────────┤
                  │MONGOC_READ_NEAREST             │ Operations read from  among  the │
                  │                                │ nearest  members  of the replica │
                  │                                │ set,   irrespective    of    the │
                  │                                │ member's type.                   │
                  └────────────────────────────────┴──────────────────────────────────┘

TAG SETS

       Tag  sets  allow  you  to  specify custom read preferences and write concerns so that your
       application can target operations to specific members.

       Custom read preferences and write concerns evaluate tags  sets  in  different  ways:  read
       preferences  consider the value of a tag when selecting a member to read from, while write
       concerns ignore the value of a tag when selecting a member, except to consider whether  or
       not the value is unique.

       You can specify tag sets with the following read preference modes:

       • primaryPreferred

       • secondary

       • secondaryPreferred

       • nearest

       Tags  are  not  compatible  with  MONGOC_READ_PRIMARY  and,  in  general,  only apply when
       selecting a secondary member of a set for a read  operation.  However,  the  nearest  read
       mode,  when  combined  with  a  tag  set,  will select the nearest member that matches the
       specified tag set, which may be a primary or secondary.

       Tag sets are represented as a comma-separated list of colon-separated key-value pairs when
       provided as a connection string, e.g. dc:ny,rack:1.

       To specify a list of tag sets, using multiple readPreferenceTags, e.g.

          readPreferenceTags=dc:ny,rack:1;readPreferenceTags=dc:ny;readPreferenceTags=

       Note the empty value for the last one, which means "match any secondary as a last resort".

       Order matters when using multiple readPreferenceTags.

       Tag Sets can also be configured using mongoc_read_prefs_set_tags().

       All interfaces use the same member selection logic to choose the member to which to direct
       read operations, basing the choice on read preference mode and tag sets.

MAX STALENESS

       When connected to replica set running MongoDB 3.4  or  later,  the  driver  estimates  the
       staleness  of  each  secondary  based  on  lastWriteDate  values  provided in server hello
       responses.

       Max Staleness is the maximum replication lag in seconds (wall clock time) that a secondary
       can  suffer and still be eligible for reads. The default is MONGOC_NO_MAX_STALENESS, which
       disables  staleness  checks.  Otherwise,  it  must  be  a  positive   integer   at   least
       MONGOC_SMALLEST_MAX_STALENESS_SECONDS (90 seconds).

       Max  Staleness  is  also  supported by sharded clusters of replica sets if all servers run
       MongoDB 3.4 or later.

HEDGED READS

       When connecting to a sharded cluster running MongoDB 4.4 or later, reads can  be  sent  in
       parallel  to  the  two  "best"  hosts.   Once  one  result  returns, any other outstanding
       operations that were part of the hedged read are cancelled.

       When the read preference mode is MONGOC_READ_NEAREST and the sharded  cluster  is  running
       MongoDB 4.4 or later, hedged reads are enabled by default.  Additionally, hedged reads may
       be explicitly enabled or disabled by calling  mongoc_read_prefs_set_hedge()  with  a  BSON
       document, e.g.

          {
             enabled: true
          }

       Appropriate values for the enabled key are true or false.

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc