The increment methods enable you to increase a given stored integer value. These are the incremental equivalent of the decrement operations and work on the same basis; updating the value of a key if it can be parsed to an integer. The update operation occurs on the server and is provided at the protocol level. This simplifies what would otherwise be a two-stage get and set operation.
| API Call | client.incr(key, offset) | ||
| Asynchronous | no | ||
| Description | Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value. | ||
| Returns | long (
Numeric value
) | ||
| Arguments | |||
String key | Document ID used to identify the value | ||
int offset | Integer offset value to increment/decrement (default 1) | ||
The first form of the incr() method
accepts the keyname and offset (increment) value to be used when
increasing the server-side integer. For example, to increment the
server integer dlcounter by 5:
client.incr("dlcounter",5);The return value is the updated value of the specified key.
| API Call | client.incr(key, offset, default) | ||
| Asynchronous | no | ||
| Description | Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value. | ||
| Returns | long (
Numeric value
) | ||
| Arguments | |||
String key | Document ID used to identify the value | ||
int offset | Integer offset value to increment/decrement (default 1) | ||
int default | Default value to increment/decrement if key does not exist | ||
The second form of the incr() method
supports the use of a default value which will be used to set the
corresponding key if that value does already exist in the
database. If the key exists, the default value is ignored and the
value is incremented with the provided offset value. This can be
used in situations where you are recording a counter value but do
not know whether the key exists at the point of storage.
For example, if the key dlcounter does not
exist, the following fragment will return 1000:
long newcount = client.incr("dlcount",1,1000); System.out.printf("Updated counter is %d\n",newcount);
A subsequent identical call will return the value 1001 as the key
dlcount already exists and the value (1000) is
incremented by 1.
| API Call | client.incr(key, offset, default, expiry) | ||
| Asynchronous | no | ||
| Description | Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value. | ||
| Returns | long (
Numeric value
) | ||
| Arguments | |||
String key | Document ID used to identify the value | ||
int offset | Integer offset value to increment/decrement (default 1) | ||
int default | Default value to increment/decrement if key does not exist | ||
int expiry | Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). | ||
The third format of the incr() method
supports setting an expiry value on the given key, in addition to
a default value if key does not already exist.
For example, to increment a counter, using a default of 1000 if the value does not exist, and an expiry of 1 hour (3600 seconds):
long newcount = client.incr("dlcount",1,1000,3600);
For information on expiry values, see Section 4.4, “Expiry Values”.
| API Call | client.asyncIncr(key, offset) | ||
| Asynchronous | yes | ||
| Description | Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value. | ||
| Returns | Future<Long> (
Asynchronous request value, as Long
) | ||
| Arguments | |||
String key | Document ID used to identify the value | ||
int offset | Integer offset value to increment/decrement (default 1) | ||
The asyncIncr() method supports an
asynchronous increment on the value for a corresponding key.
Asynchronous increments are useful when you do not want to
immediately wait for the return value of the increment operation.
OperationFuture<Long> incrOp = client.asyncIncr("samplekey",1,1000,24000);