read_preferences – 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.

    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 a nearest read preference. To explicitly enable hedged reads, set the enabled key to true:

      To explicitly disable hedged reads, set the enabled key to False:

      1. >>> 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’s min_wire_version, or the driver raises ConfigurationError.

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

    Changed in version 3.11: Added hedge parameter.

    • hedge

      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 the enabled key to true:

      To explicitly disable hedged reads, set the key to False:

      1. >>> 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’s min_wire_version, or the driver raises .

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

    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 a nearest read preference. To explicitly enable hedged reads, set the enabled key to true:

      To explicitly disable hedged reads, set the enabled key to False:

      1. >>> 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’s min_wire_version, or the driver raises ConfigurationError.

    • mode

      The mode of this read preference instance.

    • mongos_mode

      The mongos mode of this read preference.

    • name

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

    Changed in version 3.11: Added 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 a nearest read preference. To explicitly enable hedged reads, set the enabled key to true:

      To explicitly disable hedged reads, set the enabled key to False:

      1. >>> 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’s min_wire_version, or the driver raises .

    • 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:

    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 the replicaSet option:

    • PRIMARY: Read from the primary. This is the default, and provides the strongest consistency. If no primary is available, raise .
    • 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.

    connected to a mongos, with a sharded cluster of replica sets:

    • PRIMARY: Read from the primary of the shard, or raise OperationFailure 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 raise 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)