Описание

final public MongoDB\Driver\ReadPreference::__construct(string $mode, ?array $tagSets = null, ?array $options = null)

Метод создаёт новый объект MongoDB\Driver\ReadPreference — неизменяемый объект значения.

Список параметров

mode

Режим предпочтения чтения

Значение Описание

"primary"
Операции считываются из текущего первичного узла набора реплик. Это предпочтение чтения по умолчанию для БД MongoDB.

"primaryPreferred"
В большей части случаев операции считываются из первичного узла, но если узел недоступен, операции считываются из вторичных узлов.

"secondary"
Операции считываются из вторичных узлов набора реплик.

"secondaryPreferred"
В большей части случаев операции считываются из вторичных членов, но если вторичные члены недоступны, операции считываются из первичного узла.

"nearest"
Операции считываются из члена набора реплик с наименьшей задержкой сети, независимо от типа члена.

tagSets

**Режим предпочтения чтения**
Значение	Описание
`"primary"`	Операции считываются из текущего первичного узла набора реплик. Это предпочтение чтения по умолчанию для БД MongoDB.
`"primaryPreferred"`	В большей части случаев операции считываются из первичного узла, но если узел недоступен, операции считываются из вторичных узлов.
`"secondary"`	Операции считываются из вторичных узлов набора реплик.
`"secondaryPreferred"`	В большей части случаев операции считываются из вторичных членов, но если вторичные члены недоступны, операции считываются из первичного узла.
`"nearest"`	Операции считываются из члена набора реплик с наименьшей задержкой сети, независимо от типа члена.

Наборы тегов разрешают нацеливать операции чтения на конкретных членов набора реплик. Аргумент формируют как массив ассоциативных массивов, каждый из которых содержит ноль или больше пар ключ-значение. Для операции чтения драйвер выбирает сервер, в конфигурации которого узел содержит каждый тег набора — ассоциативного массива пар ключей и значений. Драйвер выполнит попытку со следующими наборами, если не получилось выбрать узел. Пустой набор тегов array() совпадёт с любым узлом, его передают как запасной вариант.

Теги несовместимы с режимом "primary", и по ним сервер чаще выбирает только вторичного члена набора для операции чтения. Между тем, при сочетании режима "nearest" с набором тегов драйвер выбирает члена с наименьшей задержкой в сети. Тогда членом, которого выберет драйвер, окажется первичный или вторичный узел.

options

options

Опция Тип Описание

hedge object|array
Определяет, использовать ли » хеджированные считывания , которые БД MongoDB 4.4+ поддерживают для шардированных запросов.

Хеджированные считывания с сервера доступны для непервичных предпочтений чтения и включаются по умолчанию в режиме "nearest". Через эту опцию явно разрешают серверу считывание с хеджированием для непервичных предпочтений чтения путём установки аргумента ['enabled' => true] или явно запрещают серверу чтения с хеджированием для предпочтения чтения в режиме "nearest" путём установки аргумента ['enabled' => false].

maxStalenessSeconds int
Определяет максимальное отставание репликации (англ. staleness) для чтения из вторичных узлов. Когда по оценке клиента отставания репликации вторичных узлов превышает это значение, драйвер прекращает использовать отставание для операций чтения.

Максимальное значение отставания репликации указывают как 32-битное целое число со знаком, которое больше или равно значению константы MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS.

Значение по умолчанию для опции равно значению константы MongoDB\Driver\ReadPreference::NO_MAX_STALENESS. При таком значении драйвер не будет учитывать отставания репликаций вторичных узлов при выборе направления для операции чтения.

Опция несовместима с режимом "primary". Со значением максимального отставания репликации умеют работать только экземпляры MongoDB с БД MongoDB 3.4+ в развёртывании. Метод выбросит исключение во время выполнения, если версия сервера хотя бы одного экземпляра MongoDB в развёртывании старее.

**options**
Опция	Тип	Описание
hedge	object\|array	Определяет, использовать ли » хеджированные считывания , которые БД MongoDB 4.4+ поддерживают для шардированных запросов. Хеджированные считывания с сервера доступны для непервичных предпочтений чтения и включаются по умолчанию в режиме `"nearest"`. Через эту опцию явно разрешают серверу считывание с хеджированием для непервичных предпочтений чтения путём установки аргумента `['enabled' => true]` или явно запрещают серверу чтения с хеджированием для предпочтения чтения в режиме `"nearest"` путём установки аргумента `['enabled' => false]`.
maxStalenessSeconds	int	Определяет максимальное отставание репликации (англ. staleness) для чтения из вторичных узлов. Когда по оценке клиента отставания репликации вторичных узлов превышает это значение, драйвер прекращает использовать отставание для операций чтения. Максимальное значение отставания репликации указывают как 32-битное целое число со знаком, которое больше или равно значению константы `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. Значение по умолчанию для опции равно значению константы `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`. При таком значении драйвер не будет учитывать отставания репликаций вторичных узлов при выборе направления для операции чтения. Опция несовместима с режимом `"primary"`. Со значением максимального отставания репликации умеют работать только экземпляры MongoDB с БД MongoDB 3.4+ в развёртывании. Метод выбросит исключение во время выполнения, если версия сервера хотя бы одного экземпляра MongoDB в развёртывании старее.

Ошибки

При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException при недопустимом значении аргумента mode.
Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если аргумент tagSets передали для предпочтения чтения первичного узла или аргумент неправильно сформировали — передали не массив из нуля или больше документов.
Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опцию "maxStalenessSeconds" передали для предпочтения чтения первичного узла или указали значение за пределами диапазона.

Список изменений

Версия Описание

PECL-модуль mongodb 2.0.0 Передача значения с типом int в аргументе mode больше не поддерживается.

PECL-модуль mongodb 1.20.0 Передача целых чисел (int) в аргументе mode УСТАРЕЛА.

PECL-модуль mongodb 1.8.0 Добававили опцию "hedge".

PECL-модуль mongodb 1.3.0
Параметр mode теперь принимает строковое значение, которое соответствует URI-опции "readPreference" метода MongoDB\Driver\Manager::__construct().

PECL-модуль mongodb 1.2.0
Добавили в сигнатуру метода третий параметр — options, который поддерживает опцию "maxStalenessSeconds".

Версия	Описание
PECL-модуль mongodb 2.0.0	Передача значения с типом int в аргументе `mode` больше не поддерживается.
PECL-модуль mongodb 1.20.0	Передача целых чисел (int) в аргументе `mode` УСТАРЕЛА.
PECL-модуль mongodb 1.8.0	Добававили опцию `"hedge"`.
PECL-модуль mongodb 1.3.0	Параметр `mode` теперь принимает строковое значение, которое соответствует URI-опции `"readPreference"` метода MongoDB\Driver\Manager::__construct().
PECL-модуль mongodb 1.2.0	Добавили в сигнатуру метода третий параметр — `options`, который поддерживает опцию `"maxStalenessSeconds"`.

Примеры

Пример #1 Пример создания нового объекта ReadPreference методом MongoDB\Driver\ReadPreference::__construct()

<?php

/* Предпочитать вторичный узел, но в случае отказа отступить к первичному */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED));

/* Предпочитать узел в Нью-Йоркском центре обработки данных с минимальной задержкой */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST, [['dc' => 'ny']]));

/* Требуется дополнительный узел, задержка репликации которого в пределах двух минут от основного */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['maxStalenessSeconds' => 120]));

/* Явно разрешить серверу хеджированные считывания */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['hedge' => ['enabled' => true]]));

?>

Результат выполнения приведённого примера:

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)
  }
}

Смотрите также

» Руководство по предпочтению чтения