PHP 8.4.0 RC4 available for testing

MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommandВыполняет команду базы данных

Описание

final public MongoDB\Driver\Manager::executeCommand(string $db, MongoDB\Driver\Command $command, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor

Метод выбирает сервер в соответствии с опцией readPreference и выполняет команду на этом сервере.

Этот метод не применяет особую логику к команде. Значения по умолчанию для опций readPreference, readConcern и writeConcern метод получит из активной транзакции (указывает опция session). Если активной транзакции нет, для выбора сервера метод использует основное предпочтение чтения.

Значения по умолчанию не будут получены из URI-идентификатора соединения. Поэтому пользователям рекомендуется использовать методы команд чтения и (или) записи, если это возможно.

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

db (string)

Имя базы данных, в которой запускается команда.

command (MongoDB\Driver\Command)

Команда для выполнения.

options

options
Опция Тип Описание
readConcern MongoDB\Driver\ReadConcern

Гарантия чтения для применения к операции.

Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.

readPreference MongoDB\Driver\ReadPreference

Предпочтение чтения, используемая для выбора сервера для выполнения операции.

session MongoDB\Driver\Session

Сессия для связывания с операцией.

writeConcern MongoDB\Driver\WriteConcern

Гарантия записи для применения к операции.

Внимание

При использовании "session" и наличии незавершённых транзакций, вы не можете указать "readConcern" or "writeConcern" option. Это приведёт к выбрасыванию исключения MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого вы должны установить эти две опции при создании транзакции с помощью MongoDB\Driver\Session::startTransaction().

Возвращаемые значения

В случае успешного выполнения метод возвращает курсор MongoDB\Driver\Cursor.

Ошибки

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

Версия Описание
PECL mongodb 1.4.4 Если опция session используется в сочетании с неподтверждённой гарантией записи, выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException.
PECL mongodb 1.4.0 Третий параметр теперь представляет собой массив options. Для обратной совместимости этот параметр всё равно принимает объект MongoDB\Driver\ReadPreference.

Примеры

Пример #1 Пример использования метода MongoDB\Driver\Manager::executeCommand() с командой, которая возвращает одиночный документ

<?php

$manager
= new MongoDB\Driver\Manager('mongodb://localhost:27017');
$command = new MongoDB\Driver\Command(['ping' => 1]);

try {
$cursor = $manager->executeCommand('admin', $command);
} catch(
MongoDB\Driver\Exception $e) {
echo
$e->getMessage(), "\n";
exit;
}

/* Команда ping возвращает одиночный результат, поэтому мы должны получить доступ к
* первому результату в курсор. */
$response = $cursor->toArray()[0];

var_dump($response);

?>

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

array(1) {
  ["ok"]=>
  float(1)
}

Пример #2 Пример использования MongoDB\Driver\Manager::executeCommand() с командой, возвращающей курсор

<?php

$manager
= new MongoDB\Driver\Manager("mongodb://localhost:27017");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1, 'y' => 'foo']);
$bulk->insert(['x' => 2, 'y' => 'bar']);
$bulk->insert(['x' => 3, 'y' => 'bar']);
$manager->executeBulkWrite('db.collection', $bulk);

$command = new MongoDB\Driver\Command([
'aggregate' => 'collection',
'pipeline' => [
[
'$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
],
'cursor' => new stdClass,
]);
$cursor = $manager->executeCommand('db', $command);

/* Команда aggragete опционально может вернуть результаты в курсоре вместо
* одиночного документа. В таком случае мы можем перебирать на курсоре для
* непосредственного доступа к результатам. */
foreach ($cursor as $document) {
var_dump($document);
}

?>

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

object(stdClass)#6 (2) {
  ["_id"]=>
  string(3) "bar"
  ["sum"]=>
  int(10)
}
object(stdClass)#7 (2) {
  ["_id"]=>
  string(3) "foo"
  ["sum"]=>
  int(2)
}

Пример #3 Ограничение времени выполнения запроса

Опция "maxTimeMS" класса MongoDB\Driver\Query может использоваться для ограничения времени выполнения запроса. Обратите внимание, что этот срок применяется на стороне сервера и не учитывает задержки сети. Смотрите » Завершение выполнения операций в руководстве MongoDB для получения дополнительной информации.

<?php

$manager
= new MongoDB\Driver\Manager('mongodb://localhost:27017');

$command = new MongoDB\Driver\Command([
'count' => 'collection',
'query' => ['x' => ['$gt' => 1]],
'maxTimeMS' => 1000,
]);

$cursor = $manager->executeCommand('db', $command);

var_dump($cursor->toArray()[0]);

?>

Если запрос не завершится через секунду после начала выполнения на сервере, будет выброшено исключение MongoDB\Driver\Exception\ExecutionTimeoutException.

Примечания

Замечание: Если будет использован вторичный сервер из опции readPreference, то вызывающий код берёт на себя ответственность за гарантию выполнения команды command на вторичном узле. Драйвер не выполняет проверку.

Замечание: Этот метод — не метод по умолчанию, чтобы получить предпочтения чтения из URI-адреса подключения MongoDB. Приложения, которым нужно это поведение, могут вызывать метод MongoDB\Driver\Manager::executeReadCommand().

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

Добавить

Примечания пользователей

Пользователи ещё не добавляли примечания для страницы
To Top