xref: /6.0.3/couchstore/csdata.md (revision 0689f161)
1## Couchstore Data Types
2
3Struct members not listed should be considered internal to Couchstore.
4
5### sized\_buf
6    struct sized_buf {
7        char* buf;
8        size_t size;
9    }
10
11Couchstore uses `sized_buf`s to point to data buffers.
12
13### DocInfo
14    struct DocInfo {
15        sized_buf id;
16        uint64_t db_seq;
17        uint64_t rev_seq;
18        sized_buf rev_meta;
19        int deleted;
20        uint8_t content_meta;
21    }
22
23* `id` - Document ID
24* `db_seq` - Change sequence number the document was inserted at.
25* `rev_seq` - The version number of the document
26* `rev_meta` - Revision metadata. Used by ep-engine to store CAS value, expiry time, and flags
27* `deleted` - 1 if document should be considered "deleted" and not subject to indexing, otherwise 0.
28* `content_meta` - Number field used to store flags indicating metadata about the document content (is it JSON, etc.)
29
30#### The `content_meta` field
31
32* The least-significant two bits are used to encode why/whether the body is or is not JSON
33    * 0 - Document body *is* JSON
34    * 1 - Inserted data was not valid JSON
35    * 2 - Inserted data was valid JSON, but contained a key reserved for internal use, such as one with a `$` prefix.
36    * 3 - The document was inserted in non-JSON mode.
37* If the most-significant bit is set the document body data has been compressed with snappy.
38
39When saving documents with `save_doc` or `save_docs`, `id`, `rev_seq`, `rev_meta`, `deleted`, and `content_meta` must be set on the `DocInfo`s passed to Couchstore. The `db_seq` is determined at insert time.
40
41#### The `rev_meta` field
42
43[128 bit binary value]
44| 64 bits  | 32 bits    | 32 bits    |
45-----------|------------|------------|
46 CAS Value | Expiration | User flags |
47
48 All values are Big Endian.
49
50 * CAS Value - Random nonce value set by Memcached, used to allow ensuring value has not been modified since it was read when writing.
51 * Expiration - 32 bit timestamp for value expiry time. 0 if item does not expire.
52 * User flags - Memcache API allows users to set this 32 bit number along with values, it is not used by memcached internally.
53
54### Doc
55    struct Doc {
56        sized_buf id;
57        sized_buf data;
58    }
59
60`id` contains the document ID, `data` contains the document body data. Couchstore does not compress or modify the body data in any way, unless the COMPRESS_DOC_BODIES or DECOMPRESS_DOC_BODIES flags are passed to the read and write functions, then it will check the `content_meta` of the corresponding doc info to see if it should compress or decompress the doc data.
61
62### LocalDoc
63    struct LocalDoc {
64        sized_buf id;
65        sized_buf json;
66        int deleted;
67    }
68
69* `id`  - The local document ID, it must start with `_local/`
70* `json` - The local document body.
71* `deleted` - if set to 1 on a LocalDoc passed to save_local_doc, `json` will be ignored, and the local document with the ID in `id` will be removed, if it exists.
72
73
74## C API
75
76Documented in `include/libcouchstore/couch_db.h`
77
78