From 1953a103767fb19f1608d40c6171d0d5310a5241 Mon Sep 17 00:00:00 2001 From: Neville Mehta Date: Fri, 4 Oct 2024 01:02:27 -0700 Subject: [PATCH] Audit and make documentation for command JSON.CLEAR consistent (#887) Co-authored-by: Neville Mehta --- docs/src/content/docs/commands/JSON.CLEAR.md | 135 ++++++++----------- 1 file changed, 56 insertions(+), 79 deletions(-) diff --git a/docs/src/content/docs/commands/JSON.CLEAR.md b/docs/src/content/docs/commands/JSON.CLEAR.md index 253bdbfb4..a3c46e41f 100644 --- a/docs/src/content/docs/commands/JSON.CLEAR.md +++ b/docs/src/content/docs/commands/JSON.CLEAR.md @@ -3,16 +3,27 @@ title: JSON.CLEAR description: Documentation for the DiceDB command JSON.CLEAR --- -The `JSON.CLEAR` command is part of the DiceDBJSON module, which allows you to manipulate JSON data stored in DiceDB. This command is used to clear the value at a specified path in a JSON document, effectively setting it to an empty state. This can be particularly useful when you want to reset a part of your JSON document without removing the key itself. +The `JSON.CLEAR` command allows you to manipulate JSON data stored in DiceDB. This command is used to clear the value at a specified path in a JSON document, effectively setting it to an empty state. This can be particularly useful when you want to reset a part of your JSON document without removing the key itself. + +## Syntax + +``` +JSON.CLEAR key [path] +``` ## Parameters -- `key`: (String) The key under which the JSON document is stored. -- `path`: (String) The path within the JSON document that you want to clear. The path should be specified in JSONPath format. If the path is omitted, the root path (`$`) is assumed. +| Parameter | Description | Type | Required | +|-----------|---------------------------------------------------------------------------|---------|----------| +| `key` | (String) The key under which the JSON document is stored. | String | Yes | +| `path` | (String) The path within the JSON document that you want to clear. The path should be specified in JSONPath format. If the path is omitted, the root path (`$`) is assumed. | String | No | -## Return Value +## Return values -- `Integer`: The number of paths that were cleared. +| Condition | Return Value | +|------------------------------------------------|---------------------------------------------------| +| Command is successful | `Integer` (The number of paths that were cleared) | +| Syntax or specified constraints are invalid | error | ## Behaviour @@ -20,99 +31,65 @@ When the `JSON.CLEAR` command is executed, it traverses the JSON document stored - For objects, it removes all key-value pairs. - For arrays, it removes all elements. -- For strings, it sets the value to an empty string. +- For strings, the value remaines unchanged. - For numbers, it sets the value to `0`. -- For booleans, it sets the value to `false`. +- For booleans, the value remaines unchanged. If the specified path does not exist, the command does nothing and returns `0`. -## Error Handling +## Errors The `JSON.CLEAR` command can raise the following errors: - `(error) ERR wrong number of arguments for 'json.clear' command`: This error is raised if the command is called with an incorrect number of arguments. -- `(error) ERR key does not exist`: This error is raised if the specified key does not exist in the DiceDB database. -- `(error) ERR path is not a valid JSONPath`: This error is raised if the specified path is not a valid JSONPath expression. -- `(error) ERR path does not exist`: This error is raised if the specified path does not exist within the JSON document. - -## Example Usage +- `(error) ERR could not perform this operation on a key that doesn't exist`: This error is raised if the specified key does not exist in the DiceDB database. +- `(error) ERR invalid JSONPath`: This error is raised if the specified path is not a valid JSONPath expression. +- `(error) ERR Existing key has wrong Dice type`: This error is raised if the key exists but the value is not of the expected JSON type and encoding. -### Example 1: Clearing a JSON Object - -Suppose you have a JSON document stored under the key `user:1001`: - -```json -{ - "name": "John Doe", - "age": 30, - "address": { - "street": "123 Main St", - "city": "Anytown" - } -} -``` - -To clear the `address` object, you would use the following command: - -```sh -JSON.CLEAR user:1001 $.address -``` +Note: If the specified path does not exist within the JSON document, the command will not raise an error but will simply not modify anything. -After executing this command, the JSON document would be: - -```json -{ - "name": "John Doe", - "age": 30, - "address": {} -} -``` - -### Example 2: Clearing an Array - -Suppose you have a JSON document stored under the key `user:1002`: - -```json -{ - "name": "Jane Doe", - "hobbies": ["reading", "swimming", "hiking"] -} -``` - -To clear the `hobbies` array, you would use the following command: - -```sh -JSON.CLEAR user:1002 $.hobbies -``` +## Example Usage -After executing this command, the JSON document would be: +### Clearing a JSON Object -```json -{ - "name": "Jane Doe", - "hobbies": [] -} +```bash +127.0.0.1:7379> JSON.SET user:1001 $ '{"name": "John Doe", "age": 30, "address": {"street": "123 Main St", "city": "Anytown"}}' +OK +127.0.0.1:7379> JSON.CLEAR user:1001 $.address +(integer) 1 +127.0.0.1:7379> JSON.GET user:1001 +"{\"name\":\"John Doe\",\"age\":30,\"address\":{}}" ``` -### Example 3: Clearing the Root Path - -Suppose you have a JSON document stored under the key `user:1003`: +### Clearing a Number -```json -{ - "name": "Alice", - "age": 25 -} +```bash +127.0.0.1:7379> JSON.SET user:1001 $ '{"name": "John Doe", "age": 30, "address": {"street": "123 Main St", "city": "Anytown"}}' +OK +127.0.0.1:7379> JSON.CLEAR user:1001 $.age +(integer) 1 +127.0.0.1:7379> JSON.GET user:1001 +"{\"name\":\"John Doe\",\"age\":0,\"address\":{\"street\":\"123 Main St\",\"city\":\"Anytown\"}}" ``` -To clear the entire JSON document, you would use the following command: +### Clearing an Array -```sh -JSON.CLEAR user:1003 +```bash +127.0.0.1:7379> JSON.SET user:1002 $ '{"name": "Jane Doe", "hobbies": ["reading", "swimming", "hiking"]}' +OK +127.0.0.1:7379> JSON.CLEAR user:1002 $.hobbies +(integer) 1 +127.0.0.1:7379> JSON.GET user:1002 +"{\"name\":\"Jane Doe\",\"hobbies\":[]}" ``` -After executing this command, the JSON document would be: +### Clearing the Root Path -```json -{} +```bash +127.0.0.1:7379> JSON.SET user:1003 $ '{"name": "Alice", "age": 25}' +OK +127.0.0.1:7379> JSON.CLEAR user:1003 +(integer) 1 +127.0.0.1:7379> JSON.GET user:1003 +"{}" ```