Skip to content

Document

Jump to bottom
Dominic Barnes edited this page May 21, 2014 · 2 revisions

Document(db, [id], [rev])

Represents a CouchDB document. DesignDocument and LocalDocument also inherit directly from this.

The first parameter is required, it can either be just a String _id, or it can be an Object representing the document body.

The second parameter is optional, and it's the _rev of the document. (if it is known)

var couchdb = require("couchdb-api");

var db = couchdb().db("mydb");

// a document with a known id
var doc = db.doc("mydoc");

// a document with a known id and rev
var doc = db.doc("mydoc", "some-rev");

// a document with a body
var doc = db.doc({
    hello: "world"
});

Document#url([path])

This helper method is for generating a String URL relative to the document. If path is specified, it will resolve that path relative to the document's base URL. (therefore, beginning a path with will make the resolved path relative to the server itself) path can also be an Array:String.

var base = doc.url();
// => http://localhost:5984/mydb

var attachment = doc.url("myattachment.txt");
// => http://localhost:5984/mydb/mydoc/myattachment.txt

var root = doc.url("/");
// => http://localhost:5984/

Document#id([id])

This helper method gets or sets the _id property on the body of this document.

// getter
var id = doc.id();

// setter
doc.id("some-other-id");

Document#rev([rev])

This helper method gets or sets the _rev property on the body of this document.

// getter
var rev = doc.rev();

// setter
doc.rev("some-other-rev");

Document#body([body])

This helper method gets or sets the body of this document.

Note: If you leave out the _id or _rev properties, it will affect what the behavior of various write commands to this document object. (eg: save, delete, etc)

If you only wish to augment the body, use Document#extend() instead. If you want to remove the current contents of the document, preserving the _id and _rev, then use Document#empty()

// getter
var body = doc.body();

// setter
doc.body({
    _id: "some-id",
    hello: "world"
});

Document#empty()

This helper method removes all contents of the document's body except for _id and _rev.

var doc = db.doc({
    _id: "abc-123",
    hello: "world",
    foo: "bar"
});

doc.empty();

var body = doc.body();
// => { _id: "abc-123" }

Document#extend(body)

This helper method augments the current contents of the body via extend.

var doc = db.doc({ hello: "world" });

doc.extend({ foo: "bar" });

var body = doc.body();
// => { hello: "world", foo: "bar" }

Document#destroy(callback)

DELETE /{db}/{doc} CouchDB Documentation

Deletes this document.

Note: If you are deleting an existing document, you will need the _rev number before the delete will be successful. (like any other write operation) Currently, if you don't know the revision number ahead of time, you will need to call Document#get(callback) prior to deleting.

doc.destroy(function (err, results) {
    // ...
});

Document#exists(callback)

HEAD /{db}/{doc} CouchDB Documentation

Checks for this document's existence.

doc.exists(function (err, exists) {
    // ...
});

Document#get(callback)

GET /{db}/{doc} CouchDB Documentation

Retrieves this document from the server.

Note: Currently, additional querystring parameters (like attachments or rev) are not supported.

doc.get(function (err, body) {
    // ...
});

Document#save(callback)

Saves the body of the document to the server. If an _id is present, it will use the PUT method. Otherwise, it will use a POST instead.

Note: Currently, additional querystring parameters (like batch) are not supported.

doc.save(function (err, results) {
    // ...
});

Document#show(name, [body], callback)

Runs this document object (can be a null document if _id is unspecified) through a show function.

The name parameter must be a string formatted like {ddoc}/{showfn}. (denoting both the design document and show function name)

If a request body is specified, (via the optional body argument) then the request will be a POST instead of a GET.

// typical show via GET
doc.show("myddoc/myshowfn", function (err, results) {
    // ...
});

// show via POST (with request body)
ddoc.show("myddoc/myshowfn", { hello: "world" }, function (err, results) {
    // ...
})

Document#update(name, [body], callback)

Runs an update handler for this document object. (can be a null document if no _id is specified)

The name parameter must be a string formatted like {ddoc}/{updatefn}. (denoting both the design document and update handler function name)

Like the Document#save() method, this will switch between PUT and POST depending on whether an _id is present or not.

// typical show via GET
doc.show("myddoc/myshowfn", function (err, results) {
    // ...
});

// show via POST (with request body)
ddoc.show("myddoc/myshowfn", { hello: "world" }, function (err, results) {
    // ...
})

Clone this wiki locally