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.

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

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

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

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

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

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

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

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

PECL mongo 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"

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