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 serveris 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 ofthe 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.readpreferences.PrimaryPreferred(_tag_sets=None, max_staleness=-1)

• PrimaryPreferred read preference.

  • When directly connected to one mongod queries are allowed to standaloneservers, to a replica set primary, or to replica set secondaries.
  • When connected to a mongos queries are sent to the primary of a shard ifavailable, otherwise a shard secondary.
  • When connected to a replica set queries are sent to the primary ifavailable, otherwise a secondary.

Parameters:

• tag_sets: The tag_sets to use if the primary is notavailable.
• max_staleness: (integer, in seconds) The maximum estimatedlength of time a replica set secondary can fall behind the primary inreplication before it will no longer be selected for operations.Default -1, meaning no maximum. If it is set, it must be at least90 seconds.

• document

• Read preference as a document.

• max_staleness

• The maximum estimated length of time (in seconds) a replica setsecondary can fall behind the primary in replication before it willno 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’}] toread only from members whose dc tag has the value "ny".To specify a priority-order for tag sets, provide a list oftag sets: [{'dc': 'ny'}, {'dc': 'la'}, {}]. A final, empty tagset, {}, means “read from any member that matches the mode,ignoring tags.” MongoReplicaSetClient tries each set of tags in turnuntil it finds a set of tags with at least one matching member.

See also

Data-Center Awareness

• class pymongo.readpreferences.Secondary(_tag_sets=None, max_staleness=-1)

• Secondary read preference.

  • When directly connected to one mongod queries are allowed to standaloneservers, to a replica set primary, or to replica set secondaries.
  • When connected to a mongos queries are distributed among shardsecondaries. An error is raised if no secondaries are available.
  • When connected to a replica set queries are distributed amongsecondaries. 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 estimatedlength of time a replica set secondary can fall behind the primary inreplication before it will no longer be selected for operations.Default -1, meaning no maximum. If it is set, it must be at least90 seconds.

• document

• Read preference as a document.

• max_staleness

• The maximum estimated length of time (in seconds) a replica setsecondary can fall behind the primary in replication before it willno 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’}] toread only from members whose dc tag has the value "ny".To specify a priority-order for tag sets, provide a list oftag sets: [{'dc': 'ny'}, {'dc': 'la'}, {}]. A final, empty tagset, {}, means “read from any member that matches the mode,ignoring tags.” MongoReplicaSetClient tries each set of tags in turnuntil it finds a set of tags with at least one matching member.

See also

Data-Center Awareness

• class pymongo.readpreferences.SecondaryPreferred(_tag_sets=None, max_staleness=-1)

• SecondaryPreferred read preference.

  • When directly connected to one mongod queries are allowed to standaloneservers, to a replica set primary, or to replica set secondaries.
  • When connected to a mongos queries are distributed among shardsecondaries, or the shard primary if no secondary is available.
  • When connected to a replica set queries are distributed amongsecondaries, 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 estimatedlength of time a replica set secondary can fall behind the primary inreplication before it will no longer be selected for operations.Default -1, meaning no maximum. If it is set, it must be at least90 seconds.

• document

• Read preference as a document.

• max_staleness

• The maximum estimated length of time (in seconds) a replica setsecondary can fall behind the primary in replication before it willno 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’}] toread only from members whose dc tag has the value "ny".To specify a priority-order for tag sets, provide a list oftag sets: [{'dc': 'ny'}, {'dc': 'la'}, {}]. A final, empty tagset, {}, means “read from any member that matches the mode,ignoring tags.” MongoReplicaSetClient tries each set of tags in turnuntil it finds a set of tags with at least one matching member.

See also

Data-Center Awareness

• class pymongo.readpreferences.Nearest(_tag_sets=None, max_staleness=-1)

• Nearest read preference.

  • When directly connected to one mongod queries are allowed to standaloneservers, to a replica set primary, or to replica set secondaries.
  • When connected to a mongos queries are distributed among all members ofa shard.
  • When connected to a replica set queries are distributed among allmembers.

Parameters:

• tag_sets: The tag_sets for this read preference.
• max_staleness: (integer, in seconds) The maximum estimatedlength of time a replica set secondary can fall behind the primary inreplication before it will no longer be selected for operations.Default -1, meaning no maximum. If it is set, it must be at least90 seconds.

• document

• Read preference as a document.

• max_staleness

• The maximum estimated length of time (in seconds) a replica setsecondary can fall behind the primary in replication before it willno 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’}] toread only from members whose dc tag has the value "ny".To specify a priority-order for tag sets, provide a list oftag sets: [{'dc': 'ny'}, {'dc': 'la'}, {}]. A final, empty tagset, {}, means “read from any member that matches the mode,ignoring tags.” MongoReplicaSetClient tries each set of tags in turnuntil it finds a set of tags with at least one matching member.

See also

Data-Center Awareness

• 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 replicaset primary.

• All other modes allow queries to standalone servers, to a replica setprimary, or to replica set secondaries.MongoClient initialized with thereplicaSet option:

• PRIMARY: Read from the primary. This is the default, and provides thestrongest consistency. If no primary is available, raiseAutoReconnect.

• PRIMARY_PREFERRED: Read from the primary if available, or if there isnone, read from a secondary.
• SECONDARY: Read from a secondary. If no secondary is available,raise AutoReconnect.
• SECONDARY_PREFERRED: Read from a secondary if available, otherwisefrom the primary.

• NEAREST: Read from any member.MongoClient connected to a mongos, with asharded 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 isnone, 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()
• PRIMARYPREFERRED = PrimaryPreferred(tagsets=None, max_staleness=-1)
• SECONDARY = Secondary(tag_sets=None, max_staleness=-1)
• SECONDARYPREFERRED = SecondaryPreferred(tagsets=None, max_staleness=-1)
• NEAREST = Nearest(tag_sets=None, max_staleness=-1)