Syntax

table.bulkPut(items, keys?, options?)

Parameters

When to use the keys argument

• If your primary key is inbound, you MUST NOT provide the keys argument.
• If primary key is non-inbound but auto-incremented, keys argument is optional.
• If primary key is non-inbound and non-auto-incremented, keys argument is compulsory.

var db = new Dexie('test');
db.version(1).stores({
  tableWithInboundKeys: 'id,x,y,z', // Don't provide "keys"
  tableWithAutoIncNonInbound: '++,x,y,x', // Optionally provide "keys"
  tableWithoutInboundKeys: ',x,y,z' // Always provide "keys"
});

Return Value

If options argument is omitted, or options is {allKeys: false}, the return value is a promise resolving with the resulting primary key of the object that was last in given array:

Promise<LastKey>

Since 3.0.0-rc.2: If options argument is provided in second or third argument with {allKeys: true}, the return value is a promise resulting with an array of resulting primary keys. The resulting array will have the same length as given array of objects to put. Every position in given items array will correspond to the same position in the resulting array.

Promise<Key[]>

Errors

If some operations fail, bulkPut() will ignore those failures and return a rejected Promise with a Dexie.BulkError referencing the failures. If the caller does not catch the error, the transaction will abort. If the caller wants to ignore the failures, the bulkPut() operations must be caught. NOTE: If you call bulkPut() outside a transaction scope and an error occur on one of the operations, the successful operations will still be persisted to DB! If this is not desired, surround your call to bulkPut() in a transaction and catch transaction’s promise instead of the bulkPut() operation.

Remarks

Add all given objects to the store.

If you have a large number of objects to add to the object store, bulkPut() is faster than doing put() in a loop. Mainly because it only has to get called back for the last onsuccess of all indexedDB requests.

Sample

var db = new Dexie('test');
db.version(1).stores({
  raindrops: 'id,position'
});
var drops = [];
for (var i = 0; i < 100000; ++i) {
  drops.push({
    id: i,
    position: [Math.random(), Math.random(), Math.random()]
  });
}
db.raindrops
  .bulkPut(drops)
  .then(() => {
    console.log('Done putting 100,000 raindrops all over the place');
  })
  .catch((e) => {
    if (e.name === 'BulkError') {
      // Explicitly catching the bulkPut() operation makes those successful
      // additions commit despite that there were errors.
      console.error(
        'Some raindrops did not succeed. However, ' +
          100000 -
          e.failures.length +
          ' raindrops was added successfully'
      );
    } else {
      throw e; // We're only handling BulkError here.
    }
  });

See Also

Table.bulkUpdate()

Table.bulkGet()

Table.bulkAdd()

Table.bulkDelete()

Table.put()