read_preferences – Utilities for choosing which member of a replica set to read from. — PyMongo 3.11.0 documentation (original) (raw)
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=None, max_staleness=-1, hedge=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.
| 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.
document¶
Read preference as a document.
hedge¶
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 anearest read preference. To explicitly enable hedged reads, set the enabled key to true:
Nearest(hedge={'enabled': True})
To explicitly disable hedged reads, set the enabled key toFalse:
Nearest(hedge={'enabled': False})
New in version 3.11.
max_staleness¶
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.
min_wire_version¶
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’smin_wire_version, or the driver raisesConfigurationError.
mode¶
The mode of this read preference instance.
mongos_mode¶
The mongos mode of this read preference.
name¶
The name of this read preference.
tag_sets¶
Set tag_sets to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whose dc 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.” MongoReplicaSetClient tries each set of tags in turn until it finds a set of tags with at least one matching member.
class pymongo.read_preferences. Secondary(tag_sets=None, max_staleness=-1, hedge=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.
document¶
Read preference as a document.
hedge¶
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 anearest read preference. To explicitly enable hedged reads, set the enabled key to true:
Nearest(hedge={'enabled': True})
To explicitly disable hedged reads, set the enabled key toFalse:
Nearest(hedge={'enabled': False})
New in version 3.11.
max_staleness¶
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.
min_wire_version¶
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’smin_wire_version, or the driver raisesConfigurationError.
mode¶
The mode of this read preference instance.
mongos_mode¶
The mongos mode of this read preference.
name¶
The name of this read preference.
tag_sets¶
Set tag_sets to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whose dc 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.” MongoReplicaSetClient tries each set of tags in turn until it finds a set of tags with at least one matching member.
class pymongo.read_preferences. SecondaryPreferred(tag_sets=None, max_staleness=-1, hedge=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.
| 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.
document¶
Read preference as a document.
hedge¶
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 anearest read preference. To explicitly enable hedged reads, set the enabled key to true:
Nearest(hedge={'enabled': True})
To explicitly disable hedged reads, set the enabled key toFalse:
Nearest(hedge={'enabled': False})
New in version 3.11.
max_staleness¶
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.
min_wire_version¶
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’smin_wire_version, or the driver raisesConfigurationError.
mode¶
The mode of this read preference instance.
mongos_mode¶
The mongos mode of this read preference.
name¶
The name of this read preference.
tag_sets¶
Set tag_sets to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whose dc 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.” MongoReplicaSetClient tries each set of tags in turn until it finds a set of tags with at least one matching member.
class pymongo.read_preferences. Nearest(tag_sets=None, max_staleness=-1, hedge=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.
document¶
Read preference as a document.
hedge¶
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 anearest read preference. To explicitly enable hedged reads, set the enabled key to true:
Nearest(hedge={'enabled': True})
To explicitly disable hedged reads, set the enabled key toFalse:
Nearest(hedge={'enabled': False})
New in version 3.11.
max_staleness¶
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.
min_wire_version¶
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’smin_wire_version, or the driver raisesConfigurationError.
mode¶
The mode of this read preference instance.
mongos_mode¶
The mongos mode of this read preference.
name¶
The name of this read preference.
tag_sets¶
Set tag_sets to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whose dc 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.” MongoReplicaSetClient tries each set of tags in turn until it finds a set of tags with at least one matching member.
class pymongo.read_preferences. ReadPreference¶
An enum that defines the read preference modes supported by PyMongo.
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, raise AutoReconnect.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)¶