Skip to content

Commit

Permalink
Command Migration: ('HINCRBY', 'HINCRBYFLOAT', 'HRANDFIELD') (DiceDB#…
Browse files Browse the repository at this point in the history 
…1081)

* Migration, cmdmeta, eval refactor

* fix build err + lint

* unittests migrated + additional fixes

* 1032:Migrates of PFDADD,PFCOUNT,PFMERGE to Multi-threaded architecture.(DiceDB#1097)

* Migration, cmdmeta, eval refactor

* unittests migrated + additional fixes

* migration resp tests added + lint fix

* refactor hincrbyfloat resp testname

* cleanup merge resolutions

* fix non-hashmap key error

* Added HTTP tests for HINCRBY, HINCRBYFLOAT, HRANDFIELD

* fix lint errors

* Removed async tests post migration

* 1032:Migrates of PFDADD,PFCOUNT,PFMERGE to Multi-threaded architecture.(DiceDB#1097)

* Websocket tests for HINCR,HINCRBY,HRANDFIELD

* Lint fixes

* Migrate selectrandomfields to hmap.go

* Added Docs + minor test refactor

* lint fixes + merge conflicts

* Fix build

* undo rename

* Fix websocket tests

* Revert "Merge branch 'master' into saish-migrate-1023"

This reverts commit e8b1e62, reversing
changes made to 2204237.

* linkfixes + build fix

* Docs refactored + comments

* Update internal/eval/store_eval.go

* Reapply "Merge branch 'master' into saish-migrate-1023"

This reverts commit deb877e.

* fix lint

---------

Co-authored-by: Ashwin Kulkarni <[email protected]>
  • Loading branch information
@sashpawar11 @AshwinKul28
sashpawar11 and AshwinKul28 authored Oct 20, 2024
1 parent cd796f4 commit 7747ff1
Show file tree
Hide file tree
Showing 21 changed files with 1,520 additions and 386 deletions.
144 changes: 144 additions & 0 deletions docs/src/content/docs/commands/HINCRBY.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
---
title: HINCRBY
description: The `HINCRBY` command in DiceDB is used to increment the value of a hash stored at a specified key. This command is useful when you need to increment or decrement the value associated with a field stored in a hash key.
---

The `HINCRBY` command in DiceDB is used to increment the value of a hash stored at a specified key. This command is useful when you need to increment or decrement the value associated with a field stored in a hash key.

## Syntax

```bash
HINCRBY key field increment
```

## 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 incremment/decrement | String | Yes |
| `increment` | The integer with which you want to increment/decrement the value stored in the field | Integer | Yes |


## Return values


| Condition | Return Value |
|------------------------------------------------|---------------------------------------------------|
| If `key` and the `field` exists and is a hash | `Integer`
| If `key` exists and is a hash , but the `field` does not exist |`Integer` |
| If `key` and `field` do not exist | `Integer` |
| If `key` exists and is a hash , but the `field` does not have a value that is an integer | `error` |
| If `increment` results in an integer overflow | `error` |
| If `increment` is not a valid integer | `error` |


## Behaviour
- DiceDB checks if the increment is a valid integer. If not, an error is returned.
- It then checks if the key exists. If the key is not a hash, an error is returned.
- If the key exists and is of type hash, DiceDB 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, an error is returned.
- If the increment results in an overflow, an 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

1. `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.
2. `Non-integer hash value`:
- Error Message: `(error) ERROR hash value is not an integer`
- Occurs when attempting to increment a value that is not a valid integer
3. `Increment or decrement overflow`:
- Error Message: `(error) ERROR increment or decrement would overflow`
- Occurs when attempting to increment a value that results in an integer overflow.
4. `Invalid increment type`
- Error Message: `(error) ERROR value is not an integer or out of range`
- Occurs when attempting to increment a value with an invalid increment type.
5. `Invalid number of arguments`
- Error Message: `(error) ERROR wrong number of arguments for 'hincrby' command`
- Occurs hwen an invalid number of arguments are passed to the command.
## Example Usage
### Basic Usage
Executing `hincrby` on a non-exsiting hash key
```bash
127.0.0.1:7379> HINCRBY keys field1 10
(integer) 10
```

### Usage on a non-existing field
Executing `hincrby` on a existing hash with a non-existing field
```bash
127.0.0.1:7379> HINCRBY keys field2 10
(integer) 10
```

### Usage on a existing hash and a field
Executing `hincrby` on a existing hash with a existing field
```bash
127.0.0.1:7379> HINCRBY keys field2 10
(integer) 20
```

### Usage by passing a negative increment
Executing `hincrby` to decrement a value
```bash
127.0.0.1:7379> HINCRBY keys field -20
(integer) 0
```
### Invalid key usage
Executing `hincrby` on a non-hash key
```bash
127.0.0.1:7379> SET user:3000 "This is a string"
OK
127.0.0.1:7379> HINCRBY user:3000 field1 10
(error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value
```

### Invalid number of arguments
Passing invalid number of arguments to the `hincrby` command

```bash
127.0.0.1:7379> HINCRBY user:3000 field
(error) ERROR wrong number of arguments for 'hincrby' command
```

### Invalid value type
Executing `hincrby` on a non-integer hash value

```bash
127.0.0.1:7379> HSET user:3000 field "hello"
(integer) 1
127.0.0.1:7379> HINCRBY user:3000 field 2
(error) ERROR hash value is not an integer
```


### Invalid increment type passed
Executing `hincrby` with a string increment value

```bash
127.0.0.1:7379> HINCRBY user:3000 field new
(error) ERROR value is not an integer or out of range
```


### Increment resulting in an integer overflow
Incrementing the hash value with a very large integer results in an integer overflow

```bash
127.0.0.1:7379> HSET new-key field 9000000000000000000
(integer) 1
127.0.0.1:7379> HINCRBY new-key field 1000000000000000000
(error) ERROR increment or decrement would overflow
```
## Best Practices
- `Ensure Field is Numeric`: Always ensure that the field being incremented holds a numeric value to avoid errors related to type mismatches.
- `Monitor Keyspace`: Keep track of hash keys and their fields to prevent unexpected behavior due to the creation of new hashes.

## Alternatives
- `HINCRBYFLOAT`: If you need to increment a hash field by a floating-point number, consider using the `HINCRBYFLOAT` command, which is specifically designed for that purpose.

### Notes
- The `HINCRBY` command is a powerful tool for managing counters and numerical values stored in hash fields, making it essential for applications that rely on incremental updates.
127 changes: 127 additions & 0 deletions docs/src/content/docs/commands/HINCRBYFLOAT.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
---
title: HINCRBYFLOAT
description: 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.
---

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

```bash
HINCRBYFLOAT key field increment
```

## 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

1. `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.
2. `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
3. `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.
4. `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.
## Example Usage
### Basic Usage
Executing `hincrbyfloat` on a non-exsiting hash key
```bash
127.0.0.1:7379> HINCRBYFLOAT keys field1 10.2
"10.2"
```

### Usage on a non-existing field
Executing `hincrbyfloat` on a existing hash with a non-existing field
```bash
127.0.0.1:7379> HINCRBYFLOAT keys field2 0.2
"0.2"
```

### Usage on a existing hash and a field
Executing `hincrbyfloat` on a existing hash with a existing field
```bash
127.0.0.1:7379> HINCRBYFLOAT keys field2 1.2
"1.4"
```

### Invalid key usage
Executing `hincrbyfloat` on a non-hash key

```bash
127.0.0.1:7379> SET user:3000 "This is a string"
OK
127.0.0.1:7379> HINCRBYFLOAT user:3000 field1 10
(error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value
```

### Invalid number of arguments
Passing invalid number of arguments to the `hincrbyfloat` command
```bash
127.0.0.1:7379> HINCRBYFLOAT user:3000 field
(error) ERROR wrong number of arguments for 'hincrbyfloat' command
```

### Invalid value type
Executing `hincrbyfloat` on a non-integer hash value
```bash
127.0.0.1:7379> HSET user:3000 field "hello"
(integer) 1
127.0.0.1:7379> HINCRBYFLOAT user:3000 field 2
(error) ERROR value is not an integer or a float
```

### Invalid increment type passed
Executing `hincrbyfloat` with a string increment value

```bash
127.0.0.1:7379> HINCRBYFLOAT user:3000 field new
(error) ERROR value is not an integer or a float
```

### 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` and `HGET`: If you need to set or retrieve values without incrementing, consider using `HSET` to assign a value directly and HGET 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.
115 changes: 115 additions & 0 deletions docs/src/content/docs/commands/HRANDFIELD.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
---
title: HRANDFIELD
description: The `HRANDFIELD` command in DiceDB is used to return one or more random fields from a hash stored at a specified key. It can also return the values associated with those fields if specified.
---

The `HRANDFIELD` command in DiceDB is used to return one or more random fields from a hash stored at a specified key. It can also return the values associated with those fields if specified.

## Syntax

```
HRANDFIELD key [count [WITHVALUES]]
```

## Parameters

| Parameter | Description | Type | Required |
|-------------|----------------------------------------------------------------------------|---------|----------|
| `key` | The key of the hash from which random fields are to be returned | String | Yes |
| `count` | The number of random fields to retrieve. If negative, allows repetition | Integer | No |
| `WITHVALUES`| Option to include the values associated with the returned fields | Flag | No |

## Return values

| Condition | Return Value |
|------------------------------------------------------|-------------------------------------------------|
| Key exists and count is not specified | `(String)` |
| Key exists and count is specified | Array of random fields (or field-value pairs if `WITHVALUES` is used) |
| Key does not exist | `nil` |
| Key exists but is not a hash | `error` |

## Behaviour
- DiceDB checks if the specified `key` exists.
- If the key does not exist, the command returns `nil`.
- If the key exists but is not a hash, an error is returned.
- If the key does not have any fields, an empty array is returned.
- If no `count` parameter is passed, it is defaulted to `1`
- If the `count` or `WITHVALUES` parameters are passed,they are checked for typechecks and syntax errors.
- If the `count` parameter is negative, the command allows repeated fields in the result.
- The command will return the random field(s) based on the specified `count`.
- If the `WITHVALUES` option is provided, the command returns the fields along with their associated values.

## Errors
1. `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.
2. `Invalid count type`:
- Error Message: `(error) ERROR value is not an integer or out of range`
- Occurs when a non-integer count parameter is passed.
3. `Invalid number of arguments`
- Error Message: `(error) ERROR wrong number of arguments for 'hrandfield' command`
- Occurs when an invalid number of arguments are passed to the command.
## Example Usage

### Basic Usage
Executing `HRANDFIELD` on a key without any parameters
```bash
127.0.0.1:6379> HSET keys field1 value1 field2 value2 field3 value3
(integer) 3
127.0.0.1:6379> HRANDFIELD keys
"field1"
```

### Usage with `count` parameter
Executing `HRANDFIELD` on a key with a `count` parameter of 2
```bash
127.0.0.1:6379> HRANDFIELD keys 2
1) "field2"
2) "field1"
```

### Usage with `WITHVALUES` parameter
Executing `HRANDFIELD` with the `WITHVALUES` parameter
```bash
127.0.0.1:6379> HRANDFIELD keys 2 WITHVALUES
1) "field2"
2) "value2"
3) "field1"
4) "value1"
```

### Invalid key usage
Executing `hrandfield` on a non-hash key

```bash
127.0.0.1:6379> SET key "not a hash"
OK
127.0.0.1:6379> HRANDFIELD key
(error) WRONGTYPE Operation against a key holding the wrong kind of value
```

### Invalid count parameter
Non-integer value passed as `count`

```bash
127.0.0.1:6379> HRANDFIELD keys hello
(error) ERROR value is not an integer or out of range
```

### Invalid number of arguments
Passing invalid number of arguments to the `hrandfield` command
```bash
127.0.0.1:6379> HRANDFIELD
(error) ERR wrong number of arguments for 'hrandfield' command
```


### Best Practices
- `Check Key Existence`: Before using `HRANDFIELD`, ensure that the hash key exists to avoid unnecessary errors. You can use the `HEXISTS` command to verify the presence of the key.

### Alternatives
- `HKEYS`: Use `HKEYS` to retrieve all fields in a hash. If you need to work with all fields rather than a random selection, this command provides a complete view.
- `Sampling with HSCAN`: For larger hashes, consider using `HSCAN` to iterate through the fields and randomly select a subset. This approach can help manage memory usage when dealing with large datasets.
### Notes
- The `HRANDFIELD` command is useful for scenarios where random selection from hash fields is required, such as in games, lotteries, or randomized surveys.
- The command can return multiple fields at once, allowing for efficient random sampling without the need for multiple calls. This can be particularly advantageous when working with larger hashes.
Loading

0 comments on commit 7747ff1

Please sign in to comment.