diff --git a/src/content/docs/commands/PING.md b/src/content/docs/commands/PING.md index e600300..8f8225b 100644 --- a/src/content/docs/commands/PING.md +++ b/src/content/docs/commands/PING.md @@ -5,13 +5,7 @@ description: The `PING` command in DiceDB is used to test the connection between The `PING` command in DiceDB is used to test the connection between the client and the DiceDB server. It's a crucial command for ensuring that the DiceDB server is reachable and functional. It is often utilized to check the health of the server and ensure that it is responsive. -## Parameters - -The `PING` command can optionally take a single argument which is a string. - -- `message`: Optional. A string that you want the DiceDB server to return as a response. If a message is provided, the DiceDB server will respond with the same message. - -### Syntax +## Syntax The basic syntax of the `PING` command is as follows: @@ -22,58 +16,84 @@ PING [message] - If `[message]` is provided, it will be echoed back in the response. - If `[message]` is not provided, default response is `PONG`. -## Return Value +## Parameters + +| Parameter | Description | Type | Required | +|-----------------|--------------------------------------------------|---------|----------| +| `message` | `message` echoed in the response | String | No | + +## Return values + +| Condition | Return Value | +|------------------------------------------------|---------------------------------------------------| +| No `message` provided | `PONG` | +| `message` provided | `message` | + +## Behaviour + +When the `PING` command is fired: + +- If no `message` is given, it sends back a `PONG`. +- If a `message` is provided, it sends back the same message in the response. +- If `message` provided is non-string value, the value is internally coerced to string and echoed as response. + +This helps clients determine if the server is up and responsive. Essentially, it acts as a keep-alive or heartbeat mechanism for clients to validate their connection with the DiceDB server. + +## Errors -The return value varies based on the presence of the optional `[message]` parameter. +1. `Syntax Error`: If the syntax is incorrect, such as including unexpected additional parameters, an error will be raised: -- `No message provided`: If no message is provided, `PING` will return a simple string reply `PONG`. -- `Message provided`: If a message is provided, `PING` will return a simple string that echoes the given message. + - `Error message`: `(error) ERR wrong number of arguments for 'ping' command` + - `Scenario`: If more than one argument is provided. + + ```bash + 127.0.0.1:7379> PING "Message 1" "Message 2" + (error) ERR wrong number of arguments for 'ping' command + ``` ## Example Usage -### Example 1: Pinging the server without a message +### Basic Usage + +`PING` DiceDB server without a message and the server echoes with `PONG`. ```bash 127.0.0.1:7379> PING PONG ``` -### Example 2: Pinging the server with a message +### Pinging the server with a message + +DiceDB server is pinged with `Hello, DiceDB!` and the server echoes with `Hello, DiceDB!`. ```bash 127.0.0.1:7379> PING "Hello, DiceDB!" "Hello, DiceDB!" ``` -## Behaviour - -When the `PING` command is fired: +### Pinging the server with int message -1. If no message is given, it sends back a `PONG`. -1. If a message is provided, it sends back the same message in the response. +DiceDB server is pinged with `1234` and the server echoes with `"1234"` coerced to string internally. -This helps clients determine if the server is up and responsive. Essentially, it acts as a keep-alive or heartbeat mechanism for clients to validate their connection with the DiceDB server. - -## Error Handling - -### Potential Errors - -1. `Syntax Error`: If the syntax is incorrect, such as including unexpected additional parameters, an error will be raised: +```bash +127.0.0.1:7379> PING 1234 +"1234" +``` - - `Error message`: `(error) ERR wrong number of arguments for 'ping' command` - - `Scenario`: If more than one argument is provided. +### Pinging the server with list message - ```bash - > PING "Message 1" "Message 2" - (error) ERR wrong number of arguments for 'ping' command - ``` +DiceDB server is pinged with `[1234]` and the server echoes with `"[1234]"` coerced to string internally. -2. `Data Type Error`: If the argument provided is not a string (for example, if a list or other data type is provided), a type error will be raised. +```bash +127.0.0.1:7379> PING [1234] +"[1234]" +``` - - `Error message`: This specific type of error handling is internal, and improper types are generally implicitly converted or rejected by the protocol, raising basic syntax errors or allowing them based on DiceDB' internal type coercion rules. +### Invalid Usage -## Additional Notes +DiceDB server is pinged with multiple parameters `"hello" "world"` and the server echoes with error message as `"(error) ERR wrong number of arguments for 'ping' command"`. -- The `PING` command works similarly in both standalone and clustered DiceDB environments. -- It is typically sent periodically by clients to ensure the connection is still active. -- The `PING` command does not modify the data within the DiceDB server or affect any ongoing transactions. +```bash +127.0.0.1:7379> PING "hello" "world" +"(error) ERR wrong number of arguments for 'ping' command" +```