MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference

Description

final public MongoDB\Driver\ReadPreference::__construct ( string|int $mode [, array $tagSets = NULL [, array $options = array() ]] )

Constructs a new MongoDB\Driver\ReadPreference, which is an immutable value object.

Parameters

mode

{| |+ Read preference mode ! Value ! Description |- | MongoDB\Driver\ReadPreference::RP_PRIMARY or "primary" |

All operations read from the current replica set primary. This is the default read preference for MongoDB.

|- | MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED or "primaryPreferred"

|

In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.

|- | MongoDB\Driver\ReadPreference::RP_SECONDARY or "secondary"

|

All operations read from the secondary members of the replica set.

|- | MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED or "secondaryPreferred"

|

In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.

|- | MongoDB\Driver\ReadPreference::RP_NEAREST or "nearest"

|

Operations read from member of the replica set with the least network latency, irrespective of the member's type.

|}

tagSets

Tag sets allow you to target read operations to specific members of a replica set. This parameter should be an array of associative arrays, each of which contain zero or more key/value pairs. When selecting a server for a read operation, the driver attempt to select a node having all tags in a set (i.e. the associative array of key/value pairs). If selection fails, the driver will attempt subsequent sets. An empty tag set (array()) will match any node and may be used as a fallback.

Tags are not compatible with the MongoDB\Driver\ReadPreference::RP_PRIMARY mode and, in general, only apply when selecting a secondary member of a set for a read operation. However, the MongoDB\Driver\ReadPreference::RP_NEAREST mode, when combined with a tag set, selects the matching member with the lowest network latency. This member may be a primary or secondary.

options

{| |+ options !width="33%"| Option !width="33%"| Type !width="33%"| Description |- | hedge | object|array |

Specifies whether to use » hedged reads, which are supported by MongoDB 4.4+ for sharded queries.

Server hedged reads are available for all non-primary read preferences and are enabled by default when using the "nearest" mode. This option allows explicitly enabling server hedged reads for non-primary read preferences by specifying ['enabled' => true], or explicitly disabling server hedged reads for the "nearest" read preference by specifying ['enabled' => false].

|- | maxStalenessSeconds | int |

Specifies a maximum replication lag, or "staleness", for reads from secondaries. When a secondary's estimated staleness exceeds this value, the driver stops using it for read operations.

If specified, the max staleness must be a signed 32-bit integer greater than or equal to MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS.

Defaults to MongoDB\Driver\ReadPreference::NO_MAX_STALENESS, which means that the driver will not consider a secondary's lag when choosing where to direct a read operation.

This option is not compatible with the MongoDB\Driver\ReadPreference::RP_PRIMARY mode. Specifying a max staleness also requires all MongoDB instances in the deployment to be using MongoDB 3.4+. An exception will be thrown at execution time if any MongoDB instances in the deployment are of an older server version.

|}

Errors/Exceptions

Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
Throws MongoDB\Driver\Exception\InvalidArgumentException if mode is invalid.
Throws MongoDB\Driver\Exception\InvalidArgumentException if tagSets is provided for a primary read preference or is malformed (i.e. not an array of zero or more documents).
Throws MongoDB\Driver\Exception\InvalidArgumentException if the "maxStalenessSeconds" option is provided for a primary read preference or is out of range.

Changelog

Version	Description
PECL mongodb 1.8.0	Added the `"hedge"` option.
PECL mongodb 1.3.0	The `mode` argument now accepts a string value, which is consistent with the `"readPreference"` URI option for MongoDB\Driver\Manager::__construct().
PECL mongodb 1.2.0	Added a third `options` argument, which supports the `"maxStalenessSeconds"` option.

Examples

Example #1 MongoDB\Driver\ReadPreference::__construct() example

<?php/* Prefer a secondary node but fall back to a primary. */var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED));/* Prefer a node in the New York data center with lowest latency. */var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_NEAREST, [[../'dc' => 'ny']]));/* Require a secondary node whose replication lag is within two minutes of the primary */var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['maxStalenessSeconds' => 120]));/* Explicitly enable server hedged reads */var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['hedge' => ['enabled' => true]]));?>

The above example will output:

object(MongoDB\Driver\ReadPreference)#1 (1) {
  ["mode"]=>
  string(18) "secondaryPreferred"
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(7) "nearest"
  ["tags"]=>
  array(1) {
    [0]=>
    object(stdClass)#2 (1) {
      ["dc"]=>
      string(2) "ny"
    }
  }
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["maxStalenessSeconds"]=>
  int(120)
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["hedge"]=>
  object(stdClass)#1 (1) {
    ["enabled"]=>
    bool(true)
  }
}

Php/docs/mongodb-driver-readpreference.construct

Contents