(mongodb >=1.0.0)
MongoDB\Driver\Manager::executeCommand — Выполняет команду базы данных
$db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor
Метод выбирает сервер в соответствии с опцией readPreference
и выполняет команду на этом сервере.
Метод не применяет особую логику к команде. Значения
по умолчанию для опций readPreference,
readConcern и writeConcern
метод получит из активной транзакции (указывает
опция session). Для выбора сервера метод использует
основное предпочтение чтения, если активной транзакции нет.
Метод не получает значения по умолчанию из URI-идентификатора соединения. Поэтому пользователям рекомендуют использовать методы команд чтения и (или) записи, если это возможно.
db (string)Название базы данных, в которой запускается команда.
command (MongoDB\Driver\Command)Команда для выполнения.
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, если выполнился успешно.
"session" указана с соответствующей транзакцией в сочетании с опцией "readConcern" или "writeConcern"."session" указана в сочетании с неподтверждённой гарантией записи.
| Версия | Описание |
|---|---|
| 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().