The set operations store a value into Couchbase or Memcached using the specified key and value. The value is stored against the specified key, even if the key already exists and has data. This operation overwrites the existing with the new data.
| API Call | object.set(key, value, options) | ||
| Asynchronous | no | ||
| Description | Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists. | ||
| 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 options | Hash containing option/value pairs used during a set operation. | ||
| Structure definition: | |||
:ttl (int) | :ttl (Expiry) | ||
| Time for document to exist in server before it is automatically destroyed. This option symbol is :ttl and the value can be any number representing seconds. | |||
:flags (fixnum) | Flags for storage options. | ||
| Flags used during the set. These flags are ignored by the Couchbase server but preserved for use by a client. This includes default flags recorded for new values and was used as part of the memcached protocol. | |||
:format (symbol) | How to represent value in storage. | ||
| Determines how a value is represented in storage. Possible values include :document for JSON data, :plain for string storage, and :marshal to serialize your ruby object using Marshall.dump and Marshal.load. | |||
: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. | |||
| Exceptions | |||
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::ValueFormat | Exception object indicating the value cannot be serialized with chosen encoder, e.g. if you try to store the Hash in :plain mode. | ||
Examples of using set as follows:
#Store a key/value which expires in 2 seconds using relative TTL c.set("foo", "bar", :ttl => 2) #Store the key that expires in 2 seconds using absolute TTL c.set("foo", "bar", :ttl => Time.now.to_i + 2) #Apply JSON document format for value at set c.set("foo", {"bar" => "baz}, :format => :document) #Use index and value as hash syntax to store value during set c.set["foo"] = {"bar" => "baz} #Use extended hash syntax to store a value at set c["foo", {:flags => 0x1000, :format => :plain}] = "bar" c["foo", :flags => 0x1000] = "bar" # for ruby 1.9.x only #Set application specific flags (note that it will be OR-ed with format flags) c.set("foo", "bar", :flags => 0x1000) #Perform optimistic locking by specifying last known CAS version c.set("foo", "bar", :cas => 8835713818674332672) #Perform asynchronous call c.run do c.set("foo", "bar") do |ret| ret.operation #=> :set ret.success? #=> true ret.key #=> "foo" ret.cas end end