A newer version of this documentation is available.

View Latest

Raw append and prepend

These methods should not be used with JSON documents
The append and prepend operations operate at the byte level and are unsuitable for dealing with JSON documents. Use these methods only when explicitly dealing with binary or UTF-8 documents. Using the append and prepend methods may invalidate an existing JSON document.
append(docid, fragment)
prepend(docid, fragment)

The append and prepend methods atomically add bytes to the end or beginning of a binary document. They are an efficient alternative to retrieving a binary document in its entirety, appending the contents locally, and then saving the contents back to the server.

Because these methods do raw string manipulation, they are only suitable for non-JSON documents: Prepending or appending anything to a JSON document will invalidate the JSON and make it unparseable by standard JSON parsers.

The semantics of the append and prepend functions are similar to those of the upsert family of methods, except that they accept the fragment to append as their value, rather than the entire document. These functions may be used to add efficiency for custom binary data structures (such as logs), as they avoid transferring the contents of the entire document for each operation. Consider the following versions (which are equivalent)

Append using get() and replace() (slow)
import couchbase
import couchbase.exceptions
import couchbase.bucket

cb = couchbase.bucket.Bucket('couchbase://10.0.0.31/default')
# Store the document
cb.upsert('binary_doc', '\x01', format=couchbase.FMT_BYTES)

while True:
    # Retrieve the entire document
    rv = cb.get('binary_doc')
    value = rv.value + '\x02'
    try:
        # Upload the entire document
        cb.replace('binary_doc', value, format=couchbase.FMT_BYTES)
        break
    except couchbase.exceptions.KeyExistsError:
        continue

print repr(cb.get('binary_doc').value)
Append using append() (fast)
import couchbase
import couchbase.exceptions
import couchbase.bucket

cb = couchbase.bucket.Bucket('couchbase://10.0.0.31/default')
# Store the document
cb.upsert('binary_doc', '\x01', format=couchbase.FMT_BYTES)

# Append a fragment
cb.append('binary_doc', '\x02', format=couchbase.FMT_BYTES)

print repr(cb.get('binary_doc').value)

Note that since the append() method is done atomically, there is no need for a CAS check (though one can still be supplied if the document must be at a specific state).

SDK Examples

Examples of using prepend and append in Couchbase SDKs:

C | Python | Java | .NET | Go | node.js | PHP

Performance considerations

Users of the append and prepend methods should ensure that the resulting documents do not become too large. Couchbase has a hard document size limit of 20MB.

Using append and prepend on larger documents may cause performance degradation and memory fragmentation at the server level, as for each append operation the server must allocate memory for the new document size and then append the fragment to the new memory. The performance impact may be significant when document sizes reach beyond 100KB.

Finally, note that while append saves network traffic from the client to server (by only specifying the fragment to append), the entire document is replicated for each mutation. Five append operations on a single 10MB document will result in 50MB of traffic to each replica.