read_preferences
– Utilities for choosing which member of a replica set to read from.#
Utilities for choosing which member of a replica set to read from.
- class pymongo.read_preferences.Primary#
Primary read preference.
When directly connected to one mongod queries are allowed if the server is standalone or a replica set primary.
When connected to a mongos queries are sent to the primary of a shard.
When connected to a replica set queries are sent to the primary of the replica set.
- document#
Read preference as a document.
- mode#
The mode of this read preference instance.
- name#
The name of this read preference.
- class pymongo.read_preferences.PrimaryPreferred(tag_sets: Sequence[Mapping[str, Any]] | None = None, max_staleness: int = -1, hedge: Mapping[str, Any] | None = None)#
PrimaryPreferred read preference.
When directly connected to one mongod queries are allowed to standalone servers, to a replica set primary, or to replica set secondaries.
When connected to a mongos queries are sent to the primary of a shard if available, otherwise a shard secondary.
When connected to a replica set queries are sent to the primary if available, otherwise a secondary.
Note
When a
MongoClient
is first created reads will be routed to an available secondary until the primary of the replica set is discovered.- Parameters:
tag_sets: The
tag_sets
to use if the primary is not available.max_staleness: (integer, in seconds) The maximum estimated length of time a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations. Default -1, meaning no maximum. If it is set, it must be at least 90 seconds.
hedge: The
hedge
to use if the primary is not available.
Changed in version 3.11: Added
hedge
parameter.- property hedge: Mapping[str, Any] | None#
The read preference
hedge
parameter.A dictionary that configures how the server will perform hedged reads. It consists of the following keys:
enabled
: Enables or disables hedged reads in sharded clusters.
Hedged reads are automatically enabled in MongoDB 4.4+ when using a
nearest
read preference. To explicitly enable hedged reads, set theenabled
key totrue
:>>> Nearest(hedge={'enabled': True})
To explicitly disable hedged reads, set the
enabled
key toFalse
:>>> Nearest(hedge={'enabled': False})
New in version 3.11.
- property max_staleness: int#
The maximum estimated length of time (in seconds) a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations, or -1 for no maximum.
- property min_wire_version: int#
The wire protocol version the server must support.
Some read preferences impose version requirements on all servers (e.g. maxStalenessSeconds requires MongoDB 3.4 / maxWireVersion 5).
All servers’ maxWireVersion must be at least this read preference’s min_wire_version, or the driver raises
ConfigurationError
.
- property tag_sets: Sequence[Mapping[str, Any]]#
Set
tag_sets
to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whosedc
tag has the value"ny"
. To specify a priority-order for tag sets, provide a list of tag sets:[{'dc': 'ny'}, {'dc': 'la'}, {}]
. A final, empty tag set,{}
, means “read from any member that matches the mode, ignoring tags.” MongoClient tries each set of tags in turn until it finds a set of tags with at least one matching member. For example, to only send a query to an analytic node:Nearest(tag_sets=[{"node":"analytics"}])
Or using
SecondaryPreferred
:SecondaryPreferred(tag_sets=[{"node":"analytics"}]) .. seealso:: `Data-Center Awareness <https://www.mongodb.com/docs/manual/data-center-awareness/>`_
- class pymongo.read_preferences.Secondary(tag_sets: Sequence[Mapping[str, Any]] | None = None, max_staleness: int = -1, hedge: Mapping[str, Any] | None = None)#
Secondary read preference.
When directly connected to one mongod queries are allowed to standalone servers, to a replica set primary, or to replica set secondaries.
When connected to a mongos queries are distributed among shard secondaries. An error is raised if no secondaries are available.
When connected to a replica set queries are distributed among secondaries. An error is raised if no secondaries are available.
- Parameters:
tag_sets: The
tag_sets
for this read preference.max_staleness: (integer, in seconds) The maximum estimated length of time a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations. Default -1, meaning no maximum. If it is set, it must be at least 90 seconds.
hedge: The
hedge
for this read preference.
Changed in version 3.11: Added
hedge
parameter.- property hedge: Mapping[str, Any] | None#
The read preference
hedge
parameter.A dictionary that configures how the server will perform hedged reads. It consists of the following keys:
enabled
: Enables or disables hedged reads in sharded clusters.
Hedged reads are automatically enabled in MongoDB 4.4+ when using a
nearest
read preference. To explicitly enable hedged reads, set theenabled
key totrue
:>>> Nearest(hedge={'enabled': True})
To explicitly disable hedged reads, set the
enabled
key toFalse
:>>> Nearest(hedge={'enabled': False})
New in version 3.11.
- property max_staleness: int#
The maximum estimated length of time (in seconds) a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations, or -1 for no maximum.
- property min_wire_version: int#
The wire protocol version the server must support.
Some read preferences impose version requirements on all servers (e.g. maxStalenessSeconds requires MongoDB 3.4 / maxWireVersion 5).
All servers’ maxWireVersion must be at least this read preference’s min_wire_version, or the driver raises
ConfigurationError
.
- property tag_sets: Sequence[Mapping[str, Any]]#
Set
tag_sets
to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whosedc
tag has the value"ny"
. To specify a priority-order for tag sets, provide a list of tag sets:[{'dc': 'ny'}, {'dc': 'la'}, {}]
. A final, empty tag set,{}
, means “read from any member that matches the mode, ignoring tags.” MongoClient tries each set of tags in turn until it finds a set of tags with at least one matching member. For example, to only send a query to an analytic node:Nearest(tag_sets=[{"node":"analytics"}])
Or using
SecondaryPreferred
:SecondaryPreferred(tag_sets=[{"node":"analytics"}]) .. seealso:: `Data-Center Awareness <https://www.mongodb.com/docs/manual/data-center-awareness/>`_
- class pymongo.read_preferences.SecondaryPreferred(tag_sets: Sequence[Mapping[str, Any]] | None = None, max_staleness: int = -1, hedge: Mapping[str, Any] | None = None)#
SecondaryPreferred read preference.
When directly connected to one mongod queries are allowed to standalone servers, to a replica set primary, or to replica set secondaries.
When connected to a mongos queries are distributed among shard secondaries, or the shard primary if no secondary is available.
When connected to a replica set queries are distributed among secondaries, or the primary if no secondary is available.
Note
When a
MongoClient
is first created reads will be routed to the primary of the replica set until an available secondary is discovered.- Parameters:
tag_sets: The
tag_sets
for this read preference.max_staleness: (integer, in seconds) The maximum estimated length of time a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations. Default -1, meaning no maximum. If it is set, it must be at least 90 seconds.
hedge: The
hedge
for this read preference.
Changed in version 3.11: Added
hedge
parameter.- property hedge: Mapping[str, Any] | None#
The read preference
hedge
parameter.A dictionary that configures how the server will perform hedged reads. It consists of the following keys:
enabled
: Enables or disables hedged reads in sharded clusters.
Hedged reads are automatically enabled in MongoDB 4.4+ when using a
nearest
read preference. To explicitly enable hedged reads, set theenabled
key totrue
:>>> Nearest(hedge={'enabled': True})
To explicitly disable hedged reads, set the
enabled
key toFalse
:>>> Nearest(hedge={'enabled': False})
New in version 3.11.
- property max_staleness: int#
The maximum estimated length of time (in seconds) a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations, or -1 for no maximum.
- property min_wire_version: int#
The wire protocol version the server must support.
Some read preferences impose version requirements on all servers (e.g. maxStalenessSeconds requires MongoDB 3.4 / maxWireVersion 5).
All servers’ maxWireVersion must be at least this read preference’s min_wire_version, or the driver raises
ConfigurationError
.
- property tag_sets: Sequence[Mapping[str, Any]]#
Set
tag_sets
to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whosedc
tag has the value"ny"
. To specify a priority-order for tag sets, provide a list of tag sets:[{'dc': 'ny'}, {'dc': 'la'}, {}]
. A final, empty tag set,{}
, means “read from any member that matches the mode, ignoring tags.” MongoClient tries each set of tags in turn until it finds a set of tags with at least one matching member. For example, to only send a query to an analytic node:Nearest(tag_sets=[{"node":"analytics"}])
Or using
SecondaryPreferred
:SecondaryPreferred(tag_sets=[{"node":"analytics"}]) .. seealso:: `Data-Center Awareness <https://www.mongodb.com/docs/manual/data-center-awareness/>`_
- class pymongo.read_preferences.Nearest(tag_sets: Sequence[Mapping[str, Any]] | None = None, max_staleness: int = -1, hedge: Mapping[str, Any] | None = None)#
Nearest read preference.
When directly connected to one mongod queries are allowed to standalone servers, to a replica set primary, or to replica set secondaries.
When connected to a mongos queries are distributed among all members of a shard.
When connected to a replica set queries are distributed among all members.
- Parameters:
tag_sets: The
tag_sets
for this read preference.max_staleness: (integer, in seconds) The maximum estimated length of time a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations. Default -1, meaning no maximum. If it is set, it must be at least 90 seconds.
hedge: The
hedge
for this read preference.
Changed in version 3.11: Added
hedge
parameter.- property hedge: Mapping[str, Any] | None#
The read preference
hedge
parameter.A dictionary that configures how the server will perform hedged reads. It consists of the following keys:
enabled
: Enables or disables hedged reads in sharded clusters.
Hedged reads are automatically enabled in MongoDB 4.4+ when using a
nearest
read preference. To explicitly enable hedged reads, set theenabled
key totrue
:>>> Nearest(hedge={'enabled': True})
To explicitly disable hedged reads, set the
enabled
key toFalse
:>>> Nearest(hedge={'enabled': False})
New in version 3.11.
- property max_staleness: int#
The maximum estimated length of time (in seconds) a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations, or -1 for no maximum.
- property min_wire_version: int#
The wire protocol version the server must support.
Some read preferences impose version requirements on all servers (e.g. maxStalenessSeconds requires MongoDB 3.4 / maxWireVersion 5).
All servers’ maxWireVersion must be at least this read preference’s min_wire_version, or the driver raises
ConfigurationError
.
- property tag_sets: Sequence[Mapping[str, Any]]#
Set
tag_sets
to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whosedc
tag has the value"ny"
. To specify a priority-order for tag sets, provide a list of tag sets:[{'dc': 'ny'}, {'dc': 'la'}, {}]
. A final, empty tag set,{}
, means “read from any member that matches the mode, ignoring tags.” MongoClient tries each set of tags in turn until it finds a set of tags with at least one matching member. For example, to only send a query to an analytic node:Nearest(tag_sets=[{"node":"analytics"}])
Or using
SecondaryPreferred
:SecondaryPreferred(tag_sets=[{"node":"analytics"}]) .. seealso:: `Data-Center Awareness <https://www.mongodb.com/docs/manual/data-center-awareness/>`_
- class pymongo.read_preferences.ReadPreference#
An enum that defines some commonly used read preference modes.
Apps can also create a custom read preference, for example:
Nearest(tag_sets=[{"node":"analytics"}])
See High Availability and PyMongo for code examples.
A read preference is used in three cases:
MongoClient
connected to a single mongod:PRIMARY
: Queries are allowed if the server is standalone or a replica set primary.All other modes allow queries to standalone servers, to a replica set primary, or to replica set secondaries.
MongoClient
initialized with thereplicaSet
option:PRIMARY
: Read from the primary. This is the default, and provides the strongest consistency. If no primary is available, raiseAutoReconnect
.PRIMARY_PREFERRED
: Read from the primary if available, or if there is none, read from a secondary.SECONDARY
: Read from a secondary. If no secondary is available, raiseAutoReconnect
.SECONDARY_PREFERRED
: Read from a secondary if available, otherwise from the primary.NEAREST
: Read from any member.
MongoClient
connected to a mongos, with a sharded cluster of replica sets:PRIMARY
: Read from the primary of the shard, or raiseOperationFailure
if there is none. This is the default.PRIMARY_PREFERRED
: Read from the primary of the shard, or if there is none, read from a secondary of the shard.SECONDARY
: Read from a secondary of the shard, or raiseOperationFailure
if there is none.SECONDARY_PREFERRED
: Read from a secondary of the shard if available, otherwise from the shard primary.NEAREST
: Read from any shard member.
- PRIMARY = Primary()#
- PRIMARY_PREFERRED = PrimaryPreferred(tag_sets=None, max_staleness=-1, hedge=None)#
- SECONDARY = Secondary(tag_sets=None, max_staleness=-1, hedge=None)#
- SECONDARY_PREFERRED = SecondaryPreferred(tag_sets=None, max_staleness=-1, hedge=None)#
- NEAREST = Nearest(tag_sets=None, max_staleness=-1, hedge=None)#