docs/_includes/api/batch_create.html
{% include anchor.html edit="true" title="Create/update a batch of documents" hash="batch_create" %} {% highlight "js" %} db.bulkDocs(docs, [options], [callback]) {% endhighlight %} Create, update or delete multiple documents. The docs argument is an array of documents. If you omit an _id parameter on a given document, the database will create a new document and assign the ID for you. To update a document, you must include both an _id parameter and a _rev parameter, which should match the ID and revision of the document on which to base your updates. Finally, to delete a document, include a _deleted parameter with the value true. #### Example Usage: Put some new docs, providing the _ids: {% include code/start.html id="bulk_docs_1" type="callback" %} {% highlight "js" %} db.bulkDocs([{title : 'Lisa Says', _id: 'doc1'}, {title : 'Space Oddity', _id: 'doc2'}], function(err, response) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="bulk_docs_1" type="async" %} {% highlight "js" %} try { const result = await db.bulkDocs([{title : 'Lisa Says', _id: 'doc1'}, {title : 'Space Oddity', _id: 'doc2'}]); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="bulk_docs_1" type="promise" %} {% highlight "js" %} db.bulkDocs([{title : 'Lisa Says', _id: 'doc1'}, {title : 'Space Oddity', _id: 'doc2'}]).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} Post some new docs and auto-generate the _ids: {% include code/start.html id="bulk_docs_2" type="callback" %} {% highlight "js" %} db.bulkDocs([{title : 'Lisa Says'}, {title : 'Space Oddity'}], function(err, response) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="bulk_docs_2" type="async" %} {% highlight "js" %} try { const result = await db.bulkDocs([{title : 'Lisa Says'}, {title : 'Space Oddity'}]); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="bulk_docs_2" type="promise" %} {% highlight "js" %} db.bulkDocs([{title : 'Lisa Says'}, {title : 'Space Oddity'}]).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} #### Example Response: {% highlight "js" %} [{ "ok": true, "id": "doc1", "rev": "1-84abc2a942007bee7cf55007cba56198" }, { "ok": true, "id": "doc2", "rev": "1-7b80fc50b6af7a905f368670429a757e" }] {% endhighlight %} The response contains an array of the familiar ok/rev/id from the put()/post() API. If there are any errors, they will be provided individually like so: {% highlight "js" %} [{ status: 409, name: 'conflict', message: 'Document update conflict', error: true }] {% endhighlight %} The results are returned in the same order as the supplied "docs" array. Note that bulkDocs() is not transactional, and that you may get back a mixed array of errors/non-errors. In CouchDB/PouchDB, the smallest atomic unit is the document. #### Bulk update/delete: You can also use bulkDocs() to update/delete many documents at once: {% include code/start.html id="bulk_docs3" type="callback" %} {% highlight "js" %} db.bulkDocs([{ title : 'Lisa Says', artist : 'Velvet Underground', _id : "doc1", _rev : "1-84abc2a942007bee7cf55007cba56198" }, { title : 'Space Oddity', artist : 'David Bowie', _id : "doc2", _rev : "1-7b80fc50b6af7a905f368670429a757e" }], function(err, response) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="bulk_docs3" type="async" %} {% highlight "js" %} try { const result = await db.bulkDocs([{ title : 'Lisa Says', artist : 'Velvet Underground', _id : "doc1", _rev : "1-84abc2a942007bee7cf55007cba56198" }, { title : 'Space Oddity', artist : 'David Bowie', _id : "doc2", _rev : "1-7b80fc50b6af7a905f368670429a757e" }]); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="bulk_docs3" type="promise" %} {% highlight "js" %} db.bulkDocs([{ title : 'Lisa Says', artist : 'Velvet Underground', _id : "doc1", _rev : "1-84abc2a942007bee7cf55007cba56198" }, { title : 'Space Oddity', artist : 'David Bowie', _id : "doc2", _rev : "1-7b80fc50b6af7a905f368670429a757e" }]).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} Or delete them: {% include code/start.html id="bulk_docs_4" type="callback" %} {% highlight "js" %} db.bulkDocs([{ title : 'Lisa Says', _deleted : true, _id : "doc1", _rev : "1-84abc2a942007bee7cf55007cba56198" }, { title : 'Space Oddity', _deleted : true, _id : "doc2", _rev : "1-7b80fc50b6af7a905f368670429a757e" }], function(err, response) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="bulk_docs_4" type="async" %} {% highlight "js" %} try { const result = await db.bulkDocs([{ title : 'Lisa Says', _deleted : true, _id : "doc1", _rev : "1-84abc2a942007bee7cf55007cba56198" }, { title : 'Space Oddity', _deleted : true, _id : "doc2", _rev : "1-7b80fc50b6af7a905f368670429a757e" }]); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="bulk_docs_4" type="promise" %} {% highlight "js" %} db.bulkDocs([{ title : 'Lisa Says', _deleted : true, _id : "doc1", _rev : "1-84abc2a942007bee7cf55007cba56198" }, { title : 'Space Oddity', _deleted : true, _id : "doc2", _rev : "1-7b80fc50b6af7a905f368670429a757e" }]).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} **Note:** If you set a new_edits property on the options object to false, you can post existing documents from other databases without having new revision IDs assigned to them. Normally, only the replication algorithm needs to do this.