Documents — Data Model
Overview
In Couchbase Lite, a document’s body takes the form of a JSON object — a collection of key/value pairs where the values can be different types of data such as numbers, strings, arrays or even nested objects. Every document is identified by a document ID, which can be automatically generated (as a UUID) or specified programmatically; the only constraints are that it must be unique within the database, and it can’t be changed.
Initializers
The following methods/initializers can be used:
-
The MutableDocument() initializer can be used to create a new document where the document ID is randomly generated by the database.
-
The MutableDocument(String id) initializer can be used to create a new document with a specific ID.
-
The Database.GetDocument() method can be used to get a document. If it doesn’t exist in the database, it will return
null. This method can be used to check if a document with a given ID already exists in the database.
The following code example creates a document and persists it to the database.
using (var newTask = new MutableDocument("xyz")) {
newTask.SetString("type", "task")
.SetString("owner", "todo")
.SetDate("createdAt", DateTimeOffset.UtcNow);
db.Save(newTask);
}Mutability
By default, when a document is read from the database it is immutable. The Document.ToMutable() method should be used to create an instance of the document which can be updated.
Changes to the document are persisted to the database when the save method is called.
using(var document = db.GetDocument("xyz"))
using (var mutableDocument = document.ToMutable()) {
mutableDocument.SetString("name", "apples");
db.Save(mutableDocument);
}Typed Accessors
Scalar type
The Document class now offers a set of property accessors for various scalar types, including boolean, integers, floating-point and strings.
These accessors take care of converting to/from JSON encoding, and make sure you get the type you’re expecting.
Date accessors
In addition, as a convenience we offer Date accessors.
Dates are a common data type, but JSON doesn’t natively support them, so the convention is to store them as strings in ISO-8601 format.
The following example sets the date on the createdAt property and reads it back using the Document.GetDate() accessor method.
newTask.SetValue("createdAt", DateTimeOffset.UtcNow);
var date = newTask.GetDate("createdAt");Checking for properties
To check whether a given property exists in the document, you should use the Document.Contains(String key) method.
If the property doesn’t exist in the document it will return the default value for that getter method (0 for Document.GetInt() 0.0 for Document.GetFloat() etc.).
Batch operations
If you’re making multiple changes to a database at once, it’s faster to group them together. The following example persists a few documents in batch.
db.InBatch(() =>
{
for (var i = 0; i < 10; i++) {
using (var doc = new MutableDocument()) {
doc.SetString("type", "user");
doc.SetString("name", $"user {i}");
doc.SetBoolean("admin", false);
db.Save(doc);
Console.WriteLine($"Saved user document {doc.GetString("name")}");
}
}
});At the local level this operation is still transactional: no other Database instances, including ones managed by the replicator can make changes during the execution of the block, and other instances will not see partial changes.
But Couchbase Mobile is a distributed system, and due to the way replication works, there’s no guarantee that Sync Gateway or other devices will receive your changes all at once.
Document change events
It’s also possible to register for document changes.
The following example registers for changes to the document with ID user.john and prints the verified_account property.
db.AddDocumentChangeListener("user.john", (sender, args) =>
{
using (var doc = Db.GetDocument(args.DocumentID)) {
Console.WriteLine($"Status :: {doc.GetString("verified_account")}");
}
});Document Expiration
Document expiration allows users to set the expiration date to a document. When the document is expired, the document will be purged from the database. The purge will not be replicated to Sync Gateway.
The following example sets the TTL for a document to 5 minutes from the current time.
// Purge the document one day from now
var ttl = DateTimeOffset.UtcNow.AddDays(1);
db.SetDocumentExpiration("doc123", ttl);
// Reset expiration
db.SetDocumentExpiration("doc1", null);
// Query documents that will be expired in less than five minutes
var fiveMinutesFromNow = DateTimeOffset.UtcNow.AddMinutes(5).ToUnixTimeMilliseconds();
var query = QueryBuilder
.Select(SelectResult.Expression(Meta.ID))
.From(DataSource.Database(db))
.Where(Meta.Expiration.LessThan(Expression.Double(fiveMinutesFromNow)));Document Constraints
Couchbase Lite APIs do not explicitly disallow the use of attributes with the underscore prefix at the top level of document. This is to facilitate the creation of documents for use either in local only mode where documents are not synced, or when used exclusively in peer-to-peer sync.
| "_id", :"_rev" and "_sequence" are reserved keywords and must not be used as top-level attributes — see Example 3. |
Users are cautioned that any attempt to sync such documents to Sync Gateway will result in an error. To be future proof, you are advised to avoid creating such documents. Use of these attributes for user-level data may result in undefined system behavior.
For more guidance — see: Sync Gateway - data modeling guidelines
-
_attachments
-
_id
-
_deleted
-
_removed
-
_rev