# `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.

See also

This module is compatible with both the synchronous and asynchronous PyMongo APIs.

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.

  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 (Optional[_TagSets]) – The `tag_sets` to use if the primary is not available.

    - max_staleness (int) – (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 (Optional[_Hedge]) – DEPRECATED - The `hedge` for this read preference.

  Changed in version 3.11: Added `hedge` parameter.

  property document: dict[str, Any]

    Read preference as a document.

  property hedge: Mapping[str, Any] | None

    DEPRECATED - The read preference ‘hedge’ option is deprecated in PyMongo 4.12+ because hedged reads are deprecated in MongoDB version 8.0+. Support for ‘hedge’ will be removed in PyMongo 5.0.

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

        >>> Nearest(hedge={'enabled': True})

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

        >>> Nearest(hedge={'enabled': False})

    Added 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 mode: int

    The mode of this read preference instance.

  property mongos_mode: str

    The mongos mode of this read preference.

  property name: str

    The name of this read preference.

  property tag_sets: Sequence[Mapping[str, Any]]

    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.” 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=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 (Optional[_TagSets]) – The `tag_sets` for this read preference.

    - max_staleness (int) – (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 (Optional[_Hedge]) – DEPRECATED - The `hedge` for this read preference.

  Changed in version 3.11: Added `hedge` parameter.

  property document: dict[str, Any]

    Read preference as a document.

  property hedge: Mapping[str, Any] | None

    DEPRECATED - The read preference ‘hedge’ option is deprecated in PyMongo 4.12+ because hedged reads are deprecated in MongoDB version 8.0+. Support for ‘hedge’ will be removed in PyMongo 5.0.

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

        >>> Nearest(hedge={'enabled': True})

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

        >>> Nearest(hedge={'enabled': False})

    Added 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 mode: int

    The mode of this read preference instance.

  property mongos_mode: str

    The mongos mode of this read preference.

  property name: str

    The name of this read preference.

  property tag_sets: Sequence[Mapping[str, Any]]

    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.” 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=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.

  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 (Optional[_TagSets]) – The `tag_sets` for this read preference.

    - max_staleness (int) – (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 (Optional[_Hedge]) – DEPRECATED - The `hedge` for this read preference.

  Changed in version 3.11: Added `hedge` parameter.

  property document: dict[str, Any]

    Read preference as a document.

  property hedge: Mapping[str, Any] | None

    DEPRECATED - The read preference ‘hedge’ option is deprecated in PyMongo 4.12+ because hedged reads are deprecated in MongoDB version 8.0+. Support for ‘hedge’ will be removed in PyMongo 5.0.

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

        >>> Nearest(hedge={'enabled': True})

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

        >>> Nearest(hedge={'enabled': False})

    Added 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 mode: int

    The mode of this read preference instance.

  property mongos_mode: str

    The mongos mode of this read preference.

  property name: str

    The name of this read preference.

  property tag_sets: Sequence[Mapping[str, Any]]

    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.” 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=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 (Optional[_TagSets]) – The `tag_sets` for this read preference.

    - max_staleness (int) – (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 (Optional[_Hedge]) – DEPRECATED - The `hedge` for this read preference.

  Changed in version 3.11: Added `hedge` parameter.

  property document: dict[str, Any]

    Read preference as a document.

  property hedge: Mapping[str, Any] | None

    DEPRECATED - The read preference ‘hedge’ option is deprecated in PyMongo 4.12+ because hedged reads are deprecated in MongoDB version 8.0+. Support for ‘hedge’ will be removed in PyMongo 5.0.

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

        >>> Nearest(hedge={'enabled': True})

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

        >>> Nearest(hedge={'enabled': False})

    Added 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 mode: int

    The mode of this read preference instance.

  property mongos_mode: str

    The mongos mode of this read preference.

  property name: str

    The name of this read preference.

  property tag_sets: Sequence[Mapping[str, Any]]

    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.” 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 Read and Write Settings 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 the `replicaSet` option:

  - `PRIMARY`: Read from the primary. This is the default, and provides the strongest consistency. If no primary is available, raise `AutoReconnect`.

  - `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 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 `OperationFailure` 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()
    Parameters:

      selection (Selection)

    Return type:

      Selection

  PRIMARY_PREFERRED = PrimaryPreferred(tag_sets=None, max_staleness=-1, hedge=None)
    Parameters:

      selection (Selection)

    Return type:

      Selection

  SECONDARY = Secondary(tag_sets=None, max_staleness=-1, hedge=None)
    Parameters:

      selection (Selection)

    Return type:

      Selection

  SECONDARY_PREFERRED = SecondaryPreferred(tag_sets=None, max_staleness=-1, hedge=None)
    Parameters:

      selection (Selection)

    Return type:

      Selection

  NEAREST = Nearest(tag_sets=None, max_staleness=-1, hedge=None)
    Parameters:

      selection (Selection)

    Return type:

      Selection