Skip to contents

Create documents to a database.


doc_create(cushion, dbname, doc, docid = NULL, how = "rows", as = "list", ...)



A Cushion object. Required.


Database name3


Document content, can be character string or a list. The character type can be XML as well, if embedded in JSON. When the document is retrieved via doc_get(), the XML is given back and you can parse it as normal.


Document ID


(character) One of rows (default) or columns. If rows, each row becomes a separate document; if columns, each column becomes a separate document.


(character) One of list (default) or json


Curl args passed on to HttpClient


JSON as a character string or a list (determined by the as parameter)


Documents can have attachments just like email. There are two ways to use attachments: the first one is via a separate REST call (see doc_attach_create()); the second is inline within your document, you can do so with this fxn. See for help on formatting json appropriately.

Note that you can create documents from a data.frame with this function, where each row or column is a separate document. However, this function does not use the bulk API

Digits after the decimal

If you have any concern about number of digits after the decimal in your documents, make sure to look at digits in your R options. The default value is 7 (see options for more informnation). You can set the value you like with e.g., options(digits = 10), and get what digits is set to with getOption("digits").

Note that in doc_create() we convert your document to JSON with jsonlite::toJSON() if given as a list, which has a digits parameter. We pass getOption("digits") to the digits parameter in jsonlite::toJSON()


if (FALSE) {
user <- Sys.getenv("COUCHDB_TEST_USER")
pwd <- Sys.getenv("COUCHDB_TEST_PWD")
(x <- Cushion$new(user=user, pwd=pwd))

if ("sofadb" %in% db_list(x)) {
  invisible(db_delete(x, dbname="sofadb"))
db_create(x, 'sofadb')

# write a document WITH a name (uses PUT)
doc1 <- '{"name": "drink", "beer": "IPA", "score": 5}'
doc_create(x, dbname="sofadb", doc1, docid="abeer")
doc_create(x, dbname="sofadb", doc1, docid="morebeer", as='json')
doc_get(x, dbname = "sofadb", docid = "abeer")
## with factor class values
doc2 <- list(name = as.factor("drink"), beer = "stout", score = 4)
doc_create(x, doc2, dbname="sofadb", docid="nextbeer", as='json')
doc_get(x, dbname = "sofadb", docid = "nextbeer")

# write a json document WITHOUT a name (uses POST)
doc2 <- '{"name": "food", "icecream": "rocky road"}'
doc_create(x, doc2, dbname="sofadb")
doc3 <- '{"planet": "mars", "size": "smallish"}'
doc_create(x, doc3, dbname="sofadb")
## assigns a UUID instead of a user given name
db_alldocs(x, dbname = "sofadb")

# write an xml document WITH a name (uses PUT). xml is written as xml in
# couchdb, just wrapped in json, when you get it out it will be as xml
doc4 <- "<top><a/><b/><c><d/><e>bob</e></c></top>"
doc_create(x, doc4, dbname="sofadb", docid="somexml")
doc_get(x, dbname = "sofadb", docid = "somexml")

# You can pass in lists that autoconvert to json internally
doc1 <- list(name = "drink", type = "soda", score = 9)
doc_create(x, dbname="sofadb", doc1, docid="gooddrink")

# Write directly from a data.frame
## Each row or column becomes a separate document
### by rows
if ("test" %in% db_list(x)) {
  invisible(db_delete(x, dbname="test"))
db_create(x, dbname = "test")
doc_create(x, mtcars, dbname="test", how="rows")
doc_create(x, mtcars, dbname="test", how="columns")

if ("testiris" %in% db_list(x)) {
  invisible(db_delete(x, dbname="testiris"))
db_create(x, dbname = "testiris")
doc_create(x, iris, dbname = "testiris")