Documents — Data Model


    Description — Couchbase Lite concepts — Data model — Documents
    Related Content — Databases | Blobs | Indexes |


    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.


    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.

    Example 1. Persist a document
    using (var newTask = new MutableDocument("xyz")) {
        newTask.SetString("type", "task")
            .SetString("owner", "todo")
            .SetDate("createdAt", DateTimeOffset.UtcNow);


    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.

    Example 2. Make a mutable document

    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");

    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);
                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

    Document Constraints

    Example 3. Reserved Keys List

    You should avoid using certain reserved words as keys within your document. These include:

    • _attachments

    • _id

    • _deleted

    • _removed

    • _rev