GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MONGODB::READPREFERENCE (3)

.ds Aq ’

NAME

MongoDB::ReadPreference - Encapsulate and validate read preferences

CONTENTS

VERSION

version v1.2.3

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:
o candidates X based on mode, servers that could be suitable, based on tag_sets and other logic
o eligible X these are candidates that match tag_sets
o suitable X 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 <B>onlyB> 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.

<B>NOTEB>: 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 <B>anyB> 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) X or equivalently a server tag set (S) matches a read preference tag set (T) X if T is a subset of S (i.e. T X 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 X {} X 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:
o primary
o primaryPreferred
o secondary
o secondaryPreferred
o 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.

AUTHORS

o David Golden <david@mongodb.com>
o Mike Friedman <friedo@friedo.com>
o Kristina Chodorow <k.chodorow@gmail.com>
o Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by MongoDB, Inc..

This is free software, licensed under:



  The Apache License, Version 2.0, January 2004



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MONGODB::READPREFERENCE (3) 2016-03-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.