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 = array() ] ) : MongoDB\Driver\Cursor

Выбирает сервер в соответствии с опцией "readPreference" и выполняет запрос на этом сервере. По умолчанию будет использоваться предпочтение чтения из URI URI подключения MongoDB.

Этот метод не применяет особую логику к команде. Хотя этот метод принимает "readConcern" и "writeConcern", которые будут включены в документы коанды, эти опции не будут соответствовать значениям по умолчанию из MongoDB URI соединения , и не будет учитываться версия сервера MongoDB. Поэтому пользователям рекомендуется использовать конкретные методы команды чтения и/или записи если это возможно.

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

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.

Ошибки

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

Версия Описание
1.4.4 Если опция "session" используется в сочетании с неподтвержденной гарантией записи, выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException.
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 может быть выполнен на вторичном узле. Проверка не выполняется драйвером.

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