Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MongoDB::ReadPreferencUser Contributed Perl DocumentMongoDB::ReadPreference(3)

NAME
       MongoDB::ReadPreference - Encapsulate and validate read preferences

VERSION
       version v1.8.0

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 a	based on "mode", servers that could be suitable, based
	   on "tag_sets" and other logic

       o   eligible aA these are candidates that match "tag_sets"

       o   suitable aA 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") a	or
       equivalently a server tag set ("S") matches a read preference tag set
       ("T") a if "T" is a subset of "S" (i.e. "T a 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 a "{}" a 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.

   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
       o   David Golden	<david@mongodb.com>

       o   Rassi <rassi@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) 2017 by MongoDB, Inc.

       This is free software, licensed under:

	 The Apache License, Version 2.0, January 2004

perl v5.24.1			  2017-04-10	    MongoDB::ReadPreference(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | USAGE | ATTRIBUTES | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MongoDB::ReadPreference&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help