MongoCollection::batchInsert

(PECL mongo >=0.9.0)

MongoCollection::batchInsert — Вставляет несколько документов в коллекцию

Описание

public MongoCollection::batchInsert ( array $a [, array $options = array() ] ) : mixed

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

a

Массив массивов или объектов. Если какие-либо объекты используются, они могут не иметь защищенных или частных свойств.

Замечание:

Если документы для вставки не имеют ключа или свойства _id, будет создан новый экземпляр MongoId и назначен ему. Посмотрите MongoCollection::insert() для получения дополнительной информации об этом поведении.

options

Массив опций для пакета операций вставки. В настоящее время доступны следующие варианты:

  • "continueOnError"

    Булево, по умолчанию FALSE. Если установлено, база данных не будет останавливать обработку массовой вставки в случае сбоя (например, из-за дублирования идентификаторов). Это приведет к тому, что массовая вставка ведет себя аналогично серии одиночных вставок, за исключением того, что при вызове MongoDB::lastError() будет установлена ошибка в случае сбоя любой вставки, а не только последней. Если происходит несколько ошибок, MongoDB::lastError() сообщает о самых последних ошибках.

    Замечание:

    Обратите внимание, что continueOnError влияет на ошибки только на стороне базы данных. Если вы попытаетесь вставить документ с ошибками (например, он содержит ключ с пустым именем), то этот документ даже не будет перенесен в базу данных, так как драйвер обнаружит эту ошибку и выгрузится. continueOnError не влияет на ошибки, обнаруженные в документах драйвером.

  • "fsync"

    Булево, по умолчанию FALSE. Если включено журналирование, то работает также как и "j". Если журналирование не включено, то операции записи блокируются пока не будут синхронизированы с файлами на жестком диске. Если TRUE, то применяется подтвержденная вставка и эта опция переопределяет опцию "w" в значение 0.

    Замечание: Если журналирование включено, то пользователю настоятельно рекомендуется использовать опцию "j" вместо "fsync". Не используйте "fsync" и "j" одновременно,так как это может привести к ошибке.

  • "j"

    Булево, по умолчанию FALSE. Блокирует операции записи пока они не будут синхронизированы с журналом на диске. Если TRUE, то применяется подтвержденная вставка и эта опция переопределяет опцию "w" в значение 0.

    Замечание: Если применяется эта опция и журналирование отключено, то MongoDB 2.6+ выбросит ошибку и прервет запись; старые версии сервера просто игнорируют эту опцию.

  • "socketTimeoutMS"

    Эта опция определяет время в миллисекундах для общения в socket. Если сервер не ответил за отведенное время, то будет брошено исключение MongoCursorTimeoutException, и не будет никакой возможности определить произвел ли сервер запись или нет. Значение -1 используется для постоянно отключения этой функции. Значением по умолчанию для MongoClient является 30000 (30 секунд).

  • "w"

    Смотрите Контроль записи. Значение по умолчанию для MongoClient является 1.

  • "wTimeoutMS"

    Эта опция определяет лимит времени в миллисекундах для подтверждения контроля записи. Она применима только, если "w" больше 1, так как ограничение времени относится к репликации. Если контроль записи не подтвержден за отведенное время, то будет выброшено исключение MongoCursorException. Значение 0 для постоянного отключения. Значением по умолчанию для MongoClient является 10000 (десять секунд).

Следующие параметры устарели и больше не должны использоваться:

  • "safe"

    Устаревшая опция. Используйте опцию "w" контроля записи.

  • "timeout"

    Устаревший псевдоним для "socketTimeoutMS".

  • "wtimeout"

    Устаревший псевдоним для "wTimeoutMS".

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

Если параметр w установлен для подтверждения записи, возвращает ассоциативный массив со статусом вставок ("ok") и любой ошибкой, которая могла произойти ("err"). В противном случае возвращает TRUE, если пакетная вставка была успешно отправлена, иначе FALSE.

Ошибки

Выдает исключение MongoException, если какие-либо вставленные документы пусты или содержат ключи нулевой длины. Попытка вставить объект с защищенными и закрытыми свойствами приведет к ошибке ключа нулевой длины.

Исключение MongoCursorException бросается, если установлена опция "w" и не прошла запись.

Исключение MongoCursorTimeoutException бросается, если опция "w" установлена в значение больше одного и операция заняла больше, чем MongoCursor::$timeout миллисекунд. При этом операция на сервере не прерывается, так как это ограничение времени работает на клиентской стороне. Операция в миллисекундах в MongoCollection::$wtimeout.

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

Версия Описание
1.5.0

Добавлена опция "wTimeoutMS", которая заменяет "wtimeout". Выдает E_DEPRECATED, когда используется "wtimeout".

Добавлена опция "socketTimeoutMS", которая заменяет "timeout". Выдает E_DEPRECATED, когда используется "timeout".

Выдает E_DEPRECATED, когда используется "safe".

1.3.4 Добавлена опция "wtimeout".
1.3.0 Добавлена опция "w".
1.2.7 Добавлена опция "continueOnError".
1.0.9

Добавлена возможность передавать целые числа в опцию "safe", которая ранее принимала только логические значения.

Добавлена опция "fsync".

1.0.5 Добавлен параметр options.

Примеры

Пример #1 Пример использования MongoCollection::batchInsert()

Пакетная вставка - это быстрый способ добавить сразу несколько элементов в базу данных.

<?php

$users = array();
for ($i = 0; $i<100; $i++) {
  $users[] = array('username' => 'user'.$i, 'i' => $i);
}

$mongo = new MongoClient();
$collection = $mongo->my_db->users;
$collection->drop();

$collection->batchInsert($users);

foreach ($users as $user) {
  echo $user['_id']."\n"; // населенный экземпляром MongoId
}

$users = $collection->find()->sort(array('i' => 1));
foreach ($users as $user) {
    var_dump($user['username']);
}

?>

Результатом выполнения данного примера будет что-то подобное:

4bf43ac68ead0e1971000000
4bf43ac68ead0e1971010000
4bf43ac68ead0e1971020000
...
string(5) "user1"
string(5) "user2"
string(5) "user3"
...

Пример #2 Пример использования MongoCollection::batchInsert() с игнорированием ошибок

<?php

$con = new Mongo;
$db = $con->demo;

$doc1 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010001'),
        'id' => 1,
        'desc' => "ONE",
);
$doc2 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010002'),
        'id' => 2,
        'desc' => "TWO",
);
$doc3 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010002'), // тот же _id, что и выше
        'id' => 3,
        'desc' => "THREE",
);
$doc4 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010004'),
        'id' => 4,
        'desc' => "FOUR",
);

$c = $db->selectCollection('c');
$c->batchInsert(
    array($doc1, $doc2, $doc3, $doc4),
    array('continueOnError' => true)
);

$docs = $c->find();
foreach ($docs as $doc) {
    var_dump($doc['desc']);
}
?>

Результатом выполнения данного примера будет что-то подобное:

string(3) "ONE"
string(3) "TWO"
string(4) "FOUR"

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