# MongoCollection::batchInsert

(PECL mongo >=0.9.0)

MongoCollection::batchInsert — Inserts multiple documents into this collection

### Description

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

### Parameters

`a`

  An array of arrays or objects. If any objects are used, they may not have protected or private properties.

  > Note:

  > If the documents to insert do not have an `_id` key or property, a new MongoId instance will be created and assigned to it. See MongoCollection::insert() for additional information on this behavior.

`options`

  An array of options for the batch of insert operations. Currently available options include:

  - `"continueOnError"`

    Boolean, defaults to `FALSE`. If set, the database will not stop processing a bulk insert if one fails (eg due to duplicate IDs). This makes bulk insert behave similarly to a series of single inserts, except that calling MongoDB::lastError() will have an error set if any insert fails, not just the last one. If multiple errors occur, only the most recent will be reported by MongoDB::lastError().

    > Note:

    > Please note that `continueOnError` affects errors on the database side only. If you try to insert a document that has errors (for example it contains a key with an empty name), then the document is not even transferred to the database as the driver detects this error and bails out. `continueOnError` has no effect on errors detected in the documents by the driver.

  - `"fsync"`

    Boolean, defaults to `FALSE`. If journaling is enabled, it works exactly like `"j"`. If journaling is not enabled, the write operation blocks until it is synced to database files on disk. If `TRUE`, an acknowledged insert is implied and this option will override setting `"w"` to `0`.

    > Note: If journaling is enabled, users are strongly encouraged to use the `"j"` option instead of `"fsync"`. Do not use `"fsync"` and `"j"` simultaneously, as that will result in an error.

  - `"j"`

    Boolean, defaults to `FALSE`. Forces the write operation to block until it is synced to the journal on disk. If `TRUE`, an acknowledged write is implied and this option will override setting `"w"` to `0`.

    > Note: If this option is used and journaling is disabled, MongoDB 2.6+ will raise an error and the write will fail; older server versions will simply ignore the option.

  - `"socketTimeoutMS"`

    This option specifies the time limit, in milliseconds, for socket communication. If the server does not respond within the timeout period, a MongoCursorTimeoutException will be thrown and there will be no way to determine if the server actually handled the write or not. A value of `-1` may be specified to block indefinitely. The default value for MongoClient is `30000` (30 seconds).

  - `"w"`

    See Write Concerns. The default value for MongoClient is `1`.

  - `"wTimeoutMS"`

    This option specifies the time limit, in milliseconds, for write concern acknowledgement. It is only applicable when `"w"` is greater than `1`, as the timeout pertains to replication. If the write concern is not satisfied within the time limit, a MongoCursorException will be thrown. A value of `0` may be specified to block indefinitely. The default value for MongoClient is `10000` (ten seconds).

  The following options are deprecated and should no longer be used:

  - `"safe"`

    Deprecated. Please use the write concern `"w"` option.

  - `"timeout"`

    Deprecated alias for `"socketTimeoutMS"`.

  - `"wtimeout"`

    Deprecated alias for `"wTimeoutMS"`.

### Return Values

If the `w` parameter is set to acknowledge the write, returns an associative array with the status of the inserts ("ok") and any error that may have occurred ("err"). Otherwise, returns `TRUE` if the batch insert was successfully sent, `FALSE` otherwise.

### Errors/Exceptions

Throws MongoException if any inserted documents are empty or if they contains zero-length keys. Attempting to insert an object with protected and private properties will cause a zero-length key error.

Throws MongoCursorException if the `"w"` option is set and the write fails.

Throws MongoCursorTimeoutException if the `"w"` option is set to a value greater than one and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. The operation in MongoCollection::$wtimeout is milliseconds.

### Changelog

Version | Description
--- | ---
PECL mongo 1.5.0 | Added the `"wTimeoutMS"` option, which replaces `"wtimeout"`. Emits `E_DEPRECATED` when `"wtimeout"` is used. Added the `"socketTimeoutMS"` option, which replaces `"timeout"`. Emits `E_DEPRECATED` when `"timeout"` is used. Emits `E_DEPRECATED` when `"safe"` is used.
PECL mongo 1.3.4 | Added `"wtimeout"` option.
PECL mongo 1.3.0 | Added `"w"` option.
PECL mongo 1.2.7 | Added `"continueOnError"` option.
PECL mongo 1.0.9 | Added ability to pass integers to the `"safe"` option, which previously only accepted booleans. Added `"fsync"` option.
PECL mongo 1.0.5 | Added `options` parameter.

### Examples

Example #1 MongoCollection::batchInsert() example

Batch insertion is a quick way to add many elements to the database at once

`<?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"; // populated with instanceof MongoId
}
$users = $collection->find()->sort(array('i' => 1));
foreach ($users as $user) {
var_dump($user['username']);
}
?>`

The above example will output something similar to:

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

Example #2 MongoCollection::batchInsert() example with ignoring errors

`<?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'), // same _id as above
'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']);
}
?>`

The above example will output something similar to:

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

### See Also

- MongoCollection::insert() - Inserts a document into the collection
- MongoCollection::update() - Update records based on a given criteria
- MongoCollection::find() - Queries this collection, returning a MongoCursor for the result set
- MongoCollection::remove() - Remove records from this collection
- MongoDB core docs on » insert.