The add method adds a value to the
database with the specified key, but will fail if the key already
exists in the database.
| API Call | object.add(key, value, options) | ||
| Asynchronous | no | ||
| Description | Add a value with the specified key that does not already exist. Will fail if the key/value pair already exist. | ||
| 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 | |||
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::ValueFormat | Exception object indicating the value cannot be serialized with chosen encoder, for instance, occurs if you try to store Hash in :plain mode. | ||
The add method adds a value to the
database using the specified key.
couchbase.add("someKey", 0, someObject);Unlike Section 5.3, “Set Operations” the operation can fail (and return false) if the specified key already exists.
For example, the first operation in the example below may complete if the key does not already exist, but the second operation will always fail as the first operation will set the key:
c.add("foo", "bar") # stores successully c.add("foo", "baz") # raises Couchbase::Error::KeyExists: # fails to store value (key="foo", error=0x0c)