docs/_includes/api/create_document.html
{% include anchor.html edit="true" title="Create/update a document" hash="create_document" %} ### Using db.put() {% highlight "js" %} db.put(doc, [options], [callback]) {% endhighlight %} Create a new document or update an existing document. If the document already exists, you must specify its revision _rev, otherwise a conflict will occur. If you want to update an existing document even if there's conflict, you should specify the base revision _rev and use force=true option, then a new conflict revision will be created. doc must be a "pure JSON object", i.e. a collection of name/value pairs. If you try to store non-JSON data (for instance Date objects) you may see [inconsistent results]({{ site.baseurl }}/errors.html#could_not_be_cloned). #### Example Usage: Create a new doc with an _id of 'mydoc': {% include code/start.html id="newDoc" type="callback" %} {% highlight "js" %} db.put({ _id: 'mydoc', title: 'Heroes' }, function(err, response) { if (err) { return console.log(err); } // handle response }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="newDoc" type="async" %} {% highlight "js" %} try { const response = await db.put({ _id: 'mydoc', title: 'Heroes' }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="newDoc" type="promise" %} {% highlight "js" %} db.put({ _id: 'mydoc', title: 'Heroes' }).then(function (response) { // handle response }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} You can update an existing doc using _rev: {% include code/start.html id="updateDoc" type="callback" %} {% highlight "js" %} db.get('mydoc', function(err, doc) { if (err) { return console.log(err); } db.put({ _id: 'mydoc', _rev: doc._rev, title: "Let's Dance" }, function(err, response) { if (err) { return console.log(err); } // handle response }); }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="updateDoc" type="async" %} {% highlight "js" %} try { const doc = await db.get('mydoc'); const response = await db.put({ _id: 'mydoc', _rev: doc._rev, title: "Let's Dance" }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="updateDoc" type="promise" %} {% highlight "js" %} db.get('mydoc').then(function(doc) { return db.put({ _id: 'mydoc', _rev: doc._rev, title: "Let's Dance" }); }).then(function(response) { // handle response }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} #### Example Response: {% highlight "js" %} { "ok": true, "id": "mydoc", "rev": "1-A6157A5EA545C99B00FF904EEF05FD9F" } {% endhighlight %} The response contains the id of the document, the new rev, and an ok to reassure you that everything is okay. ### Using db.post() {% highlight "js" %} db.post(doc, [options], [callback]) {% endhighlight %} Create a new document and let PouchDB auto-generate an _id for it. #### Example Usage: {% include code/start.html id="post_doc" type="callback" %} {% highlight "js" %} db.post({ title: 'Ziggy Stardust' }, function (err, response) { if (err) { return console.log(err); } // handle response }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="post_doc" type="async" %} {% highlight "js" %} try { const response = await db.post({ title: 'Ziggy Stardust' }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="post_doc" type="promise" %} {% highlight "js" %} db.post({ title: 'Ziggy Stardust' }).then(function (response) { // handle response }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} #### Example Response: {% highlight "js" %} { "ok" : true, "id" : "8A2C3761-FFD5-4770-9B8C-38C33CED300A", "rev" : "1-d3a8e0e5aa7c8fff0c376dac2d8a4007" } {% endhighlight %} **Put vs. post**: The basic rule of thumb is: put() new documents with an _id, post() new documents without an _id. You should also prefer put() to post(), because when you post(), you are missing an opportunity to use allDocs() to sort documents by _id (because your _ids are random). For more info, read the PouchDB pro tips.