(mongodb >=1.0.0)
MongoDB\Driver\Manager::executeCommand — Выполняет команду базы данных
$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
Опция | Тип | Описание |
---|---|---|
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.
"session"
указана с соответствующей транзакцией в сочетании с опцией "readConcern"
или "writeConcern"
."session"
указана в сочетании с неподтверждённой гарантией записи.
Версия | Описание |
---|---|
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().