Выполняет операции записи

# MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Выполняет операции записи

### Описание

final public function MongoDB\Driver\Manager::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

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

Объект класса MongoDB\Driver\BulkWrite создают с одной или несколькими операциями записи: обновления, удаления или вставки. Драйвер попытается отправить операции одного и того же типа на сервер с минимальным количества запросов, чтобы сократить обращения к серверу.

Значение по умолчанию для опции `"writeConcern"` автоматически определяется на основе активной транзакции или URI-идентификатора соединения, если транзакция не содержит значения. На активную транзакцию указывает опция `"session"`.

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

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`bulk` (MongoDB\Driver\BulkWrite)
  Записи для выполнения.
`опции`

  options
  Опция | Тип | Описание
  --- | --- | ---
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

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

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

### Ошибки

- При отсутствии какой-либо операции записи в параметр `bulk`, метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Если параметр `bulk` уже выполнился, метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException. Объекты MongoDB\Driver\BulkWrite нельзя выполнить несколько раз.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При ошибке записи метод выбрасывает исключение MongoDB\Driver\Exception\BulkWriteException.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При возникновении других ошибок, метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

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

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Параметр `options` больше не принимает объекты MongoDB\Driver\WriteConcern.
PECL-модуль mongodb 1.21.0 | Передача объекта MongoDB\Driver\WriteConcern как опции параметра `options` устарела, а с версии 2.0 передачу объекта запретят.
PECL-модуль mongodb 1.4.4 | Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опцию `"session"` указать вместе с неподтверждаемым уровнем записи.
PECL-модуль mongodb 1.4.0 | Третий параметр `options` стал массивом опций, но в целях обратной совместимости пока ещё принимает объект MongoDB\Driver\WriteConcern.
PECL-модуль mongodb 1.3.0 | Метод теперь выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если параметр `bulk` не содержит операций записи. Раньше выбрасывалось исключение MongoDB\Driver\Exception\BulkWriteException.

### Примеры

Пример #1 Пример записи методом MongoDB\Driver\Manager::executeBulkWrite()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite();

    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);

    $bulk->update(['x' => 2], ['$set' => ['x' => 1]], ['multi' => false, 'upsert' => false]);
    $bulk->update(['x' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);
    $bulk->update(['_id' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);

    $bulk->insert(['_id' => 4, 'x' => 2]);

    $bulk->delete(['x' => 1], ['limit' => 1]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 100);
    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    printf("Количество вставленных документов: %d\n", $result->getInsertedCount());
    printf("Количество документов для обновления: %d\n", $result->getMatchedCount());
    printf("Количество обновлённых документов: %d\n", $result->getModifiedCount());
    printf("Количество операций upsert: %d\n", $result->getUpsertedCount());
    printf("Количество удалённых документов: %d\n", $result->getDeletedCount());

    foreach ($result->getUpsertedIds() as $index => $id) {
        printf('upsertedId[%d]: ', $index);
        var_dump($id);
    }

    /* При невозможности выполнить требование WriteConcern */
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf(
            "%s (%d): %s\n",
            $writeConcernError->getMessage(),
            $writeConcernError->getCode(),
            var_export($writeConcernError->getInfo(), true)
        );
    }

    /* При невозможности записи */
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Операция#%d: %s (%d)\n", $writeError->getIndex(), $writeError->getMessage(), $writeError->getCode());
    }

    ?>

Вывод приведённого примера будет похож на:

    Количество вставленных документов: 3
    Количество документов для обновления: 1
    Количество обновлённых документов: 1
    Количество операций upsert: 2
    Количество удалённых документов: 1
    upsertedId[3]: object(MongoDB\BSON\ObjectId)#5 (1) {
      ["oid"]=>
      string(24) "54d3adc3ce7a792f4d703756"
    }
    upsertedId[4]: int(3)

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

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWrite() - Выполняет операции записи на сервере

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open