This method will update the value for a key, if the key already
exists. If the key does not exist, it will fail and return an
Replace is useful in cases where
you do care whether or not a key exists, for instance, your
application logic will perform one action if a key exists, but
perform another action if the key does not exist. This method is
roughly analogous to a
UPDATE command in SQL.
For instance, going back to a game application example, imagine you want to show new users a special offerings page with a variety of new games. In this case you could have a document in Couchbase Server which stores last login times for users. When a new user initially logs in, your application tries to replace the last login document with the current time, but it receive an error that the key does not exist. Your application would then know that the key does not exist because this is the first user login and could then show the special offer page.
Some Couchbase Server developers prefer to exclusively use
replace anytime they update documents.
With this approach you will know whether the key exists or not
prior to updating it; using
will return error information if the key is missing which you
can handle in your application logic.
In Couchbase SDKs you can update the value with
replace while simultaneously updating
the document expiration.
Here is a simple example of
This will replace the value for the key
with the new string 'bar'; if the key does not exist, it will
return a 'key not found' error. The following example
demonstrates use of
replace in PHP:
$script_access_count=$cb_obj->get($script_name); $cb_obj->replace("DATE::" . $script_name,date("F j, Y, g:i:s a "));
In this example we use the
update the latest access date and time for a server script. We
update the date and time using a standard PHP date format.
The equivalent call in the memcached protocol is
replace; for more information, see
If a key does not exist, you will receive 'key not found' type
error. If you receive this error and you expected it to exist,
you should check your application logic to see why it does not
exist. Any logic that creates that type of key, or any logic
that deletes it may inadvertently cause that error. Another
reason why you might get this error is that the item expired;
once a key is expired Couchbase Server will return a 'key not
found' error in response to a
request. So you will want to check any explicit expiration set
for that key.
One option to handle this error is to create the value if it
does not already exist. After you receive an error that the
value could not be replaced, you can attempt an
add to create the key.
The types of errors that can occur during this operation include 1) inability to connect to a node, or 2) some error exists while attempting to format a value being set. If you have a connection-level error you may need to reattempt connection, and possibly check the status of the server. If you have an error with the size of your value or formatting, you need to check the value itself, and how it is encoded and see if there are any issues that make the document incompatible with Couchbase Server.