In Redis, the DECRBY command decrements the value of a key by the specified amount.

If the key doesn’t exist, DECRBY creates the key with a value of 0 and then decrements it by the specified amount.

An error occurs if the key contains a value of the wrong type or contains a string that cannot be represented as integer. DECRBY operations are limited to 64 bit signed integers.

Syntax

DECRBY key decrement

Where key is the key to decrement, and decrement is the amount to decrement it by.

Example

Suppose we set a key like this:

SET points "10"

Result:

OK

Let’s quickly take a look at it:

GET points

Result:

"10"

OK, now let’s decrement it by three:

DECRBY points 3

Result:

(integer) 7

We get an integer reply with the value of the key after the DECRBY operation was performed.

Let’s run the GET command again:

GET points

Result:

"7"

As expected, the original value of 10 has been decremented by 3, and the result is 7.

Negative Values

Redis does not have a dedicated integer type. However, the string stored at the key is interpreted as a base-10 64 bit signed integer to execute the operation. Therefore, we can decrement negative values just as we can decrement positive values.

Set a negative value:

SET points "-10"

Result:

OK

Let’s quickly take a look at it:

GET points

Result:

"-10"

OK, now let’s decrement it by three:

DECRBY points 3

Result:

(integer) -13

The value has been decremented as specified.

We can check this at any time by running the GET command again:

GET points

Result:

"-13"

We can also decrement it by a negative amount, which has the effect of incrementing the value:

DECRBY points -10

Result:

(integer) -3

We can also use the INCR, INCRBY, and INCRBYFLOAT commands to increment values.

When the Key Doesn’t Exist

If the key doesn’t exist, DECRBY creates the key with a value of 0 and then decrements it by the specified amount.

Let’s delete our points key:

DEL points

Result:

(integer) 1

The DEL command returns the number of keys that were deleted – in this case 1.

Now let’s try to decrement that (non-existent) key:

DECRBY points 10

Result:

(integer) -10

So we can see that points has been recreated and decremented to a value of -10.

When the Value is the Wrong Type

An error occurs if the key contains a value of the wrong type or contains a string that cannot be represented as an integer.

To test this, let’s try decrementing a value that can’t be represented as an integer.

Set the amount:

SET points "Ten"

Result:

OK

Let’s quickly take a look at it:

GET points

Result:

"Ten"

OK, now let’s try to decrement it by seven:

DECRBY points 7

Result:

(error) ERR value is not an integer or out of range

An error occurred as expected.

Decrement by One

Although DECRBY can be used to decrement a key by one, there’s another command called DECR that is designed to do exactly that. When using DECR, you don’t need to specify the decrement amount – you only need to specify the key.

So the following:

DECR points

Is the equivalent of this:

DECRBY points 1