# MongoDB::ReadPreference - phpMan

## NAME
    [MongoDB::ReadPreference] - Encapsulate and validate read preferences

## VERSION
    version v2.2.2

## SYNOPSIS
        use [MongoDB::ReadPreference];

        $rp = [MongoDB::ReadPreference]->new(); # mode: primary

        $rp = [MongoDB::ReadPreference]->new(
            mode     => 'primaryPreferred',
            tag_sets => [ { dc => 'useast' }, {} ],
        );

## DESCRIPTION
    A read preference indicates which servers should be used for read
    operations.

    For core documentation on read preference see
    <<http://docs.mongodb.org/manual/core/read-preference/>>.

## USAGE
    Read preferences work via two attributes: "mode" and "tag_sets". The
    "mode" parameter controls the types of servers that are candidates for a
    read operation as well as the logic for applying the "tag_sets"
    attribute to further restrict the list.

    The following terminology is used in describing read preferences:

    *   candidates – based on "mode", servers that could be suitable, based
        on "tag_sets" and other logic

    *   eligible – these are candidates that match "tag_sets"

    *   suitable – servers that meet all criteria for a read operation

  Read preference modes
   primary
    Only an available primary is suitable. "tag_sets" do not apply and must
    not be provided or an exception is thrown.

   secondary
    All secondaries (and only secondaries) are candidates, but only eligible
    candidates (i.e. after applying "tag_sets") are suitable.

   primaryPreferred
    Try to find a server using mode "primary" (with no "tag_sets"). If that
    fails, try to find one using mode "secondary" and the "tag_sets"
    attribute.

   secondaryPreferred
    Try to find a server using mode "secondary" and the "tag_sets"
    attribute. If that fails, try to find a server using mode "primary"
    (with no "tag_sets").

   nearest
    The primary and all secondaries are candidates, but only eligible
    candidates (i.e. after applying "tag_sets" to all candidates) are
    suitable.

    NOTE: in retrospect, the name "nearest" is misleading, as it implies a
    choice based on lowest absolute latency or geographic proximity, neither
    which are true.

    The "nearest" mode merely includes both primaries and secondaries
    without any preference between the two. All are filtered on "tag_sets".
    Because of filtering, servers might not be "closest" in any sense. And
    if multiple servers are suitable, one is randomly chosen based on the
    rules for server selection, which again might not be the closest in
    absolute latency terms.

  Tag set matching
    The "tag_sets" parameter is a list of tag sets (i.e. key/value pairs) to
    try in order. The first tag set in the list to match any candidate
    server is used as the filter for all candidate servers. Any subsequent
    tag sets are ignored.

    A read preference tag set ("T") matches a server tag set ("S") – or
    equivalently a server tag set ("S") matches a read preference tag set
    ("T") — if "T" is a subset of "S" (i.e. "T ⊆ S").

    For example, the read preference tag set "{ dc => 'ny', rack => 2 }"
    matches a secondary server with tag set "{ dc => 'ny', rack => 2, size
    => 'large' }".

    A tag set that is an empty document – "{}" – matches any server, because
    the empty tag set is a subset of any tag set.

## ATTRIBUTES
  mode
    The read preference mode determines which server types are candidates
    for a read operation. Valid values are:

    *   primary

    *   primaryPreferred

    *   secondary

    *   secondaryPreferred

    *   nearest

  tag_sets
    The "tag_sets" parameter is an ordered list of tag sets used to restrict
    the eligibility of servers, such as for data center awareness.

    The application of "tag_sets" varies depending on the "mode" parameter.
    If the "mode" is 'primary', then "tag_sets" must not be supplied.

  max_staleness_seconds
    The "max_staleness_seconds" parameter represents the maximum replication
    lag in seconds (wall clock time) that a secondary can suffer and still
    be eligible for reads. The default is -1, which disables staleness
    checks.

    If the "mode" is 'primary', then "max_staleness_seconds" must not be
    supplied.

## AUTHORS
    *   David Golden <<david@mongodb.com>>

    *   Rassi <<rassi@mongodb.com>>

    *   Mike Friedman <<friedo@friedo.com>>

    *   Kristina Chodorow <<k.chodorow@gmail.com>>

    *   Florian Ragwitz <<rafl@debian.org>>

## COPYRIGHT AND LICENSE
    This software is Copyright (c) 2020 by MongoDB, Inc.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004