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.

  1. {
  2. "body": "undefined",
  3. "cookie": {
  4. "AuthSession": "cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
  5. "m": "3234"
  6. },
  7. "form": {},
  8. "headers": {
  9. "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  10. "Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
  11. "Accept-Encoding": "gzip,deflate,sdch",
  12. "Accept-Language": "en-US,en;q=0.8",
  13. "Connection": "keep-alive",
  14. "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",
  15. "Host": "127.0.0.1:5984",
  16. "User-Agent": "Mozilla/5.0 (Windows NT 5.2) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.75 Safari/535.7"
  17. },
  18. "id": "foo",
  19. "info": {
  20. "committed_update_seq": 2701412,
  21. "compact_running": false,
  22. "db_name": "mailbox",
  23. "disk_format_version": 6,
  24. "doc_count": 2262757,
  25. "doc_del_count": 560,
  26. "instance_start_time": "1347601025628957",
  27. "purge_seq": 0,
  28. "sizes": {
  29. "active": 7580843252,
  30. "disk": 14325313673,
  31. "external": 7803423459
  32. },
  33. "update_seq": 2701412
  34. },
  35. "method": "GET",
  36. "path": [
  37. "mailbox",
  38. "_design",
  39. "request",
  40. "_show",
  41. "dump",
  42. "foo"
  43. ],
  44. "peer": "127.0.0.1",
  45. "query": {},
  46. "raw_path": "/mailbox/_design/request/_show/dump/foo",
  47. "requested_path": [
  48. "mailbox",
  49. "_design",
  50. "request",
  51. "_show",
  52. "dump",
  53. "foo"
  54. ],
  55. "secObj": {
  56. "admins": {
  57. "names": [
  58. "Bob"
  59. ],
  60. "roles": []
  61. },
  62. "members": {
  63. "names": [
  64. "Mike",
  65. "Alice"
  66. ],
  67. "roles": []
  68. }
  69. },
  70. "userCtx": {
  71. "db": "mailbox",
  72. "name": "Mike",
  73. "roles": [
  74. "user"
  75. ]
  76. },
  77. "uuid": "3184f9d1ea934e1f81a24c71bde5c168"
  78. }

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

  1. {
  2. "admins": {
  3. "names": [
  4. "Bob"
  5. ],
  6. "roles": []
  7. },
  8. "members": {
  9. "names": [
  10. "Mike",
  11. "Alice"
  12. ],
  13. "roles": []
  14. }
  15. }

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.

  1. {
  2. "db": "mailbox",
  3. "name": null,
  4. "roles": [
  5. "_admin"
  6. ]
  7. }

2.22. View Head Information

Field

Description

total_rows

Number of documents in the view

offset

Offset where the document list started

  1. {
  2. "total_rows": 42,
  3. "offset": 3
  4. }