Couchbase Client Library Ruby 1.0 - Chapter 7. Ruby — Update Operations

7.1. Append Methods
Prev	Chapter 7. Ruby — Update Operations	Next

7.1. Append Methods

The append methods allow you to add information to an existing key/value pair in the database. You can use this to add information to a string or other data after the existing data.

The append methods append raw serialized data on to the end of the existing data in the key. If you have previously stored a serialized object into Couchbase and then use append, the content of the serialized object will not be extended. For example, adding an Array of integers into the database, and then using append to add another integer will result in the key referring to a serialized version of the array, immediately followed by a serialized version of the integer. It will not contain an updated array with the new integer appended to it. De-serialization of objects that have had data appended may result in data corruption.

API Call	`object.append(key, value [, ruby-append-options ])`
Asynchronous	no
Description	Append a value to an existing key
Returns	`fixnum` ( The CAS value for the object stored. A fixed number )
Arguments
`string key`	Document ID used to identify the value
`object value`	Value to be stored
`hash ruby-append-options`	Hash of options containing key/value pairs
	Structure definition:
	`:cas` (fixnum)	CAS Value
	The CAS value for an object. This value was created on the server and is guaranteed to be unique for each value for a given key. You provide this value as an option when you want basic optimistic concurrency control while doing sets.
	`:format` (symbol)	How to represent value in storage.
	Determines how a value is represented in storage. Possible values include :plain for string storage.
Exceptions
`ArgumentError`	Exception object indicating failed attempt to pass a block in synchronous mode.
`Couchbase::Error::Connect`	Exception object specifying failure to connect to a node.
`Couchbase::Error::KeyExists`	Exception object indicating the key already exists on the server.
`Couchbase::Error::NotStored`	Exception object indicating the key/value does not exist in the database.

The append appends information to the end of an existing key/value pair. The append function requires a CAS value. For more information on CAS values, see Chapter 6, Ruby — Retrieve Operations.

For example, to append a string to an existing key:

#sets foo key to text 'Hello'

couchbase.set("foo", "Hello")

#adds text to end of key foo, resulting in 'Hello, world!'

couchbase.append("foo", ", world!")

#gets foo
couchbase.get("foo")
#=> "Hello, world!"

Other examples of using append are as follows:

#Perform a simple append

c.set("foo", "aaa")
c.append("foo", "bbb")
c.get("foo")           # returns "aaabbb"

#Perform optimistic locking. The operations fails if the
#given CAS does not match the CAS for the key

ver = c.set("foo", "aaa")
c.append("foo", "bbb", :cas => ver)


#Creates custom data groups/sets using append
#appends minus to indicate item not part of set
#appends plus to indicate item is part of set

def set_add(key, *values)
    encoded = values.flatten.map{|v| "+#{v} "}.join
    append(key, encoded)
end

def set_remove(key, *values)
    encoded = values.flatten.map{|v| "-#{v} "}.join
    append(key, encoded)
end

def set_get(key)
    encoded = get(key)
    ret = Set.new
    
    encoded.split(' ').each do |v|
          op, val = v[0], v[1..-1]
          case op
                when "-"
                    ret.delete(val)
                when "+"
                    ret.add(val)
          end
    end
    ret
end