2. JSON Structure Reference

The following appendix provides a quick reference to all the JSON structures that you can supply to CouchDB, or get in return to requests.

2.1. All Database Documents

Field	Description
total_rows	Number of documents in the database/view
offset	Offset where the document list started
update_seq (optional)	Current update sequence for the database
rows [array]	Array of document object

2.2. Bulk Document Response

Field	Description
docs [array]	Bulk Docs Returned Documents
id	Document ID
error	Error type
reason	Error string with extended reason

2.3. Bulk Documents

Field	Description
docs [array]	Bulk Documents Document
_id (optional)	Document ID
_rev (optional)	Revision ID (when updating an existing document)
_deleted (optional)	Whether the document should be deleted

2.4. Changes information for a database

Field	Description
last_seq	Last update sequence
pending	Count of remaining items in the feed
results [array]	Changes made to a database
seq	Update sequence
id	Document ID
changes [array]	List of changes, field-by-field, for this document

2.5. CouchDB Document

Field	Description
_id (optional)	Document ID
_rev (optional)	Revision ID (when updating an existing document)

2.6. CouchDB Error Status

Field	Description
id	Document ID
error	Error type
reason	Error string with extended reason

2.7. CouchDB database information object

Field	Description
db_name	The name of the database.
committed_update_seq	The number of committed updates.
doc_count	The number of documents in the database.
doc_del_count	The number of deleted documents.
compact_running	Set to true if the database compaction routine is operating on this database.
disk_format_version	The version of the physical format used for the data when it is stored on hard disk.
disk_size	Size in bytes of the data as stored on disk. View indexes are not included in the calculation.
instance_start_time	Timestamp indicating when the database was opened, expressed in microseconds since the epoch.
purge_seq	The number of purge operations on the database.
update_seq	Current update sequence for the database.

2.8. Design Document

Field	Description
_id	Design Document ID
_rev	Design Document Revision
views	View
viewname	View Definition
map	Map Function for View
reduce (optional)	Reduce Function for View

2.9. Design Document Information

Field	Description
name	Name/ID of Design Document
view_index	View Index
compact_running	Indicates whether a compaction routine is currently running on the view
disk_size	Size in bytes of the view as stored on disk
language	Language for the defined views
purge_seq	The purge sequence that has been processed
signature	MD5 signature of the views for the design document
update_seq	The update sequence of the corresponding database that has been indexed
updater_running	Indicates if the view is currently being updated
waiting_clients	Number of clients waiting on views from this design document
waiting_commit	Indicates if there are outstanding commits to the underlying database that need to processed

2.10. Document with Attachments

Field	Description
_id (optional)	Document ID
_rev (optional)	Revision ID (when updating an existing document)
_attachments (optional)	Document Attachment
filename	Attachment information
content_type	MIME Content type string
data	File attachment content, Base64 encoded

2.11. List of Active Tasks

Field	Description
tasks [array]	Active Tasks
pid	Process ID
status	Task status message
task	Task name
type	Operation Type

2.12. Replication Settings

Field	Description
source	Source database name or URL.
target	Target database name or URL.
cancel (optional)	Cancels the replication.
checkpoint_interval (optional)	Specifies the checkpoint interval in ms.
continuous (optional)	Configure the replication to be continuous.
create_target (optional)	Creates the target database.
doc_ids (optional)	Array of document IDs to be synchronized.
filter (optional)	name of the filter function in the form of ddoc/myfilter.
source_proxy (optional)	Address of a proxy server through which replication from the source should occur.
target_proxy (optional)	Address of a proxy server through which replication to the target should occur.
query_params (optional)	Query parameter that are passed to the filter function; the value should be a document containing parameters as members.
selector (optional)	Select the documents included in the replication. This option provides performance benefits compared with using the filter option.
since_seq (optional)	Sequence from which the replication should start.
use_checkpoints (optional)	Whether to use replication checkpoints or not.

2.13. Replication Status

Field	Description
ok	Replication status
session_id	Unique session ID
source_last_seq	Last sequence number read from the source database
history [array]	Replication History
session_id	Session ID for this replication operation
recorded_seq	Last recorded sequence number
docs_read	Number of documents read
docs_written	Number of documents written to target
doc_write_failures	Number of document write failures
start_time	Date/Time replication operation started
start_last_seq	First sequence number in changes stream
end_time	Date/Time replication operation completed
end_last_seq	Last sequence number in changes stream
missing_checked	Number of missing documents checked
missing_found	Number of missing documents found

2.14. Request object

Field	Description
body	Request body data as string. If the request method is GET this field contains the value "undefined". If the method is DELETE or HEAD the value is "" (empty string).
cookie	Cookies object.
form	Form data object. Contains the decoded body as key-value pairs if the Content-Type header was application/x-www-form-urlencoded.
headers	Request headers object.
id	Requested document id string if it was specified or null otherwise.
info	Database information
method	Request method as string or array. String value is a method as one of: HEAD, GET, POST, PUT, DELETE, OPTIONS, and TRACE. Otherwise it will be represented as an array of char codes.
path	List of requested path sections.
peer	Request source IP address.
query	URL query parameters object. Note that multiple keys are not supported and the last key value suppresses others.
requested_path	List of actual requested path section.
raw_path	Raw requested path string.
secObj	Security Object.
userCtx	User Context Object.
uuid	Generated UUID by a specified algorithm in the config file.

{
    "body": "undefined",
    "cookie": {
        "AuthSession": "cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
        "m": "3234"
    },
    "form": {},
    "headers": {
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
        "Accept-Encoding": "gzip,deflate,sdch",
        "Accept-Language": "en-US,en;q=0.8",
        "Connection": "keep-alive",
        "Cookie": "m=3234:t|3247:t|6493:t|6967:t|34e2:|18c3:t|2c69:t|5acb:t|ca3:t|c01:t|5e55:t|77cb:t|2a03:t|1d98:t|47ba:t|64b8:t|4a01:t; AuthSession=cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
        "Host": "127.0.0.1:5984",
        "User-Agent": "Mozilla/5.0 (Windows NT 5.2) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.75 Safari/535.7"
    },
    "id": "foo",
    "info": {
        "committed_update_seq": 2701412,
        "compact_running": false,
        "db_name": "mailbox",
        "disk_format_version": 6,
        "doc_count": 2262757,
        "doc_del_count": 560,
        "instance_start_time": "1347601025628957",
        "purge_seq": 0,
        "sizes": {
          "active": 7580843252,
          "disk": 14325313673,
          "external": 7803423459
        },
        "update_seq": 2701412
    },
    "method": "GET",
    "path": [
        "mailbox",
        "_design",
        "request",
        "_show",
        "dump",
        "foo"
    ],
    "peer": "127.0.0.1",
    "query": {},
    "raw_path": "/mailbox/_design/request/_show/dump/foo",
    "requested_path": [
        "mailbox",
        "_design",
        "request",
        "_show",
        "dump",
        "foo"
    ],
    "secObj": {
        "admins": {
            "names": [
                "Bob"
            ],
            "roles": []
        },
        "members": {
            "names": [
                "Mike",
                "Alice"
            ],
            "roles": []
        }
    },
    "userCtx": {
        "db": "mailbox",
        "name": "Mike",
        "roles": [
            "user"
        ]
    },
    "uuid": "3184f9d1ea934e1f81a24c71bde5c168"
}

2.15. Request2 object

Field	Description
body	Request body data as string. If the request method is GET this field contains the value "undefined". If the method is DELETE or HEAD the value is "" (empty string).
cookie	Cookies object.
headers	Request headers object.
method	Request method as string or array. String value is a method as one of: HEAD, GET, POST, PUT, DELETE, OPTIONS, and TRACE. Otherwise it will be represented as an array of char codes.
path	List of requested path sections.
peer	Request source IP address.
query	URL query parameters object. Note that multiple keys are not supported and the last key value suppresses others.
requested_path	List of actual requested path section.
raw_path	Raw requested path string.
secObj	Security Object.
userCtx	User Context Object.

2.16. Response object

Field	Description
code	HTTP status code number.
json	JSON encodable object. Implicitly sets Content-Type header as application/json.
body	Raw response text string. Implicitly sets Content-Type header as text/html; charset=utf-8.
base64	Base64 encoded string. Implicitly sets Content-Type header as application/binary.
headers	Response headers object. Content-Type header from this object overrides any implicitly assigned one.
stop	boolean signal to stop iteration over view result rows (for list functions only)

Warning

The body, base64 and json object keys are overlapping each other where the last one wins. Since most realizations of key-value objects do not preserve the key order or if they are mixed, confusing situations can occur. Try to use only one of them.

Note

Any custom property makes CouchDB raise an internal exception. Furthermore, the Response object could be a simple string value which would be implicitly wrapped into a {"body": ...} object.

2.17. Returned CouchDB Document with Detailed Revision Info

Field	Description
_id (optional)	Document ID
_rev (optional)	Revision ID (when updating an existing document)
_revs_info [array]	CouchDB document extended revision info
rev	Full revision string
status	Status of the revision

2.18. Returned CouchDB Document with Revision Info

Field	Description
_id (optional)	Document ID
_rev (optional)	Revision ID (when updating an existing document)
_revisions	CouchDB document revisions
ids [array]	Array of valid revision IDs, in reverse order (latest first)
start	Prefix number for the latest revision

2.19. Returned Document with Attachments

Field	Description
_id (optional)	Document ID
_rev (optional)	Revision ID (when updating an existing document)
_attachments (optional)	Document attachment
filename	Attachment
stub	Indicates whether the attachment is a stub
content_type	MIME Content type string
length	Length (bytes) of the attachment data
revpos	Revision where this attachment exists

2.20. Security Object

Field	Description
admins	Roles/Users with admin privileges
roles [array]	List of roles with parent privilege
names [array]	List of users with parent privilege
members	Roles/Users with non-admin privileges
roles [array]	List of roles with parent privilege
names [array]	List of users with parent privilege

{
    "admins": {
        "names": [
            "Bob"
        ],
        "roles": []
    },
    "members": {
        "names": [
            "Mike",
            "Alice"
        ],
        "roles": []
    }
}

2.21. User Context Object

Field	Description
db	Database name in the context of the provided operation.
name	User name.
roles	List of user roles.

{
    "db": "mailbox",
    "name": null,
    "roles": [
        "_admin"
    ]
}

2.22. View Head Information

Field	Description
total_rows	Number of documents in the view
offset	Offset where the document list started

{
    "total_rows": 42,
    "offset": 3
}