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 error. 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.

Figure 2.10. Using Replace to Determine Offer Status

Figure 2.11. Make Offer After Replace

Some Couchbase Server developers prefer to exclusively use replace anytime they update items; this way they will know whether the key exists or not prior to updating it; using replace will it provides 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 replace in Ruby:

c.replace("foo", "bar")

This will replace the value for the key foo 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 replace to 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 memcached protocol.

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 replace 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 item incompatible with Couchbase Server.

For more information about connections and connection-level settings, see Section 6.4.4, “Optimizing Client Instances” and Section 6.6.1, “Client-Side Timeouts”