Data Modelling
Couchbase Sync Gateway’s data model; for secure cloud-to-edge synchronization of enterprise data.
Introduction
The guidance and constraints documented here relate to the design of data buckets and documents that you require, or may potentially require, to replicate using sync gateway functionality. They do not necessarily align with constraints on the local storage and use of such documents.
Property Naming
- What to avoid
-
You should avoid designing user property names prefixed with an underscore character (
_, ASCII_). - Why it’s an issue
-
The underscore character (
_) is a reserved prefix for Document system properties, for example: the document’s identifier (_id) and revision property (_rev).Any document which does contain user properties with a leading underscore will be rejected by Sync Gateway — see Example 1 for the error details.
Example 1. Property prefix error message"{"error":"Bad Request","reason":"user defined top level properties beginning with '_' are not allowed in document body"}" - Where it applies
-
This rule applies to writes performed through:
-
Couchbase Lite SDKs
-
Sync Gateway REST APIs
-
Couchbase Server SDKs when shared bucket access is enabled.
-
- When you might encounter the error
-
You are especially likely to encounter the error in the following deployment situations:
-
In Mobile-to-Web Data Sync with Node.js Server SDK and Ottoman.js (the Node.js ODM for Couchbase), where the rule conflicts with the
_typeproperty that is automatically added by Ottoman.js.A suggested workaround in this scenario is to fork the Ottoman.js library, perform a search-replace for the
_typeproperty and replace it without a leading underscore.
-
|
For versions 2.x of Sync Gateway, you can encounter the following error:
|
- How to avoid the error
-
You should change any top-level user properties that have a key with a leading underscore , by either:
-
Renaming them to remove the underscore, or,
-
Wrapping them inside another object with a key that doesn’t have a leading underscore.
-
Document Structure
Couchbase’s unit of data is a document, this is the NOSQL equivalent of a row or record.
Documents are stored as a key-value pair, which comprises a unique and immutable key, the Id, and a value representing the users' data (a JSON-object or binary blob).
Key
The document key, the Id, is:
-
A UTF-8 string with no spaces, although it may contain special characters, such as (, %, /, ", and _
-
No longer than 250 bytes
-
Unique within the bucket
-
Automatically generated (as a UUID) or be set by the user or application when saved
-
Immutable; that is, once saved the Id cannot be changed.
Value
The document value is either:
-
A JSON value, termed a Document.
This JSON object is itself collection of key/value pairs, where the values may be numbers, strings, arrays or even nested objects themselves. As a result documents can represent highly-complex data structures in a readily parsable and self-organizing manner.
-
a binary object (also known as a blob or attachment)
These attachments provide a means to store large media files or any other non-textual data. Couchbase Lite supports attachments of unlimited size, although the Sync Gateway currently imposes a 20MB limit for attachments synced to it.
Document Attributes
Each Document has the following attributes:
-
A document ID
-
A current revision ID (which changes every time the document is updated)
-
A history of past revision IDs (usually linear, but will form a branching tree if the document has or has had conflicts)
-
A body in the form of a JSON object, i.e. a set of key/value pairs
-
Zero or more named binary attachments
Document Change History
Couchbase Lite tracks the change history of every document as a series of revisions, like version control systems such as Git or Subversion. Its main purpose being to enable the replicator to determine the data to sync and any conflicts arising.
Each document change is assigned a unique revision ID. The IDs of past revisions are available. The content of past revisions may be available if the revision was created locally and the database has not yet been compacted.