HINCRBYFLOAT
The HINCRBYFLOAT
command in DiceDB is used to increment the value of a hash stored at a specified key representing a floating point value. This command is useful when you need to increment or decrement the value associated with a field stored in a hash key using a floating point value.
Syntax
Parameters
Parameter | Description | Type | Required |
---|---|---|---|
key | The key of the hash, which consists of the field whose value you want to increment/decrement | String | Yes |
field | The field present in the hash, whose value you want to increment/decrement | String | Yes |
increment | The floating-point value with which you want to increment/decrement the value stored in the field | Float | Yes |
Return values
Condition | Return Value |
---|---|
The key and the field exists and is a hash | String |
The key exists and is a hash , but the field does not exist | String |
The key and field do not exist | String |
The key exists and is a hash , but the field does not have a value that is a valid integer or a float | error |
The increment is not a valid integer/float | error |
Behaviour
- DiceDB checks if the increment is a valid integer or a float.
- If not, a error is returned.
- It then checks if the key exists
- If the key is not a hash, a error is returned.
- If the key exists and is of type hash, dicedb then retrieves the key along-with the field and increments the value stored at the specified field.
- If the value stored in the field is not an integer or a float, a error is returned.
- If the key does not exist, a new hash key is created with the specified field and its value is set to the
increment
passed.
Errors
Wrong type of value or key
:- Error Message:
(error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value
- Occurs when attempting to use the command on a key that is not a hash.
- Error Message:
Non-integer / Non-float hash value
:- Error Message:
(error) ERROR value is not an integer or a float
- Occurs when attempting to increment a value that is not a valid integer or a float
- Error Message:
Invalid increment type
- Error Message:
(error) ERROR value is not an integer or a float
- Occurs when attempting to increment a value with an invalid increment type.
- Error Message:
Invalid number of arguments
- Error Message:
(error) ERROR wrong number of arguments for 'hincrbyfloat' command
- Occurs when an invalid number of arguments are passed to the command.
- Error Message:
Example Usage
Basic Usage
Executing hincrbyfloat
on a non-exsiting hash key
Usage on a non-existing field
Executing hincrbyfloat
on a existing hash with a non-existing field
Usage on a existing hash and a field
Executing hincrbyfloat
on a existing hash with a existing field
Invalid key usage
Executing hincrbyfloat
on a non-hash key
Invalid number of arguments
Passing invalid number of arguments to the hincrbyfloat
command
Invalid value type
Executing hincrbyfloat
on a non-integer hash value
Invalid increment type passed
Executing hincrbyfloat
with a string increment value
Best Practices
-Ensure Field is Numeric
: Always verify that the field being incremented holds a valid numeric value (integer or float) to avoid errors related to type mismatches. -Use Appropriate Data Types
: Choose the right data types for your fields. For floating-point operations, ensure that the values are stored and manipulated as floats to maintain precision.
Alternatives
HINCRBY
: Use this command if you only need to increment a hash field by an integer. It is specifically designed for integer increments and may be more efficient for non-floating-point operations.HSET
andHGET
: If you need to set or retrieve values without incrementing, consider usingHSET
to assign a value directly andHGET
to retrieve the current value of a field.
Notes
- The
HINCRBYFLOAT
command is a powerful tool for managing floating-point counters and numerical values stored in hash fields, making it essential for applications that require precision in incremental updates. - The command operates atomically, meaning it will complete without interruption, making it safe to use in concurrent environments where multiple clients may modify the same hash fields.
HINCRBYFLOAT
can be beneficial in scenarios such as tracking scores in a game, maintaining balances in accounts, or managing quantities in inventory systems where floating-point values are common.