.\" Man page generated from reStructuredText.
.
.TH "MONGOC_READ_PREFS_T" "3" "Jun 04, 2021" "1.17.6" "libmongoc"
.SH NAME
mongoc_read_prefs_t \- mongoc_read_prefs_t
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
A read preference abstraction
.SH SYNOPSIS
.sp
\fBmongoc_read_prefs_t\fP 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.
.sp
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, \fBMONGOC_READ_PRIMARY\fP\&.  All of the other modes come with caveats that won\(aqt be covered in great detail here.
.SH READ MODES
.TS
center;
|l|l|.
_
T{
MONGOC_READ_PRIMARY
T}	T{
Default mode. All operations read from the current replica set primary.
T}
_
T{
MONGOC_READ_SECONDARY
T}	T{
All operations read from among the nearest secondary members of the replica set.
T}
_
T{
MONGOC_READ_PRIMARY_PREFERRED
T}	T{
In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.
T}
_
T{
MONGOC_READ_SECONDARY_PREFERRED
T}	T{
In most situations, operations read from among the nearest secondary members, but if no secondaries are available, operations read from the primary.
T}
_
T{
MONGOC_READ_NEAREST
T}	T{
Operations read from among the nearest members of the replica set, irrespective of the member\(aqs type.
T}
_
.TE
.SH TAG SETS
.sp
Tag sets allow you to specify custom read preferences and write concerns so that your application can target operations to specific members.
.sp
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.
.sp
You can specify tag sets with the following read preference modes:
.INDENT 0.0
.IP \(bu 2
primaryPreferred
.IP \(bu 2
secondary
.IP \(bu 2
secondaryPreferred
.IP \(bu 2
nearest
.UNINDENT
.sp
Tags are not compatible with \fBMONGOC_READ_PRIMARY\fP 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.
.sp
Tag sets are represented as a comma\-separated list of colon\-separated key\-value
pairs when provided as a connection string, e.g. \fIdc:ny,rack:1\fP\&.
.sp
To specify a list of tag sets, using multiple readPreferenceTags, e.g.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
readPreferenceTags=dc:ny,rack:1;readPreferenceTags=dc:ny;readPreferenceTags=
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note the empty value for the last one, which means "match any secondary as a last resort".
.sp
Order matters when using multiple readPreferenceTags.
.sp
Tag Sets can also be configured using \fBmongoc_read_prefs_set_tags\fP\&.
.sp
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.
.SH MAX STALENESS
.sp
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 isMaster responses.
.sp
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 \fBMONGOC_NO_MAX_STALENESS\fP, which disables staleness checks. Otherwise, it must be a positive integer at least \fBMONGOC_SMALLEST_MAX_STALENESS_SECONDS\fP (90 seconds).
.sp
Max Staleness is also supported by sharded clusters of replica sets if all servers run MongoDB 3.4 or later.
.SH HEDGED READS
.sp
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.
.sp
When the read preference mode is \fBMONGOC_READ_NEAREST\fP 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 \fBmongoc_read_prefs_set_hedge\fP with a BSON document, e.g.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
   enabled: true
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Appropriate values for the \fBenabled\fP key are \fBtrue\fP or \fBfalse\fP\&.
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.