Skip to content

Commit

Permalink
486: Support JSON.ARRINDEX (#1348)
Browse files Browse the repository at this point in the history
  • Loading branch information
@iamskp11
iamskp11 authored Dec 21, 2024
1 parent 1029a3b commit f6c3028
Show file tree
Hide file tree
Showing 8 changed files with 898 additions and 0 deletions.
153 changes: 153 additions & 0 deletions docs/src/content/docs/commands/JSON.ARRINDEX.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
---
title: JSON.ARRINDEX
description: The `JSON.ARRINDEX` command in DiceDB searches for the first occurrence of a JSON value in an array.
---

The JSON.ARRINDEX command in DiceDB provides users with the ability to search for the position of a specific element within a JSON array stored at a specified path in a document identified by a given key. By executing this command, users can efficiently locate the index of an element that matches the provided value, enabling streamlined data access and manipulation.

This functionality is especially useful for developers dealing with large or nested JSON arrays who need to pinpoint the location of particular elements for further processing or validation. With support for specifying paths and flexible querying, JSON.ARRINDEX enhances the capability of managing and navigating complex JSON datasets within DiceDB.

## Syntax

```bash
JSON.ARRINDEX key path value [start [stop]]
```
## Parameters
| Parameter | Description | Type | Required |
| --------- | ------------------------------------------------------- | ------ | -------- |
| `key` | The name of the key holding the JSON document. | String | Yes |
| `path` | JSONPath pointing to an array within the JSON document. | String | Yes |
| `value` | The value to search for within the array in JSON document. | Mixed | Yes |
| `start` | Optional index to start the search from. Defaults to 0. | Integer | No |
| `stop` | Optional index to end the search. Defaults to 0. | Integer | No |
## Return Values
| Condition | Return Value |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Success | ([]integer) `array of integer replies for each path, the first position in the array of each JSON value that matches the path` |
| Wrong number of arguments | Error: `(error) ERR wrong number of arguments for JSON.ARRINDEX command` |
| Key has wrong type | Error: `(error) ERR Existing key has wrong Dice type` |
| Invalid integer arguments | Error: `(error) ERR Couldn't parse as integer` |
| Invalid jsonpath | Error: `(error) ERR Path '<path>' does not exist` |
## Behaviour
When the JSON.ARRINDEX command is issued, DiceDB performs the following steps:
1. It checks if argument count is valid or not. If not, an error is thrown.
2. It checks for the validity of value, start(optional) and stop(optional) argument passed. If not, an error is thrown.
3. If the jsonpath passed is invalid, an error is thrown.
4. It checks the type of value passed corresponding to the key. If it is not appropriate, error is thrown.
5. For each value matching the path, it checks if the value is JSON array.
6. If it is JSON array, it finds the first occurrence of the value.
7. If value is found, it adds to array the index where the value was found. Else, -1 is added.
8. If it is not JSON array, (nil) is added to resultant array.
9. The final array is returned.
## Errors
1. `Wrong number of arguments`:
- Error Message: `(error) ERR wrong number of arguments for JSON.ARRINDEX command`
- Raised if the number of arguments are less or more than expected.
2. `Couldn't parse as integer`:
- Error Message: `(error) ERR Couldn't parse as integer`
- Raised if the optional start and stop argument are non-integer strings.
- Raised if the value is not a valid integer.
3. `Key has wrong Dice type`:
- Error Message: `(error) ERR Existing key has wrong Dice type`
- Raised if the value of the specified key doesn't match the specified value in DiceDb
4. `Path '<path>' does not exist`
- Error Message: `(error) ERR Path '<path>' does not exist`
- Raise if the path passed is not valid.
## Example Usage
### Basic usage
Searches for the first occurrence of a JSON value in an array
```bash
127.0.0.1:7379> JSON.SET a $ '{"name": "Alice", "age": 30, "mobile": [1902, 1903, 1904]}'
"OK"
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1903
1) (integer) 1
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1904
1) (integer) 2
```
### Finding the occurrence of value starting from given index
Searches for the first occurrence of a JSON value in an array starting from given index
```bash
127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "mobile": [1902, 1903, 1904]}'
"OK"
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1902 0
1) (integer) 0
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1902 1
1) (integer) -1
```
### Finding the occurrence of value starting from given index and ending at given index (exclusive)
Searches for the first occurrence of a JSON value in [start, stop) range
```bash
127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "mobile": [1902, 1903, 1904]}'
"OK"
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1902 0 2
1) (integer) 0
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1902 1 2
1) (integer) -1
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1904 0 1
1) (integer) -1
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1904 0 2
1) (integer) -1
127.0.0.1:7379> JSON.ARRINDEX a $.mobile 1904 0 3
1) (integer) 2
```
### When invalid start and stop argument is passed
Error When invalid start and stop argument is passed
```bash
127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "mobile": [1902, 1903, 1904]}'
"OK"
127.0.0.1:7379> JSON.ARRINDEX b $.mobile iamnotvalidinteger
(error) ERR Couldn't parse as integer
127.0.0.1:7379> JSON.ARRINDEX b $.mobile iamnotvalidinteger iamalsonotvalidinteger
(error) ERR Couldn't parse as integer
```
### When the jsonpath is not array object
Error When jsonpath is not array object
```bash
127.0.0.1:7379> set b '{"name":"Alice","mobile":[1902,1903,1904]}'
"OK"
127.0.0.1:7379> JSON.ARRINDEX b $.mobile 1902
(error) Existing key has wrong Redis type
```
### When the jsonpath is not valid path
Error When jsonpath is not valid path
```bash
127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "mobile": [1902, 1903, 1904]}'
"OK"
127.0.0.1:7379> JSON.ARRINDEX b $invalid_path 3
(error) ERR Path '$invalid_path' does not exist
```
176 changes: 176 additions & 0 deletions integration_tests/commands/http/json_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,8 @@ func runIntegrationTests(t *testing.T, exec *HTTPCommandExecutor, testCases []In
// fmt.Println("hi expected : ", out)
// fmt.Println("hi actual :", result)
assert.JSONEq(t, out.(string), result.(string))
case "deep_equal":
assert.ElementsMatch(t, result.([]interface{}), out.([]interface{}))
}
}
})
Expand Down Expand Up @@ -1785,3 +1787,177 @@ func TestJsonARRTRIM(t *testing.T) {
exec.FireCommand(HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "a"}})
exec.FireCommand(HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "b"}})
}

func TestJSONARRINDEX(t *testing.T) {
exec := NewHTTPCommandExecutor()

exec.FireCommand(HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "key"}})
defer exec.FireCommand(HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "key"}})

normalArray := `[0,1,2,3,4,3]`
nestedArray := `{"arrays":[{"arr":[1,2,3]},{"arr":[2,3,4]},{"arr":[1]}]}`
nestedArray2 := `{"a":[3],"nested":{"a":{"b":2,"c":1}}}`

testCases := []IntegrationTestCase{
{
name: "should return array index when given element is present",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "value": 3}},
},
expected: []interface{}{"OK", []interface{}{float64(3)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return -1 when given element is not present",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "value": 10}},
},
expected: []interface{}{"OK", []interface{}{float64(-1)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return array index with start optional param provided",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "values": []string{"3", "4"}}},
},
expected: []interface{}{"OK", []interface{}{float64(5)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return array index with start and stop optional param provided",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "values": []string{"4", "4", "5"}}},
},
expected: []interface{}{"OK", []interface{}{float64(4)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return -1 with start and stop optional param provided where start > stop",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "values": []string{"3", "2", "1"}}},
},
expected: []interface{}{"OK", []interface{}{float64(-1)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return -1 with start (out of boud) and stop (out of bound) optional param provided",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(normalArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$", "values": []string{"3", "6", "10"}}},
},
expected: []interface{}{"OK", []interface{}{float64(-1)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return list of array indexes for nested json",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$.arrays.*.arr", "value": 3}},
},
expected: []interface{}{"OK", []interface{}{float64(2), float64(1), float64(-1)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return list of array indexes for multiple json path",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..arr", "value": 3}},
},
expected: []interface{}{"OK", []interface{}{float64(2), float64(1), float64(-1)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return array of length 1 for nested json path, with index",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$.arrays[1].arr", "value": 3}},
},
expected: []interface{}{"OK", []interface{}{float64(1)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return empty array for nonexistent path in nested json",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..arr1", "value": 3}},
},
expected: []interface{}{"OK", []interface{}{}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return -1 for each nonexisting value in nested json",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..arr", "value": 5}},
},
expected: []interface{}{"OK", []interface{}{float64(-1), float64(-1), float64(-1)}},
assertType: []string{"equal", "equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return nil for non-array path and -1 for array path if value DNE",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray2)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..a", "value": 2}},
},
expected: []interface{}{"OK", []interface{}{float64(-1), nil}},
assertType: []string{"equal", "deep_equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
{
name: "should return nil for non-array path if value DNE and valid index for array path if value exists",
commands: []HTTPCommand{
{Command: "JSON.SET", Body: map[string]interface{}{"key": "key", "path": "$", "json": json.RawMessage(nestedArray2)}},
{Command: "JSON.ARRINDEX", Body: map[string]interface{}{"key": "key", "path": "$..a", "value": 3}},
},
expected: []interface{}{"OK", []interface{}{float64(0), nil}},
assertType: []string{"equal", "deep_equal"},
cleanUp: []HTTPCommand{
{Command: "DEL", Body: map[string]interface{}{"key": "key"}},
},
},
}

preTestChecksCommand := HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "key"}}
postTestChecksCommand := HTTPCommand{Command: "DEL", Body: map[string]interface{}{"key": "key"}}
runIntegrationTests(t, exec, testCases, preTestChecksCommand, postTestChecksCommand)
}
Loading

0 comments on commit f6c3028

Please sign in to comment.