array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'ru', ), 'this' => array ( 0 => 'mongodb-driver-manager.executecommand.php', 1 => 'MongoDB\\Driver\\Manager::executeCommand', 2 => 'Выполняет команду базы данных', ), 'up' => array ( 0 => 'class.mongodb-driver-manager.php', 1 => 'MongoDB\\Driver\\Manager', ), 'prev' => array ( 0 => 'mongodb-driver-manager.executebulkwritecommand.php', 1 => 'MongoDB\\Driver\\Manager::executeBulkWriteCommand', ), 'next' => array ( 0 => 'mongodb-driver-manager.executequery.php', 1 => 'MongoDB\\Driver\\Manager::executeQuery', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'ru', 'path' => 'reference/mongodb/mongodb/driver/manager/executecommand.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

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 $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" или "writeConcern". Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

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

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

Ошибки

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

Версия Описание
PECL-модуль mongodb 2.0.0 Параметр options больше не принимает объекты MongoDB\Driver\ReadPreference.
PECL-модуль mongodb 1.21.0 Передача объекта MongoDB\Driver\ReadPreference как опции параметра options устарела, а с версии 2.0 передачу объекта запретят.
PECL-модуль mongodb 1.4.4 Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опцию "session" указать вместе с неподтверждаемым уровнем записи.
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, если запрос не завершится через секунду после начала выполнения на сервере.

Примечания

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

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

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