Raw append and prepend
These methods should not be used with JSON documentsThe 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)
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
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)
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)
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).
Examples of using
append in Couchbase SDKs:
C | Python | Java | .NET | Go | node.js | PHP
Users of the
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.