diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a9c1b31d6..f7dff5a93 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,9 +1,9 @@ -DiceDB welcomes your contributions! Whether you're fixing bugs, adding new features, or improving the documentation, your help is valuable. +DiceDB welcomes your contributions! Whether you're fixing bugs, adding new features, or improving the documentation, your help is valuable. To maintain the project's quality and consistency, please follow these guidelines: -- Keep the code consistent: Use the same coding style and conventions throughout the project. -- Keep the git repository consistent: Follow proper git practices to avoid conflicts and ensure a clean history. +- Keep the code consistent: Use the same coding style and conventions throughout the project. +- Keep the git repository consistent: Follow proper git practices to avoid conflicts and ensure a clean history. # Contribution Guidelines diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 4862694d9..92f70c968 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -26,7 +26,7 @@ export default defineConfig({ // }, { label: "SDK", - autogenerate: { directory: "sdk" }, + autogenerate: { directory: "sdk" }, }, { label: "Connection Protocols", diff --git a/docs/command_docs_template.md b/docs/command_docs_template.md index d370ee71c..20a7ecf06 100644 --- a/docs/command_docs_template.md +++ b/docs/command_docs_template.md @@ -2,6 +2,7 @@ title: description: description here in 2 to 3 lines --- + @@ -15,58 +16,67 @@ description: description here in 2 to 3 lines ## Parameters - -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| | | | | -| | | | | -| | | | | + +| Parameter | Description | Type | Required | +| --------- | ----------- | ---- | -------- | +| | | | | +| | | | | +| | | | | ## Return values + -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| | | -| | | -| | | +| Condition | Return Value | +| --------- | ------------ | +| | | +| | | +| | | ## Behaviour + + - Bullet 1 - Bullet 2 - Bullet 3 ## Errors + + 1. `Wrong type of value or key`: - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs when attempting to use the command on a key that contains a non-string value. - ## Example Usage + + ### Basic Usage + ```bash 127.0.0.1:7379> SET foo bar OK ``` + + ### Invalid usage ```bash @@ -81,20 +91,25 @@ OK + ## Best Practices + ## Alternatives -## Notes +## Notes + ## Subcommands + + - **subcommand**: Optional. Available subcommands include: - `subcommand1` : some description of the subcommand. diff --git a/docs/sample_command_docs.md b/docs/sample_command_docs.md index 3fc5d9ecc..bf0c692d9 100644 --- a/docs/sample_command_docs.md +++ b/docs/sample_command_docs.md @@ -2,7 +2,9 @@ title: SET description: The `SET` command in DiceDB is used to set the value of a key. If the key already holds a value, it is overwritten, regardless of its type. This is one of the most fundamental operations in DiceDB as it allows for both creating and updating key-value pairs. --- + + The `SET` command in DiceDB is used to set the value of a key. If the key already holds a value, it is overwritten, regardless of its type. This is one of the most fundamental operations in DiceDB as it allows for both creating and updating key-value pairs. ## Syntax @@ -10,13 +12,16 @@ The `SET` command in DiceDB is used to set the value of a key. If the key alread ```bash SET key value [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] [NX | XX] ``` + ## Parameters + + | Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| +| --------- | ------------------------------------------------------------------------- | ------- | -------- | | `key` | The name of the key to be set. | String | Yes | | `value` | The value to be set for the key. | String | Yes | | `EX` | Set the specified expire time, in seconds. | Integer | No | @@ -28,18 +33,21 @@ SET key value [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix | `KEEPTTL` | Retain the time-to-live associated with the key. | None | No | ## Return values + -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| if key is set successfully | `OK` | -| If `NX` is used and key already exists | `nil` | -| If `XX` is used and key doesn't exist | `nil` | +| Condition | Return Value | +| -------------------------------------- | ------------ | +| if key is set successfully | `OK` | +| If `NX` is used and key already exists | `nil` | +| If `XX` is used and key doesn't exist | `nil` | ## Behaviour + + - If the specified key already exists, the `SET` command will overwrite the existing key-value pair with the new value unless the `NX` option is provided. - If the `NX` option is present, the command will set the key only if it does not already exist. If the key exists, no operation is performed and `nil` is returned. - If the `XX` option is present, the command will set the key only if it already exists. If the key does not exist, no operation is performed and `nil` is returned. @@ -47,8 +55,8 @@ SET key value [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix - When provided, `EX` sets the expiry time in seconds and `PX` sets the expiry time in milliseconds. - The `KEEPTTL` option ensures that the key's existing TTL is retained. - ## Errors + @@ -71,6 +79,7 @@ SET key value [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix ## Example Usage ### Basic Usage + Setting a key `foo` with the value `bar` @@ -79,7 +88,9 @@ Setting a key `foo` with the value `bar` 127.0.0.1:7379> SET foo bar OK ``` + + ### Using expiration time (in seconds) Setting a key `foo` with the value `bar` to expire in 10 seconds @@ -141,6 +152,7 @@ Trying to set key `foo` with both `EX` and `KEEPTTL` will result in an error 127.0.0.1:7379> SET foo bar EX 10 KEEPTTL (error) ERR syntax error ``` + @@ -148,29 +160,41 @@ Trying to set key `foo` with both `EX` and `KEEPTTL` will result in an error + ## Best Practices + + - `Avoid in Production`: Due to its potential to slow down the server, avoid using the `KEYS` command in a production environment. Instead, consider using the `SCAN` command, which is more efficient for large keyspaces. - `Use Specific Patterns`: When using the `KEYS` command, try to use the most specific pattern possible to minimize the number of keys returned and reduce the load on the server. + ## Alternatives + + - `SCAN`: The `SCAN` command is a cursor-based iterator that allows you to incrementally iterate over the keyspace without blocking the server. It is a more efficient alternative to `KEYS` for large datasets. + ## Notes + + - JSONPath expressions allow you to navigate and retrieve specific parts of a JSON document. Ensure that your JSONPath expressions are correctly formatted to avoid errors. By understanding the `JSON.GET` command, you can efficiently retrieve JSON data stored in your DiceDB database, enabling you to build powerful and flexible applications that leverage the capabilities of DiceDB. + ## Subcommands + + - **subcommand**: Optional. Available subcommands include: - `COUNT` : Returns the total number of commands in the DiceDB server. - `GETKEYS` : Returns the keys from the provided command and arguments. diff --git a/docs/src/components/Footer.astro b/docs/src/components/Footer.astro index d6d612aef..64e6565aa 100644 --- a/docs/src/components/Footer.astro +++ b/docs/src/components/Footer.astro @@ -50,10 +50,7 @@ import { Github } from "lucide-astro"; Commands

- + Examples

@@ -69,10 +66,7 @@ import { Github } from "lucide-astro"; Examples

- + Real-time Leaderboard

@@ -88,9 +82,7 @@ import { Github } from "lucide-astro"; About Us

-->

- - Contact Us + Contact Us


diff --git a/docs/src/components/Hero.astro b/docs/src/components/Hero.astro index de14d026e..5f12163bc 100644 --- a/docs/src/components/Hero.astro +++ b/docs/src/components/Hero.astro @@ -4,31 +4,25 @@ import Dice from "./Dice.astro"; import site from "../data/site.json"; --- -

-
-
-
- - We shipped DiceDB v0.0.4 - - -
- DiceDB Logo -
-
-

Build truly real-time applications

-

- DiceDB is an in-memory, real-time, and reactive database with Redis and SQL support optimized for modern hardware and building real-time applications. +

+
+
+
+

a super cache;

+

+ DiceDB is a redis-compliant, scalable, highly available, unified cache + optimized for modern hardware + *

-
- +

+ docker run -p 7379:7379 dicedb/dicedb +

+
+ Get Started → GitHub (6k+)
-

- Want to evaluate and adopt DiceDB at your org? - block our calendar. +

+ * DiceDB is a work in progress; track + roadmap and follow along.

-
-
-
- -
diff --git a/docs/src/components/Nav.astro b/docs/src/components/Nav.astro index ade34a2f5..38f5a671e 100644 --- a/docs/src/components/Nav.astro +++ b/docs/src/components/Nav.astro @@ -36,19 +36,19 @@ import SocialHandlesIcons from "./SocialHandlesIcons.astro"; class={`navbar-item ${currentPage === "benchmarks" && "is-active"}`} href="/benchmarks" > - Benchmarks + Benchmarks - Docs + Docs - Blog + Blog
diff --git a/docs/src/content/blog/dicedb-is-redis-replacement.md b/docs/src/content/blog/dicedb-is-redis-replacement.md new file mode 100644 index 000000000..3b6b35fe4 --- /dev/null +++ b/docs/src/content/blog/dicedb-is-redis-replacement.md @@ -0,0 +1,30 @@ +--- +title: "Why DiceDB chose to be a Redis replacement?" +description: "Redis has become synonymous with in-memory caching, creating an ecosystem of tools, best practices, and mental models that many engineers already know well. Redis's simplicity and reliability have helped it scale across countless production systems, so building a completely new caching paradigm risked reinventing the wheel." +published_at: 2024-11-04 +author: arpit +--- + +Redis has become synonymous with in-memory caching, creating an ecosystem of tools, best practices, and mental models that many engineers already know well. Redis's simplicity and reliability have helped it scale across countless production systems, so building a completely new caching paradigm risked reinventing the wheel. + +Instead, we focused on delivering a solution that would align closely with Redis's familiarity while introducing major improvements for modern applications. Here’s why we chose to position DiceDB as a Redis-compatible replacement. + +# Redis Compatibility for Easy Adoption + +Adoption hurdles for new databases are often high. Engineers and developers must rework existing codebases, learn new APIs, and update dependencies, all of which introduce friction and slow down adoption. By making DiceDB Redis-compatible, we enable engineers and developers to start with minimal modifications and existing code often works as-is. This seamless integration not only reduces migration costs but also empowers teams to leverage DiceDB without substantial rewrites or operational overhead. + +# Targeting Redis’s Architectural Gaps + +Redis was designed over a decade ago, before multi-core systems became as prevalent and powerful as they are today. [Redis's single-threaded](https://redis.io/learn/operate/redis-at-scale/talking-to-redis/redis-server-overview) event loop approach, while effective in its time, does not fully harness the compute potential of modern, multi-core hardware. We identified this architectural gap as [a bottleneck](/benchmarks), limiting Redis's throughput on today's processors. + +![DiceDB vs Redis - Throughput vs Number of Cores](https://github.com/user-attachments/assets/367f25c8-bc59-4787-bb37-63fd5d4314e4) + +Following in the footsteps of architectures like [DragonflyDB](https://www.youtube.com/watch?v=XbV1LoVsbME), DiceDB employs a multi-threaded architecture that can more efficiently utilize all CPU cores, resulting in higher throughput and significantly better resource utilization. This design choice allows DiceDB to serve high-request-rate applications with lower latency and greater efficiency, without the need to sacrifice the familiar simplicity of Redis commands. + +# Building Toward Horizontal Scalability + +Unlike solutions that push single-node performance limits, DiceDB's goal is to serve as a unified, horizontally scalable cache capable of holding and querying large volumes of cached data across distributed systems and microservices. DiceDB's architecture is designed to scale out and up both, enabling applications to get max out of single node while being able to add nodes dynamically as demand increases. This approach provides a more practical path to scaling for large applications. + +# End + +By addressing these architectural limitations, DiceDB aims to be more than just a faster Redis clone. It's designed to be the foundational infrastructure for the next generation of applications and micro-services offering Redis familiarity combined with high performance and scalability across distributed environments. diff --git a/docs/src/content/docs/commands/APPEND.md b/docs/src/content/docs/commands/APPEND.md index 675fc8857..8ada6fd98 100644 --- a/docs/src/content/docs/commands/APPEND.md +++ b/docs/src/content/docs/commands/APPEND.md @@ -2,6 +2,7 @@ title: APPEND description: The `APPEND` command in DiceDB is used to either set the value of a key or append a value to an existing key. This command allows for both creating and updating key-value pairs. --- + The `APPEND` command in DiceDB is used to either set the value of a key or append a value to an existing key. This command allows for both creating and updating key-value pairs. ## Syntax @@ -11,23 +12,25 @@ APPEND key value ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The name of the key to be set. | String | Yes | -| `value` | The value to be set for the key. | String | Yes | + +| Parameter | Description | Type | Required | +| --------- | -------------------------------- | ------ | -------- | +| `key` | The name of the key to be set. | String | Yes | +| `value` | The value to be set for the key. | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| if key is set successfully | length of the string. | +| Condition | Return Value | +| -------------------------- | --------------------- | +| if key is set successfully | length of the string. | ## Behaviour -- If the specified key does not exist, the `APPEND` command will create a new key-value pair. -- If the specified key already exists, the `APPEND` command will append the value to the existing value of the key. +- If the specified key does not exist, the `APPEND` command will create a new key-value pair. +- If the specified key already exists, the `APPEND` command will append the value to the existing value of the key. ## Errors + 1. `Wrong type of value or key`: - Error Message: `(error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value` @@ -49,7 +52,7 @@ Setting a key `foo` with the value `bar` using `APPEND` (integer) 3 ``` -Appending to key `foo` that contains `bar` with `baz` +Appending to key `foo` that contains `bar` with `baz` ```bash 127.0.0.1:7379> SET foo bar @@ -65,9 +68,11 @@ Trying to use `APPEND` without giving the value 127.0.0.1:7379> APPEND foo (error) ERROR wrong number of arguments for 'append' command ``` + Trying to use `APPEND` on a invalid data type. + ```bash 127.0.0.1:7379> LPUSH foo bar 127.0.0.1:7379> APPEND foo baz (error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/commands/AUTH.md b/docs/src/content/docs/commands/AUTH.md index c2867b735..537141c2a 100644 --- a/docs/src/content/docs/commands/AUTH.md +++ b/docs/src/content/docs/commands/AUTH.md @@ -7,22 +7,22 @@ The `AUTH` command is a DiceDB command that enables you to authenticate a client ## Syntax -``` +```bash AUTH password ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `password`| The password that you have set for the DiceDB server. | String | Yes | +| Parameter | Description | Type | Required | +| ---------- | ----------------------------------------------------- | ------ | -------- | +| `password` | The password that you have set for the DiceDB server. | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Authentication is successful | `OK` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------ | +| Authentication is successful | `OK` | +| Syntax or specified constraints are invalid | error | ## Behaviour diff --git a/docs/src/content/docs/commands/BF.ADD.md b/docs/src/content/docs/commands/BF.ADD.md index 94999d7f2..b4b987e92 100644 --- a/docs/src/content/docs/commands/BF.ADD.md +++ b/docs/src/content/docs/commands/BF.ADD.md @@ -13,17 +13,17 @@ BF.ADD key item ## Parameters -| Parameter | Description | Type | Required | -|-----------|--------------------------------------------------|--------|----------| +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------- | ------ | -------- | | `key` | The name of the Bloom Filter to which the item will be added. | String | Yes | -| `item` | The item to be added to the Bloom Filter. | String | Yes | +| `item` | The item to be added to the Bloom Filter. | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Item was not already present in the Bloom Filter | `1` | -| Item was already present in the Bloom Filter (could be wrong) | `0` | +| Condition | Return Value | +| ------------------------------------------------------------- | ------------ | +| Item was not already present in the Bloom Filter | `1` | +| Item was already present in the Bloom Filter (could be wrong) | `0` | ## Behaviour @@ -34,12 +34,12 @@ When the `BF.ADD` command is executed, the specified item is added to the Bloom ## Errors -1. `Incorrect number of arguments`: - - Error message: `(error) ERR wrong number of arguments for 'BF.ADD' command` - - The command requires exactly two arguments: the key and the item to be added to the Bloom Filter. +1. `Incorrect number of arguments`: + - Error message: `(error) ERR wrong number of arguments for 'BF.ADD' command` + - The command requires exactly two arguments: the key and the item to be added to the Bloom Filter. 2. `Key is not a Bloom Filter`: - - Error message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - - The specified key does not refer to a Bloom Filter. + - Error message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - The specified key does not refer to a Bloom Filter. ## Example Usage diff --git a/docs/src/content/docs/commands/BF.EXISTS.md b/docs/src/content/docs/commands/BF.EXISTS.md index 1625b07a9..54c1b9c36 100644 --- a/docs/src/content/docs/commands/BF.EXISTS.md +++ b/docs/src/content/docs/commands/BF.EXISTS.md @@ -13,19 +13,18 @@ BF.EXISTS key item ## Parameters -| Parameter | Description | Type | Required | -|-----------|-----------------------------------------------------------------------------|--------|----------| -| `key` | The key under which the Bloom Filter is stored. | String | Yes | -| `item` | The item to check for existence in the Bloom Filter. | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ---------------------------------------------------- | ------ | -------- | +| `key` | The key under which the Bloom Filter is stored. | String | Yes | +| `item` | The item to check for existence in the Bloom Filter. | String | Yes | ## Return Value -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Item may exist in the Bloom Filter | `1` | -| Item definitely does not exist in the Bloom Filter | `0` | -| Key does not exist | `0` | +| Condition | Return Value | +| -------------------------------------------------- | ------------ | +| Item may exist in the Bloom Filter | `1` | +| Item definitely does not exist in the Bloom Filter | `0` | +| Key does not exist | `0` | ## Behaviour @@ -37,22 +36,22 @@ When the `BF.EXISTS` command is executed, it checks the Bloom Filter associated ## Errors The `BF.EXISTS` command can raise errors in the following scenarios: -1. `Incorrect number of arguments`: - - Error message: `(error) ERR wrong number of arguments for 'bf.exists' command` - - The command requires exactly two arguments: the key and the item to check for existence in the Bloom Filter. -2. `Key is not a Bloom Filter`: - - Error message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - - The specified key does not refer to a Bloom Filter. +1. `Incorrect number of arguments`: + - Error message: `(error) ERR wrong number of arguments for 'bf.exists' command` + - The command requires exactly two arguments: the key and the item to check for existence in the Bloom Filter. +2. `Key is not a Bloom Filter`: + - Error message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - The specified key does not refer to a Bloom Filter. ## Example Usage ### Checking for an existing item ```bash -127.0.0.1:6379> BF.ADD myBloomFilter "apple" +127.0.0.1:7379> BF.ADD myBloomFilter "apple" (integer) 1 -127.0.0.1:6379> BF.EXISTS myBloomFilter "apple" +127.0.0.1:7379> BF.EXISTS myBloomFilter "apple" (integer) 1 ``` @@ -61,7 +60,7 @@ In this example, the item "apple" is added to the Bloom Filter `myBloomFilter`. ### Checking for a non-existing item ```bash -127.0.0.1:6379> BF.EXISTS myBloomFilter "banana" +127.0.0.1:7379> BF.EXISTS myBloomFilter "banana" (integer) 0 ``` @@ -70,7 +69,7 @@ In this example, the item "banana" is checked in the Bloom Filter `myBloomFilter ### Handling a non-existing key ```bash -127.0.0.1:6379> BF.EXISTS nonExistingKey "apple" +127.0.0.1:7379> BF.EXISTS nonExistingKey "apple" (integer) 0 ``` @@ -79,9 +78,9 @@ In this example, the key `nonExistingKey` does not exist in the database. The co ### Handling a wrong type of key ```bash -127.0.0.1:6379> SET myString "hello" +127.0.0.1:7379> SET myString "hello" OK -127.0.0.1:6379> BF.EXISTS myString "apple" +127.0.0.1:7379> BF.EXISTS myString "apple" (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` @@ -90,7 +89,7 @@ In this example, the key `myString` is associated with a string value, not a Blo ### Incorrect number of arguments ```bash -127.0.0.1:6379> BF.EXISTS myBloomFilter +127.0.0.1:7379> BF.EXISTS myBloomFilter (error) ERR wrong number of arguments for 'bf.exists' command ``` diff --git a/docs/src/content/docs/commands/BF.INFO.md b/docs/src/content/docs/commands/BF.INFO.md index f3f361740..168c3655d 100644 --- a/docs/src/content/docs/commands/BF.INFO.md +++ b/docs/src/content/docs/commands/BF.INFO.md @@ -2,8 +2,10 @@ title: BF.INFO description: Documentation for the DiceDB command BF.INFO --- + -BF.INFO command is used to get the information about the Bloom Filter key. + +BF.INFO command is used to get the information about the Bloom Filter key. ## Syntax @@ -12,26 +14,25 @@ BF.INFO key [CAPACITY | SIZE | FILTERS | ITEMS | EXPANSION] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The name of the Bloom Filter key to get information about. | string | Yes | -| `CAPACITY` | Optional. Returns the capacity of the Bloom Filter. | string | No | -| `SIZE` | Optional. Returns the size of the Bloom Filter. | string | No | -| `FILTERS` | Optional. Returns the number of filters in the Bloom Filter. | string | No | -| `ITEMS` | Optional. Returns the number of items added to the Bloom Filter. | string | No | -| `EXPANSION` | Optional. Returns the expansion factor of the Bloom Filter. | string | No | - -Only one of the optional parameters can be used at a time. +| Parameter | Description | Type | Required | +| ----------- | ---------------------------------------------------------------- | ------ | -------- | +| `key` | The name of the Bloom Filter key to get information about. | string | Yes | +| `CAPACITY` | Optional. Returns the capacity of the Bloom Filter. | string | No | +| `SIZE` | Optional. Returns the size of the Bloom Filter. | string | No | +| `FILTERS` | Optional. Returns the number of filters in the Bloom Filter. | string | No | +| `ITEMS` | Optional. Returns the number of items added to the Bloom Filter. | string | No | +| `EXPANSION` | Optional. Returns the expansion factor of the Bloom Filter. | string | No | +Only one of the optional parameters can be used at a time. ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command executed successfully | Information about the Bloom Filter as an array with capacity, size, filters, items, expansion rate | -| If an optional parameter is used | Information about the specific parameter | -| Error such as invalid number of arguments, invalid parameters | `(error)` |, +| Condition | Return Value | +| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --- | +| Command executed successfully | Information about the Bloom Filter as an array with capacity, size, filters, items, expansion rate | +| If an optional parameter is used | Information about the specific parameter | +| Error such as invalid number of arguments, invalid parameters | `(error)` | , | ## Behaviour @@ -48,11 +49,11 @@ Only one of the optional parameters can be used at a time. - Error Message: `(error) ERR wrong number of arguments for 'bf.info' command` - Occurs when the command is not provided with the correct number of arguments. 3. `Invalid parameter`: - - Error Message: `(error) ERR invalid parameter` - - Occurs when an invalid parameter is provided with the command. + - Error Message: `(error) ERR invalid parameter` + - Occurs when an invalid parameter is provided with the command. 4. `Key does not exist`: - - Error Message: `(error) ERR not found` - - Occurs when the specified key does not exist in the database. + - Error Message: `(error) ERR not found` + - Occurs when the specified key does not exist in the database. ## Example Usage @@ -71,8 +72,11 @@ Only one of the optional parameters can be used at a time. 9) Expansion 10) 2 ``` + ### Getting Capacity + + ```bash 127.0.0.1:7379> BF.INFO myBloomFilter CAPACITY 1) Capacity @@ -105,16 +109,15 @@ OK ## Notes 1. The `CAPACITY` parameter returns the capacity of the Bloom Filter. - - The capacity is the maximum number of elements that can be added to the Bloom Filter. + - The capacity is the maximum number of elements that can be added to the Bloom Filter. 2. The `SIZE` parameter returns the size of the Bloom Filter. - - The size is the number of bits used in the Bloom Filter. + - The size is the number of bits used in the Bloom Filter. 3. The `FILTERS` parameter returns the number of filters in the Bloom Filter. - - The number of filters is the number of hash functions used in the Bloom Filter. - - The number of filters is also the number of bits set to 1 when an element is added to the Bloom Filter. - - More filters reduce the false positive rate but increase the memory usage. + - The number of filters is the number of hash functions used in the Bloom Filter. + - The number of filters is also the number of bits set to 1 when an element is added to the Bloom Filter. + - More filters reduce the false positive rate but increase the memory usage. 4. The `ITEMS` parameter returns the number of items added to the Bloom Filter. - - The number of items is the total number of elements added to the Bloom Filter. + - The number of items is the total number of elements added to the Bloom Filter. 5. The `EXPANSION` parameter returns the expansion factor of the Bloom Filter. - - The expansion factor is the ratio of the number of bits in the Bloom Filter to the number of elements added to the Bloom Filter. - - A higher expansion factor indicates a higher false positive rate. - + - The expansion factor is the ratio of the number of bits in the Bloom Filter to the number of elements added to the Bloom Filter. + - A higher expansion factor indicates a higher false positive rate. diff --git a/docs/src/content/docs/commands/BF.RESERVE.md b/docs/src/content/docs/commands/BF.RESERVE.md index e240cdba1..6079a0802 100644 --- a/docs/src/content/docs/commands/BF.RESERVE.md +++ b/docs/src/content/docs/commands/BF.RESERVE.md @@ -13,19 +13,18 @@ BF.RESERVE key [options] ## Parameters -| Parameter | Description | Type | Required | -|---|---|---|---| -| `key` | The key under which the Bloom Filter will be stored. | String | Yes | -| `error_rate` | The desired probability of false positives. The default value is 0.01 (1%). | Float | No | -| `initial_capacity` | The initial capacity of the Bloom Filter. The default value is 1000 elements. | Integer | No | +| Parameter | Description | Type | Required | +| ------------------ | ----------------------------------------------------------------------------- | ------- | -------- | +| `key` | The key under which the Bloom Filter will be stored. | String | Yes | +| `error_rate` | The desired probability of false positives. The default value is 0.01 (1%). | Float | No | +| `initial_capacity` | The initial capacity of the Bloom Filter. The default value is 1000 elements. | Integer | No | ## Return Value -| Condition | Return Value | -|---|---| -| Command successful | Simple string reply: `OK` | -| Unsuccessful command | `error` | - +| Condition | Return Value | +| -------------------- | ------------------------- | +| Command successful | Simple string reply: `OK` | +| Unsuccessful command | `error` | ## Behaviour @@ -33,25 +32,35 @@ When the `BF.RESERVE` command is executed, DiceDB will create a new Bloom Filter ## Errors -1. `Incorrect Number of Arguments`: - - Error message: `(error) ERR wrong number of arguments for 'BF.RESERVE' command` - - This error occurs when the command does not have the correct number of arguments. -2. `Invalid Error Rate Range`: - - Error message: `(error) Err (0 < error rate range < 1) ` - - This error occurs when the error rate is not within the valid range (0, 1). +1. `Incorrect Number of Arguments`: + +- Error message: `(error) ERR wrong number of arguments for 'BF.RESERVE' command` +- This error occurs when the command does not have the correct number of arguments. + +2. `Invalid Error Rate Range`: + +- Error message: `(error) Err (0 < error rate range < 1) ` +- This error occurs when the error rate is not within the valid range (0, 1). + 3. `Invalid Initial Capacity`: - - Error message: `(error) ERR (capacity should be larger than 0)` - - This error occurs when the initial capacity is not a valid positive integer. + +- Error message: `(error) ERR (capacity should be larger than 0)` +- This error occurs when the initial capacity is not a valid positive integer. + 4. `Invalid Data Type`: - - Error message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - - This error occurs when the key is already associated with a value of a different data type. + +- Error message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` +- This error occurs when the key is already associated with a value of a different data type. + 5. `Bad error rate`: - - Error message: `(error) ERR bad error rate` - - This error occurs when the error rate is not a valid float value. + +- Error message: `(error) ERR bad error rate` +- This error occurs when the error rate is not a valid float value. + 6. `Bad initial capacity`: - - Error message: `(error) ERR bad capacity` - - This error occurs when the initial capacity is not a valid integer value. +- Error message: `(error) ERR bad capacity` +- This error occurs when the initial capacity is not a valid integer value. ## Example Usage @@ -61,6 +70,7 @@ When the `BF.RESERVE` command is executed, DiceDB will create a new Bloom Filter 127.0.0.1:7379> BF.RESERVE my_bloom_filter 0.005 5000 OK ``` + This command initializes a Bloom Filter named `my_bloom_filter` with an error rate of 0.005 (0.5%) and an initial capacity of 5000 elements. ### Wrong Data Error @@ -89,5 +99,3 @@ This sequence of commands will result in an error because `my_bloom_filter` is a ``` This command will result in an error because the initial capacity is not a valid positive integer. - - diff --git a/docs/src/content/docs/commands/BGREWRITEAOF.md b/docs/src/content/docs/commands/BGREWRITEAOF.md index 2e93a608c..ba6af7dc9 100644 --- a/docs/src/content/docs/commands/BGREWRITEAOF.md +++ b/docs/src/content/docs/commands/BGREWRITEAOF.md @@ -7,16 +7,16 @@ The `BGREWRITEAOF` command in DiceDB is used to asynchronously rewrite the Appen ## Syntax -``` +```bash BGREWRITEAOF ``` ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | `OK` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------ | +| Command is successful | `OK` | +| Syntax or specified constraints are invalid | error | ## Behaviour @@ -42,7 +42,8 @@ When the `BGREWRITEAOF` command is issued, DiceDB performs the following steps: ## Example Usage ### Basic Usage -```sh + +```bash 127.0.0.1:7379> BGREWRITEAOF OK ``` diff --git a/docs/src/content/docs/commands/BITCOUNT.md b/docs/src/content/docs/commands/BITCOUNT.md index f8ff0e540..cd65f6beb 100644 --- a/docs/src/content/docs/commands/BITCOUNT.md +++ b/docs/src/content/docs/commands/BITCOUNT.md @@ -7,34 +7,33 @@ The `BITCOUNT` command in DiceDB is used to count the number of set bits (i.e., ## Syntax -``` +```bash BITCOUNT key [start end [BYTE | BIT]] ``` - By default, the `start` and `end` parameters are byte positions, but we can use an additional argument BIT to specify a bit position. - Negative values for `start` and `end` are interpreted as offsets from the end of the string. For example, -1 means the last byte/bit, -2 means the second last byte/bit, and so on. - ## Parameters -| Parameter | Description | Type | Required | Default | -|-----------|---------------------------------------------------------------------------|---------|----------|---------| -| `key` | The key of the string for which the bit count is to be calculated. | String | Yes | | -| `start` | The starting byte/bit position (inclusive) to count the bits. | Integer | No | 0 | -| `end` | The ending byte/bit position (inclusive) to count the bits. | Integer | No | -1(end) | -| `BYTE` | Use the specified range as byte indices | String | No | | -| `BIT` | Use the specified ragne as bit indices | String | No | | +| Parameter | Description | Type | Required | Default | +| --------- | ------------------------------------------------------------------ | ------- | -------- | ------- | +| `key` | The key of the string for which the bit count is to be calculated. | String | Yes | | +| `start` | The starting byte/bit position (inclusive) to count the bits. | Integer | No | 0 | +| `end` | The ending byte/bit position (inclusive) to count the bits. | Integer | No | -1(end) | +| `BYTE` | Use the specified range as byte indices | String | No | | +| `BIT` | Use the specified ragne as bit indices | String | No | | ## Return Value The `BITCOUNT` command returns an integer representing the number of bits set to 1 in the specified range of the string. -| Condition | Return Value | -|------------------------------------------------|-----------------------------------------------------------------------------------------| -| Command is successful | number of bits set to 1 in the specified range of the string | -| Non-existent key | `0` | -| Out of range indices | no. of set bits based on the valid range (if any) inside the specified range | -| Invalid syntax / wrong key type | error | +| Condition | Return Value | +| ------------------------------- | ---------------------------------------------------------------------------- | +| Command is successful | number of bits set to 1 in the specified range of the string | +| Non-existent key | `0` | +| Out of range indices | no. of set bits based on the valid range (if any) inside the specified range | +| Invalid syntax / wrong key type | error | ## Behaviour @@ -58,7 +57,7 @@ When the `BITCOUNT` command is executed, DiceDB will: (integer) 0 ``` -2. `Wrong Type of Key`: +2. `Wrong Type of Key`: - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs if the key exists but does not hold a string value @@ -89,7 +88,6 @@ When the `BITCOUNT` command is executed, DiceDB will: (error) ERR value is not an integer or out of range ``` - 4. `Out of Range Indices`: - Error Message: None (will be handled gracefully by considering the valid range within the string) @@ -123,6 +121,7 @@ OK 127.0.0.1:7379> BITCOUNT mykey 1 3 (integer) 15 ``` + In this example, the command counts the bits set to 1 in the bytes from position 1 to 3 (inclusive) of the string "foobar". ### Example 3: Counting bits in a specified range using bit indices @@ -133,4 +132,5 @@ OK 127.0.0.1:7379> BITCOUNT mykey 8 31 BIT (integer) 15 ``` + In this example, the command counts the bits set to 1 in the bit ranges from position 8 to 31 (inclusive) of the string "foobar". diff --git a/docs/src/content/docs/commands/BITOP.md b/docs/src/content/docs/commands/BITOP.md index ecfdc63d5..239efeb3e 100644 --- a/docs/src/content/docs/commands/BITOP.md +++ b/docs/src/content/docs/commands/BITOP.md @@ -7,7 +7,7 @@ The `BITOP` command in DiceDB is used to perform bitwise operations between stri ## Syntax -```plaintext +```bash BITOP operation destkey key [key ...] ``` @@ -60,7 +60,7 @@ The `BITOP` command can raise errors in the following cases: ### Example 1: Bitwise AND Operation -```plaintext +```bash SET key1 "foo" SET key2 "bar" BITOP AND result key1 key2 @@ -76,7 +76,7 @@ GET result ### Example 2: Bitwise OR Operation -```plaintext +```bash SET key1 "foo" SET key2 "bar" BITOP OR result key1 key2 @@ -92,7 +92,7 @@ GET result ### Example 3: Bitwise XOR Operation -```plaintext +```bash SET key1 "foo" SET key2 "bar" BITOP XOR result key1 key2 @@ -108,7 +108,7 @@ GET result ### Example 4: Bitwise NOT Operation -```plaintext +```bash SET key1 "foo" BITOP NOT result key1 GET result diff --git a/docs/src/content/docs/commands/BITPOS.md b/docs/src/content/docs/commands/BITPOS.md index 5cc85b895..9fb738997 100644 --- a/docs/src/content/docs/commands/BITPOS.md +++ b/docs/src/content/docs/commands/BITPOS.md @@ -7,7 +7,7 @@ The `BITPOS` command in DiceDB is used to find the position of the first bit set ## Syntax -```plaintext +```bash BITPOS key bit [start] [end] ``` @@ -49,14 +49,14 @@ The `BITPOS` command can raise errors in the following cases: Find the position of the first bit set to 1 in the string stored at key `mykey`: -```plaintext +```bash SET mykey "foobar" BITPOS mykey 1 ``` `Output`: -```plaintext +```bash 6 ``` @@ -64,14 +64,14 @@ BITPOS mykey 1 Find the position of the first bit set to 0 in the string stored at key `mykey`, starting from byte position 2 and ending at byte position 4: -```plaintext +```bash SET mykey "foobar" BITPOS mykey 0 2 4 ``` `Output`: -```plaintext +```bash 16 ``` @@ -79,14 +79,14 @@ BITPOS mykey 0 2 4 If the specified bit is not found within the specified range, the command returns -1: -```plaintext +```bash SET mykey "foobar" BITPOS mykey 1 2 4 ``` `Output`: -```plaintext +```bash -1 ``` @@ -96,14 +96,14 @@ BITPOS mykey 1 2 4 Attempting to use `BITPOS` on a key that holds a non-string value: -```plaintext +```bash LPUSH mylist "item" BITPOS mylist 1 ``` `Output`: -```plaintext +```bash (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` @@ -111,14 +111,14 @@ BITPOS mylist 1 Using a bit value other than 0 or 1: -```plaintext +```bash SET mykey "foobar" BITPOS mykey 2 ``` `Output`: -```plaintext +```bash (error) ERR bit is not an integer or out of range ``` @@ -126,13 +126,13 @@ BITPOS mykey 2 Using non-integer values for the `start` or `end` parameters: -```plaintext +```bash SET mykey "foobar" BITPOS mykey 1 "a" "b" ``` `Output`: -```plaintext +```bash (error) ERR value is not an integer or out of range ``` diff --git a/docs/src/content/docs/commands/COPY.md b/docs/src/content/docs/commands/COPY.md index 7a25d9b4d..891ecafd5 100644 --- a/docs/src/content/docs/commands/COPY.md +++ b/docs/src/content/docs/commands/COPY.md @@ -12,20 +12,20 @@ COPY [DB destination-db] [REPLACE] ``` ## Parameters -|Parameter | Description | Type | Required| -|----------|-------------|------|:---------:| -| source |The key of the value you want to copy. This key must exist. | String | Yes| -| destination | The key where the value will be copied to. This key must not exist unless the `REPLACE` option is specified. | String | Yes | -|DB destination-db|The database number where the destination key will be created. If not specified, the destination key will be created in the same database as the source key. | Integer | optional| -|REPLACE|If specified, the command will overwrite the destination key if it already exists.| String | Optional| +| Parameter | Description | Type | Required | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | :------: | +| source | The key of the value you want to copy. This key must exist. | String | Yes | +| destination | The key where the value will be copied to. This key must not exist unless the `REPLACE` option is specified. | String | Yes | +| DB destination-db | The database number where the destination key will be created. If not specified, the destination key will be created in the same database as the source key. | Integer | optional | +| REPLACE | If specified, the command will overwrite the destination key if it already exists. | String | Optional | ## Return Value -| Condition | Return Value | -|-----------| :-------------:| -| key was copied successfully | `1` | -| key was not copied | `0` | +| Condition | Return Value | +| --------------------------- | :----------: | +| key was copied successfully | `1` | +| key was not copied | `0` | ## Behaviour @@ -41,13 +41,13 @@ When the `COPY` command is executed, DiceDB will: The `COPY` command can raise the following errors: -1. `Wrong type of value or key`: - - Error message `(error) WRONGTYPE Operation against a key holding the wrong kind of value`: - - This error occurs if the source key holds a value that is not compatible with the `COPY` operation. -2. `Not existent key`: - - Error message: `(error) ERR no such key` - - This error occurs if the source key does not exist. - - This error occurs if the destination key already exists and the `REPLACE` option is not specified. +1. `Wrong type of value or key`: + - Error message `(error) WRONGTYPE Operation against a key holding the wrong kind of value`: + - This error occurs if the source key holds a value that is not compatible with the `COPY` operation. +2. `Not existent key`: + - Error message: `(error) ERR no such key` + - This error occurs if the source key does not exist. + - This error occurs if the destination key already exists and the `REPLACE` option is not specified. ## Example Usage @@ -69,8 +69,7 @@ Copy the value from `key1` to `key2`, replacing `key2` if it already exists. (integer) 1 ``` - -### Not-Existent Source Key +### Not-Existent Source Key ```bash 127.0.0.1:7379> COPY nonexistent key2 @@ -78,18 +77,19 @@ Copy the value from `key1` to `key2`, replacing `key2` if it already exists. ``` ### Destination key already exist + ```bash 127.0.0.1:7379> COPY key1 key2 (integer) 1 127.0.0.1:7379> COPY key1 key2 -(integer) 0 +(integer) 0 ``` + ## Notes - The `COPY` command is available starting from DiceDB version 6.2. - The `COPY` command is atomic, meaning that the copy operation is performed as a single, indivisible operation. - The `COPY` command does not modify the source key; it only duplicates its value to the destination key. - The `DB destinationDB` is not yet supported with the current versions of DiceDB. It acts as a placeholder for now. It will still return `0` -By understanding the `COPY` command and its parameters, you can effectively duplicate keys within your DiceDB databases, ensuring data consistency and reducing the need for manual data manipulation. - + By understanding the `COPY` command and its parameters, you can effectively duplicate keys within your DiceDB databases, ensuring data consistency and reducing the need for manual data manipulation. diff --git a/docs/src/content/docs/commands/DBSIZE.md b/docs/src/content/docs/commands/DBSIZE.md index 92302c960..b17c2eb41 100644 --- a/docs/src/content/docs/commands/DBSIZE.md +++ b/docs/src/content/docs/commands/DBSIZE.md @@ -3,11 +3,13 @@ title: DBSIZE description: The `DBSIZE` command in DiceDB returns the number of keys in the currently selected database, providing a quick way to understand the size of your database. --- +> **Important Note:** As of the current version, DiceDB does not support multiple databases. Therefore, while the documentation mentions database selection via the `SELECT` command, all operations occur on a single database space. + The `DBSIZE` command in DiceDB is used to return the number of keys in the currently selected database. This command is useful for monitoring and managing the size of your DiceDB database, providing a quick way to understand the number of keys stored. ## Syntax -``` +```bash DBSIZE ``` @@ -31,10 +33,11 @@ The `DBSIZE` command does not take any parameters. - If multiple databases are in use, `DBSIZE` will only count keys in the currently selected database. ## Errors -The `DBSIZE` command is straightforward and does not typically result in errors under normal usage. However, there are a few scenarios where errors might be encountered: +The `DBSIZE` command is straightforward and does not typically result in errors under normal usage. However, there are a few scenarios where errors might be encountered: 1. `Connection Issues`: + - Error Message: `ERR Connection lost` - Occurs when there is a problem with the connection to the DiceDB server. @@ -48,7 +51,7 @@ The `DBSIZE` command is straightforward and does not typically result in errors Getting the number of keys in the currently selected database: -```shell +```bash 127.0.0.1:7379> DBSIZE (integer) 42 ``` @@ -57,9 +60,9 @@ In this example, the currently selected database contains 42 keys. ### Using with Multiple Databases -If you are working with multiple databases, you can switch between them using the `SELECT` command and then use `DBSIZE` to get the number of keys in each database: +While the following example shows the traditional syntax for working with multiple databases, please note that in the current version of DiceDB, all operations occur on a single database space: -```shell +```bash 127.0.0.1:7379> SELECT 0 OK 127.0.0.1:7379> DBSIZE @@ -68,16 +71,20 @@ OK 127.0.0.1:7379> SELECT 1 OK 127.0.0.1:7379> DBSIZE -(integer) 15 +(integer) 42 ``` -In this example, database 0 contains 42 keys, and database 1 contains 15 keys. +In the current implementation, both commands will return the same count as they operate on the same database space. ### Error Scenarios 1. Attempting to use `DBSIZE` without proper authentication: -```shell +```bash 127.0.0.1:7379> DBSIZE (error) NOAUTH Authentication required ``` + +## Notes + +As mentioned at the beginning of this document, the current version of DiceDB operates on a single database space. While the `SELECT` command is available as a placeholder, switching databases will not affect the operation of the `DBSIZE` command, and it will always return the count of keys from the single available database space. diff --git a/docs/src/content/docs/commands/DECR.md b/docs/src/content/docs/commands/DECR.md index 73d6f941b..75f583be6 100644 --- a/docs/src/content/docs/commands/DECR.md +++ b/docs/src/content/docs/commands/DECR.md @@ -7,22 +7,22 @@ The `DECR` command in DiceDB is used to decrement the integer value of a key by ## Syntax -```plaintext +```bash DECR key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|--------------------------------------------------|---------|----------| -| `key` | The key whose value you want to decrement. This key must hold a string that can be represented as an integer. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key whose value you want to decrement. This key must hold a string that can be represented as an integer. | String | Yes | ## Return Value -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | `Integer`: The new value of the key after the decrement operation. | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------------------------------------------------------------ | +| Command is successful | `Integer`: The new value of the key after the decrement operation. | +| Syntax or specified constraints are invalid | error | ## Behaviour @@ -38,7 +38,7 @@ When the `DECR` command is executed, the following steps occur: The `DECR` command can raise errors in the following scenarios: 1. `Wrong Type Error`: If the key exists but the value is not a string that can be represented as an integer, DiceDB will return an error. - - `Error Message`: `(error) ERR value is not an integer or out of range` + - `Error Message`: `(error) ERR value is not an integer or out of range` 1. `Out of Range Error`: If the value of the key is out of the range of a 64-bit signed integer after the decrement operation, DiceDB will return an error. - `Error Message`: `(error) ERR increment or decrement would overflow` @@ -58,7 +58,6 @@ OK 1. The `SET` command initializes the key `mycounter` with the value `10`. 2. The `DECR` command decrements the value of `mycounter` by 1, resulting in `9`. - ### Key Does Not Exist ```bash @@ -71,7 +70,6 @@ OK 1. The key `newcounter` does not exist. 2. DiceDB sets `newcounter` to `0` and then decrements it by 1, resulting in `-1`. - ### Error Scenario: Non-Integer Value ```bash @@ -86,7 +84,6 @@ OK 1. The `SET` command initializes the key `mystring` with the value `"hello"`. 2. The `DECR` command attempts to decrement the value of `mystring`, but since it is not an integer, an error is raised. - ### Error Scenario: Out of Range ```bash diff --git a/docs/src/content/docs/commands/DECRBY.md b/docs/src/content/docs/commands/DECRBY.md index 0372b876e..6a29a6781 100644 --- a/docs/src/content/docs/commands/DECRBY.md +++ b/docs/src/content/docs/commands/DECRBY.md @@ -7,34 +7,34 @@ The `DECRBY` command in DiceDB is used to decrement the integer value of a key b ## Syntax -``` +```bash DECRBY key delta ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------------------------------------------|---------|----------| -| `key` | The key whose value you want to decrement. This key must hold a string that can be represented as an integer. | String | Yes | -|`delta` | The integer value by which the key's value should be decreased. This value can be positive or negative. | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key whose value you want to decrement. This key must hold a string that can be represented as an integer. | String | Yes | +| `delta` | The integer value by which the key's value should be decreased. This value can be positive or negative. | String | Yes | ## Return values -| Condition | Return Value | -|--------------------------------------------------|------------------------------------------------------------------| -| Key exists and holds an integer string | `(integer)` The value of the key after decrementing by delta. | -| Key does not exist | `(integer)` -delta | - +| Condition | Return Value | +| -------------------------------------- | ------------------------------------------------------------- | +| Key exists and holds an integer string | `(integer)` The value of the key after decrementing by delta. | +| Key does not exist | `(integer)` -delta | ## Behaviour + When the `DECRBY` command is executed, the following steps occur: -- DiceDB checks if the key exists. -- If the key does not exist, DiceDB treats the key's value as 0 before performing the decrement operation. -- If the key exists but does not hold a string that can be represented as an integer, an error is returned. -- The value of the key is decremented by the specified decrement value. -- The new value of the key is returned. +- DiceDB checks if the key exists. +- If the key does not exist, DiceDB treats the key's value as 0 before performing the decrement operation. +- If the key exists but does not hold a string that can be represented as an integer, an error is returned. +- The value of the key is decremented by the specified decrement value. +- The new value of the key is returned. + ## Errors The `DECRBY` command can raise errors in the following scenarios: @@ -59,14 +59,14 @@ The `DECRBY` command can raise errors in the following scenarios: ### Example with Decrementing the Value of an Existing Key - ```bash 127.0.0.1:7379>SET mycounter 10 OK 127.0.0.1:7379>DECRBY mycounter 3 (integer)7 ``` -`Explanation:` + +`Explanation:` - In this example, the value of `mycounter` is set to 10 - The `DECRBY` command decremented `mycounter`by 3, resulting in a new value of 7. @@ -77,8 +77,11 @@ OK 127.0.0.1:7379>DECRBY newcounter 5 (integer)-5 ``` -`Explanation:` + +`Explanation:` + - In this example, since `newcounter` does not exist, DiceDB treats its value as 0 and decrements it by 5, resulting in a new value of -5. + ### Example with Error Due to Non-Integer Value in Key ```bash @@ -87,7 +90,9 @@ OK 127.0.0.1:7379>DECRBY mystring 2 (error) ERR value is not an integer or out of range ``` -`Explanation:` + +`Explanation:` + - In this example, the key `mystring` holds a non-integer value, so the `DECRBY` command returns an error. ### Example with Error Due to Invalid Decrement Value (Non-Integer Decrement) @@ -97,7 +102,6 @@ OK (error) ERR value is not an integer or out of range ``` -`Explanation:` -- In this example, the decrement value "two" is not a valid integer, so the `DECRBY` command returns an error. - +`Explanation:` +- In this example, the decrement value "two" is not a valid integer, so the `DECRBY` command returns an error. diff --git a/docs/src/content/docs/commands/DEL.md b/docs/src/content/docs/commands/DEL.md index 525b377cc..b671f1d49 100644 --- a/docs/src/content/docs/commands/DEL.md +++ b/docs/src/content/docs/commands/DEL.md @@ -1,31 +1,29 @@ --- title: DEL description: The `DEL` command in DiceDB is used to remove one or more keys from the database. If a given key does not exist, it is ignored. This command is fundamental for data management in DiceDB, allowing for the deletion of key-value pairs. The command returns the number of keys that were removed. - - --- The `DEL` command in DiceDB is used to remove one or more keys from the database. If a given key does not exist, it is ignored. This command is fundamental for data management in DiceDB, allowing for the deletion of key-value pairs. The command returns the number of keys that were removed. ## Syntax -``` +```bash DEL key [key ...] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|--------------------------------------------------|--------|----------| -| `key` | The name of the key(s) to be deleted. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------- | ------ | -------- | +| `key` | The name of the key(s) to be deleted. | String | Yes | ## Return values -| Condition | Return Value | -|-------------------------------------|---------------------------------------------------| -| Command is successful | Integer (number of keys successfully deleted) | -| No keys match the specified pattern | 0 | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | --------------------------------------------- | +| Command is successful | Integer (number of keys successfully deleted) | +| No keys match the specified pattern | 0 | +| Syntax or specified constraints are invalid | error | ## Behaviour @@ -49,7 +47,6 @@ The `DEL` command is generally robust and straightforward, but there are a few s - `Error Message`: `(error) ERR wrong number of arguments for 'del' command` - ## Example Usage ### Basic Usage @@ -97,6 +94,7 @@ OK ``` In this example: + - Three keys are set: `key1`, `key2`, and `key3`. - The `DEL` command attempts to delete `key1`, `key2`, and `key4`. - `key1` and `key2` are successfully deleted. @@ -111,5 +109,3 @@ Calling `DEL` without any arguments: 127.0.0.1:7379> DEL (error) ERR wrong number of arguments for 'del' command ``` - - diff --git a/docs/src/content/docs/commands/ECHO.md b/docs/src/content/docs/commands/ECHO.md index edcd4f537..2b460dae9 100644 --- a/docs/src/content/docs/commands/ECHO.md +++ b/docs/src/content/docs/commands/ECHO.md @@ -5,28 +5,29 @@ description: The `ECHO` command in DiceDB is used to print a message ### Syntax -``` +```bash ECHO message ``` + ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `message` | A string of characters, numbers, or a mix of both to print | String / Number| Yes| +| Parameter | Description | Type | Required | +| --------- | ---------------------------------------------------------- | --------------- | -------- | +| `message` | A string of characters, numbers, or a mix of both to print | String / Number | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful |The message passed as a parameter | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | --------------------------------- | +| Command is successful | The message passed as a parameter | +| Syntax or specified constraints are invalid | error | ## ERROR -`Error Message` : `(error) ERROR wrong number of arguments for 'echo' command` -Occurs when message parameter is not passed or more than one message parameter is passed +`Error Message` : `(error) ERROR wrong number of arguments for 'echo' command` +Occurs when message parameter is not passed or more than one message parameter is passed ## Example Usage @@ -35,22 +36,29 @@ Occurs when message parameter is not passed or more than one message parameter ```bash 127.0.0.1:7379> ECHO "DiceDB is very efficient" ``` + `Response`: -- `"DiceDB is very efficient"` + +- `"DiceDB is very efficient"` ### Invalid Usage ```bash 127.0.0.1:7379> ECHO ``` + `Response`: + - `(error) ERROR wrong number of arguments for 'echo' command` ```bash 127.0.0.1:7379> ECHO "DiceDB is" "very efficient" ``` + `Response`: + - `(error) ERROR wrong number of arguments for 'echo' command` ## Conclusion + In DiceDB, the ECHO command accepts only one message string and prints it. If no message or more than one message is provided, it results in an error diff --git a/docs/src/content/docs/commands/EXISTS.md b/docs/src/content/docs/commands/EXISTS.md index d463911b5..888115f86 100644 --- a/docs/src/content/docs/commands/EXISTS.md +++ b/docs/src/content/docs/commands/EXISTS.md @@ -6,30 +6,34 @@ description: The `EXISTS` command in DiceDB is used to determine if one or more The `EXISTS` command in DiceDB is used to determine if one or more specified keys exist in the database. It returns the number of keys that exist among the specified ones. ## Syntax -``` + +```bash EXISTS key [key ...] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|------------------------------------------------|--------|----------| +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------------------ | ------ | -------- | | `key` | The key(s) to check for existence. One or more keys can be specified, separated by spaces. | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| None of the specified keys exist | `0` | -| One or more specified keys exist | Integer representing the count of keys that exist | +| Condition | Return Value | +| -------------------------------- | ------------------------------------------------- | +| None of the specified keys exist | `0` | +| One or more specified keys exist | Integer representing the count of keys that exist | ## Behaviour + - The `EXISTS` command checks whether the specified keys are present in the database. - Returns 1 or 0, or for multiple keys returns the count of existing keys. - The command performs a read-only operation and does not modify the database. ## Errors + 1. `Wrong number of arguments`: + - Error Message: `(error) ERR wrong number of arguments for 'exists' command` - Occurs when no key is provided. @@ -40,6 +44,7 @@ EXISTS key [key ...] ## Example Usage ### Single Key Check + Checking if a key `mykey` exists in the database: ```bash @@ -50,6 +55,7 @@ OK ``` ### Multiple Keys Check + Checking if multiple keys (`key1`, `key2`, `key3`) exist in the database: ```bash @@ -60,15 +66,18 @@ OK 127.0.0.1:7379> EXISTS key1 key2 key3 (integer) 2 ``` + In this case, `key1` and `key2` exist, but `key3` does not. ### Non-Existent Key + Checking if a non-existent key (`nonExistentKey`) is present in the database: ```bash 127.0.0.1:7379> EXISTS nonExistentKey (integer) 0 ``` + ### All Non-Existent Keys Checking if all non-existent keys return 0: diff --git a/docs/src/content/docs/commands/EXPIRE.md b/docs/src/content/docs/commands/EXPIRE.md index 4d94460b6..cf301c16e 100644 --- a/docs/src/content/docs/commands/EXPIRE.md +++ b/docs/src/content/docs/commands/EXPIRE.md @@ -7,142 +7,100 @@ The `EXPIRE` command in DiceDB is used to set a timeout on a specified key. Afte ## Syntax -``` +```bash EXPIRE key seconds [NX | XX | GT | LT] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The key to set the timeout on. Must be an existing key. | String | Yes | -| `seconds` | Timeout duration in seconds. Must be a positive integer. | Integer | Yes | -| `NX` | Set expiry only if the key does not already have an expiry. | None | No | -| `XX` | Set expiry only if the key already has an expiry. | None | No | -| `GT` | Set expiry only if the new expiry is greater than the current one. | None | No | -| `LT` | Set expiry only if the new expiry is less than the current one. | None | No | - +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------ | ------- | -------- | +| `key` | The key to set the timeout on. Must be an existing key. | String | Yes | +| `seconds` | Timeout duration in seconds. Must be a positive integer. | Integer | Yes | +| `NX` | Set expiry only if the key does not already have an expiry. | None | No | +| `XX` | Set expiry only if the key already has an expiry. | None | No | +| `GT` | Set expiry only if the new expiry is greater than the current one. | None | No | +| `LT` | Set expiry only if the new expiry is less than the current one. | None | No | -## Return Value +## Return Values -The `EXPIRE` command returns an integer value: - -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Timeout was successfully set. | `1` | -| Timeout was not set (e.g., key does not exist, or conditions not met).| `0` | +| Condition | Return Value | +| ---------------------------------------------------------------------- | ------------ | +| Timeout was successfully set. | `1` | +| Timeout was not set (e.g., key does not exist, or conditions not met). | `0` | ## Behaviour -When the `EXPIRE` command is issued: - -1. If the specified key exists, DiceDB sets a timeout on the key. The key will be automatically deleted after the specified number of seconds. -2. If the key does not exist, no timeout is set, and the command returns `0`. -3. If the key already has a timeout, the existing timeout is replaced with the new one specified by the `EXPIRE` command. +- When a key exists, DiceDB sets a timeout on it. The key will be automatically deleted after the specified seconds. +- If the key doesn't exist, no timeout is set, and the command returns `0`. +- If the key already has a timeout, the existing timeout is replaced with the new one. +- Conditional flags (NX, XX, GT, LT) control when the expiry can be set based on existing timeouts. -## Error Handling +## Errors -The `EXPIRE` command can raise errors in the following scenarios: - -1. `Syntax Error`: If the command is not used with the correct number of arguments, DiceDB will return a syntax error. - - Error Message: `(error) ERROR wrong number of arguments for 'expire' command` - - Returned if the command is issued with an incorrect number of arguments. +1. `Syntax Error`: + - Error Message: `(error) ERROR wrong number of arguments for 'expire' command` + - Returned if the command is issued with an incorrect number of arguments. ## Example Usage -### Setting a Timeout on a Key - -```bash -127.0.0.1:7379> SET mykey "Hello" -OK -``` -```bash -127.0.0.1:7379> EXPIRE mykey 10 -(integer) 1 -``` - -In this example, the key `mykey` is set with the value "Hello". The `EXPIRE` command sets a timeout of 10 seconds on `mykey`. After 10 seconds, `mykey` will be automatically deleted. +### Basic Usage -### Checking if Timeout was Set +This example demonstrates the fundamental usage of the EXPIRE command. First, we set a key with a value, then set it to expire in 10 seconds. The TTL command shows the remaining time to live. ```bash 127.0.0.1:7379> SET mykey "Hello" OK -``` -```bash 127.0.0.1:7379> EXPIRE mykey 10 (integer) 1 -``` -```bash 127.0.0.1:7379> TTL mykey (integer) 10 ``` -The `TTL` command shows the remaining time to live for mykey, which is 10 seconds. +### Using Conditional Flags + +This example shows how to use the NX and XX flags to conditionally set expiration times. NX sets the expiry only when there isn't one, while XX updates an existing expiry. -### Setting Expiry with Conditions (NX and XX) ```bash 127.0.0.1:7379> SET mykey "Hello" OK -``` -```bash 127.0.0.1:7379> EXPIRE mykey 10 NX (integer) 1 -``` -```bash 127.0.0.1:7379> EXPIRE mykey 20 XX (integer) 1 ``` -The `NX` option sets the expiry only if there was no expiry set, and the `XX` option updates it because there was an existing expiry. - ### Replacing an Existing Timeout +This example illustrates how EXPIRE can replace an existing timeout with a new value. The final TTL command confirms the updated expiration time. ```bash 127.0.0.1:7379> SET mykey "Hello" OK -``` - -```bash 127.0.0.1:7379> EXPIRE mykey 10 (integer) 1 -``` - -```bash 127.0.0.1:7379> EXPIRE mykey 20 (integer) 1 -``` - -```bash 127.0.0.1:7379> TTL mykey (integer) 20 ``` -The initial `EXPIRE` command sets a timeout of 10 seconds. The subsequent `EXPIRE` command replaces the existing timeout with a new timeout of 20 seconds. +### Invalid Key -### Attempting to Set Timeout on a Non-Existent Key +This example shows what happens when trying to set an expiration on a non-existent key. The command returns 0 to indicate failure. ```bash 127.0.0.1:7379> EXPIRE non_existent_key 10 (integer) 0 ``` -The command returns `0`, indicating that the key does not exist and no timeout was set. - -## Error Handling Examples - -### Syntax Error - -```bash -127.0.0.1:7379> EXPIRE mykey -(error) ERROR wrong number of arguments for 'expire' command -``` +## Best Practices -This example shows a syntax error due to missing the `seconds` argument. +- Use `TTL` command to check remaining time before expiration +- Consider using `PERSIST` command to remove expiration if needed +- Choose appropriate conditional flags (NX, XX, GT, LT) based on your use case +- Ensure timeout values are appropriate for your application's needs -## Additional Notes +## Alternatives -- The `EXPIRE` command is often used in conjunction with other commands like `SET`, `GET`, and `DEL` to manage the lifecycle of keys in DiceDB. -- The timeout can be removed by using the `PERSIST` command, which removes the expiration from the key. -- The `TTL` command can be used to check the remaining time to live of a key with an expiration. +- Use `EXPIREAT` command for more precise expiration control based on Unix timestamps diff --git a/docs/src/content/docs/commands/EXPIREAT.md b/docs/src/content/docs/commands/EXPIREAT.md index 66cdac48a..bb3010aa3 100644 --- a/docs/src/content/docs/commands/EXPIREAT.md +++ b/docs/src/content/docs/commands/EXPIREAT.md @@ -7,7 +7,7 @@ The `EXPIREAT` command is used to set the expiration time of a key in DiceDB. Un ## Syntax -```plaintext +```bash EXPIREAT key timestamp [NX|XX|GT|LT] ``` @@ -22,68 +22,46 @@ EXPIREAT key timestamp [NX|XX|GT|LT] | `GT` | Set the expiration only if the new expiration time is greater than or equal to the current one. | None | No | | `LT` | Set the expiration only if the new expiration time is less than the current one. | None | No | -## Return values +## Return Values -| Condition | Return Value | -| -------------------------------------------------- | ------------ | -| Command is successful | `1` | -| Key does not exist or the timeout could not be set | `0` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ---------------------------------------------------------------------- | ------------ | +| Timeout was successfully set. | `1` | +| Timeout was not set (e.g., key does not exist, or conditions not met). | `0` | ## Behaviour - When the `EXPIREAT` command is executed, DiceDB will set the expiration time of the specified key to the given Unix timestamp. - If the key already has an expiration time, it will be overwritten with the new timestamp. -- If the key does not exist, the command will return `0` and no expiration time will be set. +- If the key does not exist, no timeout is set, and the command returns `0`. +- Conditional flags (NX, XX, GT, LT) control when the expiry can be set based on existing timeouts. ## Errors -### Wrong number of arguments - -When the `EXPIREAT` command is called with the wrong number of arguments, an error is returned. +1. `Syntax Error`: -```bash -127.0.0.1:7379> EXPIREAT testkey1 -(error) ERROR wrong number of arguments for 'EXPIREAT' command -``` + - Error Message: `(error) ERROR wrong number of arguments for 'expireat' command` + - Returned if the command is issued with an incorrect number of arguments. -### Invalid timestamp +2. `Invalid Timestamp`: -When the provided timestamp is not a valid integer, an error is returned. + - Error Message: `(error) ERROR value is not an integer or out of range` + - Returned if the timestamp is not a valid integer. -```bash -127.0.0.1:7379> EXPIREAT testkey1 17282112781a -(error) ERROR value is not an integer or out of range -``` - -### Invalid format of Unix Timestamp - -When the provided timestamp is not a valid Unix timestamp, or is outside the supported range, an error is returned. - -```bash -127.0.0.1:7379> EXPIREAT testkey1 11111111111111111 -(error) ERROR invalid expire time in 'EXPIREAT' command -``` +3. `Invalid Unix Timestamp Format`: + - Error Message: `(error) ERROR invalid expire time in 'EXPIREAT' command` + - Returned if the timestamp is outside the supported range. ## Example Usage -### Setting an Expiration Time +### Basic Usage -Setting a key `mykey` to expire at the Unix timestamp `17282126871`. +This example demonstrates setting a key to expire at a specific Unix timestamp. ```bash 127.0.0.1:7379> SET mykey "Hello" OK -127.0.0.1:7379> EXPIREAT mykey 17282126871 -(integer) 1 -``` - -### Checking the expiration time - -Checking the remaining time to live of a key (in seconds). - -```bash -127.0.0.1:7379> EXPIREAT mykey 17282126871 +127.0.0.1:7379> EXPIREAT mykey 1728212687 (integer) 1 127.0.0.1:7379> TTL mykey (integer) 15553913293 @@ -94,7 +72,7 @@ Checking the remaining time to live of a key (in seconds). Trying to set an expiration time for a non-existing key. ```bash -127.0.0.1:7379> EXPIREAT nonexistingkey 17282126871 +127.0.0.1:7379> EXPIREAT nonexistingkey 1728212687 (integer) 0 ``` @@ -117,12 +95,12 @@ Here, the `XX` option is used to set the expiration time only if the key already ```bash 127.0.0.1:7379> SET key value -OK +OK 127.0.0.1:7379> EXPIREAT key 12345677777 XX (integer) 0 127.0.0.1:7379> EXPIREAT key 12345677777 (integer) 1 -127.0.0.1:7379> EXPIREAT key 123456777722 XX +127.0.0.1:7379> EXPIREAT key 123456777722 XX (integer) 1 ``` @@ -132,12 +110,12 @@ The `GT` option is used to set the expiration time only if the new expiration ti ```bash 127.0.0.1:7379> SET key value -OK +OK 127.0.0.1:7379> EXPIREAT key 12334444444 (integer) 1 -127.0.0.1:7379> EXPIREAT key 12334444424 GT +127.0.0.1:7379> EXPIREAT key 12334444424 GT (integer) 0 -127.0.0.1:7379> EXPIREAT key 12334444524 GT +127.0.0.1:7379> EXPIREAT key 12334444524 GT (integer) 1 ``` @@ -147,7 +125,7 @@ Similar to the `GT` option, the `LT` option is used to set the expiration time o ```bash 127.0.0.1:7379> SET key value -OK +OK 127.0.0.1:7379> EXPIREAT key 12334444444 (integer) 1 127.0.0.1:7379> EXPIREAT key 12334444445 LT @@ -156,17 +134,14 @@ OK (integer) 1 ``` -## Additional notes - -- The `EXPIREAT` command is useful when you need to synchronize the expiration of keys across multiple DiceDB instances or when you need to set an expiration time based on an external event that provides a Unix timestamp. -- The timestamp should be in seconds. If you have a timestamp in milliseconds, you need to convert it to seconds before using it with `EXPIREAT`. -- There is an arbitrary limit to the size of the `unix-time-seconds` of [9223372036854775](https://github.com/DiceDB/dice/blob/b74dc8ffd5e518eaa9b82020d2b25a592c6472d4/internal/eval/eval.go#L69). +## Best Practices -## Related commands +- Use `TTL` command to check remaining time before expiration +- Consider using `PERSIST` command to remove expiration if needed +- Choose appropriate conditional flags (NX, XX, GT, LT) based on your use case +- Ensure Unix timestamps are in seconds, not milliseconds +- Be aware of the timestamp limit of [9223372036854775](https://github.com/DiceDB/dice/blob/b74dc8ffd5e518eaa9b82020d2b25a592c6472d4/internal/eval/eval.go#L69) -- `EXPIRE`: Sets the expiration time of a key in seconds from the current time. -- `PEXPIREAT`: Sets the expiration time of a key as an absolute Unix timestamp in milliseconds. -- `TTL`: Returns the remaining time to 127.0.0.1:7379 of a key in seconds. -- `PTTL`: Returns the remaining time to live of a key in milliseconds. +## Alternatives -By understanding and using the `EXPIREAT` command, you can effectively manage the lifecycle of keys in your DiceDB database, ensuring that data is available only as long as it is needed. +- Use `EXPIRE` command for simpler expiration control based on relative time diff --git a/docs/src/content/docs/commands/EXPIRETIME.md b/docs/src/content/docs/commands/EXPIRETIME.md index 9e94d9d7c..0774ab7d5 100644 --- a/docs/src/content/docs/commands/EXPIRETIME.md +++ b/docs/src/content/docs/commands/EXPIRETIME.md @@ -1,106 +1,79 @@ --- title: EXPIRETIME -description: Documentation for the DiceDB command EXPIRETIME +description: The `EXPIRETIME` command in DiceDB is used to retrieve the absolute Unix timestamp (in seconds) at which a given key will expire. This command is particularly useful for understanding the exact expiration time of a key, which can help in debugging and managing key lifetimes. --- The `EXPIRETIME` command in DiceDB is used to retrieve the absolute Unix timestamp (in seconds) at which a given key will expire. This command is particularly useful for understanding the exact expiration time of a key, which can help in debugging and managing key lifetimes. ## Syntax -``` +```bash EXPIRETIME key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The name of the key whose expiration time is to be retrieved | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------ | ------ | -------- | +| `key` | The name of the key whose expiration time is to be retrieved | String | Yes | -## Return Value - -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| The key exists and has an expiration time | Unix timestamp (in seconds) | -| The key exists but has no expiration time | -1 | -| The key does not exist | -2 | +## Return Values +| Condition | Return Value | +| ----------------------------------------- | --------------------------- | +| The key exists and has an expiration time | Unix timestamp (in seconds) | +| The key exists but has no expiration time | -1 | +| The key does not exist | -2 | ## Behaviour -When the `EXPIRETIME` command is executed: - -1. DiceDB checks if the specified key exists in the database. -2. If the key exists and has an associated expiration time, DiceDB returns the absolute Unix timestamp (in seconds) at which the key will expire. -3. If the key exists without an expiration time, the command returns `-1`. -4. If the key doesn't exist, the command returns `-2`. +- DiceDB checks if the specified key exists in the database +- If the key exists and has an associated expiration time, DiceDB returns the absolute Unix timestamp (in seconds) +- If the key exists without an expiration time, the command returns `-1` +- If the key doesn't exist, the command returns `-2` -## Error Handling +## Errors -The `EXPIRETIME` command can raise errors in the following scenarios: - -1. `Wrong number of arguments`: If the command is called with an incorrect number of arguments, DiceDB will return an error message: - ``` - (error) ERROR wrong number of arguments for 'expiretime' command - ``` -2. `Invalid key type`: If the key is not a valid string, DiceDB will return an error message: - ``` - (error) ERROR invalid key type - ``` +1. `Wrong number of arguments`: + - Error Message: `(error) ERROR wrong number of arguments for 'expiretime' command` + - Occurs when the command is called with an incorrect number of arguments ## Example Usage -### Example 1: Key with Expiration Time +### Key with Expiration Time ```bash 127.0.0.1:7379> SET mykey "Hello" OK -``` -```bash 127.0.0.1:7379> EXPIRE mykey 60 (integer) 1 -``` -```bash 127.0.0.1:7379> EXPIRETIME mykey -``` - -`Output:` - -``` (integer) 1728548993 ``` In this example, the key `mykey` is set with a value "Hello" and an expiration time of 60 seconds. The `EXPIRETIME` command returns the Unix timestamp at which `mykey` will expire. -### Example 2: Key without Expiration Time +### Key without Expiration Time ```bash 127.0.0.1:7379> SET mykey "Hello" OK -``` - -```bash 127.0.0.1:7379> EXPIRETIME mykey -``` - -`Output:` - -``` (integer) -1 ``` In this example, the key `mykey` is set with a value "Hello" but no expiration time is set. The `EXPIRETIME` command returns `-1` indicating that the key does not have an associated expiration time. -### Example 3: Non-Existent Key +### Non-Existent Key ```bash 127.0.0.1:7379> EXPIRETIME nonExistentKey -``` - -`Output:` - -``` (integer) -2 ``` In this example, the key `nonExistentKey` does not exist in the database. The `EXPIRETIME` command returns `-2` indicating that the key does not exist. + +## Alternatives + +- Use `TTL` to get relative expiration times +- Use `PTTL` to get relative expiration times in milliseconds diff --git a/docs/src/content/docs/commands/FLUSHDB.md b/docs/src/content/docs/commands/FLUSHDB.md index 1f3877002..8db708ccb 100644 --- a/docs/src/content/docs/commands/FLUSHDB.md +++ b/docs/src/content/docs/commands/FLUSHDB.md @@ -1,19 +1,28 @@ --- title: FLUSHDB -description: Documentation for the DiceDB command FLUSHDB +description: The FLUSHDB command removes all keys from the currently selected database, providing a way to clear all data in a specific database space. --- The `FLUSHDB` command is used to remove all keys from the currently selected database in a DiceDB instance. This command is useful when you need to clear all the data in a specific database without affecting other databases in the same DiceDB instance. +## Syntax + +```bash +FLUSHDB +``` + ## Parameters The `FLUSHDB` command does not take any parameters. -## Return Value - -The `FLUSHDB` command returns a simple string reply: +## Return Values -- `OK`: Indicates that the operation was successful and all keys in the current database have been removed. +| Condition | Return Value | +| ----------------------- | ------------------------------------------------------------------------- | +| Command is successful | `OK` | +| Authentication required | Error: `NOAUTH Authentication required` | +| Permission denied | Error: `NOPERM this user has no permissions to run the 'flushdb' command` | +| Read-only mode | Error: `READONLY You can't write against a read-only replica` | ## Behaviour @@ -27,46 +36,59 @@ When the `FLUSHDB` command is executed, the following actions occur: The `FLUSHDB` command is straightforward and does not typically raise errors under normal circumstances. However, there are a few scenarios where issues might arise: -1. `Permission Denied`: If the DiceDB instance is configured with ACLs (Access Control Lists) and the user does not have the necessary permissions to execute the `FLUSHDB` command, an error will be raised. +1. `Authentication Issues`: - - Error: `(error) NOAUTH Authentication required.` or `(error) NOPERM this user has no permissions to run the 'flushdb' command` + - Error Message: `(error) NOAUTH Authentication required` + - Occurs when authentication is required but not provided -2. `Read-Only Mode`: If the DiceDB instance is in read-only mode (e.g., a read-only replica), the `FLUSHDB` command will not be allowed. +2. `Permission Issues`: - - Error: `(error) READONLY You can't write against a read-only replica.` + - Error Message: `(error) NOPERM this user has no permissions to run the 'flushdb' command` + - Occurs when the user lacks necessary permissions to execute the command + +3. `Read-Only Mode`: + - Error Message: `(error) READONLY You can't write against a read-only replica` + - Occurs when attempting to execute on a read-only instance ## Example Usage ### Basic Usage -To clear all keys from the currently selected database: - -```sh -127.0.0.1:6379> FLUSHDB +```bash +127.0.0.1:7379> FLUSHDB OK ``` -### Using with Multiple Databases - -If you have multiple databases and want to clear a specific one, you need to select the database first using the `SELECT` command, then execute `FLUSHDB`: +### Verifying Empty Database -```sh -127.0.0.1:6379> SELECT 1 -OK -127.0.0.1:6379[1]> FLUSHDB +```bash +127.0.0.1:7379> FLUSHDB OK +127.0.0.1:7379> DBSIZE +(integer) 0 ``` -### Checking the Result +### Example with SELECT Command -After executing `FLUSHDB`, you can verify that the database is empty by using the `DBSIZE` command, which returns the number of keys in the currently selected database: +While the following example shows the traditional syntax for working with multiple databases, please note that in the current version, all operations occur on a single database space: -```sh -127.0.0.1:6379> DBSIZE +```bash +127.0.0.1:7379> SELECT 1 +OK +127.0.0.1:7379> FLUSHDB +OK +127.0.0.1:7379> DBSIZE (integer) 0 ``` +## Best Practices + +- Always verify that you're operating on the intended database before executing FLUSHDB +- Consider using backup mechanisms before executing FLUSHDB in production environments +- Use appropriate access controls to restrict FLUSHDB usage to authorized users only + ## Notes -- `Data Loss`: The `FLUSHDB` command will result in the loss of all data in the selected database. Use this command with caution, especially in production environments. -- `Atomic Operation`: The `FLUSHDB` command is atomic, meaning that all keys are removed in a single operation without any intermediate states. +- The current version of DiceDB operates on a single database space. While the `SELECT` command is available as a placeholder, switching databases will not affect the operation of the `FLUSHDB` command, and it will always clear the keys from the single available database space. + +- The command is particularly powerful and should be used with caution as it results in immediate, irreversible data loss for all keys in the database. diff --git a/docs/src/content/docs/commands/GET.md b/docs/src/content/docs/commands/GET.md index bcff5aa33..6b45a0290 100644 --- a/docs/src/content/docs/commands/GET.md +++ b/docs/src/content/docs/commands/GET.md @@ -14,17 +14,17 @@ GET key ## Parameters -| Parameter | Description | Type | Required | -|-----------|--------------------------------------------------------------------------|--------|----------| -| key | The name of the key whose value you want to retrieve. The key is a string.| string | Yes | +| Parameter | Description | Type | Required | +| --------- | -------------------------------------------------------------------------- | ------ | -------- | +| key | The name of the key whose value you want to retrieve. The key is a string. | string | Yes | ## Return Values -| Condition | Return Value | -|--------------------------------------------------------|---------------------------------------------------------------------------------------------------| -| The specified key exists and holds a string value | The string value stored at the key. | -| The specified key does not exist | `nil` | -| The specified key exists but is not a string, or multiple keys are passed | error | +| Condition | Return Value | +| ------------------------------------------------------------------------- | ----------------------------------- | +| The specified key exists and holds a string value | The string value stored at the key. | +| The specified key does not exist | `nil` | +| The specified key exists but is not a string, or multiple keys are passed | error | ## Behaviour @@ -38,14 +38,15 @@ When the GET command is issued, DiceDB checks the existence of the specified key The GET command is a read-only operation and does not modify the state of the DiceDB database. ## Errors + 1. **Expected string but got another type:** - - Error Message: (error) ERR expected string but got another type - - Occurs when the specified key holds a value that is not a string (e.g., a list, set, hash, or zset). DiceDB uses strict type checking to ensure that the correct type of operation is performed on the appropriate data type. + + - Error Message: (error) ERR expected string but got another type + - Occurs when the specified key holds a value that is not a string (e.g., a list, set, hash, or zset). DiceDB uses strict type checking to ensure that the correct type of operation is performed on the appropriate data type. 2. **Wrong number of arguments for 'GET' command:** - - Error Message: (error) ERR wrong number of arguments for 'get' command - - Occurs when multiple keys are passed as parameters. - + - Error Message: (error) ERR wrong number of arguments for 'get' command + - Occurs when multiple keys are passed as parameters. ## Example Usage diff --git a/docs/src/content/docs/commands/GETBIT.md b/docs/src/content/docs/commands/GETBIT.md index c59057f55..3bc809199 100644 --- a/docs/src/content/docs/commands/GETBIT.md +++ b/docs/src/content/docs/commands/GETBIT.md @@ -7,23 +7,23 @@ The `GETBIT` command is used to retrieve the bit value at a specified offset in ## Syntax -``` +```bash GETBIT key offset ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The key of the string from which the bit value is to be retrieved. This key must reference a string value. | String | Yes | -| `offset` | The position of the bit to retrieve. The offset is a zero-based integer, meaning the first bit is at position 0. | Integer | Yes | +| Parameter | Description | Type | Required | +| --------- | ---------------------------------------------------------------------------------------------------------------- | ------- | -------- | +| `key` | The key of the string from which the bit value is to be retrieved. This key must reference a string value. | String | Yes | +| `offset` | The position of the bit to retrieve. The offset is a zero-based integer, meaning the first bit is at position 0. | Integer | Yes | ## Return Values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | `0` or `1` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------ | +| Command is successful | `0` or `1` | +| Syntax or specified constraints are invalid | error | ## Behaviour @@ -37,18 +37,18 @@ GETBIT key offset 1. `Wrong number of arguments`: - - Error Message: `(error) wrong number of arguments for 'GETBIT' command` - - Occurs if both key and offset are not provided. + - Error Message: `(error) wrong number of arguments for 'GETBIT' command` + - Occurs if both key and offset are not provided. 2. `Non-string value stored against the key`: - - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - - Occurs if the key exists but does not contain a string value. + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if the key exists but does not contain a string value. 3. `Non-integer or negative value for offset`: - - Error Message: `(error) ERR bit offset is not an integer or out of range` - - Occurs if the offset is not a valid integer or is negative. + - Error Message: `(error) ERR bit offset is not an integer or out of range` + - Occurs if the offset is not a valid integer or is negative. ## Example Usage diff --git a/docs/src/content/docs/commands/GETDEL.md b/docs/src/content/docs/commands/GETDEL.md index 7cdd54ad5..0958c0379 100644 --- a/docs/src/content/docs/commands/GETDEL.md +++ b/docs/src/content/docs/commands/GETDEL.md @@ -7,36 +7,31 @@ The `GETDEL` command in DiceDB is used to retrieve the value of a specified key ## Syntax -``` +```bash GETDEL key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The key whose value you want to retrieve and delete. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ---------------------------------------------------- | ------ | -------- | +| `key` | The key whose value you want to retrieve and delete. | String | Yes | ## Return values -| Condition | Return Value | -|----------------------|------------------------------------------------------------------| -| Key exists | `String`: The command returns the value associated with the key. | -| Key does not exist | `nil`: The command returns `nil`. | +| Condition | Return Value | +| ------------------ | ---------------------------------------------------------------- | +| Key exists | `String`: The command returns the value associated with the key. | +| Key does not exist | `nil`: The command returns `nil`. | ## Behaviour -When the `GETDEL` command is executed, the following steps occur: - 1. The command checks if the specified key exists in the DiceDB database. - 2. If the key exists, the value associated with the key is retrieved. - 3. The key is then deleted from the database. - 4. The retrieved value is returned to the client. - 5. If the key does not exist, `nil` is returned, and no deletion occurs. +- If the specified key exists, `GETDEL` retrieves its value and then deletes the key from the database. +- The retrieved value is returned to the client. +- If the key does not exist, `GETDEL` returns `nil` and no deletion is performed. ## Errors -The `GETDEL` command can raise errors in the following scenarios: - 1. `Wrong Type Error`: - Error Message: `ERROR WRONGTYPE Operation against a key holding the wrong kind of value` @@ -47,9 +42,11 @@ The `GETDEL` command can raise errors in the following scenarios: - Error Message: `ERROR wrong number of arguments for 'getdel' command` - Occurs if the command is called without the required parameter. -## Examples +## Example Usage -### Example with Existent key +### Retreive and Delete an Existing Key + +Setting a key `mykey` with the value `"Hello, World!"` and then using `GETDEL` to retrieve and delete it. ```bash 127.0.0.1:7379> SET mykey "Hello, World!" @@ -60,34 +57,43 @@ OK (nil) ``` -`Explanation:` - -- The key `mykey` is set with the value `"Hello, World!"`. -- The `GETDEL` command retrieves the value `"Hello, World!"` and deletes the key `mykey` from the database. -- The `GET` command attempts to retrieve the value associated with the key `mykey` and returns `nil` as the key no longer exists. +<<<<<<< HEAD +`Explanation:` +======= +### Using `GETDEL` on a Non-Existent Key +>>>>>>> d43577926873d0df0c8f189cdde6afa65c515ccb -### Example with a Non-Existent Key +Trying to retrieve and delete a key `nonexistingkey` that does not exist. ```bash 127.0.0.1:7379> GETDEL nonexistingkey (nil) ``` -`Explanation:` +<<<<<<< HEAD +`Explanation:` - The key `nonexistingkey` does not exist in the database. - The `GETDEL` command returns `nil` since the key is not found. +======= +### Using `GETDEL` on a Key with a Different Data Type +>>>>>>> d43577926873d0df0c8f189cdde6afa65c515ccb -### Example with a Wrong Type of Key +Setting a key `mylist` as a list and then trying to use `GETDEL`, which is incompatible with non-string data types. ```bash 127.0.0.1:7379> LPUSH mylist "item1" (integer) 1 127.0.0.1:7379> GETDEL mylist +<<<<<<< HEAD ERROR WRONGTYPE Operation against a key holding the wrong kind of value ``` -`Explanation:` +`Explanation:` - The key `mylist` is a list, not a string. -- The `GETDEL` command raises a `WRONGTYPE` error because it expects the key to be a string. \ No newline at end of file +- The `GETDEL` command raises a `WRONGTYPE` error because it expects the key to be a string. +======= +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` +>>>>>>> d43577926873d0df0c8f189cdde6afa65c515ccb diff --git a/docs/src/content/docs/commands/GETEX.md b/docs/src/content/docs/commands/GETEX.md index 7a83f76ac..26ced9427 100644 --- a/docs/src/content/docs/commands/GETEX.md +++ b/docs/src/content/docs/commands/GETEX.md @@ -1,60 +1,64 @@ --- title: GETEX -description: Documentation for the DiceDB command GETEX +description: The `GETEX` command in DiceDB is used to retrieve the value of a specified key and simultaneously set its expiration time. This command is particularly useful when you want to access the value of a key and ensure that it expires after a certain period, all in a single atomic operation. --- The `GETEX` command in DiceDB is used to retrieve the value of a specified key and simultaneously set its expiration time. This command is particularly useful when you want to access the value of a key and ensure that it expires after a certain period, all in a single atomic operation. ## Syntax -``` +```bash GETEX key [EX seconds|PX milliseconds|EXAT timestamp|PXAT milliseconds-timestamp|PERSIST] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The key whose value you want to retrieve and set an expiration for. | String | Yes | -| `EX` | Set the expiration time in seconds. | Integer | No | -| `EXAT` | Set the expiration time as a Unix timestamp in seconds. | Integer | No | -| `PX` | Set the expiration time in milliseconds. | Integer | No | -| `PXAT` | Set the expiration time as a Unix timestamp in milliseconds. | Integer | No | -| `PERSIST` | Remove the existing expiration time, making the key persistent. | None | No | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------- | ------- | -------- | +| `key` | The key whose value you want to retrieve and set an expiration for. | String | Yes | +| `EX` | Set the expiration time in seconds. | Integer | No | +| `EXAT` | Set the expiration time as a Unix timestamp in seconds. | Integer | No | +| `PX` | Set the expiration time in milliseconds. | Integer | No | +| `PXAT` | Set the expiration time as a Unix timestamp in milliseconds. | Integer | No | +| `PERSIST` | Remove the existing expiration time, making the key persistent. | None | No | ## Return Values -| Condition | Return Value | -|---------------------------------------------------|---------------------------------------------------| -| The specified key exists and holds a value | The value stored at the key | -| The specified key does not exist | `nil` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | --------------------------- | +| The specified key exists and holds a value | The value stored at the key | +| The specified key does not exist | `nil` | +| Syntax or specified constraints are invalid | error | ## Behaviour -When the `GETEX` command is executed, it performs the following actions: +- If the specified key does not exist, `GETEX` will return nil, and no expiration time will be set. +- If the key exists, `GETEX` retrieves and returns its current value. +- When used with the `EX`, `PX`, `EXAT`, or `PXAT` options, `GETEX` will adjust the key's expiration time according to the specified option. +- Using the `PERSIST` option removes any existing expiration, making the key persist indefinitely. -1. Retrieves the value of the specified key. -2. Sets the expiration time for the key based on the provided option (`EX`, `PX`, `EXAT`, `PXAT`, or `PERSIST`). -3. Returns the value of the key. +## Errors -If the key does not exist, the command will return `nil` and no expiration time will be set. +1. `Wrong number of arguments`: -## Errors + - Error Message: `(error) ERR wrong number of arguments for 'getex' command` + - Occurs when the command is executed with an incorrect number of arguments. -The `GETEX` command can raise errors in the following scenarios: +2. `Invalid expiration option`: -1. `Wrong number of arguments`: If the command is not provided with the correct number of arguments, it will return an error. - - Error message: `(error) ERR wrong number of arguments for 'getex' command` -2. `Invalid expiration option`: If an invalid expiration option is provided, it will return an error. - - Error message: `(error) ERR syntax error` -3. `Invalid expiration time`: If the expiration time is not a valid integer or timestamp, it will return an error. - - Error message: `(error) ERR value is not an integer or out of range` + - Error Message: `(error) ERR syntax error` + - Occurs when an unrecognized or incorrect expiration option is specified. + +3. `Invalid expiration time`: + + - Error Message: `(error) ERR value is not an integer or out of range` + - Occurs when the expiration time provided is not a valid integer or timestamp. ## Example Usage -### Example 1: Retrieve value and set expiration in seconds +### Retrieve value and set expiration in seconds +This command will return `"Hello"` and set the expiration time of `mykey` to 10 seconds. ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -63,9 +67,9 @@ OK 127.0.0.1:7379> "Hello" ``` -- This command will return `"Hello"` and set the expiration time of `mykey` to 10 seconds. +### Retrieve value and set expiration in milliseconds -### Example 2: Retrieve value and set expiration in milliseconds +This command will return `"Hello"` and set the expiration time of `mykey` to 10,000 milliseconds (10 seconds). ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -74,9 +78,9 @@ OK 127.0.0.1:7379> "Hello" ``` -- This command will return `"Hello"` and set the expiration time of `mykey` to 10,000 milliseconds (10 seconds). +### Retrieve value and set expiration as Unix timestamp in seconds -### Example 3: Retrieve value and set expiration as Unix timestamp in seconds +This command will return `"Hello"` and set the expiration time of `mykey` to the Unix timestamp `1672531199`. ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -85,9 +89,9 @@ OK 127.0.0.1:7379> "Hello" ``` -- This command will return `"Hello"` and set the expiration time of `mykey` to the Unix timestamp `1672531199`. +### Retrieve value and set expiration as Unix timestamp in milliseconds -### Example 4: Retrieve value and set expiration as Unix timestamp in milliseconds +This command will return `"Hello"` and set the expiration time of `mykey` to the Unix timestamp `1672531199000` milliseconds. ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -96,9 +100,9 @@ OK 127.0.0.1:7379> "Hello" ``` -- This command will return `"Hello"` and set the expiration time of `mykey` to the Unix timestamp `1672531199000` milliseconds. +### Retrieve value and remove expiration -### Example 5: Retrieve value and remove expiration +This command will return `"Hello"` and remove the expiration time of `mykey`, making it persistent. ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -109,8 +113,6 @@ OK 127.0.0.1:7379> "Hello" ``` -- This command will return `"Hello"` and remove the expiration time of `mykey`, making it persistent. - ## Notes - The `GETEX` command is atomic, meaning it ensures that the retrieval of the value and the setting of the expiration time happen as a single, indivisible operation. @@ -118,4 +120,3 @@ OK - The `PERSIST` option is useful when you want to make a key persistent again after it has been set to expire. By understanding and utilizing the `GETEX` command, you can efficiently manage key-value pairs in DiceDB with precise control over their expiration times. - diff --git a/docs/src/content/docs/commands/GETRANGE.MD b/docs/src/content/docs/commands/GETRANGE.MD index 245d85cbe..390cfc368 100644 --- a/docs/src/content/docs/commands/GETRANGE.MD +++ b/docs/src/content/docs/commands/GETRANGE.MD @@ -2,6 +2,7 @@ title: GETRANGE description: The `GETRANGE` command in DiceDB is used to get a substring of a string, provided the start and end indices --- + The `GETRANGE` command in DiceDB is used to get a substring of a string, provided the start and end indices. ## Syntax @@ -11,28 +12,32 @@ GETRANGE key start end ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The name of the key containing the string. | String | Yes | -| `start` | The starting index of the required substring. | Integer | Yes | -| `end` | The ending index of the required substring. | Integer | Yes | + +| Parameter | Description | Type | Required | +| --------- | --------------------------------------------- | ------- | -------- | +| `key` | The name of the key containing the string. | String | Yes | +| `start` | The starting index of the required substring. | Integer | Yes | +| `end` | The ending index of the required substring. | Integer | Yes | + ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| if key contains a valid string | a substring based on the start and end indices | -| if `start` is greater than `end` | an empty string is returned | -| if the `end` exceeds the length of the string present at `key` | the entire string is returned | -| if the `start` is greater than the length of the string | an empty string is returned. | +| Condition | Return Value | +| -------------------------------------------------------------- | ---------------------------------------------- | +| if key contains a valid string | a substring based on the start and end indices | +| if `start` is greater than `end` | an empty string is returned | +| if the `end` exceeds the length of the string present at `key` | the entire string is returned | +| if the `start` is greater than the length of the string | an empty string is returned. | ## Behaviour -- If the specified key does not exist, the `GETRANGE` command returns an empty string. + +- If the specified key does not exist, the `GETRANGE` command returns an empty string. - If `start` is greater than `end`, the `GETRANGE` command returns an empty string. - If `start` is not within the length of the string, the `GETRANGE` command returns an empty string. - `start` and `end` can be negative which removed `end + 1` characters from the other side of the string. - Both `start` and `end` can be negative, which removes characters from the string, starting from the `end + 1` position on the right. ## Errors + 1. `Wrong type of value or key`: - Error Message: `(error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value` diff --git a/docs/src/content/docs/commands/GETSET.md b/docs/src/content/docs/commands/GETSET.md index 39291d5b8..0c3bf9058 100644 --- a/docs/src/content/docs/commands/GETSET.md +++ b/docs/src/content/docs/commands/GETSET.md @@ -7,26 +7,23 @@ The `GETSET` command in DiceDB is a powerful atomic operation that combines the ## Syntax -``` +```bash GETSET key value ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|--------------------------------------------------|---------|----------| -| `key` | The key whose value you want to retrieve and set. | String | Yes | -| `value` | The new value to set for the specified key. | String | Yes | - - +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------- | ------ | -------- | +| `key` | The key whose value you want to retrieve and set. | String | Yes | +| `value` | The new value to set for the specified key. | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| The old value stored at the specifiied `key` | A string value | -| The key does not exist | `nil` | - +| Condition | Return Value | +| -------------------------------------------- | -------------- | +| The old value stored at the specifiied `key` | A string value | +| The key does not exist | `nil` | ## Behaviour @@ -37,7 +34,6 @@ When the `GETSET` command is executed, the following sequence of actions occurs: 3. If the specified key had an existing `TTL` , it is reset. 4. The old value is returned to the client. - This operation is atomic, meaning that no other commands can be executed on the key between the get and set operations. ## Errors @@ -53,7 +49,7 @@ The `GETSET` command can raise errors in the following scenarios: ### Basic Example -```DiceDB +```bash 127.0.0.1:7379> SET mykey "Hello" 127.0.0.1:7379> GETSET mykey "World" "Hello" @@ -67,7 +63,7 @@ The `GETSET` command can raise errors in the following scenarios: ### Example with Non-Existent Key -```DiceDB +```bash 127.0.0.1:7379> GETSET newkey "NewValue" (nil) ``` @@ -78,9 +74,9 @@ The `GETSET` command can raise errors in the following scenarios: - The `GETSET` command sets the value of `newkey` to "NewValue". - Since the key did not exist before, `nil` is returned. - ### Example with Key having pre-existing TTL -```DiceDB + +```bash 127.0.0.1:7379> SET newkey "test" OK 127.0.0.1:7379> EXPIRE newkey 60 @@ -99,10 +95,9 @@ OK - When `GETSET` is executed on the mentioned key, it updates the value and resets the `TTL` on the key. - Hence, the `TTL` on `newkey` post `GETSET` returns `-1` , suggesting that the key exists without any `TTL` configured - ### Error Example: Wrong Type -```DiceDB +```bash 127.0.0.1:7379> LPUSH mylist "item" 127.0.0.1:7379> GETSET mylist "NewValue" (error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value @@ -115,7 +110,7 @@ OK ### Error Example: Syntax Error -```DiceDB +```bash 127.0.0.1:7379> GETSET mykey (error) ERROR wrong number of arguments for 'getset' command ``` @@ -124,4 +119,3 @@ OK - The `GETSET` command requires exactly two arguments: a key and a value. - Since only one argument is provided, DiceDB returns a syntax error. - diff --git a/docs/src/content/docs/commands/HDEL.md b/docs/src/content/docs/commands/HDEL.md new file mode 100644 index 000000000..64e2bfbc0 --- /dev/null +++ b/docs/src/content/docs/commands/HDEL.md @@ -0,0 +1,132 @@ +--- +title: HDEL +description: The HDEL command in DiceDB deletes a specified field within a hash stored at a given key. If either the key or field does not exist, no action is taken, and 0 is returned. +--- + +# HDEL +The HDEL command in DiceDB deletes a specified field within a hash stored at a given key. If either the key or field does not exist, no action is taken, and 0 is returned. + +## Syntax + +```bash +HDEL key field [field ...] +``` + +## Parameters + +| Parameter | Description | Type | Required | +|-----------|-------------------------------------------------------------------|---------|----------| +| `key` | The key of the hash from which the field(s) are to be deleted. | String | Yes | +| `field` | One or more fields within the hash to be deleted. | String | Yes | + +## Return Values + +| Condition | Return Value | +|---------------------------------------------|-----------------------------------------------------------------------------| +| Field(s) deleted successfully | `Integer` (Number of fields deleted) | +| Field does not exist | `0` | +| Key does not exist | `0` | +| Wrong data type | `(error) WRONGTYPE Operation against a key holding the wrong kind of value` | +| Incorrect Argument Count | `(error) ERR wrong number of arguments for 'hdel' command` | + +## Behaviour + +When the `HDEL` command is executed, DiceDB performs the following steps: + +- It checks if the key exists in the database. +- If the key exists and is of type hash, it then checks for the specified field(s) within the hash. +- If the specified field(s) exist, they are deleted, and DiceDB returns the count of deleted fields. +- If the key does not exist or the field(s) are not present, it returns `0`. + +## Errors + +1. `Non-hash type or wrong data type`: + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if `key` holds a non-hash data structure. + +2. `Incorrect Argument Count`: + + - Error Message: `(error) ERR wrong number of arguments for 'hdel' command` + - Occurs if the command is not provided with the correct number of arguments (i.e., fewer than two). + +## Example Usage + +### Basic Usage + +#### Deleting a field from a hash + +```bash +127.0.0.1:7379> HSET user:1000 name "John Doe" +(integer) 1 +127.0.0.1:7379> HDEL user:1000 name +(integer) 1 +127.0.0.1:7379> HGET user:1000 name +(nil) +``` + +#### Deleting multiple fields from a hash + +```bash +127.0.0.1:7379> HSET user:1000 name "John Doe" +(integer) 1 +127.0.0.1:7379> HSET user:1000 age "30" +(integer) 1 +127.0.0.1:7379> HDEL user:1000 name age +(integer) 2 +``` + +#### Field does not exist + +```bash +127.0.0.1:7379> HDEL user:1000 email +(integer) 0 +``` + +#### Key does not exist + +```bash +127.0.0.1:7379> HDEL user:2000 name +(integer) 0 +``` + +#### Key is not a hash + +```bash +127.0.0.1:7379> SET user:3000 "Not a hash" +OK +127.0.0.1:7379> HDEL user:3000 name +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` + +### Invalid Usage + +Attempting to delete a field in a key that is not a hash + +```bash +127.0.0.1:7379> SET user:5000 "This is a string" +OK +127.0.0.1:7379> HDEL user:5000 name +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` + +- **Behavior**: The `SET` command sets the key `user:5000` to a string value. +- **Error**: The `HDEL` command raises a `WRONGTYPE` error because user:5000 is not a hash, and `HDEL` only operates on hash data structures. + +Wrong Number of Arguments for HDEL Command + +```bash +127.0.0.1:7379> HDEL +(error) ERR wrong number of arguments for 'hdel' command + +127.0.0.1:7379> HDEL user:5000 +(error) ERR wrong number of arguments for 'hdel' command +``` +- **Behavior**: The `HDEL` command requires at least two arguments: the key and the field name. +- **Error**: The command fails because `HDEL` requires at least a `key` and one `field` as arguments. If these are not provided, DiceDB raises an error indicating an incorrect number of arguments. + +## Notes + +- The `HDEL` command is essential for managing hash data in DiceDB, allowing fields to be efficiently removed when no longer needed. + + diff --git a/docs/hexists_command_docs.md b/docs/src/content/docs/commands/HEXISTS.md similarity index 83% rename from docs/hexists_command_docs.md rename to docs/src/content/docs/commands/HEXISTS.md index 5e0641394..beff229fa 100644 --- a/docs/hexists_command_docs.md +++ b/docs/src/content/docs/commands/HEXISTS.md @@ -14,16 +14,16 @@ HEXISTS key field ## Parameters | Parameter | Description | Type | Required | -|-----------|------------------------------------|--------|----------| +| --------- | ---------------------------------- | ------ | -------- | | `key` | The name of the key holding a hash | String | Yes | | `field` | The field to check within the hash | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If the field exists within the hash | `1` | -| If the field does not exist within the hash | `0` | +| Condition | Return Value | +| ------------------------------------------- | ------------ | +| If the field exists within the hash | `1` | +| If the field does not exist within the hash | `0` | ## Behaviour @@ -83,4 +83,4 @@ If the hash `user:1002` does not exist: - If `key` is not of type hash, consider using commands specifically designed for other data types. -By utilizing the `HEXISTS` command, you can conditionally manage hash data in DiceDB, verifying field presence before performing operations based on field existence. \ No newline at end of file +By utilizing the `HEXISTS` command, you can conditionally manage hash data in DiceDB, verifying field presence before performing operations based on field existence. diff --git a/docs/src/content/docs/commands/HGET.md b/docs/src/content/docs/commands/HGET.md index f3bb46dc3..714e06dfb 100644 --- a/docs/src/content/docs/commands/HGET.md +++ b/docs/src/content/docs/commands/HGET.md @@ -1,96 +1,118 @@ --- title: HGET -description: Documentation for the DiceDB command HGET +description: The `HGET` command in DiceDB is used to retrieve the value associated with a specified field within a hash stored at a given key. If the key or the field does not exist, the command returns a `nil` value. --- The `HGET` command in DiceDB is used to retrieve the value associated with a specified field within a hash stored at a given key. If the key or the field does not exist, the command returns a `nil` value. ## Syntax -``` +```bash HGET key field ``` ## Parameters -- `key`: The key of the hash from which the field's value is to be retrieved. This is a string. -- `field`: The field within the hash whose value is to be retrieved. This is also a string. +| Parameter | Description | Type | Required | +|-----------|-----------------------------------------------------------------------|---------|----------| +| `key` | The key of the hash from which the field's value is to be retrieved. | String | Yes | +| `field` | The field within the hash whose value is to be retrieved. | String | Yes | -## Return Value +## Return Values -- `String`: The value associated with the specified field within the hash. -- `nil`: If the key does not exist or the field is not present in the hash. +| Condition | Return Value | +|---------------------------------------------|-----------------------------------------------------------------------------| +| Field exists in the hash | `String` (value of the field) | +| Key does not exist or field not present | `nil` | +| Wrong data type | `(error) WRONGTYPE Operation against a key holding the wrong kind of value` | +| Incorrect Argument Count | `(error) ERR wrong number of arguments for 'hget' command` | ## Behaviour When the `HGET` command is executed, DiceDB performs the following steps: -1. It checks if the key exists in the database. -2. If the key exists and is of type hash, it then checks if the specified field exists within the hash. -3. If the field exists, it retrieves and returns the value associated with the field. -4. If the key does not exist or the field is not present in the hash, it returns `nil`. +- It checks if the key exists in the database. +- If the key exists and is of type hash, it then checks if the specified field exists within the hash. +- If the field exists, it retrieves and returns the value associated with the field. +- If the key does not exist or the field is not present in the hash, it returns `nil`. -## Error Handling +## Errors -- `WRONGTYPE Operation against a key holding the wrong kind of value`: This error is raised if the key exists but is not of type hash. DiceDB expects the key to be associated with a hash data structure for the `HGET` command to work correctly. +1. `Non-hash type or wrong data type`: -## Example Usage + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if `key` holds a non-hash data structure. -### Example 1: Retrieving a value from a hash +2. `Incorrect Argument Count`: -```DiceDB -HSET user:1000 name "John Doe" -HSET user:1000 age "30" -HGET user:1000 name -``` + - Error Message: `(error) ERR wrong number of arguments for 'hget' command` + - Occurs if the command is not provided with the correct number of arguments (i.e., fewer than two). -`Output:` +## Example Usage -``` -"John Doe" -``` +### Basic Usage -### Example 2: Field does not exist +#### Retrieving a value from a hash -```DiceDB -HGET user:1000 email +```bash +127.0.0.1:7379> HSET user:1000 name "John Doe" +(integer) 1 +127.0.0.1:7379> HSET user:1000 age "30" +(integer) 1 +127.0.0.1:7379> HGET user:1000 name +"John Doe" ``` -`Output:` +#### Field does not exist -``` +```bash +127.0.0.1:7379> HGET user:1000 email (nil) ``` -### Example 3: Key does not exist +#### Key does not exist -```DiceDB -HGET user:2000 name +```bash +127.0.0.1:7379> HGET user:2000 name +(nil) ``` -`Output:` +### Key is not a hash -``` -(nil) +```bash +127.0.0.1:7379> SET user:3000 "Not a hash" +OK +127.0.0.1:7379> HGET user:3000 name +(error) WRONGTYPE Operation against a key holding the wrong kind of value ``` -### Example 4: Key is not a hash +### Invalid Usage -```DiceDB -SET user:3000 "Not a hash" -HGET user:3000 name +Trying to get a field from a key that is not a hash. + +```bash +127.0.0.1:7379> SET product:2000 "This is a string" +OK +127.0.0.1:7379> HGET product:2000 name +(error) WRONGTYPE Operation against a key holding the wrong kind of value ``` +- **Behavior**: The `SET` command sets the key `product:2000` to a string value. +- **Error**: The `HGET` command will raise a WRONGTYPE error because `product:2000` is not a hash. -`Output:` +Wrong Number of Arguments for HGET Command +```bash +127.0.0.1:7379> HGET product:2000 +(error) ERR wrong number of arguments for 'hget' command + +127.0.0.1:7379> HGET product:2000 name name2 +(error) ERR wrong number of arguments for 'hget' command ``` -(error) WRONGTYPE Operation against a key holding the wrong kind of value -``` +- **Behavior**: The `HGET` command requires exactly two arguments: the key and the field name. +- **Error**: The command will raise an error if provided with an incorrect number of arguments, indicating that the command requires a specific count. ## Notes - The `HGET` command is a read-only command and does not modify the hash or any other data in the DiceDB database. -- It is a constant time operation, O(1), meaning it executes in the same amount of time regardless of the size of the hash. By understanding the `HGET` command, you can efficiently retrieve values from hashes stored in your DiceDB database, ensuring that your application can access the necessary data quickly and reliably. - diff --git a/docs/src/content/docs/commands/HGETALL.md b/docs/src/content/docs/commands/HGETALL.md index b08b8b07d..974146341 100644 --- a/docs/src/content/docs/commands/HGETALL.md +++ b/docs/src/content/docs/commands/HGETALL.md @@ -7,24 +7,22 @@ The `HGETALL` command in DiceDB is used to retrieve all the fields and values of ## Syntax -``` +```bash HGETALL key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|--------------------------------------------------|---------|----------| -| `key` | The key of the hash from which you want to retrieve all fields and values. | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | -------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key of the hash from which you want to retrieve all fields and values. | String | Yes | ## Return values - -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| The `key` exists and is a hash | Array of strings -| The `key` does not exist | Empty array | +| Condition | Return Value | +| ------------------------------ | ---------------- | +| The `key` exists and is a hash | Array of strings | +| The `key` does not exist | Empty array | ## Behaviour @@ -42,11 +40,12 @@ The `HGETALL` command can raise the following errors: - `(error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value`: This error is raised if the specified key exists but is not a hash. DiceDB expects the key to be associated with a hash data structure, and if it is associated with a different data type (e.g., string, list, set, etc.), this error will be triggered. - `(empty array)` : This error is raised if the specified key does not exist. - `(error) ERROR wrong number of arguments for 'hgetall' command` : This error is raised if an invalid number of arguments are passed to the `HGETALL` command. + ## Example Usage ### Example 1: Retrieving all fields and values from an existing hash -```DiceDB +```bash 127.0.0.1:7379> HSET user:1000 name "John Doe" age "30" country "USA" (integer) 3 127.0.0.1:7379> HGETALL user:1000 @@ -65,7 +64,7 @@ The `HGETALL` command can raise the following errors: ### Example 2: Retrieving from a non-existing key -```DiceDB +```bash 127.0.0.1:7379> HGETALL user:2000 ``` @@ -76,9 +75,10 @@ The `HGETALL` command can raise the following errors: ``` ### Error Example: + Key is not a hash -```DiceDB +```bash 127.0.0.1:7379> SET user:3000 "This is a string" OK 127.0.0.1:7379> HGETALL user:3000 @@ -90,14 +90,16 @@ OK (error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value ``` -### Error Example: +### Error Example: + Invalid number of arguments are passed -```DiceDB +```bash 127.0.0.1:7379> HGETALL user:3000 helloworld ``` + `Output:` ``` (error) ERROR wrong number of arguments for 'hgetall' command -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/commands/HINCRBY.md b/docs/src/content/docs/commands/HINCRBY.md index d011cad86..160d82da3 100644 --- a/docs/src/content/docs/commands/HINCRBY.md +++ b/docs/src/content/docs/commands/HINCRBY.md @@ -13,27 +13,25 @@ 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 | - +| 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` | - +| 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. @@ -41,7 +39,6 @@ HINCRBY key field increment - 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`: @@ -51,44 +48,57 @@ HINCRBY key field increment - 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` + - 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` + - 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 +### 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 @@ -97,6 +107,7 @@ OK ``` ### Invalid number of arguments + Passing invalid number of arguments to the `hincrby` command ```bash @@ -105,6 +116,7 @@ Passing invalid number of arguments to the `hincrby` command ``` ### Invalid value type + Executing `hincrby` on a non-integer hash value ```bash @@ -114,8 +126,8 @@ Executing `hincrby` on a non-integer hash value (error) ERROR hash value is not an integer ``` - ### Invalid increment type passed + Executing `hincrby` with a string increment value ```bash @@ -123,8 +135,8 @@ Executing `hincrby` with a string increment value (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 @@ -133,12 +145,16 @@ Incrementing the hash value with a very large integer results in an integer over 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. \ No newline at end of file + +- 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. diff --git a/docs/src/content/docs/commands/HINCRBYFLOAT.md b/docs/src/content/docs/commands/HINCRBYFLOAT.md index 1a13bb715..e05323ad7 100644 --- a/docs/src/content/docs/commands/HINCRBYFLOAT.md +++ b/docs/src/content/docs/commands/HINCRBYFLOAT.md @@ -13,26 +13,24 @@ 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 | - +| 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` | - +| 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 @@ -41,7 +39,6 @@ HINCRBYFLOAT key field increment - 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`: @@ -54,31 +51,40 @@ HINCRBYFLOAT key field increment - 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` + - 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 +### 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 @@ -89,14 +95,18 @@ OK ``` ### 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 @@ -105,6 +115,7 @@ Executing `hincrbyfloat` on a non-integer hash value ``` ### Invalid increment type passed + Executing `hincrbyfloat` with a string increment value ```bash @@ -113,15 +124,16 @@ 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. +-`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. \ No newline at end of file +- `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. diff --git a/docs/hkeys_command_docs.md b/docs/src/content/docs/commands/HKEYS.md similarity index 81% rename from docs/hkeys_command_docs.md rename to docs/src/content/docs/commands/HKEYS.md index 6c993206a..36367bab0 100644 --- a/docs/hkeys_command_docs.md +++ b/docs/src/content/docs/commands/HKEYS.md @@ -14,15 +14,15 @@ HKEYS key ## Parameters | Parameter | Description | Type | Required | -|-----------|------------------------------------|--------|----------| +| --------- | ---------------------------------- | ------ | -------- | | `key` | The name of the key holding a hash | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If the key exists and holds a hash | Array of field names | -| If the key does not exist or is empty | Empty array `[]` | +| Condition | Return Value | +| ------------------------------------- | -------------------- | +| If the key exists and holds a hash | Array of field names | +| If the key does not exist or is empty | Empty array `[]` | ## Behaviour @@ -85,4 +85,4 @@ If the hash `user:1003` does not exist: - Ensure that `key` is of type hash before using `HKEYS`, as other data types will produce errors. -Using the `HKEYS` command, you can efficiently access all field names in hash structures, making it a valuable tool for dynamic data inspection in DiceDB. \ No newline at end of file +Using the `HKEYS` command, you can efficiently access all field names in hash structures, making it a valuable tool for dynamic data inspection in DiceDB. diff --git a/docs/src/content/docs/commands/HLEN.md b/docs/src/content/docs/commands/HLEN.md index 65d271201..2a2b8747f 100644 --- a/docs/src/content/docs/commands/HLEN.md +++ b/docs/src/content/docs/commands/HLEN.md @@ -7,23 +7,22 @@ The `HLEN` command in DiceDB is used to obtain the number of fields contained wi ## Syntax -``` +```bash HLEN key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|------------------------------------------------------------------------------------------|---------|----------| -| `key` | The key associated with the hash for which the number of fields is to be retrieved | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ---------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key associated with the hash for which the number of fields is to be retrieved | String | Yes | ## Return Value -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If specified key exists | number of fields in the hash at key | -| If key doesn't exist | `0` | +| Condition | Return Value | +| ----------------------- | ----------------------------------- | +| If specified key exists | number of fields in the hash at key | +| If key doesn't exist | `0` | ## Behaviour @@ -44,36 +43,38 @@ HLEN key - Error Message: `(error) -ERR wrong number of arguments for 'HLEN' command` - Occurs if key isn't specified in the command. - ## Example Usage ### Basic Usage + Creating hash `myhash` with two fields `field1` and `field2`. Getting hash length of `myhash`. -```DiceDB -> HSET myhash field1 "value1" field2 "value2" +```bash +127.0.0.1:7379> HSET myhash field1 "value1" field2 "value2" (integer) 2 -> HLEN myhash +127.0.0.1:7379> HLEN myhash (integer) 2 ``` ### Invalid Usage on non-existent key + Getting hash length from a non-existent hash key `nonExistentHash`. -```DiceDB -> HLEN nonExistentHash +```bash +127.0.0.1:7379> HLEN nonExistentHash (integer) 0 ``` ### Invalid Usage on non-hash key + Getting hash length from a key `mystring` associated with a non-hash type. -```DiceDB -> SET mystring "This is a string" +```bash +127.0.0.1:7379> SET mystring "This is a string" OK -> HLEN mystring +127.0.0.1:7379> HLEN mystring (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` @@ -83,4 +84,3 @@ OK - This command is useful for quickly determining the size of a hash without needing to retrieve all the fields and values. By understanding the `HLEN` command, you can efficiently manage and interact with hash data structures in DiceDB, ensuring that your applications can handle hash-based data effectively. - diff --git a/docs/src/content/docs/commands/HMGET.md b/docs/src/content/docs/commands/HMGET.md new file mode 100644 index 000000000..186daebde --- /dev/null +++ b/docs/src/content/docs/commands/HMGET.md @@ -0,0 +1,108 @@ +--- +title: HMGET +description: The `HMGET` command in DiceDB is used to retrieve the values of one or more specified fields from a hash. It allows efficient fetching of specific fields from a hash without retrieving the entire hash. +--- + +The `HMGET` command in DiceDB is used to retrieve the values of one or more specified fields from a hash. It allows efficient fetching of specific fields from a hash without retrieving the entire hash. + +## Syntax + +```bash +HMGET key field [field ...] +``` + +## Parameters + +| Parameter | Description | Type | Required | +|-----------------|---------------------------------------------------------------|---------|----------| +| `key` | The name of the hash. | String | Yes | +| `field` | The field within the hash to retrieve the value for. | String | Yes | +| `[field ...]` | Additional fields to retrieve from the hash. | String | No | + +## Return Values + +| Condition | Return Value | +|----------------------------------------------|-----------------------------------------------------------------------------| +| Field exists | `String` (The value of the field) | +| Field does not exist | `nil` | +| Multiple fields retrieved | List of values for each field | +| Wrong data type | `(error) WRONGTYPE Operation against a key holding the wrong kind of value` | +| Incorrect Argument Count | `(error) ERR wrong number of arguments for 'hmget' command` | + +## Behaviour + +When the `HMGET` command is executed, the following actions occur: + +- The specified fields are fetched from the hash. +- If a field exists, its value is returned. +- If a field does not exist, `nil` is returned for that field. +- The command returns a list of values, corresponding to each field requested. + +## Errors + +The `HMGET` command can raise errors in the following scenarios: + +1. `Non-hash type or wrong data type`: + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if `key` holds a non-hash data structure. + +2. `Incorrect Argument Count`: + + - Error Message: `(error) ERR wrong number of arguments for 'hmget' command` + - Occurs if the command is not provided with the correct number of arguments (i.e., fewer than two). + +## Example Usage + +### Basic Usage + +#### Retrieving Multiple Fields + +```bash +127.0.0.1:7379> HMGET product:2000 name price stock +1) "Laptop" +2) "999.99" +3) "50" +``` +- **Behaviour**: The values of the fields `name`, `price`, and `stock` from the hash `product:2000` are retrieved and returned in the order specified. +- **Return Value**: List of field values. + +#### Retrieving Fields with Missing Values + +```bash +127.0.0.1:7379> HMGET product:2000 name description +1) "Laptop" +2) (nil) +``` +- **Behaviour**: The `name` field exists, so its value is returned. The `description` field does not exist in the hash, so `nil` is returned. +- **Return Value**: List with value and `nil`. + +### Invalid Usage + +Trying to retrieve fields from a key that is not a hash. + +```bash +127.0.0.1:7379> SET product:2000 "This is a string" +OK +127.0.0.1:7379> HMGET product:2000 name price +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` + +- **Behaviour**: The `SET` command sets the key `product:2000` to a string value. +- **Error**: The `HMGET` command will raise a `WRONGTYPE` error because `product:2000` is not a hash. + +Missing Key or Field Arguments + +```bash +127.0.0.1:7379> HMGET +(error) ERR wrong number of arguments for 'hmget' command + +127.0.0.1:7379> HMGET product:2000 +(error) ERR wrong number of arguments for 'hmget' command +``` +- **Behavior**: The `HGET` command requires at least two arguments: the key and the field name. +- **Error**: The command fails if no key or fields are specified. DiceDB raises an error indicating that the number of arguments is incorrect. + +### Best Practices + +- Use `HMGET` to fetch only the fields you need from a hash to minimize data transfer and improve performance. diff --git a/docs/src/content/docs/commands/HMSET.md b/docs/src/content/docs/commands/HMSET.md new file mode 100644 index 000000000..4b07238e7 --- /dev/null +++ b/docs/src/content/docs/commands/HMSET.md @@ -0,0 +1,107 @@ +--- +title: HMSET +description: The `HMSET` command in DiceDB is used to set multiple field-value pairs in a hash at once. If the hash does not exist, a new hash is created. This command is efficient for setting multiple fields at once within a hash data structure. +--- + +The `HMSET` command in DiceDB is used to set multiple field-value pairs in a hash at once. If the hash does not exist, a new hash is created. This command is efficient for setting multiple fields at once within a hash data structure. + +## Syntax + +```bash +HMSET key field value [field value ...] +``` + +## Parameters + +| Parameter | Description | Type | Required | +|---------------------|---------------------------------------------------------------|---------|----------| +| `key` | The name of the hash. | String | Yes | +| `field` | The field within the hash to set the value for. | String | Yes | +| `value` | The value to set for the specified field. | String | Yes | +| `[field value ...]` | Additional field-value pairs to set in the hash. | String | No | + +## Return Values + +| Condition | Return Value | +|----------------------------------------------|-----------------------------------------------------------------------------| +| A new field added | `OK` | +| Existing field updated | `OK` | +| Multiple fields added | `OK` | +| Non-hash type or wrong data type | `(error) WRONGTYPE Operation against a key holding the wrong kind of value` | +| Incorrect Argument Count | `(error) ERR wrong number of arguments for 'hmset' command` | + + +## Behaviour + +When the `HMSET` command is executed, the following actions occur: + +- If the specified hash does not exist, a new hash is created. +- The specified fields and values are set in the hash. +- If any field already exists, its value is updated with the new value provided. +- The command returns `OK` to indicate successful execution. + +## Errors + +The `HMSET` command can raise errors in the following scenarios: + +1. `Non-hash type or wrong data type`: + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if `key` holds a non-hash data structure. + +2. `Incorrect Argument Count`: + + - Error Message: `(error) ERR wrong number of arguments for 'hmset' command` + - Occurs if the command is not provided with the correct number of arguments (i.e., an even number of arguments after the key). + +## Example Usage + +### Basic Usage + +#### Creating a New Hash with Multiple Fields + +```bash +127.0.0.1:7379> HMSET product:4000 name "Tablet" price 299.99 stock 30 +OK +``` +- **Behaviour**: A new hash is created with the key `product:4000`. The fields `name`, `price`, and `stock` are set with the respective values. +- **Return Value**: `OK` + +#### Updating an Existing Hash with Multiple Fields + +```bash +127.0.0.1:7379> HMSET product:4000 price 279.99 stock 25 +OK +``` +- **Behaviour**: The `price` and `stock` fields in the hash `product:4000` are updated with the new values. +- **Return Value**: `OK` + +### Invalid Usage + +Trying to set fields in a key that is not a hash. + +```bash +127.0.0.1:7379> SET product:4000 "This is a string" +OK +127.0.0.1:7379> HMSET product:4000 name "Tablet" +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` + +- **Behaviour**: The `SET` command sets the key `product:4000` to a string value. +- **Error**: The `HMSET` command will raise a `WRONGTYPE` error because `product:4000` is not a hash. + +Wrong Number of Arguments for HMSET Command + +```bash +127.0.0.1:7379> HMSET product:4000 +(error) ERR wrong number of arguments for 'hmset' command + +127.0.0.1:7379> HMSET product:4000 name +(error) ERR wrong number of arguments for 'hmset' command +``` +- **Behavior**: The `HMSET` command requires atleast three arguments: the key, the field name, and the field value. +- **Error**: The command fails because it requires at least one field-value pair in addition to the key. If insufficient arguments are provided, DiceDB raises an error indicating that the number of arguments is incorrect. + +### Best Practices + +- **Use HMSET for Batch Updates**: Utilize `HMSET` when you need to set multiple fields at once in a hash to reduce command overhead and improve performance. diff --git a/docs/src/content/docs/commands/HRANDFIELD.md b/docs/src/content/docs/commands/HRANDFIELD.md index afcbf2ac2..24138be64 100644 --- a/docs/src/content/docs/commands/HRANDFIELD.md +++ b/docs/src/content/docs/commands/HRANDFIELD.md @@ -7,39 +7,41 @@ The `HRANDFIELD` command in DiceDB is used to return one or more random fields f ## Syntax -``` +```bash 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 | +| 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` | +| 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 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. @@ -49,29 +51,36 @@ HRANDFIELD key [count [WITHVALUES]] 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 +127.0.0.1:7379> HSET keys field1 value1 field2 value2 field3 value3 (integer) 3 -127.0.0.1:6379> HRANDFIELD keys +127.0.0.1:7379> 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 +127.0.0.1:7379> 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 +127.0.0.1:7379> HRANDFIELD keys 2 WITHVALUES 1) "field2" 2) "value2" 3) "field1" @@ -79,37 +88,44 @@ Executing `HRANDFIELD` with the `WITHVALUES` parameter ``` ### Invalid key usage + Executing `hrandfield` on a non-hash key ```bash -127.0.0.1:6379> SET key "not a hash" +127.0.0.1:7379> SET key "not a hash" OK -127.0.0.1:6379> HRANDFIELD key +127.0.0.1:7379> HRANDFIELD key (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` ### Invalid count parameter -Non-integer value passed as `count` + +Non-integer value passed as `count` ```bash -127.0.0.1:6379> HRANDFIELD keys hello +127.0.0.1:7379> 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 +127.0.0.1:7379> 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. \ No newline at end of file +- 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. diff --git a/docs/src/content/docs/commands/HSCAN.md b/docs/src/content/docs/commands/HSCAN.md index 5c46c6e0d..8e416e8b1 100644 --- a/docs/src/content/docs/commands/HSCAN.md +++ b/docs/src/content/docs/commands/HSCAN.md @@ -7,19 +7,18 @@ The `HSCAN` command is used to incrementally iterate over the fields of a hash s ## Syntax -``` +```bash HSCAN key cursor [MATCH pattern] [COUNT count] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|----------------------------------------------------------------------------------------------------------|---------|----------| -| `key` | The key of the hash to scan. | String | Yes | -| `cursor` | The cursor indicating the starting position of the scan. | String | Yes | -| `MATCH pattern` | Specifies a pattern to match against the fields. Only the fields that match the pattern will be returned.| String | No | -| `COUNT count` | Specifies the maximum number of fields to return. | String | Yes | - +| Parameter | Description | Type | Required | +| --------------- | --------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key of the hash to scan. | String | Yes | +| `cursor` | The cursor indicating the starting position of the scan. | String | Yes | +| `MATCH pattern` | Specifies a pattern to match against the fields. Only the fields that match the pattern will be returned. | String | No | +| `COUNT count` | Specifies the maximum number of fields to return. | String | Yes | ## Return Value @@ -48,34 +47,37 @@ The `HSCAN` command returns an array containing the next cursor and the matching ## Examples ### Basic Usage + Creating a hash `myhash` with two fields `field1` and `field2`. Getting `HSCAN` on `myhash` with valid cursors. ```bash -> HSET myhash field1 "value1" field2 "value2" +127.0.0.1:7379> HSET myhash field1 "value1" field2 "value2" 1) (integer) 2 -> HSCAN myhash 0 +127.0.0.1:7379> HSCAN myhash 0 1) "2" 2) 1) "field1" 2) "value1" 3) "field2" 4) "value2" -> HSCAN myhash 0 MATCH field* COUNT 1 +127.0.0.1:7379> HSCAN myhash 0 MATCH field* COUNT 1 1) "1" 2) 1) "field1" 2) "value1" -> HSCAN myhash 1 MATCH field* COUNT 1 +127.0.0.1:7379> HSCAN myhash 1 MATCH field* COUNT 1 1) "0" 2) 1) "field2" 2) "value2" ``` + ### Invalid Usage on non-existent key -Getting `HSCAN` on nonExistentHash. + +Getting `HSCAN` on `nonExistentHash`. ```bash -> HSCAN nonExistentHash 0 +127.0.0.1:7379> HSCAN nonExistentHash 0 1) "0" 2) (empty array) ``` diff --git a/docs/src/content/docs/commands/HSET.md b/docs/src/content/docs/commands/HSET.md index 32a1ec593..d3eeed0a0 100644 --- a/docs/src/content/docs/commands/HSET.md +++ b/docs/src/content/docs/commands/HSET.md @@ -1,95 +1,135 @@ --- title: HSET -description: Documentation for the DiceDB command HSET +description: The `HSET` command in DiceDB is used to set the value of a field in a hash. If the hash does not exist, a new hash is created. If the field already exists in the hash, the value is updated. This command is useful for managing and storing key-value pairs within a hash data structure. --- The `HSET` command in DiceDB is used to set the value of a field in a hash. If the hash does not exist, a new hash is created. If the field already exists in the hash, the value is updated. This command is useful for managing and storing key-value pairs within a hash data structure. ## Syntax -``` +```bash HSET key field value [field value ...] ``` ## Parameters -- `key`: The name of the hash. -- `field`: The field within the hash to set the value for. -- `value`: The value to set for the specified field. -- `[field value ...]`: Optional additional field-value pairs to set in the hash. +| Parameter | Description | Type | Required | +|---------------------|---------------------------------------------------------------|---------|----------| +| `key` | The name of the hash. | String | Yes | +| `field` | The field within the hash to set the value for. | String | Yes | +| `value` | The value to set for the specified field. | String | Yes | +| `[field value ...]` | Optional additional field-value pairs to set in the hash. | String | No | -## Return Value +## Return Values -- `Integer`: The number of fields that were added to the hash, not including fields that were already present and updated. +| Condition | Return Value | +|---------------------------------------------|-----------------------------------------------------------------------------| +| A new field added | `1` | +| Existing field updated | `0` | +| Multiple fields added | `Integer` (count of new fields) | +| Wrong data type | `(error) WRONGTYPE Operation against a key holding the wrong kind of value` | +| Incorrect Argument Count | `(error) ERR wrong number of arguments for 'hset' command` | ## Behaviour When the `HSET` command is executed, the following actions occur: -1. If the specified hash does not exist, a new hash is created. -2. The specified field(s) and value(s) are set in the hash. -3. If a field already exists, its value is updated with the new value provided. -4. The command returns the number of fields that were newly added to the hash. +- If the specified hash does not exist, a new hash is created. +- The specified field(s) and value(s) are set in the hash. +- If a field already exists, its value is updated with the new value provided. +- The command returns the number of fields that were newly added to the hash. -## Error Handling +## Errors The `HSET` command can raise errors in the following scenarios: -1. `WRONGTYPE Operation against a key holding the wrong kind of value`: This error occurs if the key exists but is not a hash. -2. `ERR wrong number of arguments for 'hset' command`: This error occurs if the command is not provided with the correct number of arguments (i.e., an even number of arguments after the key). +1. `Non-hash type or wrong data type`: + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if `key` holds a non-hash data structure. + +2. `Incorrect Argument Count`: + + - Error Message: `(error) ERR wrong number of arguments for 'hset' command` + - occurs if the command is not provided with the correct number of arguments (i.e., an even number of arguments after the key). ## Example Usage -### Basic Example +### Basic Usage + +#### Creating a New Hash -```DiceDB -HSET user:1000 name "John Doe" age 30 +```bash +127.0.0.1:7379> HSET product:2000 name "Laptop" price 999.99 stock 50 +3 ``` +- **Behaviour**: A new hash is created with the key `product:2000`. The fields `name`, `price`, and `stock` are set with the respective values. +- **Return Value**: `3` (since three new fields were added). -This command sets the `name` field to "John Doe" and the `age` field to 30 in the hash stored at `user:1000`. If the hash does not exist, it will be created. +#### Updating an Existing Hash -### Multiple Field-Value Pairs +Updating existing fields in a hash `product:2000`. -```DiceDB -HSET user:1000 name "John Doe" age 30 email "john.doe@example.com" +```bash +127.0.0.1:7379> HSET product:2000 price 899.99 stock 45 ``` -This command sets the `name`, `age`, and `email` fields in the hash stored at `user:1000`. If the hash does not exist, it will be created. +- **Behavior**: The `price` and `stock` fields in the hash `product:2000` are updated with the new values. +- **Return Value**: `0` (since no new fields were added, only existing fields were updated). + +#### Setting Multiple Field-Value Pairs -### Updating Existing Fields +Setting multiple fields in a hash `user:1000`. -```DiceDB -HSET user:1000 age 31 +```bash +127.0.0.1:7379> HSET user:1000 name "John Doe" age 30 email "john.doe@example.com" ``` -This command updates the `age` field to 31 in the hash stored at `user:1000`. If the `age` field already exists, its value is updated. +- **Behavior**: This command sets the `name`, `age`, and `email` fields in the hash stored at `user:1000`. If the hash does not exist, it will be created. +- **Return Value**: `3` (if all three fields were added). -## Detailed Example +#### Updating Existing Fields -### Creating a New Hash +Updating a field in an existing hash `user:1000`. -```DiceDB -HSET product:2000 name "Laptop" price 999.99 stock 50 +```bash +127.0.0.1:7379> HSET user:1000 age 31 ``` -- `Behaviour`: A new hash is created with the key `product:2000`. The fields `name`, `price`, and `stock` are set with the respective values. -- `Return Value`: `3` (since three new fields were added). +- **Behavior**: This command updates the `age` field to 31 in the hash stored at `user:1000`. If the `age` field already exists, its value is updated. +- **Return Value**: `0` (if the field was already present and only updated). -### Updating an Existing Hash +### Invalid Usage -```DiceDB -HSET product:2000 price 899.99 stock 45 +Trying to set a field in a key that is not a hash. + +```bash +127.0.0.1:7379> SET product:2000 "This is a string" +OK +127.0.0.1:7379> HSET product:2000 name "Laptop" +(error) WRONGTYPE Operation against a key holding the wrong kind of value ``` -- `Behaviour`: The `price` and `stock` fields in the hash `product:2000` are updated with the new values. -- `Return Value`: `0` (since no new fields were added, only existing fields were updated). +- **Behavior**: The `SET` command sets the key `product:2000` to a string value. +- **Error**: The `HSET` command will raise a `WRONGTYPE` error because `product:2000` is not a hash. + +Wrong Number of Arguments for HSET Command -### Error Handling Example +```bash +127.0.0.1:7379> HSET product:2000 +(error) ERR wrong number of arguments for 'hset' command -```DiceDB -SET product:2000 "This is a string" -HSET product:2000 name "Laptop" +127.0.0.1:7379> HSET product:2000 name +(error) ERR wrong number of arguments for 'hset' command ``` +- **Behavior**: The `HSET` command requires atleast three arguments: the key, the field name, and the field value. +- **Error**: The command fails because it requires at least one field-value pair in addition to the key. If insufficient arguments are provided, DiceDB raises an error indicating that the number of arguments is incorrect. + +### Best Practices + +- **Check for Existence**: Before updating fields, consider checking if the hash exists to avoid unnecessary updates. + +## Notes -- `Behaviour`: The `SET` command sets the key `product:2000` to a string value. -- `Error`: The `HSET` command will raise a `WRONGTYPE` error because `product:2000` is not a hash. +- `HSET` can also accept multiple field-value pairs, making it efficient for adding or updating multiple fields in a single command. +By understanding the `HSET` command, you can effectively update or expand hashes in your DiceDB database, allowing for quick modifications and optimizations when handling key-value pairs within hashes. diff --git a/docs/src/content/docs/commands/HSETNX.md b/docs/src/content/docs/commands/HSETNX.md new file mode 100644 index 000000000..994e4c2a8 --- /dev/null +++ b/docs/src/content/docs/commands/HSETNX.md @@ -0,0 +1,105 @@ +--- +title: HSETNX +description: The `HSETNX` command in DiceDB is used to set the value of a field in a hash only if the field does not already exist. This command is useful for ensuring that a value is only set if it is not already present. +--- + +The `HSETNX` command in DiceDB is used to set the value of a field in a hash only if the field does not already exist. This command is useful for ensuring that a value is only set if it is not already present. + +## Syntax + +```bash +HSETNX key field value +``` + +## Parameters + +| Parameter | Description | Type | Required | +|-----------|----------------------------------------------------------|---------|----------| +| `key` | The name of the hash. | String | Yes | +| `field` | The field within the hash to set the value for. | String | Yes | +| `value` | The value to set for the specified field. | String | Yes | + +## Return Values + +| Condition | Return Value | +|---------------------------------------------|-----------------------------------------------------------------------------| +| Field added | `1` | +| Field already exists | `0` | +| Wrong data type | `(error) WRONGTYPE Operation against a key holding the wrong kind of value` | +| Incorrect Argument Count | `(error) ERR wrong number of arguments for 'hsetnx' command` | + +## Behaviour + +When the `HSETNX` command is executed, the following actions occur: + +- If the specified hash does not exist, a new hash is created. +- The specified field and value are set in the hash only if the field does not already exist. +- If the field already exists, the command does not modify the existing value and returns `0`. +- The command returns `1` if the field was successfully added to the hash. + +## Errors + +The `HSETNX` command can raise errors in the following scenarios: + +1. `Non-hash type or wrong data type`: + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if `key` holds a non-hash data structure. + +2. `Incorrect Argument Count`: + + - Error Message: `(error) ERR wrong number of arguments for 'hsetnx' command` + - Occurs if the command is not provided with the correct number of arguments (i.e., fewer than three). + +## Example Usage + +### Basic Usage + +#### Creating a New Hash with `HSETNX` + +```bash +127.0.0.1:7379> HSETNX product:3000 name "Smartphone" +1 +``` +- **Behaviour**: A new hash is created with the key `product:3000`. The field `name` is set with the value "Smartphone". +- **Return Value**: `1` (since the field was added). + +#### Attempting to Set an Existing Field + +```bash +127.0.0.1:7379> HSETNX product:3000 name "Tablet" +0 +``` + +- **Behaviour**: The command attempts to set the `name` field to "Tablet", but since `name` already exists in the hash, it does not change the value. +- **Return Value**: `0` (since the field was not added). + +### Invalid Usage + +Trying to set a field in a key that is not a hash. + +```bash +127.0.0.1:7379> SET product:3000 "This is a string" +OK +127.0.0.1:7379> HSETNX product:3000 name "Smartphone" +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` + +- **Behaviour**: The `SET` command sets the key `product:3000` to a string value. +- **Error**: The `HSETNX` command raises a `WRONGTYPE` error because `product:3000` is not a hash. + +Wrong Number of Arguments for `HSETNX` Command + +```bash +127.0.0.1:7379> HSETNX product:3000 +(error) ERR wrong number of arguments for 'hsetnx' command + +127.0.0.1:7379> HSETNX product:3000 name +(error) ERR wrong number of arguments for 'hsetnx' command +``` +- **Behavior**: The `HSETNX` command requires atleast three arguments: the key, the field name, and the field value. +- **Error**: The command fails because it requires the `key`, `field`, and `value` parameters. If insufficient arguments are provided, DiceDB raises an error indicating that the number of arguments is incorrect. + +### Best Practices + +- Use `HSETNX` when you need to ensure that a field is only set if it does not already exist, preventing accidental overwrites. diff --git a/docs/src/content/docs/commands/HSTRLEN.md b/docs/src/content/docs/commands/HSTRLEN.md index 35c6e56ad..635441237 100644 --- a/docs/src/content/docs/commands/HSTRLEN.md +++ b/docs/src/content/docs/commands/HSTRLEN.md @@ -3,28 +3,28 @@ title: HSTRLEN description: Documentation for the DiceDB command HSTRLEN --- -The `HSTRLEN` command in DiceDB is used to obtain the string length of value associated with field in the hash stored at a specified key. +The `HSTRLEN` command in DiceDB is used to obtain the string length of value associated with field in the hash stored at a specified key. ## Syntax -``` +```bash HSTRLEN key field ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|------------------------------------------------------------------------------------------|---------|----------| -| `key` | The key of the hash, which consists of the field whose string length you want to obtain | String | Yes | -| `field` | The field present in the hash whose length you want to obtain | String | Yes | +| Parameter | Description | Type | Required | +| --------- | --------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key of the hash, which consists of the field whose string length you want to obtain | String | Yes | +| `field` | The field present in the hash whose length you want to obtain | String | Yes | ## Return Value -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If specified key and field exists | string length | -| If key doesn't exist | `0` | -| If field doesn't exist | `0` | +| Condition | Return Value | +| --------------------------------- | ------------- | +| If specified key and field exists | string length | +| If key doesn't exist | `0` | +| If field doesn't exist | `0` | ## Behaviour @@ -48,32 +48,35 @@ HSTRLEN key field ## Example Usage ### Basic Usage + Creating hash `myhash` with two fields `field1` and `field2`. Getting string length of value in `field1`. -```DiceDB -> HSET myhash field1 "helloworld" field2 "value2" +```bash +127.0.0.1:7379> HSET myhash field1 "helloworld" field2 "value2" (integer) 1 -> HSTRLEN myhash field1 +127.0.0.1:7379> HSTRLEN myhash field1 (integer) 10 ``` ### Invalid Usage on non-existent key + Getting string length from a non-existent key `nonExistentHash`. -```DiceDB -> HSTRLEN nonExistentHash field1 +```bash +127.0.0.1:7379> HSTRLEN nonExistentHash field1 (integer) 0 ``` ### Invalid Usage on non-hash key + Getting string length from a key `mystring` associated with a non-hash type. -```DiceDB -> SET mystring "This is a string" +```bash +127.0.0.1:7379> SET mystring "This is a string" OK -> HSTRLEN mystring field1 +127.0.0.1:7379> HSTRLEN mystring field1 (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` diff --git a/docs/hvals_command_docs.md b/docs/src/content/docs/commands/HVALS.md similarity index 81% rename from docs/hvals_command_docs.md rename to docs/src/content/docs/commands/HVALS.md index 8ab5dc3ae..c21bef414 100644 --- a/docs/hvals_command_docs.md +++ b/docs/src/content/docs/commands/HVALS.md @@ -14,15 +14,15 @@ HVALS key ## Parameters | Parameter | Description | Type | Required | -|-----------|------------------------------------|--------|----------| +| --------- | ---------------------------------- | ------ | -------- | | `key` | The name of the key holding a hash | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If the key exists and holds a hash | Array of values within the hash | -| If the key does not exist or is empty | Empty array `[]` | +| Condition | Return Value | +| ------------------------------------- | ------------------------------- | +| If the key exists and holds a hash | Array of values within the hash | +| If the key does not exist or is empty | Empty array `[]` | ## Behaviour @@ -85,4 +85,4 @@ If the hash `user:1003` does not exist: - Ensure `key` is a hash type to avoid errors when using `HVALS`. -Using the `HVALS` command enables efficient access to all values within a hash structure in DiceDB, simplifying data retrieval when field names are unnecessary. \ No newline at end of file +Using the `HVALS` command enables efficient access to all values within a hash structure in DiceDB, simplifying data retrieval when field names are unnecessary. diff --git a/docs/src/content/docs/commands/INCR.md b/docs/src/content/docs/commands/INCR.md index 2e2c0c463..1be0bfa53 100644 --- a/docs/src/content/docs/commands/INCR.md +++ b/docs/src/content/docs/commands/INCR.md @@ -7,7 +7,7 @@ The `INCR` command in DiceDB is used to increment the integer value of a key by ## Syntax -```plaintext +```bash INCR key ``` @@ -17,10 +17,10 @@ INCR key ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | `Integer` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------ | +| Command is successful | `Integer` | +| Syntax or specified constraints are invalid | error | ## Behaviour @@ -33,18 +33,17 @@ When the `INCR` command is executed, the following steps occur: 5. `Return New Value`: The new value is returned to the client. ## Errors + 1. `Wrong Type Error`: - Error Message: `(error) ERR value is not an integer or out of range` - If the key exists but does not hold a string value that can be interpreted as an integer, DiceDB will return an error. - 2. `Overflow Error`: - Error Message: `(error) ERR increment or decrement would overflow` - If the increment operation causes the value to exceed the maximum integer value that DiceDB can handle, an overflow error will occur. - ## Example Usage ### Basic Usage @@ -69,6 +68,7 @@ Incrementing a non-existent key `newkey` by `1`: ### Error Scenario: Non-Integer Value Incrementing a key `mykey` with a non-integer value: + ```bash 127.0.0.1:7379> SET mykey "hello" 127.0.0.1:7379> INCR mykey @@ -78,6 +78,7 @@ Incrementing a key `mykey` with a non-integer value: ### Error Scenario: Overflow Incrementing a key `mykey` with a value that exceeds the maximum integer value: + ```bash 127.0.0.1:7379> SET mykey 9223372036854775807 127.0.0.1:7379> INCR mykey @@ -90,7 +91,6 @@ Incrementing a key `mykey` with a value that exceeds the maximum integer value: - The atomic nature of the `INCR` command ensures that it is safe to use in concurrent environments without additional synchronization mechanisms. - For decrementing a value, you can use the `DECR` command, which works similarly but decreases the value by one. - ## Alternatives - You can also use the `INCRBY` command to increment the value of a key by a specified amount. diff --git a/docs/src/content/docs/commands/INCRBY.md b/docs/src/content/docs/commands/INCRBY.md index 9ebc383ec..7c2c893d1 100644 --- a/docs/src/content/docs/commands/INCRBY.md +++ b/docs/src/content/docs/commands/INCRBY.md @@ -7,34 +7,34 @@ The `INCRBY` command in DiceDB is used to increment the integer value of a key b ## Syntax -``` +```bash INCRBY key delta ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------------------------------------------|---------|----------| -| `key` | The key whose value you want to increment. This key must hold a string that can be represented as an integer. | String | Yes | -|`delta` | The integer value by which the key's value should be increased. This value can be positive or negative. | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key whose value you want to increment. This key must hold a string that can be represented as an integer. | String | Yes | +| `delta` | The integer value by which the key's value should be increased. This value can be positive or negative. | String | Yes | ## Return values -| Condition | Return Value | -|--------------------------------------------------|------------------------------------------------------------------| -| Key exists and holds an integer string | `(integer)` The value of the key after incrementing by delta. | -| Key does not exist | `(integer)` delta | - +| Condition | Return Value | +| -------------------------------------- | ------------------------------------------------------------- | +| Key exists and holds an integer string | `(integer)` The value of the key after incrementing by delta. | +| Key does not exist | `(integer)` delta | ## Behaviour + When the `INCRBY` command is executed, the following steps occur: -- DiceDB checks if the key exists. -- If the key does not exist, DiceDB treats the key's value as 0 before performing the increment operation. -- If the key exists but does not hold a string that can be represented as an integer, an error is returned. -- The value of the key is incremented by the specified increment value. -- The new value of the key is returned. +- DiceDB checks if the key exists. +- If the key does not exist, DiceDB treats the key's value as 0 before performing the increment operation. +- If the key exists but does not hold a string that can be represented as an integer, an error is returned. +- The value of the key is incremented by the specified increment value. +- The new value of the key is returned. + ## Errors The `INCRBY` command can raise errors in the following scenarios: @@ -55,19 +55,18 @@ The `INCRBY` command can raise errors in the following scenarios: - Error Message: `ERR increment or decrement would overflow` - If the increment operation causes the value to exceed the maximum integer value that DiceDB can handle, an overflow error will occur. - ## Examples ### Example with Incrementing the Value of an Existing Key - ```bash 127.0.0.1:7379>SET mycounter 10 OK 127.0.0.1:7379>INCRBY mycounter 3 (integer)13 ``` -`Explanation:` + +`Explanation:` - In this example, the value of `mycounter` is set to 10 - The `INCRBY` command incremented `mycounter` by 3, resulting in a new value of 13. @@ -78,8 +77,11 @@ OK 127.0.0.1:7379>INCRBY newcounter 5 (integer)5 ``` -`Explanation:` + +`Explanation:` + - In this example, since `newcounter` does not exist, DiceDB treats its value as 0 and increments it by 5, resulting in a new value of 5. + ### Example with Error Due to Non-Integer Value in Key ```bash @@ -88,7 +90,9 @@ OK 127.0.0.1:7379>INCRBY mystring 2 (error) ERR value is not an integer or out of range ``` -`Explanation:` + +`Explanation:` + - In this example, the key `mystring` holds a non-integer value, so the `INCRBY` command returns an error. ### Example with Error Due to Invalid Increment Value (Non-Integer Decrement) @@ -98,7 +102,6 @@ OK (error) ERR value is not an integer or out of range ``` -`Explanation:` -- In this example, the increment value "two" is not a valid integer, so the `INCRBY` command returns an error. - +`Explanation:` +- In this example, the increment value "two" is not a valid integer, so the `INCRBY` command returns an error. diff --git a/docs/src/content/docs/commands/INCRBYFLOAT.md b/docs/src/content/docs/commands/INCRBYFLOAT.md index fcdd293a7..c93fc898d 100644 --- a/docs/src/content/docs/commands/INCRBYFLOAT.md +++ b/docs/src/content/docs/commands/INCRBYFLOAT.md @@ -7,34 +7,34 @@ The `INCRBYFLOAT` command in DiceDB is used to increment the numeric value of a ## Syntax -``` +```bash INCRBYFLOAT key delta ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------------------------------------------|---------|----------| -| `key` | The key whose value you want to increment. This key must hold a string that can be represented as an number. | String | Yes | -|`delta` | The fractional value by which the key's value should be increased. This value can be positive or negative. | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------------------------------------ | ------ | -------- | +| `key` | The key whose value you want to increment. This key must hold a string that can be represented as an number. | String | Yes | +| `delta` | The fractional value by which the key's value should be increased. This value can be positive or negative. | String | Yes | ## Return values -| Condition | Return Value | -|--------------------------------------------------|------------------------------------------------------------------| -| Key exists and holds an numeric string | `(float)` The value of the key after incrementing by delta. | -| Key does not exist | `(float)` delta | - +| Condition | Return Value | +| -------------------------------------- | ----------------------------------------------------------- | +| Key exists and holds an numeric string | `(float)` The value of the key after incrementing by delta. | +| Key does not exist | `(float)` delta | ## Behaviour + When the `INCRBYFLOAT` command is executed, the following steps occur: -- DiceDB checks if the key exists. -- If the key does not exist, DiceDB treats the key's value as 0 before performing the increment operation. -- If the key exists but does not hold a string that can be represented as an number, an error is returned. -- The value of the key is incremented by the specified increment value. -- The new value of the key is returned. +- DiceDB checks if the key exists. +- If the key does not exist, DiceDB treats the key's value as 0 before performing the increment operation. +- If the key exists but does not hold a string that can be represented as an number, an error is returned. +- The value of the key is incremented by the specified increment value. +- The new value of the key is returned. + ## Errors The `INCRBYFLOAT` command can raise errors in the following scenarios: @@ -55,19 +55,18 @@ The `INCRBYFLOAT` command can raise errors in the following scenarios: - Error Message: `(error) ERR value is out of range` - If the increment operation causes the value to exceed the maximum float value that DiceDB can handle, an overflow error will occur. - ## Examples ### Example with Incrementing the Value of an Existing Key - ```bash 127.0.0.1:7379>SET mycounter 10 OK 127.0.0.1:7379>INCRBYFLOAT mycounter 3.4 "13.4" ``` -`Explanation:` + +`Explanation:` - In this example, the value of `mycounter` is set to 10 - The `INCRBYFLOAT` command incremented `mycounter` by 3.4, resulting in a new value of 13.4 @@ -78,8 +77,11 @@ OK 127.0.0.1:7379>INCRBYFLOAT newcounter 5.3 "5.3" ``` -`Explanation:` + +`Explanation:` + - In this example, since `newcounter` does not exist, DiceDB treats its value as 0 and increments it by 5.3, resulting in a new value of 5.3. + ### Example with Error Due to Wrong Value in Key ```bash @@ -88,7 +90,9 @@ OK 127.0.0.1:7379>INCRBYFLOAT mystring 2.3 (error) ERR value is not a valid float ``` -`Explanation:` + +`Explanation:` + - In this example, the key `mystring` holds a string value, so the `INCRBYFLOAT` command returns an error. ### Example with Error Due to Invalid Increment Value (Non-Integer Decrement) @@ -98,7 +102,6 @@ OK (error) ERR value is not a valid float ``` -`Explanation:` -- In this example, the increment value "two" is not a valid number, so the `INCRBYFLOAT` command returns an error. - +`Explanation:` +- In this example, the increment value "two" is not a valid number, so the `INCRBYFLOAT` command returns an error. diff --git a/docs/src/content/docs/commands/JSON.ARRAPPEND.md b/docs/src/content/docs/commands/JSON.ARRAPPEND.md index e962eb719..0b67acd40 100644 --- a/docs/src/content/docs/commands/JSON.ARRAPPEND.md +++ b/docs/src/content/docs/commands/JSON.ARRAPPEND.md @@ -28,14 +28,17 @@ When the `JSON.ARRAPPEND` command is executed, the specified JSON values are app ## Error Handling 1. `Wrong type of value or key`: + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs when attempting to use the command on a key that contains a non-string value. 2. `Invalid Key`: + - Error Message: `(error) ERR key does not exist` - Occurs when attempting to use the command on a key that does not exist. 3. `Invalid Path`: + - Error Message: `(error) ERR path %s does not exist` - Occurs when attempting to use the command on a path that does not exist in the JSON document. @@ -48,56 +51,56 @@ When the `JSON.ARRAPPEND` command is executed, the specified JSON values are app ### Example 1: Appending a single value to an array ```bash -127.0.0.1:6379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' +127.0.0.1:7379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' OK -127.0.0.1:6379> JSON.ARRAPPEND myjson .numbers 4 +127.0.0.1:7379> JSON.ARRAPPEND myjson .numbers 4 (integer) 4 -127.0.0.1:6379> JSON.GET myjson +127.0.0.1:7379> JSON.GET myjson "{\"numbers\":[1,2,3,4]}" ``` ### Example 2: Appending multiple values to an array ```bash -127.0.0.1:6379> JSON.SET myjson . '{"fruits": ["apple", "banana"]}' +127.0.0.1:7379> JSON.SET myjson . '{"fruits": ["apple", "banana"]}' OK -127.0.0.1:6379> JSON.ARRAPPEND myjson .fruits "cherry" "date" +127.0.0.1:7379> JSON.ARRAPPEND myjson .fruits "cherry" "date" (integer) 4 -127.0.0.1:6379> JSON.GET myjson +127.0.0.1:7379> JSON.GET myjson "{\"fruits\":[\"apple\",\"banana\",\"cherry\",\"date\"]}" ``` ### Example 3: Error when key does not exist ```bash -127.0.0.1:6379> JSON.ARRAPPEND nonexistingkey .array 1 +127.0.0.1:7379> JSON.ARRAPPEND nonexistingkey .array 1 (error) ERR key does not exist ``` ### Example 4: Error when path does not exist ```bash -127.0.0.1:6379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' +127.0.0.1:7379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' OK -127.0.0.1:6379> JSON.ARRAPPEND myjson .nonexistingpath 4 +127.0.0.1:7379> JSON.ARRAPPEND myjson .nonexistingpath 4 (error) ERR path .nonexistingpath does not exist ``` ### Example 5: Error when path is not an array ```bash -127.0.0.1:6379> JSON.SET myjson . '{"object": {"key": "value"}}' +127.0.0.1:7379> JSON.SET myjson . '{"object": {"key": "value"}}' OK -127.0.0.1:6379> JSON.ARRAPPEND myjson .object 4 +127.0.0.1:7379> JSON.ARRAPPEND myjson .object 4 (error) ERR path is not an array ``` ### Example 6: Error when invalid JSON is provided ```bash -127.0.0.1:6379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' +127.0.0.1:7379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' OK -127.0.0.1:6379> JSON.ARRAPPEND myjson .numbers invalidjson +127.0.0.1:7379> JSON.ARRAPPEND myjson .numbers invalidjson (error) ERR invalid JSON ``` @@ -107,4 +110,3 @@ OK - JSONPath expressions are used to navigate and specify the location within the JSON document. Familiarity with JSONPath syntax is beneficial for effective use of this command. By following this documentation, users can effectively utilize the `JSON.ARRAPPEND` command to manipulate JSON arrays within DiceDB. - diff --git a/docs/src/content/docs/commands/JSON.ARRINSERT.md b/docs/src/content/docs/commands/JSON.ARRINSERT.md index 51ff03bff..652316c53 100644 --- a/docs/src/content/docs/commands/JSON.ARRINSERT.md +++ b/docs/src/content/docs/commands/JSON.ARRINSERT.md @@ -3,7 +3,7 @@ title: JSON.ARRINSERT description: The JSON.ARRINSERT command in DiceDB is used to insert one or more JSON values into an array at a specified path before a given index. This command shifts all existing elements in the array to the right, making room for the new elements. --- -The JSON.ARRINSERT command allows you to insert one or more JSON values into an array at a specified path before a given index. All existing elements in the array are shifted to the right to make room for the new elements. +The `JSON.ARRINSERT` command allows you to insert one or more JSON values into an array at a specified path before a given index. All existing elements in the array are shifted to the right to make room for the new elements. This command returns an array of integer replies for each path, where each integer represents the new size of the array after the insertion. If the path does not exist or is not an array, it returns an error. @@ -15,22 +15,22 @@ JSON.ARRINSERT [value ...] ## 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 | -| `index` | Position where values will be inserted. Positive for start-to-end, negative for end-to-start. | Integer | Yes | -| `value` | JSON value(s) to be inserted into the array. | JSON | Yes | +| 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 | +| `index` | Position where values will be inserted. Positive for start-to-end, negative for end-to-start. | Integer | Yes | +| `value` | JSON value(s) to be inserted into the array. | JSON | Yes | ## Return Values -| Condition | Return Value | -|-------------------------------|------------------------------------------------------------------------| -| Array successfully updated | (Int) `Integer representing the new array size at each matched path` | -| Key does not exist | Error: `(error) ERR key does not exist` | -| Path is not valid | Error: `(error) ERR Existing key has wrong Dice type` | -| Invalid JSON value | Error: `(error) ERR Path does not exist` | -| Invalid index | Error: `(error) ERR index out of bounds` | +| Condition | Return Value | +| -------------------------- | -------------------------------------------------------------------- | +| Array successfully updated | (Int) `Integer representing the new array size at each matched path` | +| Key does not exist | Error: `(error) ERR key does not exist` | +| Path is not valid | Error: `(error) ERR Existing key has wrong Dice type` | +| Invalid JSON value | Error: `(error) ERR Path does not exist` | +| Invalid index | Error: `(error) ERR index out of bounds` | ## Behaviour @@ -72,12 +72,12 @@ JSON.ARRINSERT [value ...] Inserting at a valid index in the root path -```plaintext -127.0.0.1:6379> JSON.SET a $ '[1,2]' +```bash +127.0.0.1:7379> JSON.SET a $ '[1,2]' OK -127.0.0.1:6379> JSON.ARRINSERT a $ 2 3 4 5 +127.0.0.1:7379> JSON.ARRINSERT a $ 2 3 4 5 (integer) 5 -127.0.0.1:6379> JSON.GET a +127.0.0.1:7379> JSON.GET a [1,2,3,4,5] ``` @@ -85,12 +85,12 @@ OK Inserting at a negative index -```plaintext -127.0.0.1:6379> JSON.SET a $ '[1,2]' +```bash +127.0.0.1:7379> JSON.SET a $ '[1,2]' OK -127.0.0.1:6379> JSON.ARRINSERT a $ -2 3 4 5 +127.0.0.1:7379> JSON.ARRINSERT a $ -2 3 4 5 (integer) 5 -127.0.0.1:6379> JSON.GET a +127.0.0.1:7379> JSON.GET a [3,4,5,1,2] ``` @@ -98,12 +98,12 @@ OK Handling nested arrays -```plaintext -127.0.0.1:6379> JSON.SET b $ '{"name":"tom","score":[10,20],"partner2":{"score":[10,20]}}' +```bash +127.0.0.1:7379> JSON.SET b $ '{"name":"tom","score":[10,20],"partner2":{"score":[10,20]}}' OK -127.0.0.1:6379> JSON.ARRINSERT b $..score 1 5 6 true +127.0.0.1:7379> JSON.ARRINSERT b $..score 1 5 6 true (integer) 5 -127.0.0.1:6379> JSON.GET b +127.0.0.1:7379> JSON.GET b {"name":"tom","score":[10,5,6,true,20],"partner2":{"score":[10,5,6,true,20]}} ``` @@ -111,12 +111,12 @@ OK Inserting with an out-of-bounds index -```plaintext -127.0.0.1:6379> JSON.SET a $ '[1,2]' +```bash +127.0.0.1:7379> JSON.SET a $ '[1,2]' OK -127.0.0.1:6379> JSON.ARRINSERT a $ 4 3 +127.0.0.1:7379> JSON.ARRINSERT a $ 4 3 ERR index out of bounds -127.0.0.1:6379> JSON.GET a +127.0.0.1:7379> JSON.GET a [1,2] ``` @@ -124,11 +124,11 @@ ERR index out of bounds Invalid index type -```plaintext -127.0.0.1:6379> JSON.SET a $ '[1,2]' +```bash +127.0.0.1:7379> JSON.SET a $ '[1,2]' OK -127.0.0.1:6379> JSON.ARRINSERT a $ ss 3 +127.0.0.1:7379> JSON.ARRINSERT a $ ss 3 ERR value is not an integer or out of range -127.0.0.1:6379> JSON.GET a +127.0.0.1:7379> JSON.GET a [1,2] ``` diff --git a/docs/src/content/docs/commands/JSON.ARRLEN.md b/docs/src/content/docs/commands/JSON.ARRLEN.md index b7583af39..ab4a495c9 100644 --- a/docs/src/content/docs/commands/JSON.ARRLEN.md +++ b/docs/src/content/docs/commands/JSON.ARRLEN.md @@ -13,15 +13,15 @@ JSON.ARRLEN [path] ## Parameters -| Parameter | Description | Type | Required | -|-----------|-------------------------------------------------------------------------|--------|----------| -| `key` | The key under which the JSON document is stored. | String | Yes | -| `path` | The JSONPath to the array within the JSON document. Defaults to root. | String | No | +| Parameter | Description | Type | Required | +| --------- | --------------------------------------------------------------------- | ------ | -------- | +| `key` | The key under which the JSON document is stored. | String | Yes | +| `path` | The JSONPath to the array within the JSON document. Defaults to root. | String | No | ## Return values | Condition | Return Value | -|-------------------------------------------|---------------------------------------------------------------------------------| +| ----------------------------------------- | ------------------------------------------------------------------------------- | | JSON array is found at the specified path | Length of the JSON array | | JSONPath contains `*` wildcard | Indicates the length of each key in the JSON. Returns `nil` for non-array keys. | @@ -36,14 +36,17 @@ JSON.ARRLEN [path] ## Errors 1. `Wrong number of arguments`: + - Error Message: `(error) ERROR wrong number of arguments for 'JSON.ARRLEN' command` - Occurs when the command is executed with less than one argument or with an invalid number of parameters. 2. `Invalid JSONPath`: + - Error Message: `(error) ERROR Invalid JSONPath` - Occurs when the specified JSONPath is not valid or incorrect 3. `Path does not exist`: + - Error Message: `(error) ERROR Path 'NON_EXISTANT_PATH' does not exist` - Occurs when the provided JSON path does not exist in the document. diff --git a/docs/src/content/docs/commands/JSON.ARRPOP.md b/docs/src/content/docs/commands/JSON.ARRPOP.md index fc8aa2ed8..7691594cc 100644 --- a/docs/src/content/docs/commands/JSON.ARRPOP.md +++ b/docs/src/content/docs/commands/JSON.ARRPOP.md @@ -12,8 +12,9 @@ JSON.ARRPOP key [path [index]] ``` ## Parameters + | Parameter | Description | Type | Required | -|-----------|-------------------------------------------------------------------------------|---------|----------| +| --------- | ----------------------------------------------------------------------------- | ------- | -------- | | `key` | The key under which the JSON document is stored. | String | Yes | | `path` | The JSONPath expression that specifies the location within the JSON document. | String | Yes | | `index` | The index of the element that needs to be popped from the JSON Array at path. | Integer | No | @@ -30,14 +31,17 @@ When the `JSON.ARRPOP` command is executed, the specified element is popped from ## Error Handling 1. `Wrong type of value or key`: + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs when attempting to use the command on a key that contains a non-string value. 2. `Invalid Key`: + - Error Message: `(error) ERR key does not exist` - Occurs when attempting to use the command on a key that does not exist. 3. `Invalid Path`: + - Error Message: `(error) ERR path %s does not exist` - Occurs when attempting to use the command on a path that does not exist in the JSON document. @@ -50,36 +54,36 @@ When the `JSON.ARRPOP` command is executed, the specified element is popped from ### Popping value from an array ```bash -127.0.0.1:6379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' +127.0.0.1:7379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' OK -127.0.0.1:6379> JSON.ARRPOP myjson .numbers 1 +127.0.0.1:7379> JSON.ARRPOP myjson .numbers 1 (integer) 2 -127.0.0.1:6379> JSON.GET myjson +127.0.0.1:7379> JSON.GET myjson "{\"numbers\":[1,3]}" ``` ### Error when key does not exist ```bash -127.0.0.1:6379> JSON.ARRPOP nonexistingkey .array 1 +127.0.0.1:7379> JSON.ARRPOP nonexistingkey .array 1 (error) ERR key does not exist ``` ### Error when path does not exist ```bash -127.0.0.1:6379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' +127.0.0.1:7379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' OK -127.0.0.1:6379> JSON.ARRPOP myjson .nonexistingpath 4 +127.0.0.1:7379> JSON.ARRPOP myjson .nonexistingpath 4 (error) ERR path .nonexistingpath does not exist ``` ### Error when path is not an array ```bash -127.0.0.1:6379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' +127.0.0.1:7379> JSON.SET myjson . '{"numbers": [1, 2, 3]}' OK -127.0.0.1:6379> JSON.ARRPOP myjson .numbers 4 +127.0.0.1:7379> JSON.ARRPOP myjson .numbers 4 (error) ERR path is not an array ``` diff --git a/docs/src/content/docs/commands/JSON.ARRTRIM.md b/docs/src/content/docs/commands/JSON.ARRTRIM.md index a6aaf3887..62abc4dea 100644 --- a/docs/src/content/docs/commands/JSON.ARRTRIM.md +++ b/docs/src/content/docs/commands/JSON.ARRTRIM.md @@ -1,7 +1,6 @@ --- title: JSON.ARRTRIM description: The `JSON.ARRTRIM` command in DiceDB is used to trim a JSON array to only include elements within a specified range. It removes elements outside of this range, modifying the array in place. This command is part of the DiceDBJSON module, which provides native JSON capabilities in DiceDB. - --- The `JSON.ARRTRIM` command in DiceDB modifies a JSON array by removing elements outside a specified range, effectively trimming it to contain only desired elements. This in-place operation is part of the DiceDBJSON module, which enables seamless handling and manipulation of JSON data within DiceDB. @@ -13,24 +12,24 @@ JSON.ARRTRIM ``` ## 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 | -| `index` | The index of the first element to retain in the array (0-based index). | Integer | Yes | -| `value` | The index of the last element to retain in the array (inclusive). | Integer | Yes | +| 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 | +| `index` | The index of the first element to retain in the array (0-based index). | Integer | Yes | +| `value` | The index of the last element to retain in the array (inclusive). | Integer | Yes | ## Return Values -| Condition | Return Value | -|-------------------------------|---------------------------------------------------------------------------------| -| Success | (Int) `Integer representing the length of the array after the append operation.`| -| Key does not exist | Error: `(error) ERR key does not exist` | -| Wrong number of arguments | Error: `(error) ERR wrong number of arguments for JSON.ARRTRIM command` | -| Key has wrong type | Error: `(error) ERR Existing key has wrong Dice type` | -| Path doesn't exist | Error: `(error) ERR Path does not exist` | -| Operation failed | Error: `(error) ERR failed to modify JSON data` | +| Condition | Return Value | +| ------------------------- | -------------------------------------------------------------------------------- | +| Success | (Int) `Integer representing the length of the array after the append operation.` | +| Key does not exist | Error: `(error) ERR key does not exist` | +| Wrong number of arguments | Error: `(error) ERR wrong number of arguments for JSON.ARRTRIM command` | +| Key has wrong type | Error: `(error) ERR Existing key has wrong Dice type` | +| Path doesn't exist | Error: `(error) ERR Path does not exist` | +| Operation failed | Error: `(error) ERR failed to modify JSON data` | ## Behaviour @@ -72,40 +71,40 @@ JSON.ARRTRIM Trimming an array to a specific range -```plaintext -127.0.0.1:6379> JSON.SET b $ '[1, 2, 3, 4, 5]' +```bash +127.0.0.1:7379> JSON.SET b $ '[1, 2, 3, 4, 5]' "OK" -127.0.0.1:6379> JSON.ARRTRIM b $ 1 3 +127.0.0.1:7379> JSON.ARRTRIM b $ 1 3 1) "3" -127.0.0.1:6379> JSON.GET b +127.0.0.1:7379> JSON.GET b "[2,3,4]" -127.0.0.1:6379> +127.0.0.1:7379> ``` ### Trim array down to 1 element Trimming an array to a single element -```plaintext -127.0.0.1:6379> JSON.SET a $ '[0,1,2]' +```bash +127.0.0.1:7379> JSON.SET a $ '[0,1,2]' "OK" -127.0.0.1:6379> JSON.ARRTRIM a $ 1 1 +127.0.0.1:7379> JSON.ARRTRIM a $ 1 1 "1" -127.0.0.1:6379> JSON.GET a +127.0.0.1:7379> JSON.GET a "[1]" -127.0.0.1:6379> +127.0.0.1:7379> ``` ### Trimming array with out of bound index Trimming an array with out-of-bounds indices -```plaintext -127.0.0.1:6379> JSON.SET c $ '[1, 2, 3, 4, 5]' +```bash +127.0.0.1:7379> JSON.SET c $ '[1, 2, 3, 4, 5]' "OK" -127.0.0.1:6379> JSON.ARRTRIM c $ -10 10 +127.0.0.1:7379> JSON.ARRTRIM c $ -10 10 1) "5" -127.0.0.1:6379> JSON.GET c +127.0.0.1:7379> JSON.GET c "[1,2,3,4,5]" ``` @@ -113,10 +112,10 @@ Trimming an array with out-of-bounds indices Error when path does not exist -```plaintext -127.0.0.1:6379> JSON.SET d $ '[1, 2, 3, 4, 5]' +```bash +127.0.0.1:7379> JSON.SET d $ '[1, 2, 3, 4, 5]' "OK" -127.0.0.1:6379> JSON.ARRTRIM d . -10 10 +127.0.0.1:7379> JSON.ARRTRIM d . -10 10 (error) ERROR Path '.' does not exist ``` @@ -124,10 +123,10 @@ Error when path does not exist Error when key does not exist -```plaintext -127.0.0.1:6379> JSON.SET a $ '[1, 2, 3, 4, 5]' +```bash +127.0.0.1:7379> JSON.SET a $ '[1, 2, 3, 4, 5]' "OK" -127.0.0.1:6379> JSON.ARRTRIM aa . -10 10 +127.0.0.1:7379> JSON.ARRTRIM aa . -10 10 (error) ERROR key does not exist ``` diff --git a/docs/src/content/docs/commands/JSON.CLEAR.md b/docs/src/content/docs/commands/JSON.CLEAR.md index a3c46e41f..44d4d4186 100644 --- a/docs/src/content/docs/commands/JSON.CLEAR.md +++ b/docs/src/content/docs/commands/JSON.CLEAR.md @@ -7,23 +7,23 @@ The `JSON.CLEAR` command allows you to manipulate JSON data stored in DiceDB. Th ## Syntax -``` +```bash JSON.CLEAR key [path] ``` ## Parameters -| 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 | +| 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 values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | `Integer` (The number of paths that were cleared) | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------------------------------------------- | +| Command is successful | `Integer` (The number of paths that were cleared) | +| Syntax or specified constraints are invalid | error | ## Behaviour diff --git a/docs/src/content/docs/commands/JSON.DEBUG.md b/docs/src/content/docs/commands/JSON.DEBUG.md index 17fc47049..22a2c5e1b 100644 --- a/docs/src/content/docs/commands/JSON.DEBUG.md +++ b/docs/src/content/docs/commands/JSON.DEBUG.md @@ -9,7 +9,7 @@ The `JSON.DEBUG` command in DiceDB is part of the DiceDBJSON module, which allow ### Syntax -``` +```bash JSON.DEBUG [path] ``` @@ -57,8 +57,8 @@ The `JSON.DEBUG` command can raise errors in the following scenarios: ### Example 1: Debugging Memory Usage of Entire JSON Data -```sh -127.0.0.1:6379> JSON.DEBUG MEMORY myjson +```bash +127.0.0.1:7379> JSON.DEBUG MEMORY myjson (integer) 256 ``` @@ -66,8 +66,8 @@ In this example, the `JSON.DEBUG MEMORY` command is used to get the memory usage ### Example 2: Debugging Memory Usage of a Specific Path -```sh -127.0.0.1:6379> JSON.DEBUG MEMORY myjson $.store.book[0] +```bash +127.0.0.1:7379> JSON.DEBUG MEMORY myjson $.store.book[0] (integer) 64 ``` @@ -75,8 +75,8 @@ In this example, the `JSON.DEBUG MEMORY` command is used to get the memory usage ### Example 3: Handling Non-Existent Key -```sh -127.0.0.1:6379> JSON.DEBUG MEMORY nonExistentKey +```bash +127.0.0.1:7379> JSON.DEBUG MEMORY nonExistentKey (error) ERR no such key ``` @@ -84,8 +84,8 @@ In this example, the `JSON.DEBUG MEMORY` command is used on a non-existent key ` ### Example 4: Handling Invalid Path -```sh -127.0.0.1:6379> JSON.DEBUG MEMORY myjson $.nonExistentPath +```bash +127.0.0.1:7379> JSON.DEBUG MEMORY myjson $.nonExistentPath (error) ERR path '$.nonExistentPath' does not exist ``` diff --git a/docs/src/content/docs/commands/JSON.DEL.md b/docs/src/content/docs/commands/JSON.DEL.md index b0badcefb..5a6905fbe 100644 --- a/docs/src/content/docs/commands/JSON.DEL.md +++ b/docs/src/content/docs/commands/JSON.DEL.md @@ -7,22 +7,23 @@ The `JSON.DEL` command is part of the DiceDBJSON module, which allows you to man ## Syntax -``` +```bash JSON.DEL key [path] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|----------------------------------------------------------------------------------------|---------|----------| -| `key` | The key under which the JSON document is stored. | String | Yes | -| `path` | The JSONPath expression specifying the part of the JSON document to delete. If omitted, the entire JSON document will be deleted. | String | No | + +| Parameter | Description | Type | Required | +| --------- | --------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key under which the JSON document is stored. | String | Yes | +| `path` | The JSONPath expression specifying the part of the JSON document to delete. If omitted, the entire JSON document will be deleted. | String | No | ## Return Value -| Condition | Return Value | -|--------------------------------------------|------------------------------------------| -| At least one path is successfully deleted | The number of paths deleted (Integer) | -| The specified key does not exist | `0` | +| Condition | Return Value | +| ----------------------------------------- | ------------------------------------- | +| At least one path is successfully deleted | The number of paths deleted (Integer) | +| The specified key does not exist | `0` | ## Behaviour @@ -31,15 +32,15 @@ When the `JSON.DEL` command is executed, it performs the following actions: 1. `Key Existence Check`: The command first checks if the specified key exists in the DiceDB database. 2. `Path Evaluation`: If a path is provided, the command evaluates the JSONPath expression to locate the part of the JSON document to delete. 3. `Deletion`: The specified path or the entire JSON document is deleted. -4. `Return`: - - The command returns the number of paths that were successfully deleted. - - If the specified path does not exist `0` is returned, indicating that no operation was performed. +4. `Return`: - The command returns the number of paths that were successfully deleted. - If the specified path does not exist `0` is returned, indicating that no operation was performed. ## Error Handling The `JSON.DEL` command can raise the following errors: + + - `(error) ERROR Existing key has wrong Dice type` @@ -48,41 +49,41 @@ The `JSON.DEL` command can raise the following errors: ### Deleting an Entire JSON Document -```shell -127.0.0.1:6379> JSON.SET myjson $ '{"name": "John", "age": 30, "city": "New York"}' +```bash +127.0.0.1:7379> JSON.SET myjson $ '{"name": "John", "age": 30, "city": "New York"}' OK -127.0.0.1:6379> JSON.DEL myjson +127.0.0.1:7379> JSON.DEL myjson (integer) 1 -127.0.0.1:6379> JSON.GET myjson +127.0.0.1:7379> JSON.GET myjson (nil) ``` ### Deleting a Specific Path -```shell -127.0.0.1:6379> JSON.SET myjson $ '{"name": "John", "age": 30, "city": "New York"}' +```bash +127.0.0.1:7379> JSON.SET myjson $ '{"name": "John", "age": 30, "city": "New York"}' OK -127.0.0.1:6379> JSON.DEL myjson $.age +127.0.0.1:7379> JSON.DEL myjson $.age (integer) 1 -127.0.0.1:6379> JSON.GET myjson +127.0.0.1:7379> JSON.GET myjson "{\"name\":\"John\",\"city\":\"New York\"}" ``` ### Deleting a Non-Existent Path -```shell -127.0.0.1:6379> JSON.SET myjson $ '{"name": "John", "age": 30, "city": "New York"}' +```bash +127.0.0.1:7379> JSON.SET myjson $ '{"name": "John", "age": 30, "city": "New York"}' OK -127.0.0.1:6379> JSON.DEL myjson $.address +127.0.0.1:7379> JSON.DEL myjson $.address (integer) 0 ``` ### Error: Key Does Not Hold a JSON Document -```shell -127.0.0.1:6379> SET mystring "Hello, World!" +```bash +127.0.0.1:7379> SET mystring "Hello, World!" OK -127.0.0.1:6379> JSON.DEL mystring +127.0.0.1:7379> JSON.DEL mystring (error) ERROR Existing key has wrong Dice type ``` @@ -93,4 +94,3 @@ OK - The command is atomic and ensures that the deletion operation is performed consistently. By understanding the `JSON.DEL` command, you can effectively manage and manipulate JSON data within your DiceDB database, ensuring efficient and accurate data operations. - diff --git a/docs/src/content/docs/commands/JSON.FORGET.md b/docs/src/content/docs/commands/JSON.FORGET.md index 6e77463f4..e84f2f470 100644 --- a/docs/src/content/docs/commands/JSON.FORGET.md +++ b/docs/src/content/docs/commands/JSON.FORGET.md @@ -7,24 +7,24 @@ The `JSON.FORGET` command in DiceDB is used to delete a specified path from a JS ## Syntax -``` +```bash JSON.FORGET key path ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|------------------------------------------------------------------------------|---------|----------| -| `key` | The name of the key under which the JSON document is stored. | String | Yes | -| `path` | The JSONPath expression specifying the part of the JSON document to delete. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | --------------------------------------------------------------------------- | ------ | -------- | +| `key` | The name of the key under which the JSON document is stored. | String | Yes | +| `path` | The JSONPath expression specifying the part of the JSON document to delete. | String | Yes | ## Return values -| Condition | Return Value | -|--------------------------------------|-----------------------------------------| -| Command successfully deletes a path | `The number of paths deleted (Integer)` | -| Path does not exist | `0` | -| Invalid key or path | error | +| Condition | Return Value | +| ----------------------------------- | --------------------------------------- | +| Command successfully deletes a path | `The number of paths deleted (Integer)` | +| Path does not exist | `0` | +| Invalid key or path | error | ## Behaviour @@ -38,23 +38,23 @@ JSON.FORGET key path 1. `Wrong number of arguments`: - - Error Message: `(error) ERR wrong number of arguments for 'JSON.FORGET' command` - - Occurs when the command is called with an incorrect number of arguments. + - Error Message: `(error) ERR wrong number of arguments for 'JSON.FORGET' command` + - Occurs when the command is called with an incorrect number of arguments. 2. `Key does not exist`: - - Error Message: `(error) ERR key does not exist` - - Occurs if the specified key is not present in the database. + - Error Message: `(error) ERR key does not exist` + - Occurs if the specified key is not present in the database. 3. `Invalid JSONPath expression`: - - Error Message: `(error) ERR invalid path` - - Occurs when the provided JSONPath expression is invalid or malformed. + - Error Message: `(error) ERR invalid path` + - Occurs when the provided JSONPath expression is invalid or malformed. 4. `Path does not exist`: - - Error Message: `(error) ERR path does not exist` - - Occurs if the specified path does not exist within the JSON document. + - Error Message: `(error) ERR path does not exist` + - Occurs if the specified path does not exist within the JSON document. ## Example Usage @@ -77,6 +77,7 @@ Deleting the second element (`"swimming"`) from the `hobbies` array in the JSON ``` #### The updated document: + ```json { "name": "Jane Doe", diff --git a/docs/src/content/docs/commands/JSON.GET.md b/docs/src/content/docs/commands/JSON.GET.md index 611b2670c..80f15eb02 100644 --- a/docs/src/content/docs/commands/JSON.GET.md +++ b/docs/src/content/docs/commands/JSON.GET.md @@ -7,26 +7,25 @@ The `JSON.GET` command allows you to store, update, and retrieve JSON values in ## Syntax -``` +```bash JSON.GET [path] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------| -| `key` | The key against which the JSON data is stored in DiceDB | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key against which the JSON data is stored in DiceDB | String | Yes | | `path` | A JSONPath expression to specify the part of the JSON document to retrieve. If not provided, the entire JSON document is returned. Default value is **$** (root) | String | No | - ## Return Values | Condition | Return Value | | ---------------------------------------------------------------------------- | ---------------------------------------------------- | | The specified key does not exists | `nil` | -| The specified key exists and path argument is not specified | `String`: The entire JSON data for the key | +| The specified key exists and path argument is not specified | `String`: The entire JSON data for the key | | The specified key exists and the specified path exists in the JSON data | `String`: The data for the key at the specified path | -| The specified key exists and specified path does not exists in the JSON data | `error` | +| The specified key exists and specified path does not exists in the JSON data | `error` | | Syntax or specified constraints are invalid | error | ## Behaviour @@ -41,11 +40,11 @@ When the `JSON.GET` command is executed: ## Errors 1. `Incorrect number of arguments` - - Error Message: `(error) ERR wrong number of arguments for 'json.get' command` + - Error Message: `(error) ERR wrong number of arguments for 'json.get' command` 2. `Invalid JSONPath expression` - - Error Message: `(error) ERR invalid JSONPath` + - Error Message: `(error) ERR invalid JSONPath` 3. `Non-Existent JSONPath in the JSON data stored against a key` - - Error Message: `(error) ERR Path '$.' does not exist` + - Error Message: `(error) ERR Path '$.' does not exist` ## Example Usage diff --git a/docs/src/content/docs/commands/JSON.MGET.md b/docs/src/content/docs/commands/JSON.MGET.md index d0988bde4..b8a8b35ba 100644 --- a/docs/src/content/docs/commands/JSON.MGET.md +++ b/docs/src/content/docs/commands/JSON.MGET.md @@ -2,6 +2,7 @@ title: JSON.MGET description: Documentation for the DiceDB command JSON.MGET --- + # JSON.MGET The `JSON.MGET` command in DiceDB is used to retrieve the values of specific JSON keys from multiple JSON documents stored at different keys. This command is particularly useful when you need to fetch the same JSON path from multiple JSON objects in a single operation, thereby reducing the number of round trips to the DiceDB server. @@ -14,19 +15,18 @@ JSON.MGET key [key ...] path ## Parameters -| Parameter | Description | Type | Required | -|-----------|-------------------------------------------------------------------------------------------------|--------|----------| +| Parameter | Description | Type | Required | +| --------- | -------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | | `key` | One or more keys from which the JSON values will be retrieved. These keys should point to JSON documents stored in DiceDB. | String | Yes | -| `path` | The JSON path to retrieve from each of the specified keys. The path should be specified in JSONPath format. | String | Yes | +| `path` | The JSON path to retrieve from each of the specified keys. The path should be specified in JSONPath format. | String | Yes | ## Return values -| Condition | Return Value | -|-----------------------------------------------------------|---------------------------------------------------------------------------------------------| -| Command is successful | An array of JSON values corresponding to the specified path from each of the provided keys. | +| Condition | Return Value | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| Command is successful | An array of JSON values corresponding to the specified path from each of the provided keys. | | If a key does not exist or the path does not exist within a JSON document | The corresponding entry in the returned array will be `nil`. | - ## Behaviour When the `JSON.MGET` command is executed, DiceDB will: @@ -45,10 +45,10 @@ Here’s the revised error section for the `JSON.MGET` command documentation in ## Errors 1. `Key does not exist`: + - **Error Message**: `(error) ERROR could not perform this operation on a key that doesn't exist` - This error occurs when the specified key does not exist in the DiceDB database. - 2. `Invalid JSON path`: - **Error Message**: `(error) ERROR invalid JSONPath` - This error occurs when the provided JSONPath expression is not valid. @@ -98,4 +98,3 @@ To retrieve the `address` field, which does not exist in the documents: ``` In this case, `user:3` does not exist, and the `address` field does not exist in `user:1` and `user:2`, so `nil` is returned for each key. - diff --git a/docs/src/content/docs/commands/JSON.MSET.md b/docs/src/content/docs/commands/JSON.MSET.md index e8ed00748..fafc588ae 100644 --- a/docs/src/content/docs/commands/JSON.MSET.md +++ b/docs/src/content/docs/commands/JSON.MSET.md @@ -17,7 +17,7 @@ The `JSON.MSET` command requires an even number of arguments. The arguments are ### Example -```plaintext +```bash JSON.MSET key1 json1 key2 json2 ... keyN jsonN ``` @@ -56,8 +56,8 @@ The `JSON.MSET` command can raise errors in the following scenarios: ### Setting Multiple JSON Values -```plaintext -127.0.0.1:6379> JSON.MSET user:1 '{"name": "Alice", "age": 30}' user:2 '{"name": "Bob", "age": 25}' +```bash +127.0.0.1:7379> JSON.MSET user:1 '{"name": "Alice", "age": 30}' user:2 '{"name": "Bob", "age": 25}' OK ``` @@ -65,8 +65,8 @@ In this example, two keys (`user:1` and `user:2`) are set with their respective ### Error Example: Odd Number of Arguments -```plaintext -127.0.0.1:6379> JSON.MSET user:1 '{"name": "Alice", "age": 30}' user:2 +```bash +127.0.0.1:7379> JSON.MSET user:1 '{"name": "Alice", "age": 30}' user:2 (error) ERR wrong number of arguments for 'JSON.MSET' command ``` @@ -74,8 +74,8 @@ In this example, the command fails because the number of arguments is odd. DiceD ### Error Example: Invalid JSON -```plaintext -127.0.0.1:6379> JSON.MSET user:1 '{"name": "Alice", "age": 30}' user:2 '{name: "Bob", age: 25}' +```bash +127.0.0.1:7379> JSON.MSET user:1 '{"name": "Alice", "age": 30}' user:2 '{name: "Bob", age: 25}' (error) ERR invalid JSON string ``` diff --git a/docs/src/content/docs/commands/JSON.NUMINCRBY.md b/docs/src/content/docs/commands/JSON.NUMINCRBY.md index e74b18153..45773f252 100644 --- a/docs/src/content/docs/commands/JSON.NUMINCRBY.md +++ b/docs/src/content/docs/commands/JSON.NUMINCRBY.md @@ -7,14 +7,14 @@ The `JSON.NUMINCRBY` command is part of the DiceDBJSON module, which allows for ## Syntax -```plaintext +```bash JSON.NUMINCRBY ``` ## Parameters | Parameter | Description | Type | Required | -|-------------|-----------------------------------------------------------------------------------------|----------------|----------| +| ----------- | --------------------------------------------------------------------------------------- | -------------- | -------- | | `key` | The key under which the JSON document is stored. | String | Yes | | `path` | The JSONPath expression specifying the location of the numeric value to be incremented. | String | Yes | | `increment` | The numeric value by which to increment the target value. | Floating Point | Yes | @@ -22,7 +22,7 @@ JSON.NUMINCRBY ## Return Value | Condition | Return Value | -|--------------------------------------------|---------------------------------------| +| ------------------------------------------ | ------------------------------------- | | Command is successful | Array of new value for update objects | | Key does not exist or JSON path is invalid | error | @@ -35,19 +35,19 @@ JSON.NUMINCRBY 1. `Key does not exist`: - - Error Message: `(error) ERROR could not perform this operation on a key that doesn't exist` - - Occurs when the specified key does not exist in the DiceDB database. + - Error Message: `(error) ERROR could not perform this operation on a key that doesn't exist` + - Occurs when the specified key does not exist in the DiceDB database. 2. `Invalid JSON path`: - - Error Message: `(error) ERROR invalid JSONPath` - - Occurs when the provided JSONPath expression is not valid. + - Error Message: `(error) ERROR invalid JSONPath` + - Occurs when the provided JSONPath expression is not valid. ## Example Usage Create a document: -```shell +```bash 127.0.0.1:7379> JSON.SET user:1001 $ '{"name": "John Doe", "age": 30, "balance": 100.50, "account": {"id": 0, "lien": 0, "balance": 100.50}}' "OK" ``` @@ -56,7 +56,7 @@ Create a document: Incrementing the value of `age` object by 1 -```shell +```bash 127.0.0.1:7379> JSON.NUMINCRBY user:1001 $.age 1 "[31]" ``` @@ -65,7 +65,7 @@ Incrementing the value of `age` object by 1 Incrementing the value of `balance` object by 25.75 -```shell +```bash 127.0.0.1:7379> JSON.NUMINCRBY user:1001 $.balance 25.75 "[126.25]" ``` @@ -74,7 +74,7 @@ Incrementing the value of `balance` object by 25.75 Finding and recursively incrementing the values of both `balance` objects by 25.75 -```shell +```bash 127.0.0.1:7379> JSON.NUMINCRBY user:1001 $..balance 25.75 "[126.25,126.25]" ``` @@ -83,7 +83,7 @@ Finding and recursively incrementing the values of both `balance` objects by 25. Incrementing a non-numeric value -```shell +```bash 127.0.0.1:7379> JSON.NUMINCRBY user:1001 $.name 5 "[null]" ``` @@ -92,7 +92,7 @@ Incrementing a non-numeric value Incrementing a non-existent path -```shell +```bash 127.0.0.1:7379> JSON.NUMINCRBY user:1001 $.nonexistent 10 "[]" ``` @@ -101,7 +101,7 @@ Incrementing a non-existent path Trying to increment an invalid path will result in an error -```shell +```bash 127.0.0.1:7379> JSON.NUMINCRBY user:1001 . 5 (error) ERROR invalid JSONPath ``` @@ -110,7 +110,7 @@ Trying to increment an invalid path will result in an error Trying to increment a path for a non-existent key will result in an error -```shell +```bash 127.0.0.1:7379> JSON.NUMINCRBY user:1002 . 5 (error) ERROR could not perform this operation on a key that doesn't exist ``` diff --git a/docs/src/content/docs/commands/JSON.OBJKEYS.md b/docs/src/content/docs/commands/JSON.OBJKEYS.md index c0c8a2383..8a72b3364 100644 --- a/docs/src/content/docs/commands/JSON.OBJKEYS.md +++ b/docs/src/content/docs/commands/JSON.OBJKEYS.md @@ -1,10 +1,9 @@ --- title: JSON.OBJKEYS description: The `JSON.OBJKEYS` command command in DiceDB retrieves the keys of a JSON object located at a specified path within the document stored under the given key. This command is useful when you want to list the fields within a JSON object stored in a database. - --- -The `JSON.OBJKEYS` command in DiceDB allows users to access the keys of a JSON object stored at a specific path within a document identified by a given key. By executing this command, users can easily retrieve a list of the fields present in the JSON object, making it a valuable tool for exploring and managing the structure of JSON data stored in the database. +The `JSON.OBJKEYS` command in DiceDB allows users to access the keys of a JSON object stored at a specific path within a document identified by a given key. By executing this command, users can easily retrieve a list of the fields present in the JSON object, making it a valuable tool for exploring and managing the structure of JSON data stored in the database. This functionality is particularly useful for developers working with complex JSON structures who need to quickly identify and manipulate the various attributes within their data. @@ -15,21 +14,21 @@ JSON.OBJKEYS key [path] ``` ## 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 | No | -## Return Values +| 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 | No | -| Condition | Return Value | -|-------------------------------|------------------------------------------------------------------------------------------------------------| -| Success | ([]String) `Array of strings containing the keys present within the JSON object at the specified path.` | -| Key does not exist | Error: `(error) ERR could not perform this operation on a key that doesn't exist` | -| Wrong number of arguments | Error: `(error) ERR wrong number of arguments for JSON.ARRTRIM command` | -| Key has wrong type | Error: `(error) ERR Existing key has wrong Dice type` | -| Operation attempted on a key with an incompatible type | Error: `(error) ERR WRONGTYPE Operation against a key holding the wrong kind of value` | +## Return Values +| Condition | Return Value | +| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| Success | ([]String) `Array of strings containing the keys present within the JSON object at the specified path.` | +| Key does not exist | Error: `(error) ERR could not perform this operation on a key that doesn't exist` | +| Wrong number of arguments | Error: `(error) ERR wrong number of arguments for JSON.ARRTRIM command` | +| Key has wrong type | Error: `(error) ERR Existing key has wrong Dice type` | +| Operation attempted on a key with an incompatible type | Error: `(error) ERR WRONGTYPE Operation against a key holding the wrong kind of value` | ## Behaviour @@ -60,17 +59,16 @@ JSON.OBJKEYS key [path] - Error Message: `(error) ERR WRONGTYPE Operation against a key holding the wrong kind of value` - Raised if an operation attempted on a key with an incompatible type. - ## Example Usage ### Basic usage Retrieving Keys of the Root Object -```plaintext -127.0.0.1:6379> JSON.SET a $ '{"name": "Alice", "age": 30, "address": {"city": "Wonderland", "zipcode": "12345"}}' +```bash +127.0.0.1:7379> JSON.SET a $ '{"name": "Alice", "age": 30, "address": {"city": "Wonderland", "zipcode": "12345"}}' "OK" -127.0.0.1:6379> JSON.OBJKEYS a $ +127.0.0.1:7379> JSON.OBJKEYS a $ 1) "name" 2) "age" 3) "address" @@ -80,10 +78,10 @@ Retrieving Keys of the Root Object Retrieving Keys of a Nested Object -```plaintext -127.0.0.1:6379> JSON.SET b $ '{"name": "Alice", "partner": {"name": "Bob", "age": 28}}' +```bash +127.0.0.1:7379> JSON.SET b $ '{"name": "Alice", "partner": {"name": "Bob", "age": 28}}' "OK" -127.0.0.1:6379> JSON.OBJKEYS b $.partner +127.0.0.1:7379> JSON.OBJKEYS b $.partner 1) "name" 2) "age" ``` @@ -92,10 +90,10 @@ Retrieving Keys of a Nested Object Error When Path Points to a Non-Object Type -```plaintext -127.0.0.1:6379> JSON.SET c $ '{"name": "Alice", "age": 30}' +```bash +127.0.0.1:7379> JSON.SET c $ '{"name": "Alice", "age": 30}' "OK" -127.0.0.1:6379> JSON.OBJKEYS c $.age +127.0.0.1:7379> JSON.OBJKEYS c $.age (nil) ``` @@ -103,10 +101,10 @@ Error When Path Points to a Non-Object Type Error When Path Does Not Exist -```plaintext -127.0.0.1:6379> JSON.SET d $ '{"name": "Alice", "address": {"city": "Wonderland"}}' +```bash +127.0.0.1:7379> JSON.SET d $ '{"name": "Alice", "address": {"city": "Wonderland"}}' "OK" -127.0.0.1:6379> JSON.OBJKEYS d $.nonexistentPath +127.0.0.1:7379> JSON.OBJKEYS d $.nonexistentPath (empty list or set) ``` @@ -114,8 +112,7 @@ Error When Path Does Not Exist Error When Key Does Not Exist -```plaintext -127.0.0.1:6379> JSON.OBJKEYS nonexistent_key $ +```bash +127.0.0.1:7379> JSON.OBJKEYS nonexistent_key $ (error) ERROR could not perform this operation on a key that doesn't exist ``` - diff --git a/docs/src/content/docs/commands/JSON.SET.md b/docs/src/content/docs/commands/JSON.SET.md index b82f38c97..12cd06e77 100644 --- a/docs/src/content/docs/commands/JSON.SET.md +++ b/docs/src/content/docs/commands/JSON.SET.md @@ -13,22 +13,21 @@ JSON.SET [NX | XX] ## Parameters -| Parameter | Description | Type | Required | -|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------| -| `key`| The key under which the JSON document is stored. If the key does not exist, it will be created| String | Yes -| `path`| The path within the JSON document where the value should be set. The path should be specified in JSONPath format. Use `$` to refer to the root of the document | String | Yes -| `json`| The JSON value to set at the specified path. This should be a valid JSON string | JSON | Yes -| `NX` | Optional flag. Only set the value if the key does not already exist | Flag | No -| `XX`| Optional flag. Only set the value if the key already exists | Flag | No +| Parameter | Description | Type | Required | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key under which the JSON document is stored. If the key does not exist, it will be created | String | Yes | +| `path` | The path within the JSON document where the value should be set. The path should be specified in JSONPath format. Use `$` to refer to the root of the document | String | Yes | +| `json` | The JSON value to set at the specified path. This should be a valid JSON string | JSON | Yes | +| `NX` | Optional flag. Only set the value if the key does not already exist | Flag | No | +| `XX` | Optional flag. Only set the value if the key already exists | Flag | No | ## Return Values - -| Condition | Return Value | -|--------------------------------------------------------|---------------------------------------------------------------------------------------------------| -| Command is successful | returns `OK` | -| NX or XX conditions not met | returns `nil` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------- | +| Command is successful | returns `OK` | +| NX or XX conditions not met | returns `nil` | +| Syntax or specified constraints are invalid | error | ### JSONPath Support @@ -50,22 +49,20 @@ When the `JSON.SET` command is executed, the following behaviors are observed: ## Errors - 1. `Incorrect number of arguments` - `Error Message`: `(error) ERR wrong number of arguments for 'JSON.SET' command` 2. `Invalid JSON`: If the provided JSON value is not a valid JSON string, an error will be raised. - `Error Message`: `(error) expected value at line 1 column 1` -3. `Invalid JSONPath expression`: +3. `Invalid JSONPath expression`: 1. If the object is being created and the path is not root: - Error Message: `ERR new objects must be created at the root` 1. If the specified path is static but does not exist/cannot be created - Error Message: `(error) Err wrong static path` - 2. If the specified path does not exist and cannot be created + 1. If the specified path does not exist and cannot be created - Error Message: `Error occurred on position {}, "$.. <<<<----", expected one of the following: , '*'` 4. `NX/XX Conflict`: If both `NX` and `XX` flags are provided, an error will be raised. - `Error Message`: `(error) ERR syntax error` - ## Example Usage ### Basic Usage @@ -106,4 +103,4 @@ Set a JSON value only if the key already exists: OK ``` -### \ No newline at end of file +### diff --git a/docs/src/content/docs/commands/JSON.STRLEN.md b/docs/src/content/docs/commands/JSON.STRLEN.md index 292abf329..051443180 100644 --- a/docs/src/content/docs/commands/JSON.STRLEN.md +++ b/docs/src/content/docs/commands/JSON.STRLEN.md @@ -7,24 +7,23 @@ The `JSON.STRLEN` command is used to determine the length of a JSON string at a ## Syntax -``` +```bash JSON.STRLEN ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|-------------------------------------------------------------------------|--------|----------| -| `key` | The key under which the JSON document is stored. | String | Yes | -| `path` | The JSONPath to the string within the JSON document. The path must contain a string. | String | No | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------------ | ------ | -------- | +| `key` | The key under which the JSON document is stored. | String | Yes | +| `path` | The JSONPath to the string within the JSON document. The path must contain a string. | String | No | ## Return Value -| Condition | Return Value | -|-------------------------------------------|---------------------------------------------------------------------------------| -| JSON string is found at the specified path| Length of the JSON string. | -| JSONPath contains `*` wildcard | Indicates the length of each key in the JSON. Returns `nil` for non-string keys.| - +| Condition | Return Value | +| ------------------------------------------ | -------------------------------------------------------------------------------- | +| JSON string is found at the specified path | Length of the JSON string. | +| JSONPath contains `*` wildcard | Indicates the length of each key in the JSON. Returns `nil` for non-string keys. | ## Behaviour @@ -34,7 +33,7 @@ When the `JSON.STRLEN` command is executed, DiceDB will: 2. If `path` is not specified, the command takes `$` as root path and if the data at root path is string, returns an integer that represents the length of the string and if the data at root is not a string, returns an error indicating a type mismatch. 3. `$` is considered as root path which returns the length of the string if the data at root path is of type string or returns `nil` if the data at root is not of type string. 4. If the specified path exists and points to a JSON string, the command returns the length of the string. -5. Multiple results are represented as a list in case of wildcards(*), where each string length is returned in order of appearance and `nil` is returned if it's not a string. +5. Multiple results are represented as a list in case of wildcards(\*), where each string length is returned in order of appearance and `nil` is returned if it's not a string. ## Errors @@ -102,4 +101,3 @@ JSON.STRLEN user:1001 $.address - JSONPath expressions are used to navigate within the JSON document. Ensure that the path provided is valid and points to a JSON string to avoid errors. By following this documentation, users should be able to effectively utilize the `JSON.STRLEN` command to determine the length of JSON strings stored within their DiceDB database. - diff --git a/docs/src/content/docs/commands/JSON.TOGGLE.md b/docs/src/content/docs/commands/JSON.TOGGLE.md index beebdf557..45283181c 100644 --- a/docs/src/content/docs/commands/JSON.TOGGLE.md +++ b/docs/src/content/docs/commands/JSON.TOGGLE.md @@ -76,13 +76,13 @@ The `JSON.TOGGLE` command can raise the following errors: #### Command -```shell +```bash JSON.TOGGLE user:1001 $.active ``` #### Result -```shell +```bash (integer) 1 ``` @@ -102,13 +102,13 @@ JSON.TOGGLE user:1001 $.active #### Command -```shell +```bash JSON.TOGGLE user:1001 $.settings.notifications ``` #### Result -```shell +```bash (integer) 1 ``` @@ -128,13 +128,13 @@ JSON.TOGGLE user:1001 $.settings.notifications #### Command -```shell +```bash JSON.TOGGLE user:1001 $.nonexistent ``` #### Result -```shell +```bash (integer) 0 ``` @@ -142,12 +142,12 @@ JSON.TOGGLE user:1001 $.nonexistent #### Command -```shell +```bash JSON.TOGGLE user:1001 $.name ``` #### Result -```shell +```bash (error) ERR value at path is not a boolean ``` diff --git a/docs/src/content/docs/commands/JSON.TYPE.md b/docs/src/content/docs/commands/JSON.TYPE.md index 5e7b774be..d2f8be358 100644 --- a/docs/src/content/docs/commands/JSON.TYPE.md +++ b/docs/src/content/docs/commands/JSON.TYPE.md @@ -7,28 +7,27 @@ The `JSON.TYPE` command allows you to work with JSON data structures in DiceDB. ## Syntax -``` +```bash JSON.TYPE ``` ## Parameters -| Key | Description | Example | Required | -|-----|-------------|---------|----------| -| key | The key under which the JSON document is stored. | `user:1001` | yes | -| path | The JSONPath expression that specifies the location within the JSON. The default path is the root($) | `$.address.city` | yes | +| Key | Description | Example | Required | +| ---- | ---------------------------------------------------------------------------------------------------- | ---------------- | -------- | +| key | The key under which the JSON document is stored. | `user:1001` | yes | +| path | The JSONPath expression that specifies the location within the JSON. The default path is the root($) | `$.address.city` | yes | ## Return Value - -| Condition | Value | -|------------|--------| -| Value is null | `null` | -| Value is a boolean | `boolean` | -| Value is an integer or float | `number` | -| Value is a string | `string` | -| Value is an array | `array` | -| Value is an object | `object` | +| Condition | Value | +| ---------------------------- | --------- | +| Value is null | `null` | +| Value is a boolean | `boolean` | +| Value is an integer or float | `number` | +| Value is a string | `string` | +| Value is an array | `array` | +| Value is an object | `object` | ### Type diff --git a/docs/src/content/docs/commands/KEYS.md b/docs/src/content/docs/commands/KEYS.md index 5bf6eeb44..dc35f923d 100644 --- a/docs/src/content/docs/commands/KEYS.md +++ b/docs/src/content/docs/commands/KEYS.md @@ -7,37 +7,38 @@ The `KEYS` command in DiceDB is used to find all keys matching a given pattern. ## Syntax -```plaintext +```bash KEYS pattern ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|--------------------------------------------------|---------|----------| -| `pattern` | A string representing the pattern to match against the keys in DiceDB database.| String | Yes | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------- | ------ | -------- | +| `pattern` | A string representing the pattern to match against the keys in DiceDB database. | String | Yes | Supported glob-style characters: - - `*` matches any number of characters (including zero). - - `?` matches exactly one character. - - `[abc]` matches any one of the characters inside the brackets. - - `[a-z]` matches any character in the specified range. + +- `*` matches any number of characters (including zero). +- `?` matches exactly one character. +- `[abc]` matches any one of the characters inside the brackets. +- `[a-z]` matches any character in the specified range. Use `\` to escape special characters if you want to match them verbatim. ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | Array of strings, where each string is key that matches the specified pattern.| -| Command is successful but key not found | `(empty list or set)` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------------------------------------------------------------------------ | +| Command is successful | Array of strings, where each string is key that matches the specified pattern. | +| Command is successful but key not found | `(empty list or set)` | +| Syntax or specified constraints are invalid | error | ## Example usage ### Basic example -```plaintext +```bash 127.0.0.1:7379> SET key1 "value1" OK 127.0.0.1:7379> SET key2 "value2" @@ -51,7 +52,7 @@ OK ### Using wildcards -```plaintext +```bash 127.0.0.1:7379> SET key1 "value1" OK 127.0.0.1:7379> SET key2 "value2" @@ -66,7 +67,7 @@ OK ### Using character ranges -```plaintext +```bash 127.0.0.1:7379> SET key1 "value1" OK 127.0.0.1:7379> SET key2 "value2" @@ -80,7 +81,7 @@ OK ### Using \ to escape special characters -```plaintext +```bash 127.0.0.1:7379> SET key1 "value1" OK 127.0.0.1:7379> SET key2 "value2" @@ -122,7 +123,7 @@ The `KEYS` command is straightforward and does not have many error conditions. H - `SCAN`: The `SCAN` command is a cursor-based iterator that allows you to incrementally iterate over the keyspace without blocking the server. It is a more efficient alternative to `KEYS` for large datasets. -```plaintext +```bash 127.0.0.1:7379> SCAN 0 MATCH key* 1) "0" 2) 1) "key1" diff --git a/docs/src/content/docs/commands/LATENCY.md b/docs/src/content/docs/commands/LATENCY.md index 985dac747..3c59a5cfe 100644 --- a/docs/src/content/docs/commands/LATENCY.md +++ b/docs/src/content/docs/commands/LATENCY.md @@ -2,38 +2,39 @@ title: LATENCY description: The `LATENCY` command in DiceDB is used to measure and analyze the latency of various operations within the DiceDB server. This command provides insights into the performance and responsiveness of the DiceDB instance, helping administrators to identify and troubleshoot latency issues. --- + Note: `Not yet supported` The `LATENCY` command in DiceDB is used to measure and analyze the latency of various operations within the DiceDB server. This command provides insights into the performance and responsiveness of the DiceDB instance, helping administrators to identify and troubleshoot latency issues. ## Command Syntax -```plaintext +```bash LATENCY [SUBCOMMAND] [ARGUMENTS] ``` ## Parameters -| Parameter | Subcommand | Description | Return Type | Required | -|--------------|------------|----------------------------------------------------------------------|-------------|----------| -| `SUBCOMMAND` | | Specifies the operation to perform. Available subcommands are: | String | Yes | -| | `LATEST` | Returns the latest latency spikes. | Array | Yes | -| | `HISTORY` | Returns the latency history for a specific event. | Array | Yes | -| | `RESET` | Resets the latency data for specific events or all events. | Integer | Yes | -| | `GRAPH` | Returns a latency graph for a specific event. | String | Yes | -| | `DOCTOR` | Provides a human-readable report of latency issues. | String | Yes | -| `ARGUMENTS` | N/A | Additional arguments required by certain subcommands (if applicable).| Varies | No | +| Parameter | Subcommand | Description | Return Type | Required | +| ------------ | ---------- | --------------------------------------------------------------------- | ----------- | -------- | +| `SUBCOMMAND` | | Specifies the operation to perform. Available subcommands are: | String | Yes | +| | `LATEST` | Returns the latest latency spikes. | Array | Yes | +| | `HISTORY` | Returns the latency history for a specific event. | Array | Yes | +| | `RESET` | Resets the latency data for specific events or all events. | Integer | Yes | +| | `GRAPH` | Returns a latency graph for a specific event. | String | Yes | +| | `DOCTOR` | Provides a human-readable report of latency issues. | String | Yes | +| `ARGUMENTS` | N/A | Additional arguments required by certain subcommands (if applicable). | Varies | No | ## Return Values -| Condition | Return Value | -|--------------------------------------------------|---------------------------------------------------| -| `LATEST` | Array of latency spikes | -| `HISTORY` | Array of latency samples (timestamp, latency) | -| `RESET` | Integer (number of events reset) | -| `GRAPH` | String (graph representing latency data) | -| `DOCTOR` | String (detailed report with suggestions) | -| `Syntax or specified constraints are invalid` | error | +| Condition | Return Value | +| --------------------------------------------- | --------------------------------------------- | +| `LATEST` | Array of latency spikes | +| `HISTORY` | Array of latency samples (timestamp, latency) | +| `RESET` | Integer (number of events reset) | +| `GRAPH` | String (graph representing latency data) | +| `DOCTOR` | String (detailed report with suggestions) | +| `Syntax or specified constraints are invalid` | error | ## Behaviour diff --git a/docs/src/content/docs/commands/LLEN.md b/docs/src/content/docs/commands/LLEN.md index 2d2cbce34..0910ec718 100644 --- a/docs/src/content/docs/commands/LLEN.md +++ b/docs/src/content/docs/commands/LLEN.md @@ -7,29 +7,29 @@ The `LLEN` command in DiceDB is used to obtain the length of a list stored at a ## Syntax -``` +```bash LLEN key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The key associated with the list whose length you want to retrieve. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------- | ------ | -------- | +| `key` | The key associated with the list whose length you want to retrieve. | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|-----------------------------------------------------------------| -| Command is successful | `Integer` denoting the length of the list at the specified key. | -| If the key does not exist | `0` (the key is interpreted as an empty list) | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | --------------------------------------------------------------- | +| Command is successful | `Integer` denoting the length of the list at the specified key. | +| If the key does not exist | `0` (the key is interpreted as an empty list) | +| Syntax or specified constraints are invalid | error | ## Behaviour - - If the key exists and is associated with a list, the `LLEN` command returns the number of elements in the list. - - If the key does not exist, the `LLEN` command returns `0`, indicating that the list is empty. - - If the key exists but is not associated with a list, an error is returned. +- If the key exists and is associated with a list, the `LLEN` command returns the number of elements in the list. +- If the key does not exist, the `LLEN` command returns `0`, indicating that the list is empty. +- If the key exists but is not associated with a list, an error is returned. ## Errors diff --git a/docs/src/content/docs/commands/LPOP.md b/docs/src/content/docs/commands/LPOP.md index 055fa5c76..cdbaf3539 100644 --- a/docs/src/content/docs/commands/LPOP.md +++ b/docs/src/content/docs/commands/LPOP.md @@ -7,27 +7,23 @@ The `LPOP` command in DiceDB removes and returns the first element of a list at ## Syntax -```plaintext +```bash LPOP key ``` ## Parameters -| Parameter | Description | Type | Required | -| ----------- | --------------------------------------------------------------------------------| ------- | -------- | -| `key` | The key of the list from which the first element will be removed and returned. | String | Yes | - - +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------ | ------ | -------- | +| `key` | The key of the list from which the first element will be removed and returned. | String | Yes | ## Return Value | Condition | Return Value | -|------------------------------------------------|-------------------------------------------------------------------------------------------| +| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | | Command is successful | `String` The value of the first element in the list, if the list exists and is not empty. | | If the key does not exist or the list is empty | `nil` | -| Syntax or specified constraints are invalid | error | - - +| Syntax or specified constraints are invalid | error | ## Behavior @@ -46,6 +42,7 @@ When the `LPOP` command is executed for a key that exists but is not associated 127.0.0.1:7379> LPOP mystring (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` + 2. `Wrong number of arguments` If the `LPOP` command is executed with more than one key or no key, the following error is returned: @@ -63,11 +60,13 @@ If the `LPOP` command is executed with more than one key or no key, the followin ## Example Usage ### Basic Usage + Setting a list `mylist` with elements \["one", "two", "three"\]. ```bash RPUSH mylist "one" "two" "three" ``` + Removing the first element from the list `mylist` ```bash @@ -78,6 +77,7 @@ LPOP mylist The list `mylist` now contains \["two", "three"\]. If the LPOP command is executed one more time: + ```bash LPOP mylist "two" @@ -85,8 +85,6 @@ LPOP mylist The list `mylist` now contains \["three"\]. - - ### Empty List or Non-Existent Key Returns `(nil)` if the list is empty or the provided key is non-existent @@ -96,9 +94,6 @@ LPOP emptylist (nil) ``` - - - ### Key is Not a List Setting a key `mystring` with the value `hello`: @@ -138,4 +133,3 @@ LPOP mylist secondlist - `LRANGE`: Get a range of elements from a list. By understanding and using the `LPOP` command effectively, you can manage list data structures in DiceDB efficiently, implementing queue-like behaviors and more. - diff --git a/docs/src/content/docs/commands/LPUSH.md b/docs/src/content/docs/commands/LPUSH.md index 6592e2e2f..ef20ecc52 100644 --- a/docs/src/content/docs/commands/LPUSH.md +++ b/docs/src/content/docs/commands/LPUSH.md @@ -7,7 +7,7 @@ The `LPUSH` command is used to insert one or multiple values at the head (left) ## Syntax -``` +```bash LPUSH key value [value ...] ``` @@ -27,20 +27,20 @@ LPUSH key value [value ...] ## Behaviour -- The specified values are inserted at the head of the list provided by the key. -- If multiple values are provided, they are inserted in the order they are given, with the leftmost value being the first to be inserted. -- If the key does not exist, a new list is created. +- The specified values are inserted at the head of the list provided by the key. +- If multiple values are provided, they are inserted in the order they are given, with the leftmost value being the first to be inserted. +- If the key does not exist, a new list is created. - If the key exists but is not a list, an error is returned. ## Errors 1. `Wrong Number of Arguments` - - Error Message: `(error) ERR wrong number of arguments for 'lpush' command` - - Occurs if the key parameters is not provided or at least one value is not provided. + - Error Message: `(error) ERR wrong number of arguments for 'lpush' command` + - Occurs if the key parameters is not provided or at least one value is not provided. + +2. `Wrong Type of Key or Value`: -2. `Wrong Type of Key or Value`: - - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs if the key exists and is not a list. DiceDB expects the key to either be non-existent or to hold a list data type. @@ -50,17 +50,18 @@ LPUSH key value [value ...] Insert the value `world` at the head of the list stored at key `mylist`. If `mylist` does not exist, a new list is created. -```shell +```bash 127.0.0.1:7379> LPUSH mylist "world" (integer) 1 ``` ### Multiple Values Insertion -Insert the value `hello` and `world` at the head of the list stored at key `mylist`. After execution, `world` will be the first element, followed by `hello`. +Insert the value `hello` and `world` at the head of the list stored at key `mylist`. After execution, `world` will be the first element, followed by `hello`. + -```shell +```bash 127.0.0.1:7379> LPUSH mylist "hello" "world" (integer) 2 ``` @@ -69,7 +70,7 @@ Insert the value `hello` and `world` at the head of the list stored at key `myli Create a new list with the key `newlist` and inserts the value `first` at the head. -```shell +```bash 127.0.0.1:7379> LPUSH newlist "first" (integer) 1 ``` @@ -78,7 +79,7 @@ Create a new list with the key `newlist` and inserts the value `first` at the he Insert the value `value` at the head of the key `mystring`, which stores a string, not a list. -```shell +```bash 127.0.0.1:7379> SET mystring "not a list" OK 127.0.0.1:7379> LPUSH mystring "value" @@ -91,4 +92,3 @@ OK - The `LPUSH` command can be used to implement a stack (LIFO) by always pushing new elements to the head of the list. By understanding the `LPUSH` command, you can efficiently manage lists in DiceDB, ensuring that elements are added to the head of the list as needed. - diff --git a/docs/src/content/docs/commands/MGET.md b/docs/src/content/docs/commands/MGET.md index 132ecded7..2d92f1b2d 100644 --- a/docs/src/content/docs/commands/MGET.md +++ b/docs/src/content/docs/commands/MGET.md @@ -7,26 +7,25 @@ The `MGET` command in DiceDB is used to retrieve the values of multiple keys in ## Syntax -``` +```bash MGET key [key ...] ``` ## Parameters -| Parameter | Description | Type | Required | -|------------|---------------------------------------------------------|---------|----------| -| `key` | One or more keys for which the values need to be retrieved. Each key is a string. |String | Yes | - +| Parameter | Description | Type | Required | +| --------- | --------------------------------------------------------------------------------- | ------ | -------- | +| `key` | One or more keys for which the values need to be retrieved. Each key is a string. | String | Yes | ## Return Value The `MGET` command returns an array of values corresponding to the specified keys. If a key does not exist, the corresponding value in the array will be `nil`. -| Condition | Return Value | -|-----------------------------------|-------------------------------------------------------------| -| All specified keys exist | An array of values corresponding to the specified keys | -| Some keys do not exist | An array where non-existent keys have `nil` as their value | -| Keys are of the wrong type | error | +| Condition | Return Value | +| -------------------------- | ---------------------------------------------------------- | +| All specified keys exist | An array of values corresponding to the specified keys | +| Some keys do not exist | An array where non-existent keys have `nil` as their value | +| Keys are of the wrong type | error | ## Behaviour @@ -34,12 +33,12 @@ The `MGET` command returns an array of values corresponding to the specified key - If a key does not exist, its corresponding position in the returned array will contain `nil`. - If any of the keys hold non-string values (e.g., lists or sets), the `MGET` command will return an error indicating that the operation was attempted on the wrong type of key. - ## Error Handling The `MGET` command can raise errors in the following scenarios: 1. `Wrong type of value or key`: + - `Error Message`: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs when one of the keys holds a value that is not a string. @@ -53,19 +52,21 @@ The `MGET` command can raise errors in the following scenarios: Retrieving the values of multiple keys `key1`, `key2`, and `key3`: - ```bash 127.0.0.1:7379> SET key1 "value1" OK ``` + ```bash 127.0.0.1:7379> SET key2 "value2" OK ``` + ```bash 127.0.0.1:7379> SET key3 "value3" OK ``` + ```bash 127.0.0.1:7379> MGET key1 key2 key3 ``` @@ -84,13 +85,16 @@ OK 127.0.0.1:7379> SET key1 "value1" OK ``` + ```bash 127.0.0.1:7379> SET key2 "value2" OK ``` + ```bash 127.0.0.1:7379> MGET key1 key2 key3 ``` + `Output:` ``` @@ -107,10 +111,12 @@ OK 127.0.0.1:7379> SET key1 "value1" OK ``` + ```bash 127.0.0.1:7379> LPUSH key2 "value2" (integer) 1 ``` + ```bash 127.0.0.1:7379> MGET key1 key2 ``` @@ -128,14 +134,17 @@ OK 127.0.0.1:7379> SET key1 "value1" OK ``` + ```bash 127.0.0.1:7379> SET key2 "value2" OK ``` + ```bash 127.0.0.1:7379> LPUSH key2 "value3" (error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value ``` + ```bash 127.0.0.1:7379> MGET key1 key2 ``` diff --git a/docs/src/content/docs/commands/MSET.md b/docs/src/content/docs/commands/MSET.md index 01730929a..d31f63d53 100644 --- a/docs/src/content/docs/commands/MSET.md +++ b/docs/src/content/docs/commands/MSET.md @@ -7,36 +7,36 @@ The `MSET` command in DiceDB is used to set multiple key-value pairs in a single ## Syntax -```plaintext +```bash MSET key1 value1 [key2 value2 ...] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|--------------------------------------------------|---------|----------| -| `key1, key2, ...` | The keys to be set. | String | Yes | -| `value1, value2, ...` | The values to be associated with the respective keys. | String | Yes | - +| Parameter | Description | Type | Required | +| --------------------- | ----------------------------------------------------- | ------ | -------- | +| `key1, key2, ...` | The keys to be set. | String | Yes | +| `value1, value2, ...` | The values to be associated with the respective keys. | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| The command returns `OK` if the operation is successful. | A string value | - +| Condition | Return Value | +| -------------------------------------------------------- | -------------- | +| The command returns `OK` if the operation is successful. | A string value | ## Behaviour -When the `MSET` command is executed: -- DiceDB sets the specified keys to their respective values. -- This operation is atomic, meaning that either all the keys are set, or none of them are. +When the `MSET` command is executed: + +- DiceDB sets the specified keys to their respective values. +- This operation is atomic, meaning that either all the keys are set, or none of them are. - This ensures data consistency and integrity. - Any pre-existing keys are overwritten and their respective TTL (if set) are reset. ## Errors The `MSET` command can raise errors in the following scenarios: + - `Wrong number of arguments`: If the number of arguments is not even (i.e., there is a key without a corresponding value), DiceDB will return an error: ```bash (error) ERROR wrong number of arguments for 'mset' command @@ -76,7 +76,7 @@ OK Attempting to set an odd number of arguments: -```sh +```bash 127.0.0.1:7379> MSET key1 "value1" key2 (error) ERROR wrong number of arguments for 'mset' command -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/commands/OBJECT.md b/docs/src/content/docs/commands/OBJECT.md index c14378907..668aed902 100644 --- a/docs/src/content/docs/commands/OBJECT.md +++ b/docs/src/content/docs/commands/OBJECT.md @@ -7,7 +7,7 @@ The `OBJECT` command in DiceDB is used to inspect the internals of DiceDB object ## Syntax -```plaintext +```bash OBJECT ``` @@ -54,13 +54,13 @@ The `OBJECT` command can raise errors in the following scenarios: ### Example 1: Using the `REFCOUNT` Subcommand -```plaintext +```bash OBJECT REFCOUNT mykey ``` `Response:` -```plaintext +```bash (integer) 1 ``` @@ -68,13 +68,13 @@ This response indicates that the value associated with `mykey` has a reference c ### Example 2: Using the `ENCODING` Subcommand -```plaintext +```bash OBJECT ENCODING mykey ``` `Response:` -```plaintext +```bash "embstr" ``` @@ -82,13 +82,13 @@ This response indicates that the value associated with `mykey` is stored using t ### Example 3: Using the `IDLETIME` Subcommand -```plaintext +```bash OBJECT IDLETIME mykey ``` `Response:` -```plaintext +```bash (integer) 120 ``` @@ -96,13 +96,13 @@ This response indicates that `mykey` has been idle for 120 seconds. ### Example 4: Using the `FREQ` Subcommand -```plaintext +```bash OBJECT FREQ mykey ``` `Response:` -```plaintext +```bash (integer) 5 ``` diff --git a/docs/src/content/docs/commands/PERSIST.md b/docs/src/content/docs/commands/PERSIST.md index 747df3a5a..499821264 100644 --- a/docs/src/content/docs/commands/PERSIST.md +++ b/docs/src/content/docs/commands/PERSIST.md @@ -7,22 +7,22 @@ The `PERSIST` command is used to remove the expiration from a key in DiceDB. If ## Syntax -``` +```bash PERSIST key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The name of the key to persist. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ------------------------------- | ------ | -------- | +| `key` | The name of the key to persist. | String | Yes | ## Return Value -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| The timeout was successfully removed | `1` | -| The key does not exist or does not have a timeout| `0` | +| Condition | Return Value | +| ------------------------------------------------- | ------------ | +| The timeout was successfully removed | `1` | +| The key does not exist or does not have a timeout | `0` | ## Behaviour @@ -35,10 +35,10 @@ When the `PERSIST` command is executed: ## Error Handling 1. `Wrong type of value or key`: - - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - - Occurs when attempting to use the command on a key that contains a non-string value or one that does not support expiration. + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs when attempting to use the command on a key that contains a non-string value or one that does not support expiration. 2. `No timeout to persist`: - - This is not an error but occurs when the key either does not exist or does not have an expiration time. The command will return `0` in such cases. + - This is not an error but occurs when the key either does not exist or does not have an expiration time. The command will return `0` in such cases. ## Example Usage @@ -48,14 +48,17 @@ When the `PERSIST` command is executed: 127.0.0.1:7379> SET mykey "Hello" OK ``` + ```bash 127.0.0.1:7379> EXPIRE mykey 10 (integer) 1 ``` + ```bash 127.0.0.1:7379> PERSIST mykey (integer) 1 ``` + ```bash 127.0.0.1:7379> TTL mykey (integer) -1 @@ -95,8 +98,6 @@ OK - The command returns `0` because `mykey` does not have an expiration time set. - ## Summary The `PERSIST` command is a useful tool for managing the lifecycle of keys in a DiceDB database. By removing the expiration from a key, you can ensure that the key remains in the database until explicitly deleted. This command is straightforward but powerful, allowing for greater control over key persistence. - diff --git a/docs/src/content/docs/commands/PFADD.md b/docs/src/content/docs/commands/PFADD.md index d7cf05250..5428e45fb 100644 --- a/docs/src/content/docs/commands/PFADD.md +++ b/docs/src/content/docs/commands/PFADD.md @@ -7,23 +7,23 @@ The `PFADD` command in DiceDB is used to add elements to a HyperLogLog data stru ## Syntax -``` +```bash PFADD key element [element ...] ``` ## Parameters -| Parameter | Description | Type | Required | -|------------|----------------------------------------------------------------------------------------------------------|---------|----------| -| `key` | The name of the HyperLogLog data structure. If it does not exist, a new one is created. | String | Yes | -| `element` | One or more elements to add to the HyperLogLog. Multiple elements can be specified, separated by spaces. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | -------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The name of the HyperLogLog data structure. If it does not exist, a new one is created. | String | Yes | +| `element` | One or more elements to add to the HyperLogLog. Multiple elements can be specified, separated by spaces. | String | Yes | ## Return values -| Condition | Return Value | -|-----------------------------------------------------|-----------------| -| At least one internal register was altered | `1` | -| No internal register was altered | `0` | +| Condition | Return Value | +| ------------------------------------------ | ------------ | +| At least one internal register was altered | `1` | +| No internal register was altered | `0` | ## Behaviour diff --git a/docs/src/content/docs/commands/PFCOUNT.md b/docs/src/content/docs/commands/PFCOUNT.md index ec244ed30..dabe44850 100644 --- a/docs/src/content/docs/commands/PFCOUNT.md +++ b/docs/src/content/docs/commands/PFCOUNT.md @@ -7,22 +7,22 @@ The `PFCOUNT` command in DiceDB is used to return the approximate cardinality (i ## Syntax -``` +```bash PFCOUNT key [key ...] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|-------------|------|----------| -| `key` | The key(s) of the HyperLogLog data structure(s) whose cardinality you want to estimate. You can specify one or more keys. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key(s) of the HyperLogLog data structure(s) whose cardinality you want to estimate. You can specify one or more keys. | String | Yes | ## Return Values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| +| Condition | Return Value | +| ----------------------------------------------------------- | ----------------------------------------------------- | | The specified `key` exists and contains a valid HyperLogLog | The estimated number of unique elements as an integer | -| The `key` does not exist or is not a valid HyperLogLog | `0` | +| The `key` does not exist or is not a valid HyperLogLog | `0` | ## Behaviour diff --git a/docs/src/content/docs/commands/PFMERGE.md b/docs/src/content/docs/commands/PFMERGE.md index 6fb5ede26..30c464952 100644 --- a/docs/src/content/docs/commands/PFMERGE.md +++ b/docs/src/content/docs/commands/PFMERGE.md @@ -7,26 +7,23 @@ The `PFMERGE` command in DiceDB is used to merge multiple HyperLogLog data struc ## Syntax -``` +```bash PFMERGE destkey sourcekey [sourcekey ...] ``` ## Parameters - -| Parameter | Description | Type | Required | -|------------|---------------------------------------------------------------------------------|--------------|----------| -| `destkey` | The key where the merged HyperLogLog will be stored. If this key already exists, it will be overwritten. | String | Yes | -| `sourcekey`| One or more keys of the HyperLogLogs that you want to merge. These keys must already exist and contain HyperLogLog data. | List[String] | Yes | +| Parameter | Description | Type | Required | +| ----------- | ------------------------------------------------------------------------------------------------------------------------ | ------------ | -------- | +| `destkey` | The key where the merged HyperLogLog will be stored. If this key already exists, it will be overwritten. | String | Yes | +| `sourcekey` | One or more keys of the HyperLogLogs that you want to merge. These keys must already exist and contain HyperLogLog data. | List[String] | Yes | ## Return Values - -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | `OK` | -| Syntax or specified constraints are invalid | `(error)` | - +| Condition | Return Value | +| ------------------------------------------- | ------------ | +| Command is successful | `OK` | +| Syntax or specified constraints are invalid | `(error)` | ## Behaviour @@ -35,7 +32,6 @@ PFMERGE destkey sourcekey [sourcekey ...] - These `sourcekey` keys are merged into a single HyperLogLog and stored in the `destkey`. - If the `sourcekey` keys are not valid HyperLogLogs, an error is returned. - ## Errors The `PFMERGE` command can raise errors in the following scenarios: @@ -52,7 +48,7 @@ The `PFMERGE` command can raise errors in the following scenarios: Suppose you have three HyperLogLogs stored at keys `hll1`, `hll2`, and `hll3`, and you want to merge them into a new HyperLogLog stored at key `hll_merged`. -```sh +```bash 127.0.0.1:7379> PFADD hll1 "a" "b" "c" (integer) 1 127.0.0.1:7379> PFADD hll2 "c" "d" "e" @@ -69,7 +65,7 @@ OK If the `destkey` already exists, it will be overwritten by the merged HyperLogLog. -```sh +```bash 127.0.0.1:7379> PFADD hll_merged "x" "y" "z" (integer) 1 127.0.0.1:7379> PFMERGE hll_merged hll1 hll2 hll3 @@ -82,7 +78,7 @@ OK If a `sourcekey` does not exist, DiceDB will treat it as an empty HyperLogLog. -```sh +```bash 127.0.0.1:7379> PFMERGE hll_merged hll1 hll2 non_existent_key OK 127.0.0.1:7379> PFCOUNT hll_merged @@ -93,7 +89,7 @@ OK if a `sourcekey` exists and is not of type HyperLogLog, the command will result in an error -```sh +```bash 127.0.0.1:7379> PFMERGE hll_merged not_hyperLogLog (error) WRONGTYPE Key is not a valid HyperLogLog string value diff --git a/docs/src/content/docs/commands/PING.md b/docs/src/content/docs/commands/PING.md index a2dd12253..0570abb5c 100644 --- a/docs/src/content/docs/commands/PING.md +++ b/docs/src/content/docs/commands/PING.md @@ -9,7 +9,7 @@ The `PING` command in DiceDB is used to test the connection between the client a The basic syntax of the `PING` command is as follows: -``` +```bash PING [message] ``` @@ -18,16 +18,16 @@ PING [message] ## Parameters -| Parameter | Description | Type | Required | -|-----------------|--------------------------------------------------|---------|----------| -| `message` | `message` echoed in the response | String | No | +| Parameter | Description | Type | Required | +| --------- | -------------------------------- | ------ | -------- | +| `message` | `message` echoed in the response | String | No | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| No `message` provided | `PONG` | -| `message` provided | `message` | +| Condition | Return Value | +| --------------------- | ------------ | +| No `message` provided | `PONG` | +| `message` provided | `message` | ## Behaviour @@ -35,7 +35,7 @@ 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. +- 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. @@ -53,7 +53,7 @@ This helps clients determine if the server is up and responsive. Essentially, it ## Example Usage -### Basic Usage +### Basic Usage `PING` DiceDB server without a message and the server echoes with `PONG`. diff --git a/docs/src/content/docs/commands/PTTL.md b/docs/src/content/docs/commands/PTTL.md index dbee30529..c1cdf42c3 100644 --- a/docs/src/content/docs/commands/PTTL.md +++ b/docs/src/content/docs/commands/PTTL.md @@ -7,31 +7,29 @@ The `PTTL` command in DiceDB is used to retrieve the remaining time to live (TTL ## Syntax -``` +```bash PTTL key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|--------------------------------------------------------------------------|---------|----------| -| `key` | The key for which the remaining TTL is to be retrieved. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------ | ------ | -------- | +| `key` | The key for which the remaining TTL is to be retrieved | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------------------|-------------------| -| Command is successful | Returns a positive integer value representing the remaining time to live of the key in milliseconds | -| The key exists but has no associated expiration | `-1` | -| The key does not exist | `-2` | - +| Condition | Return Value | +| ------------------------------------------- | ----------------------------------------------------------------------------------- | +| Command is successful | Positive integer representing the remaining time to live of the key in milliseconds | +| Key exists but has no associated expiration | `-1` | +| Key does not exist | `-2` | ## Behaviour - The command is non-destructive and does not modify the key or its expiration in any way. - If a key's TTL is modified (e.g., by `EXPIRE` or `PEXPIRE` commands), subsequent `PTTL` calls will reflect the updated remaining time. - ## Errors 1. `Wrong number of arguments`: @@ -39,10 +37,9 @@ PTTL key - Error Message: `(error) ERR wrong number of arguments for 'pttl' command` - Occurs when attempting to use this command without any arguments or with more than one argument. - ## Example Usage -### Example 1: Key with Expiration +### Key with Expiration ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -53,7 +50,7 @@ PTTL key In this example, the key `mykey` is set with a value of "Hello" and an expiration of 10 seconds. The `PTTL` command returns `10000`, indicating that the key will expire in 10000 milliseconds. -### Example 2: Key without Expiration +### Key without Expiration ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -63,7 +60,7 @@ In this example, the key `mykey` is set with a value of "Hello" and an expiratio In this example, the key `mykey` is set with a value of "Hello" but no expiration is set. The `PTTL` command returns `-1`, indicating that the key exists but has no associated expiration. -### Example 3: Non-existent Key +### Non-existent Key ```bash 127.0.0.1:7379> PTTL nonExistentKey @@ -72,7 +69,7 @@ In this example, the key `mykey` is set with a value of "Hello" but no expiratio In this example, the key `nonExistentKey` does not exist in the DiceDB database. The `PTTL` command returns `-2`, indicating that the key does not exist. -### Example 4: Invalid usage +### Invalid usage ```bash 127.0.0.1:7379> SET newkey "value" @@ -81,3 +78,11 @@ In this example, the key `nonExistentKey` does not exist in the DiceDB database. ``` In this example, the `PTTL` command is used with an extra argument. This results in an error, as the `PTTL` command accepts only one argument. + +## Best Practices + +- Use `PTTL` in conjunction with `EXPIRE` or `PEXPIRE` commands to manage key expiration effectively + +## Alternatives + +- `TTL`: Similar to `PTTL` but returns the time-to-live in seconds instead of milliseconds diff --git a/docs/src/content/docs/commands/QWATCH.md b/docs/src/content/docs/commands/QWATCH.md index a8408b32f..52cc6ceca 100644 --- a/docs/src/content/docs/commands/QWATCH.md +++ b/docs/src/content/docs/commands/QWATCH.md @@ -13,11 +13,11 @@ to build real-time reactive applications like leaderboards. ## Protocol Support -| Protocol | Supported | -| -------- | --------- | -| TCP-RESP | ✅ | -| HTTP | ✅ | -| WebSocket| ✅ | +| Protocol | Supported | +| --------- | --------- | +| TCP-RESP | ✅ | +| HTTP | ✅ | +| WebSocket | ✅ | ## Syntax @@ -28,7 +28,7 @@ Q.WATCH ## Parameters | Parameter | Description | Type | Required | -|--------------|-------------------------------------------------------------------------------------|--------|----------| +| ------------ | ----------------------------------------------------------------------------------- | ------ | -------- | | `dsql-query` | A SQL-like query specifying the data to be monitored and operation to be performed. | String | Yes | ## DSQL Query @@ -79,7 +79,7 @@ Supported conditions: ## Return Value | Condition | Return Value | -|-----------------------|------------------------------------------------------------| +| --------------------- | ---------------------------------------------------------- | | Command is successful | A subscription confirmation message similar to `SUBSCRIBE` | | DSQL Query is invalid | error | @@ -96,18 +96,18 @@ Supported conditions: 1. `Missing query` - - Error Message: `(error) ERROR wrong number of arguments for 'q.watch' command` - - Occurs if no DSQL Query is provided. + - Error Message: `(error) ERROR wrong number of arguments for 'q.watch' command` + - Occurs if no DSQL Query is provided. 2. `Invalid query`: - - Error Message: `(error) ERROR error parsing SQL statement: syntax error at position ` - - Occurs if the provided query is malformed or has unsupported clauses. + - Error Message: `(error) ERROR error parsing SQL statement: syntax error at position ` + - Occurs if the provided query is malformed or has unsupported clauses. 3. `Max number of subscriptions reached`: - - Error Message: `(error) ERROR could not perform this operation on a key that doesn't exist` - - Occurs if the maximum number of allowed subscriptions is exceeded. + - Error Message: `(error) ERROR could not perform this operation on a key that doesn't exist` + - Occurs if the maximum number of allowed subscriptions is exceeded. ## Example Usage @@ -144,7 +144,7 @@ that the response will be RESP encoded and parsing will be handled by the SDK th 127.0.0.1:7379> SET match:100:user:0 5 ``` - Subscription does not return response as `value < 10`. + Subscription does not return response as `value < 10`. 3. Player 1 scores 15 points: @@ -153,7 +153,8 @@ that the response will be RESP encoded and parsing will be handled by the SDK th ``` Q.WATCH Response: - ```bash + + ```bash q.watch from SELECT $key, $value WHERE $key like 'match:100:*' and $value > 100 ORDER BY $value asc: `[["match:100:user:1", "15"]]` ``` @@ -164,7 +165,8 @@ that the response will be RESP encoded and parsing will be handled by the SDK th ``` Q.WATCH Response: - ```bash + + ```bash q.watch from SELECT $key, $value WHERE $key like 'match:100:*' and $value > 100 ORDER BY $value asc: `[["match:100:user:2", "20"], ["match:100:user:1", "15"]]` ``` @@ -175,7 +177,8 @@ that the response will be RESP encoded and parsing will be handled by the SDK th ``` Q.WATCH Response: - ```bash + + ```bash q.watch from SELECT $key, $value WHERE $key like 'match:100:*' and $value > 100 ORDER BY $value asc: `[["match:100:user:2", "20"], ["match:100:user:1", "15"], ["match:100:user:3", "12"]]` ``` @@ -186,7 +189,8 @@ that the response will be RESP encoded and parsing will be handled by the SDK th ``` Q.WATCH Response: - ```bash + + ```bash q.watch from SELECT $key, $value WHERE $key like 'match:100:*' and $value > 100 ORDER BY $value asc: `[["match:100:user:4", "25"], ["match:100:user:2", "20"], ["match:100:user:1", "15"]]` ``` @@ -197,7 +201,8 @@ that the response will be RESP encoded and parsing will be handled by the SDK th ``` Q.WATCH Response: - ```bash + + ```bash q.watch from SELECT $key, $value WHERE $key like 'match:100:*' and $value > 100 ORDER BY $value asc: `[["match:100:user:0", "30"], ["match:100:user:4", "25"], ["match:100:user:2", "20"]]` ``` diff --git a/docs/src/content/docs/commands/RENAME.md b/docs/src/content/docs/commands/RENAME.md index 206d152b0..39d8aabb7 100644 --- a/docs/src/content/docs/commands/RENAME.md +++ b/docs/src/content/docs/commands/RENAME.md @@ -7,7 +7,7 @@ The `RENAME` command in DiceDB is used to change the name of an existing key to ## Syntax -```plaintext +```bash RENAME oldkey newkey ``` diff --git a/docs/src/content/docs/commands/RPOP.md b/docs/src/content/docs/commands/RPOP.md index 7f464d78f..a6fab6f2b 100644 --- a/docs/src/content/docs/commands/RPOP.md +++ b/docs/src/content/docs/commands/RPOP.md @@ -7,29 +7,27 @@ The `RPOP` command in DiceDB is used to remove and return the last element of a ## Syntax -``` +```bash RPOP key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|----------------------------------------------------------------------|--------|----------| -| `key` | The key of the list from which the last element will be removed. | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ---------------------------------------------------------------- | ------ | -------- | +| `key` | The key of the list from which the last element will be removed. | String | Yes | ## Return values -| Condition | Return Value | -|------------------------------------------------|------------------------------------------------| -| The command is successful | The value of the last element in the list | -| The list is empty or the key does not exist | `nil` | -| The key is of the wrong type | Error: `WRONGTYPE Operation against a key holding the wrong kind of value` | - +| Condition | Return Value | +| ------------------------------------------- | -------------------------------------------------------------------------- | +| The command is successful | The value of the last element in the list | +| The list is empty or the key does not exist | `nil` | +| The key is of the wrong type | Error: `WRONGTYPE Operation against a key holding the wrong kind of value` | ## Behaviour -- The `RPOP` command checks if the key exists and whether it contains a list. +- The `RPOP` command checks if the key exists and whether it contains a list. - If the key does not exist, the command treats it as an empty list and returns `nil`. - If the key exists but the list is empty, `nil` is returned. - If the list has elements, the last element is removed and returned. @@ -38,6 +36,7 @@ RPOP key ## Errors 1. **Wrong type of value or key**: + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs when attempting to run `RPOP` on a key that is not a list. @@ -82,4 +81,3 @@ OK - `LPOP`: Removes and returns the first element of the list stored at key. By understanding the `RPOP` command, you can effectively manage lists in DiceDB, ensuring that you can retrieve and process elements in a LIFO order. - diff --git a/docs/src/content/docs/commands/RPUSH.md b/docs/src/content/docs/commands/RPUSH.md index d7fa6bca1..cf9f5c69e 100644 --- a/docs/src/content/docs/commands/RPUSH.md +++ b/docs/src/content/docs/commands/RPUSH.md @@ -7,50 +7,48 @@ The `RPUSH` command is used in DiceDB to insert one or multiple values at the ta ## Syntax -``` +```bash RPUSH key value [value ...] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The name of the list where the values will be inserted. If the list does not exist, a new list will be created. | String | Yes | -| `value` | One or more values to be inserted at the tail of the list. Multiple values can be specified, separated by spaces. | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ----------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The name of the list where the values will be inserted. If the list does not exist, a new list will be created. | String | Yes | +| `value` | One or more values to be inserted at the tail of the list. Multiple values can be specified, separated by spaces. | String | Yes | ## Return Value -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | integer | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------ | +| Command is successful | integer | +| Syntax or specified constraints are invalid | error | ## Behaviour -- When the `RPUSH` command is executed, the specified values are inserted at the tail of the list identified by the given key. +- When the `RPUSH` command is executed, the specified values are inserted at the tail of the list identified by the given key. - If the key does not exist, a new list is created and the values are inserted. - If the key exists but is not a list, an error is returned. - The `RPUSH` operation is atomic. If multiple clients issue `RPUSH` commands concurrently, DiceDB ensures that the list remains consistent and the values are appended in the order the commands were received. - ## Errors 1. `Non-List Key`: If the key exists but is not a list, DiceDB returns an error. + - Error Message: `WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs when trying to use the command on a key that does not contain a list. - 2. `Invalid Syntax`: If the command is not used with the correct syntax, DiceDB returns a syntax error. - Error Message: `ERR wrong number of arguments for 'rpush' command` - Occurs if the command's syntax is incorrect, like wrong number of arguments. - ## Example Usage ### Basic Usage Inserting a value `hello` into `mylist` + ```bash 127.0.0.1:7379> RPUSH mylist "hello" (integer) 1 @@ -59,6 +57,7 @@ Inserting a value `hello` into `mylist` ### Inserting Multiple Values Inserting multiple values `world`, `foo`, `bar` into `mylist` + ```bash 127.0.0.1:7379> RPUSH mylist "world" "foo" "bar" (integer) 4 @@ -73,11 +72,10 @@ Trying to insert value `val` into a non-list type `mykey` 127.0.0.1:7379> RPUSH mykey "val" (error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value ``` + Trying to run `rpush` with only 1 argument ```bash 127.0.0.1:7379> RPUSH mylist -(error) ERROR wrong number of arguments +(error) ERROR wrong number of arguments ``` - - diff --git a/docs/src/content/docs/commands/SADD.md b/docs/src/content/docs/commands/SADD.md index b7e562325..2600637a5 100644 --- a/docs/src/content/docs/commands/SADD.md +++ b/docs/src/content/docs/commands/SADD.md @@ -7,14 +7,14 @@ The `SADD` command in DiceDB is used to add one or more members to a set. If the ## Syntax -``` +```bash SADD key member [member ...] ``` ## Parameters | Parameter | Description | Type | Required | Multiple | -|-----------|----------------------------------------------------|--------|----------|----------| +| --------- | -------------------------------------------------- | ------ | -------- | -------- | | `key` | The name of the set to which members will be added | String | Yes | No | | `member` | One or more members to add to the set | String | Yes | Yes | @@ -23,10 +23,10 @@ SADD key member [member ...] ## Return values -| Condition | Return Value | -|---------------------------------------|------------------------------------------------------| -| Command is successful | Integer: Number of members added to the set | -| Key exists but is not a set | Error | +| Condition | Return Value | +| --------------------------- | ------------------------------------------- | +| Command is successful | Integer: Number of members added to the set | +| Key exists but is not a set | Error | - The integer returned represents the number of members that were actually added to the set, not including elements that were already present. - If all specified members already exist in the set, the command returns 0. @@ -34,11 +34,13 @@ SADD key member [member ...] ## Behaviour 1. **Key Existence Check**: + - If the key does not exist, DiceDB creates a new set and adds the specified members to it. - If the key exists and is a set, the command adds the new members to the existing set. - If the key exists but is not a set, an error is returned. 2. **Member Addition**: + - Each specified member is added to the set if it's not already present. - If a member already exists in the set, it is ignored, and no error is raised. - The order in which members are specified does not affect the set, as sets are unordered. @@ -47,7 +49,6 @@ SADD key member [member ...] - Sets only store unique elements. Attempting to add a duplicate element has no effect on the set. - The uniqueness is based on string comparison. For example, "1" and 1 are considered different members. - ## Errors 1. `Wrong type of value or key`: @@ -55,7 +56,6 @@ SADD key member [member ...] - Occurs when attempting to use the command on a key that contains a non-set value (e.g., string, list, hash). - This error ensures type safety in DiceDB operations. - ## Example Usage ### Basic Usage: Creating a New Set diff --git a/docs/src/content/docs/commands/SCARD.md b/docs/src/content/docs/commands/SCARD.md index 7fcedd932..2ec7eb92f 100644 --- a/docs/src/content/docs/commands/SCARD.md +++ b/docs/src/content/docs/commands/SCARD.md @@ -7,25 +7,23 @@ The `SCARD` command in DiceDB is used to get the number of members in a set. Thi ## Syntax -``` +```bash SCARD key ``` ## Parameters -| Parameter | Description | Type | Required | -|------------|---------------------------------------------------------------------------------|--------|----------| -| `key` | The key of the set whose cardinality (number of members) you want to retrieve. | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------ | ------ | -------- | +| `key` | The key of the set whose cardinality (number of members) you want to retrieve. | String | Yes | ## Return Values -| Condition | Return Value | -|-----------------------------------------|----------------------------------| -| Key of Set type exists | Number of elements in the set | -| Key doesn't exist | `0` | -| Invalid syntax/key is of the wrong type | error | - +| Condition | Return Value | +| --------------------------------------- | ----------------------------- | +| Key of Set type exists | Number of elements in the set | +| Key doesn't exist | `0` | +| Invalid syntax/key is of the wrong type | error | ## Behaviour @@ -40,14 +38,13 @@ When the `SCARD` command is executed, DiceDB will: 1. `Wrong type of key`: - - Error Message: `(error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value` - - Occurs if the key exists but is not a set. DiceDB expects the key to be associated with a set data type. If the key is associated with a different data type (e.g., a string, list, hash, or sorted set), this error will be raised. + - Error Message: `(error) ERROR WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if the key exists but is not a set. DiceDB expects the key to be associated with a set data type. If the key is associated with a different data type (e.g., a string, list, hash, or sorted set), this error will be raised. 2. `Wrong number of arguments`: - - Error Message: `(error) ERROR wrong number of arguments for 'scard' command` - - Occurs if wrong number of keys is passed to the command, such as passing more than 1 key, or passing no key. - + - Error Message: `(error) ERROR wrong number of arguments for 'scard' command` + - Occurs if wrong number of keys is passed to the command, such as passing more than 1 key, or passing no key. ## Examples @@ -95,4 +92,4 @@ Get cardinality of a set holding 0 or more than 1 argument (error) ERROR wrong number of arguments for 'scard' command 127.0.0.1:7379> SCARD myset1 myset2 (error) ERROR wrong number of arguments for 'scard' command -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/commands/SDIFF.md b/docs/src/content/docs/commands/SDIFF.md index 634209496..721684986 100644 --- a/docs/src/content/docs/commands/SDIFF.md +++ b/docs/src/content/docs/commands/SDIFF.md @@ -7,29 +7,27 @@ The `SDIFF` command in DiceDB is used to compute the difference between multiple ## Syntax -``` +```bash SDIFF key1 [key2 ... keyN] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------------|-----------------------------------------------------------------------|---------|----------| -|`key1` | The key of the first set. | String | Yes | -|`key2..keyN` | The keys of the subsequent sets to be compared with the first set. | String | No | +| Parameter | Description | Type | Required | +| ------------ | ------------------------------------------------------------------ | ------ | -------- | +| `key1` | The key of the first set. | String | Yes | +| `key2..keyN` | The keys of the subsequent sets to be compared with the first set. | String | No | ## Return Values The `SDIFF` command returns an array of elements that are present in the first set but not in any of the subsequent sets. If the first set does not exist, it is considered an empty set. If none of the sets exist, an empty array is returned. -| Condition | Return Value | -|------------------------------------------------------------------------------------------|--------------------------------------------------------------------| -| Elements present in the first set but not in any subsequent sets | `Array of elements` | -| First set does not exist | `Empty array` | -| None of the sets exist | `Empty array` | -| Syntax or specified constraints are invalid | error | - - +| Condition | Return Value | +| ---------------------------------------------------------------- | ------------------- | +| Elements present in the first set but not in any subsequent sets | `Array of elements` | +| First set does not exist | `Empty array` | +| None of the sets exist | `Empty array` | +| Syntax or specified constraints are invalid | error | ## Behaviour @@ -41,12 +39,14 @@ The `SDIFF` command returns an array of elements that are present in the first s ## Errors - `Wrong Type Error`: - - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - - If any of the keys provided do not hold a set, DiceDB will return an error of type `WRONGTYPE`. This error indicates that the operation against a key holding the wrong kind of value was attempted. + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - If any of the keys provided do not hold a set, DiceDB will return an error of type `WRONGTYPE`. This error indicates that the operation against a key holding the wrong kind of value was attempted. - `Wrong number of arguments`: - - Error Message: `(error) ERR wrong number of arguments for 'sdiff' command` - - If no keys are provided, DiceDB will return a syntax error indicating that at least one key must be specified. + + - Error Message: `(error) ERR wrong number of arguments for 'sdiff' command` + - If no keys are provided, DiceDB will return a syntax error indicating that at least one key must be specified. - `Syntax Error`: If no keys are provided, DiceDB will return a syntax error indicating that at least one key must be specified. @@ -54,7 +54,6 @@ The `SDIFF` command returns an array of elements that are present in the first s ### Example 1: Basic Usage - In this example, the difference between set1 and the union of set2 and set3 is computed. The element “b” is unique to set1. ```bash @@ -66,7 +65,6 @@ In this example, the difference between set1 and the union of set2 and set3 is c "b" ``` - ### Example 2: Single Set In this example, since only one set is provided, the command returns all elements of `set1`. diff --git a/docs/src/content/docs/commands/SELECT.md b/docs/src/content/docs/commands/SELECT.md index 69d4409c3..71825bbc2 100644 --- a/docs/src/content/docs/commands/SELECT.md +++ b/docs/src/content/docs/commands/SELECT.md @@ -3,27 +3,27 @@ title: SELECT description: Documentation for the DiceDB command SELECT --- -**Note:** As of today, DiceDB does not support multiple databases. Therefore, the `SELECT` command is currently a dummy method and does not affect the database. It remains as a placeholder. +> **Important Note:** As of the current version, DiceDB does not support multiple databases. Therefore, the `SELECT` command is currently a dummy method and does not affect the database. It remains as a placeholder. The `SELECT` command is used to switch the currently selected database for the current connection in DiceDB. By default, DiceDB starts with database 0, but it supports multiple databases, which can be accessed by using the `SELECT` command. This command is essential for managing data across different logical databases within a single DiceDB instance. ## Syntax -``` +```bash SELECT index ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|-------------------------------------------------|---------|----------| +| Parameter | Description | Type | Required | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- | | `index` | The zero-based index of the database to select. DiceDB databases are indexed starting from 0 up to a configurable maximum (default is 15, configurable via the `databases` configuration directive) | Integer | Yes | ## Return Value -| Condition | Return Value | -|--------------------------|--------------| -| Command is successful | `OK` | +| Condition | Return Value | +| --------------------- | ------------ | +| Command is successful | `OK` | ## Behaviour @@ -39,48 +39,45 @@ When the `SELECT` command is issued, the current connection's context is switche 1. `Invalid Database Index`: - - `Error`: `(error) ERR DB index is out of range` - - `Condition`: If the specified database index is outside the range of available databases. + - Error Message: `(error) ERR DB index is out of range` + - Occurs when the specified database index exceeds the configured maximum (default 15) 2. `Non-Integer Index`: - - - `Error`: `(error) ERR value is not an integer or out of range` - - `Condition`: If the provided index is not a valid integer. + - Error Message: `(error) ERR value is not an integer or out of range` + - Occurs when the provided index is not a valid integer ## Example Usage ### Switching to Database 1 -```shell +```bash 127.0.0.1:7379> SELECT 1 OK ``` -In this example, the connection switches to database 1. All subsequent commands will operate on database 1. - -### Switching to Database 0 +### Switching Back to Default Database -```shell +```bash 127.0.0.1:7379> SELECT 0 OK ``` -Here, the connection switches back to the default database 0. +### Invalid Database Index ### Error Example: Invalid Database Index -```shell +```bash 127.0.0.1:7379> SELECT 16 (error) ERR DB index is out of range ``` -In this example, an error is raised because the specified database index 16 is outside the default range of 0-15. +### Invalid Input Type -### Error Example: Non-Integer Index - -```shell +```bash 127.0.0.1:7379> SELECT one (error) ERR value is not an integer or out of range ``` -In this example, an error is raised because the provided index is not a valid integer. +## Notes + +As mentioned at the beginning of this document, the current version of DiceDB does not support multiple databases. The `SELECT` command is implemented as a placeholder for future functionality. All operations, regardless of the SELECT command, will continue to operate on a single database space. diff --git a/docs/src/content/docs/commands/SET.md b/docs/src/content/docs/commands/SET.md index 14b076641..c65db76c9 100644 --- a/docs/src/content/docs/commands/SET.md +++ b/docs/src/content/docs/commands/SET.md @@ -7,14 +7,14 @@ The `SET` command in DiceDB is used to set the value of a key. If the key alread ## Syntax -``` +```bash SET key value [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] [NX | XX] ``` ## Parameters | Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| +| --------- | ------------------------------------------------------------------------- | ------- | -------- | | `key` | The name of the key to be set. | String | Yes | | `value` | The value to be set for the key. | String | Yes | | `EX` | Set the specified expire time, in seconds. | Integer | No | @@ -27,11 +27,11 @@ SET key value [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| Command is successful | `OK` | -| `NX` or `XX` conditions are not met | `nil` | -| Syntax or specified constraints are invalid | error | +| Condition | Return Value | +| ------------------------------------------- | ------------ | +| Command is successful | `OK` | +| `NX` or `XX` conditions are not met | `nil` | +| Syntax or specified constraints are invalid | error | ## Behaviour diff --git a/docs/src/content/docs/commands/SETBIT.md b/docs/src/content/docs/commands/SETBIT.md index b77f6dfad..f4cb272ef 100644 --- a/docs/src/content/docs/commands/SETBIT.md +++ b/docs/src/content/docs/commands/SETBIT.md @@ -7,7 +7,7 @@ The `SETBIT` command in DiceDB is used to set or clear the bit at a specified of ## Syntax -``` +```bash SETBIT key offset value ``` @@ -37,7 +37,7 @@ The command returns the original bit value stored at the specified offset before ### Setting a Bit -```DiceDB +```bash SETBIT mykey 7 1 ``` @@ -45,7 +45,7 @@ This command sets the bit at offset 7 in the string value stored at `mykey` to 1 ### Clearing a Bit -```DiceDB +```bash SETBIT mykey 7 0 ``` @@ -53,7 +53,7 @@ This command clears the bit at offset 7 in the string value stored at `mykey` to ### Checking the Original Bit Value -```DiceDB +```bash SETBIT mykey 7 1 ``` @@ -61,7 +61,7 @@ If the bit at offset 7 was previously 0, this command will return 0 and then set ### Extending the String -```DiceDB +```bash SETBIT mykey 100 1 ``` @@ -71,7 +71,7 @@ If the string stored at `mykey` is shorter than 101 bits, it will be extended, a ### Invalid Offset -```DiceDB +```bash SETBIT mykey -1 1 ``` @@ -79,7 +79,7 @@ This command will raise an error: `ERR bit is not an integer or out of range` be ### Invalid Value -```DiceDB +```bash SETBIT mykey 7 2 ``` @@ -87,7 +87,7 @@ This command will raise an error: `ERR bit is not an integer or out of range` be ### Wrong Type -```DiceDB +```bash SET mykey "Hello" SETBIT mykey 7 1 ``` diff --git a/docs/src/content/docs/commands/SINTER.md b/docs/src/content/docs/commands/SINTER.md index 46a4f3e78..eb854c351 100644 --- a/docs/src/content/docs/commands/SINTER.md +++ b/docs/src/content/docs/commands/SINTER.md @@ -7,22 +7,23 @@ The `SINTER` command in DiceDB is used to compute the intersection of multiple s ## Syntax -``` +```bash SINTER key [key ...] ``` + ## Parameters -| Parameter | Description | Type | Required | -|----------------|-----------------------------------------------------------------------------------------------|---------|----------| -| `key [key ...]`| One or more identifier keys representing sets to intersect. At least one key must be provided.| String | Yes | +| Parameter | Description | Type | Required | +| --------------- | ---------------------------------------------------------------------------------------------- | ------ | -------- | +| `key [key ...]` | One or more identifier keys representing sets to intersect. At least one key must be provided. | String | Yes | ## Return Values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------------------------------| -| Common elements exist | array of elements (as strings) that are present in all the specified sets | -| No common elements exist | `(empty array)` | -| Invalid syntax or no specified keys | error | +| Condition | Return Value | +| ----------------------------------- | ------------------------------------------------------------------------- | +| Common elements exist | array of elements (as strings) that are present in all the specified sets | +| No common elements exist | `(empty array)` | +| Invalid syntax or no specified keys | error | ## Behaviour @@ -45,7 +46,7 @@ If any of the specified keys do not exist, they are treated as empty sets. The i ### Example 1: Basic Intersection -```shell +```bash # Add elements to sets 127.0.0.1:7379> SADD set1 "a" "b" "c" (integer) 3 @@ -61,7 +62,7 @@ If any of the specified keys do not exist, they are treated as empty sets. The i ### Example 2: Intersection with Non-Existent Set -```shell +```bash # Add elements to sets 127.0.0.1:7379> SADD set1 "a" "b" "c" (integer) 3 @@ -72,11 +73,12 @@ If any of the specified keys do not exist, they are treated as empty sets. The i 127.0.0.1:7379> SINTER set1 set2 set3 (empty array) ``` + Note: By default, non-existent keys (such as set3 in the example above) are treated like empty sets. There's no built-in way to create an empty set. ### Example 3: Error Handling - Wrong Type -```shell +```bash # Add elements to sets 127.0.0.1:7379> SADD set1 "a" "b" "c" (integer) 3 @@ -91,7 +93,7 @@ SINTER set1 stringKey ### Example 4: Error Handling - No Keys Provided -```shell +```bash # Attempt to compute intersection without providing any keys 127.0.0.1:7379> SINTER (error) ERR wrong number of arguments for 'sinter' command diff --git a/docs/src/content/docs/commands/SLEEP.md b/docs/src/content/docs/commands/SLEEP.md index e4e93de8a..6a3afa689 100644 --- a/docs/src/content/docs/commands/SLEEP.md +++ b/docs/src/content/docs/commands/SLEEP.md @@ -13,19 +13,17 @@ SLEEP seconds ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|--------|----------| -| `seconds` | An integer representing the number of seconds to sleep. Only integers values are allowed. | Integer | Yes | - +| Parameter | Description | Type | Required | +| --------- | ----------------------------------------------------------------------------------------- | ------- | -------- | +| `seconds` | An integer representing the number of seconds to sleep. Only integers values are allowed. | Integer | Yes | ## Return values | Condition | Return Value | -|-----------------------------------------|-------------------------------------------------| +| --------------------------------------- | ----------------------------------------------- | | Command is successful | `OK` after specified sleep duration has elapsed | | Syntax or specified datatype is invalid | error | - ## Behaviour When the `SLEEP` command is executed, the following behavior is observed: @@ -40,6 +38,7 @@ When the `SLEEP` command is executed, the following behavior is observed: The `SLEEP` command can raise errors under the following conditions: 1. `Invalid Number of Arguments`: + - Error Message: `ERR wrong number of arguments for 'sleep' command` - Occurs if the `SLEEP` command is called without the required `seconds` parameter or with more than one parameter. diff --git a/docs/src/content/docs/commands/SMEMBERS.md b/docs/src/content/docs/commands/SMEMBERS.md index 5042971fc..e0a38a07b 100644 --- a/docs/src/content/docs/commands/SMEMBERS.md +++ b/docs/src/content/docs/commands/SMEMBERS.md @@ -12,18 +12,21 @@ SMEMBERS key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|-----------------------------------------------------|--------|----------| + +| Parameter | Description | Type | Required | +| --------- | ---------------------------------------------------- | ------ | -------- | | key | The key identifying the set to retrieve members from | string | Yes | ## Return values -| Condition | Return Value | -|----------------------------------|----------------------------------------------------------| -| Key exists and is a set | Array containing all members of the set | -| Key does not exist | Empty array | -| Key exists but is not a set | Error message indicating wrong type | + +| Condition | Return Value | +| --------------------------- | --------------------------------------- | +| Key exists and is a set | Array containing all members of the set | +| Key does not exist | Empty array | +| Key exists but is not a set | Error message indicating wrong type | ## Behaviour + - Checks if the provided key exists in the database - Verifies if the key is associated with a set data structure - If key exists and is a set, retrieves all members from the set @@ -32,6 +35,7 @@ SMEMBERS key - The order of elements in the returned array is not guaranteed to be consistent ## Errors + 1. `Wrong type of key`: - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs when attempting to use SMEMBERS on a key that contains a non-set value @@ -39,6 +43,7 @@ SMEMBERS key ## Example Usage ### Basic Usage + ```bash 127.0.0.1:7379> SADD myset "apple" "banana" "cherry" (integer) 3 @@ -49,18 +54,21 @@ SMEMBERS key ``` ### Empty Set + ```bash 127.0.0.1:7379> SMEMBERS nonexistentset (empty array) ``` ### Invalid Usage + ```bash 127.0.0.1:7379> SMEMBERS (error) ERR wrong number of arguments for 'smembers' command ``` ### Wrong Type Error + ```bash 127.0.0.1:7379> SET mystring "hello" OK @@ -69,15 +77,16 @@ OK ``` ## Best Practices + 1. Always verify the key type before using SMEMBERS to avoid type errors 2. Implement proper error handling in your application for WRONGTYPE errors 3. Use EXISTS command to check for key presence before SMEMBERS if key existence is uncertain - - - + + ## Notes + 1. The command returns all members at once, which may impact performance for very large sets 2. The order of returned elements is not guaranteed and may vary between calls 3. Memory usage scales linearly with the size of the set -4. This command has O(N) time complexity where N is the set size \ No newline at end of file +4. This command has O(N) time complexity where N is the set size diff --git a/docs/src/content/docs/commands/SREM.md b/docs/src/content/docs/commands/SREM.md index 21bf7dcd6..657670968 100644 --- a/docs/src/content/docs/commands/SREM.md +++ b/docs/src/content/docs/commands/SREM.md @@ -7,7 +7,7 @@ The `SREM` command is used to remove one or more members from a set stored at a ## Syntax -``` +```bash SREM key member [member ...] ``` @@ -39,7 +39,7 @@ When the `SREM` command is executed, the following steps occur: ### Example 1: Removing a single member from a set -```DiceDB +```bash SADD myset "one" "two" "three" SREM myset "two" ``` @@ -54,7 +54,7 @@ SREM myset "two" ### Example 2: Removing multiple members from a set -```DiceDB +```bash SADD myset "one" "two" "three" SREM myset "two" "three" ``` @@ -69,7 +69,7 @@ SREM myset "two" "three" ### Example 3: Removing a non-existing member from a set -```DiceDB +```bash SADD myset "one" "two" "three" SREM myset "four" ``` @@ -84,7 +84,7 @@ SREM myset "four" ### Example 4: Removing members from a non-existing set -```DiceDB +```bash SREM myset "one" ``` @@ -98,7 +98,7 @@ SREM myset "one" ### Example 5: Error when key is not a set -```DiceDB +```bash SET mykey "value" SREM mykey "one" ``` @@ -118,4 +118,3 @@ SREM mykey "one" - If the set becomes empty after the removal of members, the key is automatically deleted from the database. By understanding the `SREM` command, you can effectively manage the members of sets in your DiceDB database, ensuring efficient and error-free operations. - diff --git a/docs/src/content/docs/commands/TOUCH.md b/docs/src/content/docs/commands/TOUCH.md index 0e7d531fa..951edf8a1 100644 --- a/docs/src/content/docs/commands/TOUCH.md +++ b/docs/src/content/docs/commands/TOUCH.md @@ -7,26 +7,24 @@ The `TOUCH` command in DiceDB is used to update the last access time of one or m ## Syntax -```plaintext +```bash TOUCH key [key ...] ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------|---------------------------------------------------------------------------|---------|----------| -| `key` | The key(s) whose last access time you want to update. You can specify multiple keys separated by spaces. | String | Yes | +| Parameter | Description | Type | Required | +| --------- | -------------------------------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key(s) whose last access time you want to update. You can specify multiple keys separated by spaces. | String | Yes | ## Return Value - -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| The access time of the key(s) was successfully updated. | `integer` | -| The type of key is unsupported. | `error` | - -## Behaviour +| Condition | Return Value | +| ------------------------------------------------------- | ------------ | +| The access time of the key(s) was successfully updated. | `integer` | +| The type of key is unsupported. | `error` | +## Behaviour - When the `TOUCH` command is executed, it will Check whether or not the specified key(s) exists in the database. - If a key exists, its last access time will be updated to the current time. @@ -43,7 +41,7 @@ The `TOUCH` command can raise the following errors: ### Single Key -```plaintext +```bash SET mykey "Hello" TOUCH mykey ``` @@ -52,7 +50,7 @@ In this example, the `TOUCH` command updates the last access time of the key `my ### Multiple Keys -```plaintext +```bash SET key1 "value1" SET key2 "value2" TOUCH key1 key2 key3 @@ -64,7 +62,7 @@ In this example, the `TOUCH` command attempts to update the last access time for Trying to touch key `mylist` will result in a `WRONGTYPE` error because `mylist` is a list, not a string. -```plaintext +```bash LPUSH mylist "element" TOUCH mylist -``` +``` diff --git a/docs/src/content/docs/commands/TTL.md b/docs/src/content/docs/commands/TTL.md index 1bac81162..5dd276ac3 100644 --- a/docs/src/content/docs/commands/TTL.md +++ b/docs/src/content/docs/commands/TTL.md @@ -12,18 +12,18 @@ TTL key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|--------------------------------------------------|---------|----------| -| `key` | The key for which you want to check the TTL. | String | Yes | -## Return values +| Parameter | Description | Type | Required | +| --------- | -------------------------------------------- | ------ | -------- | +| `key` | The key for which you want to check the TTL. | String | Yes | -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| The remaining TTL in seconds | A positive integer | -| The key exists but has no associated expiration time | `-1` | -| The key does not exist. | `-2` | +## Return values +| Condition | Return Value | +| ---------------------------------------------------- | ------------------ | +| The remaining TTL in seconds | A positive integer | +| The key exists but has no associated expiration time | `-1` | +| The key does not exist. | `-2` | ## Behaviour @@ -33,16 +33,13 @@ TTL key ## Errors -The `TTL` command can raise errors in the following scenarios: - -- `Syntax Error`: - - - (error) ERROR syntax error - - Occurs when attempting to use the command with more than one argument. +1. `Wrong number of arguments`: + - Error Message: `(error) ERR wrong number of arguments for 'ttl' command` + - Occurs when attempting to use the command with incorrect number of arguments -## Examples +## Example Usage -### Example 1: Key with Expiration +### Check TTL for key with expiration ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -51,9 +48,9 @@ The `TTL` command can raise errors in the following scenarios: (integer) 10 ``` -In this example, the key `mykey` is set with a value of "Hello" and an expiration time of 10 seconds. The `TTL` command returns `10`, indicating that the key will expire in 10 seconds. +In this example, a key `mykey` is created with a value "Hello". Then, an expiration time of 10 seconds is set using the `EXPIRE` command. When `TTL` is called on `mykey`, it returns 10, indicating that the key will expire in 10 seconds. -### Example 2: Key without Expiration +### Check TTL for key without expiration ```bash 127.0.0.1:7379> SET mykey "Hello" @@ -61,24 +58,31 @@ In this example, the key `mykey` is set with a value of "Hello" and an expiratio (integer) -1 ``` -Here, the key `mykey` is set with a value of "Hello" but no expiration time is set. The `TTL` command returns `-1`, indicating that the key has no expiration. +In this example, the key `mykey` is set with a value of "Hello" but no expiration is set. The `TTL` command returns `-1`, indicating that the key exists but has no associated expiration. -### Example 3: Non-Existent Key +### Check TTL for non-existent key ```bash 127.0.0.1:7379> TTL non_existent_key (integer) -2 ``` -In this example, the key `non_existent_key` does not exist in the database. The `TTL` command returns `-2`, indicating that the key does not exist. +In this example, the key `non_existent_key` does not exist in the DiceDB database. The `TTL` command returns `-2`, indicating that the key does not exist. +### Invalid usage -### Example 4: Invalid usage ```bash 127.0.0.1:7379> SET newkey "value" 127.0.0.1:7379> TTL newkey value (error) ERR wrong number of arguments for 'ttl' command ``` -- The `TTL` command requires exactly one argument: `key` -- Since only more than one argument is provided, DiceDB returns a syntax error. +In this example, the `TTL` command is used with an extra argument. This results in an error, as the `TTL` command accepts only one argument. + +## Best Practices + +- Use `TTL` in conjunction with `EXPIRE` or `EXPIREAT` commands to manage key expiration effectively + +## Alternatives + +- `PTTL`: Similar to `TTL` but returns the time-to-live in milliseconds instead of seconds diff --git a/docs/src/content/docs/commands/ZCARD.md b/docs/src/content/docs/commands/ZCARD.md index 0e0c1bbb3..34c5122e5 100644 --- a/docs/src/content/docs/commands/ZCARD.md +++ b/docs/src/content/docs/commands/ZCARD.md @@ -7,23 +7,22 @@ The `ZCARD` command in DiceDB is used to obtain the cardinality (number of eleme ## Syntax -``` +```bash ZCARD key ``` ## Parameters -| Parameter | Description | Type | Required | -|-----------------|------------------------------------------------------------------------------------------|---------|----------| -| `key` | The key associated with the sorted set for whose cardinality is to be retrieved | String | Yes | - +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------- | ------ | -------- | +| `key` | The key associated with the sorted set for whose cardinality is to be retrieved | String | Yes | ## Return Value -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If specified key exists | cardinality of the sorted set at key | -| If key doesn't exist | `0` | +| Condition | Return Value | +| ----------------------- | ------------------------------------ | +| If specified key exists | cardinality of the sorted set at key | +| If key doesn't exist | `0` | ## Behaviour @@ -44,42 +43,44 @@ ZCARD key - Error Message: `(error) -ERR wrong number of arguments for 'ZCARD' command` - Occurs if key isn't specified in the command. - ## Example Usage ### Basic Usage + Creating sorted set `myzset` with two fields `one`, `two` with scores 1, 2 respectively. Getting cardinality of `myzset`. Adding new element into `myzset` and getting updated cardinality. -```DiceDB -> ZADD myzset 1 "one" 2 "two" +```bash +127.0.0.1:7379> ZADD myzset 1 "one" 2 "two" (integer) 2 -> ZCARD myzset +127.0.0.1:7379> ZCARD myzset (integer) 2 -> ZADD myzset 3 "three" +127.0.0.1:7379> ZADD myzset 3 "three" (integer) 1 -> ZCARD myzset +127.0.0.1:7379> ZCARD myzset (integer) 3 ``` ### Invalid Usage on non-existent sorted set + Getting cardinality of a non-existent sorted set `nonExistentZSet`. -```DiceDB -> ZCARD nonExistentZSet +```bash +127.0.0.1:7379> ZCARD nonExistentZSet (integer) 0 ``` ### Invalid Usage on a non sorted set key -Getting cardinality of a key `myzset` associated with a non sorted set type. -```DiceDB -> SET mystring "This is a string" +Getting cardinality of a key `mystring` associated with a non sorted set type. + +```bash +127.0.0.1:7379> SET mystring "This is a string" OK -> ZCARD mystring +127.0.0.1:7379> ZCARD mystring (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` @@ -87,4 +88,3 @@ OK - The `ZCARD` command is a constant-time operation, meaning its execution time is O(1) regardless of the number of elements in the sorted set. - This command is useful for quickly determining the size of the sorted set without needing to retrieve all the fields and values. - diff --git a/docs/src/content/docs/commands/ZCOUNT.md b/docs/src/content/docs/commands/ZCOUNT.md index b9cff8f13..3b40ea265 100644 --- a/docs/src/content/docs/commands/ZCOUNT.md +++ b/docs/src/content/docs/commands/ZCOUNT.md @@ -7,28 +7,28 @@ The ZCOUNT command in DiceDB counts the number of members in a sorted set at the ## Syntax -``` +```bash ZCOUNT key min max ``` ## Parameters | Parameter | Description | Type | Required | -|-----------|--------------------------------------------------|--------|----------| +| --------- | ------------------------------------------------ | ------ | -------- | | key | The name of the sorted set to operate on. | String | Yes | | min | Minimum score (inclusive) of the range to count. | Int | Yes | | max | Maximum score (inclusive) of the range to count. | Int | Yes | ## Return Values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If the key exists and is a sorted set | Returns the count of elements in the specified range. | -| If the key does not exist | Returns `0`. | -| If the key is not a sorted set | Returns an error. | - +| Condition | Return Value | +| ------------------------------------- | ----------------------------------------------------- | +| If the key exists and is a sorted set | Returns the count of elements in the specified range. | +| If the key does not exist | Returns `0`. | +| If the key is not a sorted set | Returns an error. | ## Behaviour + Retrieves the sorted set associated with the given key. Counts all elements whose scores fall between the given min and max (inclusive). If the key does not exist, it behaves as if it is an empty sorted set and returns 0. @@ -36,13 +36,13 @@ If the key is not of the sorted set type, an error is returned. ## Errors -1. **Wrong Type**: +1. **Wrong Type**: - **Message**: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` -2. **Wrong Argument Count**: +2. **Wrong Argument Count**: - **Message**: `(error) ERROR wrong number of arguments for 'zcount' command` - ## Example Usage + ```bash 127.0.0.1:7379> ZCOUNT NON_EXISTENT_KEY 0 100 0 @@ -58,6 +58,7 @@ If the key is not of the sorted set type, an error is returned. 127.0.0.1:7379> ZCOUNT myzset 30 10 0 ``` + ### Invalid usage ```bash @@ -66,4 +67,4 @@ If the key is not of the sorted set type, an error is returned. 127.0.0.1:7379> ZCOUNT myzset "invalid" 100 (integer) 0 -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/commands/ZPOPMAX.md b/docs/src/content/docs/commands/ZPOPMAX.md index c0fd58b7d..b4b50be5b 100644 --- a/docs/src/content/docs/commands/ZPOPMAX.md +++ b/docs/src/content/docs/commands/ZPOPMAX.md @@ -1,5 +1,5 @@ --- -title: ZPOPMAX +title: ZPOPMAX description: The `ZPOPMAX` command in DiceDB is used to remove and return the members with the highest scores from the sorted set data structure at the specified key. The second argument count is optional which specifies the number of elements that needs to be popped from the sorted set. --- @@ -7,23 +7,23 @@ The `ZPOPMAX` command in DiceDB is used to remove and return the members with th ## Syntax -``` +```bash ZPOPMAX key [count] ``` ## Parameters -| Parameter | Description | Type | Required | -|------------|----------------------------------------------------------------------------------------------|---------|----------| -| `key` | The name of the sorted set data structure. If it does not exist, an empty array is returned. | String | Yes | -| `count` | The count argument specifies the maximum number of members to return from highest to lowest. | Integer | No | +| Parameter | Description | Type | Required | +| --------- | -------------------------------------------------------------------------------------------- | ------- | -------- | +| `key` | The name of the sorted set data structure. If it does not exist, an empty array is returned. | String | Yes | +| `count` | The count argument specifies the maximum number of members to return from highest to lowest. | Integer | No | ## Return values -| Condition | Return Value | -|----------------------------------------------------------|------------------------------------------| -| If the key is of valid type and records are present | List of members including their scores | -| If the key does not exist or if the sorted set is empty | `(empty list or set)` | +| Condition | Return Value | +| ------------------------------------------------------- | -------------------------------------- | +| If the key is of valid type and records are present | List of members including their scores | +| If the key does not exist or if the sorted set is empty | `(empty list or set)` | ## Behaviour @@ -34,17 +34,20 @@ ZPOPMAX key [count] - The returned array contains the members and their corresponding scores in the order of highest to lowest. ## Errors + 1. `Wrong type error`: - - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - - Occurs when trying to use the command on a key that is not a sorted set. + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs when trying to use the command on a key that is not a sorted set. 2. `Syntax error`: - - Error Message: `(error) ERROR wrong number of arguments for 'zpopMAX' command` - - Occurs when the command syntax is incorrect or missing required parameters. + + - Error Message: `(error) ERROR wrong number of arguments for 'zpopMAX' command` + - Occurs when the command syntax is incorrect or missing required parameters. 3. `Invalid argument type error`: - - Error Message : `(error) ERR value is not an integer or out of range` - - Occurs when the count argument passed to the command is not an integer. + - Error Message : `(error) ERR value is not an integer or out of range` + - Occurs when the count argument passed to the command is not an integer. ## Examples @@ -145,4 +148,4 @@ Attempting to pop from a key that is not a sorted set: OK 127.0.0.1:7379> ZPOPMAX stringkey (error) WRONGTYPE Operation against a key holding the wrong kind of value -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/commands/ZPOPMIN.md b/docs/src/content/docs/commands/ZPOPMIN.md index 1334ddafa..ff5e79d0c 100644 --- a/docs/src/content/docs/commands/ZPOPMIN.md +++ b/docs/src/content/docs/commands/ZPOPMIN.md @@ -1,5 +1,5 @@ --- -title: ZPOPMIN +title: ZPOPMIN description: The `ZPOPMIN` command in DiceDB is used to remove and return the members with the lowest scores from the sorted set data structure at the specified key. If a count is provided, it returns up to that number of members with the lowest scores, removing them from the set. --- @@ -13,19 +13,20 @@ ZPOPMIN key [count] ## Parameters -| Parameter | Description | Type | Required | -|------------|--------------------------------------------------------------------------------------|---------|----------| -| `key` | The name of the sorted set. If it does not exist, an empty array is returned. | String | Yes | -| `count` | The count argument specifies the number of members to return with the lowest scores. | Integer | No | +| Parameter | Description | Type | Required | +| --------- | ------------------------------------------------------------------------------------ | ------- | -------- | +| `key` | The name of the sorted set. If it does not exist, an empty array is returned. | String | Yes | +| `count` | The count argument specifies the number of members to return with the lowest scores. | Integer | No | ## Return values -| Condition | Return Value | -|----------------------------------------------------------|------------------------------------------| -| If the key is of valid type and records are present | List of members including their scores | -| If the key does not exist or if the sorted set is empty | `(empty list or set)` | +| Condition | Return Value | +| ------------------------------------------------------- | -------------------------------------- | +| If the key is of valid type and records are present | List of members including their scores | +| If the key does not exist or if the sorted set is empty | `(empty list or set)` | ## Behaviour + - The command first checks if the specified key exists. - If the key does not exist, an empty array is returned. - If the key exists but is not a sorted set, an error is returned. @@ -33,17 +34,20 @@ ZPOPMIN key [count] - The returned array contains the members and their corresponding scores in the order of lowest to highest. ## Errors + 1. `Wrong type of value or key`: - - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - - Occurs when trying to use the command on a key that is not a sorted set. + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs when trying to use the command on a key that is not a sorted set. 2. `Invalid syntax or conflicting options`: - - Error Message: `(error) ERROR wrong number of arguments for 'zpopmin' command` - - Occurs when the command syntax is incorrect or missing required parameters. + + - Error Message: `(error) ERROR wrong number of arguments for 'zpopmin' command` + - Occurs when the command syntax is incorrect or missing required parameters. 3. `Non-integer value for `count\`\`: - - Error Message : `(error) ERR value is not an integer or out of range` - - Occurs when the count argument passed to the command is not an integer. + - Error Message : `(error) ERR value is not an integer or out of range` + - Occurs when the count argument passed to the command is not an integer. ## Examples @@ -144,4 +148,4 @@ Attempting to pop from a key that is not a sorted set: OK 127.0.0.1:7379> ZPOPMIN stringkey (error) WRONGTYPE Operation against a key holding the wrong kind of value -``` \ No newline at end of file +``` diff --git a/docs/src/content/docs/commands/ZRANK.md b/docs/src/content/docs/commands/ZRANK.md index 93a2e3e88..7831d2e24 100644 --- a/docs/src/content/docs/commands/ZRANK.md +++ b/docs/src/content/docs/commands/ZRANK.md @@ -11,19 +11,19 @@ ZRANK key member [WITHSCORE] ## Parameters -| Parameter | Description | Type | Required | -|-------------|-----------------------------------------------------------------------------|--------|----------| -| `key` | The key of the sorted set. | String | Yes | -| `member` | The member whose rank is to be determined. | String | Yes | -| `WITHSCORE` | If provided, the command will also return the score of the member. | String | No | +| Parameter | Description | Type | Required | +| ----------- | ------------------------------------------------------------------ | ------ | -------- | +| `key` | The key of the sorted set. | String | Yes | +| `member` | The member whose rank is to be determined. | String | Yes | +| `WITHSCORE` | If provided, the command will also return the score of the member. | String | No | ## Return values -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If member exists in the sorted set | Integer (rank of the member) | -| If `WITHSCORE` option is used | Array (rank and score of the member) | -| If member or key does not exist | `nil` | +| Condition | Return Value | +| ---------------------------------- | ------------------------------------ | +| If member exists in the sorted set | Integer (rank of the member) | +| If `WITHSCORE` option is used | Array (rank and score of the member) | +| If member or key does not exist | `nil` | ## Behaviour @@ -35,10 +35,12 @@ ZRANK key member [WITHSCORE] ## Errors 1. `Wrong type of value or key`: + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` - Occurs when the specified key exists but is not associated with a sorted set. 2. `Invalid syntax or number of arguments`: + - Error Message: `(error) ERR wrong number of arguments for 'zrank' command` - Occurs if the command is issued with an incorrect number of arguments. diff --git a/docs/src/content/docs/commands/ZREM.md b/docs/src/content/docs/commands/ZREM.md index 9621c1d02..1e6cbf2f6 100644 --- a/docs/src/content/docs/commands/ZREM.md +++ b/docs/src/content/docs/commands/ZREM.md @@ -7,25 +7,24 @@ The `ZREM` command in DiceDB is used to remove the specified members from the so ## Syntax -``` +```bash ZREM key member [member ...] ``` ## Parameters -| Parameter | Description | Type | Required | Multiple | -|-----------|----------------------------------------------------|--------|----------|----------| +| Parameter | Description | Type | Required | Multiple | +| --------- | ---------------------------------------------------------------------- | ------ | -------- | -------- | | `key` | The key associated with the sorted set whose members are to be removed | String | Yes | No | -| `member` | One or more members to remove from the sorted set | String | Yes | Yes | - +| `member` | One or more members to remove from the sorted set | String | Yes | Yes | ## Return Value -| Condition | Return Value | -|------------------------------------------------|---------------------------------------------------| -| If specified key and members exists | Count of members removed from the sorted set at key | -| If key doesn't exist | `0` | -| If member doesn't exist | `0` | +| Condition | Return Value | +| ----------------------------------- | --------------------------------------------------- | +| If specified key and members exists | Count of members removed from the sorted set at key | +| If key doesn't exist | `0` | +| If member doesn't exist | `0` | ## Behaviour @@ -46,41 +45,43 @@ ZREM key member [member ...] - Error Message: `(error) -ERR wrong number of arguments for 'ZREM' command` - Occurs if key or member isn't specified in the command. - ## Example Usage ### Basic Usage + Creating sorted set `myzset` with fields `one`, `two`, `three`, `four`, `five` with scores 1, 2, 3, 4, 5 respectively. Removing elements from `myzset`. -```DiceDB -> ZADD myzset 1 "one" 2 "two" 3 "three" 4 "four" 5 "five" +```bash +127.0.0.1:7379> ZADD myzset 1 "one" 2 "two" 3 "three" 4 "four" 5 "five" (integer) 5 -> ZREM myzset one +127.0.0.1:7379> ZREM myzset one (integer) 1 -> ZREM myzset two six +127.0.0.1:7379> ZREM myzset two six (integer) 1 -> ZREM myzset three four +127.0.0.1:7379> ZREM myzset three four (integer) 2 ``` ### Invalid Usage on non-existent sorted set + Removing element from a non-existent sorted set `nonExistentZSet`. -```DiceDB -> ZREM nonExistentZSet one +```bash +127.0.0.1:7379> ZREM nonExistentZSet one (integer) 0 ``` ### Invalid Usage on a non sorted set key + Getting cardinality of a key `mystring` associated with a non sorted set type. -```DiceDB -> SET mystring "This is a string" +```bash +127.0.0.1:7379> SET mystring "This is a string" OK -> ZREM mystring +127.0.0.1:7379> ZREM mystring (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` ## Notes -- The `ZREM` command is a O(M*log(N)) time-complexity operation, with N being the number of elements in the sorted set and M the number of elements to be removed. \ No newline at end of file +- The `ZREM` command is a O(M\*log(N)) time-complexity operation, with N being the number of elements in the sorted set and M the number of elements to be removed. diff --git a/docs/src/content/docs/get-started/installation.mdx b/docs/src/content/docs/get-started/installation.mdx index 805093d7f..47cb82145 100644 --- a/docs/src/content/docs/get-started/installation.mdx +++ b/docs/src/content/docs/get-started/installation.mdx @@ -5,7 +5,7 @@ sidebar: order: 1 --- -DiceDB is a redis-compliant, in-memory, real-time, and reactive database optimized for modern hardware and for building and scaling truly real-time applications. +DiceDB is a redis-compliant, in-memory, real-time, and reactive database optimized for modern hardware and for building and scaling truly real-time applications. We are looking for Early Design Partners, so, if you want to evaluate DiceDB, [block our calendar](https://cal.com/dicedb-arpit). always up for a chat. diff --git a/docs/src/content/docs/get-started/realtime-leaderboard.mdx b/docs/src/content/docs/get-started/realtime-leaderboard.mdx index 1d59c5d44..8faa7f5eb 100644 --- a/docs/src/content/docs/get-started/realtime-leaderboard.mdx +++ b/docs/src/content/docs/get-started/realtime-leaderboard.mdx @@ -49,20 +49,21 @@ Once the DiceDB server starts, you will see output similar to this ### Starting the application server 1. Clone the repository - ```bash - git clone https://github.com/arpitbbhayani/leaderboard-go-dicedb.git - cd leaderboard-go-dicedb - ``` + ```bash + git clone https://github.com/arpitbbhayani/leaderboard-go-dicedb.git + cd leaderboard-go-dicedb + ``` 2. Start the application - ```bash - go run main.go - ``` - This will start the application server on port 8080 by default, you should see output similar to - ```bash - 2024/10/25 00:05:59 Server starting on :8080 - ``` + ```bash + go run main.go + ``` + This will start the application server on port 8080 by default, you should see output similar to + ```bash + 2024/10/25 00:05:59 Server starting on :8080 + ``` ### Interacting with the application + 1. Navigate to the application server from your desired browser at http://localhost:8080. 2. Update player with their respective scores. 3. As more player with scores get added, we can see players getting ranked accordingly. @@ -99,104 +100,110 @@ This allows users to eradicate the need to continuously poll the server as updat ## Code overview 1. WebSocket Handling: The code uses WebSocket to push real-time updates to connected users. - ```go - func handleWebSocket(w http.ResponseWriter, r *http.Request) { - conn, err := upgrader.Upgrade(w, r, nil) - if err != nil { - log.Println(err) - return - } - connectedUsers = append(connectedUsers, conn) - } - ``` - - This function establishes a WebSocket connection with clients. All connected clients are stored in connectedUsers. - - Once connected, clients will receive real-time updates whenever there is a change in the leaderboard. + ```go + func handleWebSocket(w http.ResponseWriter, r *http.Request) { + conn, err := upgrader.Upgrade(w, r, nil) + if err != nil { + log.Println(err) + return + } + + connectedUsers = append(connectedUsers, conn) + } + ``` + + - This function establishes a WebSocket connection with clients. All connected clients are stored in connectedUsers. + - Once connected, clients will receive real-time updates whenever there is a change in the leaderboard. 2. Score Updates: The `handleUpdate` function processes incoming HTTP requests to update player scores. - ```go - func handleUpdate(w http.ResponseWriter, r *http.Request) { - var score Score - if err := json.NewDecoder(r.Body).Decode(&score); err != nil { - http.Error(w, err.Error(), http.StatusBadRequest) - return - } - - // ZADD command to add player with scores to leaderboard - err := client.ZAdd(r.Context(), "leaderboard", dicedb.Z{ - Score: float64(score.Score), - Member: score.Name, - }).Err() - - if err != nil { - http.Error(w, err.Error(), http.StatusInternalServerError) - return - } - - w.WriteHeader(http.StatusOK) - } - ``` - - This function receives a JSON payload with a player's name and score, and then updates the leaderboard using `ZADD` command. - - If the player already exists, their score is updated. Otherwise, a new player is added to the leaderboard. -3. Watch Loop: This is where the magic happens. The `watchLoop` function listens for updates from DiceDB and pushes them to all connected clients. - ```go - func watchLoop() { - ctx := context.Background() - - // Established watch connection with DiceDB using WatchConn. - watchConn = client.WatchConn(ctx) - if watchConn == nil { - log.Fatal("failed to create watch connection") + ```go + func handleUpdate(w http.ResponseWriter, r *http.Request) { + var score Score + if err := json.NewDecoder(r.Body).Decode(&score); err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) return } - // ZRANGEWATCH Command to subscribe to updates from DiceDB. Arguments are as follows: - // ctx: context object for the request. - // "leaderboard": The name of the key set to be watched. - // "0": The starting index of the watch range. - // "5": The ending index of the range. This tells the watch command to monitor up to the 5th element in the leaderboard. - // "REV": Specifies that the result should be in descending order of scores. - // "WITHSCORES": Ensures that both the player name and score are returned in the response. - res, err := watchConn.ZRangeWatch(ctx, "leaderboard", "0", "5", "REV", "WITHSCORES") + // ZADD command to add player with scores to leaderboard + err := client.ZAdd(r.Context(), "leaderboard", dicedb.Z{ + Score: float64(score.Score), + Member: score.Name, + }).Err() + if err != nil { - log.Println("failed to create watch connection:", err) + http.Error(w, err.Error(), http.StatusInternalServerError) return } - watchTopics[res.Fingerprint] = "global_leaderboard" - - watchCh = watchConn.Channel() - - // Loop over channel to listen for updates from DiceDB - for { - select { - case msg := <-watchCh: - switch watchTopics[msg.Fingerprint] { - case "global_leaderboard": - var scores []Score - for _, z := range msg.Data.([]dicedb.Z) { - scores = append(scores, Score{ - Name: z.Member.(string), - Score: int(z.Score), - }) - } - - // Loop over connected users to send the score updates - for _, conn := range connectedUsers { - if err := conn.WriteJSON(scores); err != nil { - log.Println("websocket write error:", err) - } - } - } - case <-ctx.Done(): - return - } - } - } - ``` - - Watch Connection: A Watch Connection is established with DiceDB using WatchConn. - - `ZRANGEWATCH`: This command watches the top 5 scores of the leaderboard. - - Real-Time Updates: Whenever there's a change in the leaderboard, the watch channel(`watchCh`) receives an update, which is then broadcast to all connected clients via WebSocket. + + w.WriteHeader(http.StatusOK) + } + ``` + + - This function receives a JSON payload with a player's name and score, and then updates the leaderboard using `ZADD` command. + - If the player already exists, their score is updated. Otherwise, a new player is added to the leaderboard. + +3. Watch Loop: This is where the magic happens. The `watchLoop` function listens for updates from DiceDB and pushes them to all connected clients. + + ```go + func watchLoop() { + ctx := context.Background() + + // Established watch connection with DiceDB using WatchConn. + watchConn = client.WatchConn(ctx) + if watchConn == nil { + log.Fatal("failed to create watch connection") + return + } + + // ZRANGEWATCH Command to subscribe to updates from DiceDB. Arguments are as follows: + // ctx: context object for the request. + // "leaderboard": The name of the key set to be watched. + // "0": The starting index of the watch range. + // "5": The ending index of the range. This tells the watch command to monitor up to the 5th element in the leaderboard. + // "REV": Specifies that the result should be in descending order of scores. + // "WITHSCORES": Ensures that both the player name and score are returned in the response. + res, err := watchConn.ZRangeWatch(ctx, "leaderboard", "0", "5", "REV", "WITHSCORES") + if err != nil { + log.Println("failed to create watch connection:", err) + return + } + watchTopics[res.Fingerprint] = "global_leaderboard" + + watchCh = watchConn.Channel() + + // Loop over channel to listen for updates from DiceDB + for { + select { + case msg := <-watchCh: + switch watchTopics[msg.Fingerprint] { + case "global_leaderboard": + var scores []Score + for _, z := range msg.Data.([]dicedb.Z) { + scores = append(scores, Score{ + Name: z.Member.(string), + Score: int(z.Score), + }) + } + + // Loop over connected users to send the score updates + for _, conn := range connectedUsers { + if err := conn.WriteJSON(scores); err != nil { + log.Println("websocket write error:", err) + } + } + } + case <-ctx.Done(): + return + } + } + } + ``` + + - Watch Connection: A Watch Connection is established with DiceDB using WatchConn. + - `ZRANGEWATCH`: This command watches the top 5 scores of the leaderboard. + - Real-Time Updates: Whenever there's a change in the leaderboard, the watch channel(`watchCh`) receives an update, which is then broadcast to all connected clients via WebSocket. ## Conclusion diff --git a/docs/src/content/docs/protocols/http.mdx b/docs/src/content/docs/protocols/http.mdx index 08d690399..07b16777e 100644 --- a/docs/src/content/docs/protocols/http.mdx +++ b/docs/src/content/docs/protocols/http.mdx @@ -1,11 +1,11 @@ ---- +--- title: HTTP description: DiceDB supports HTTP protocol for clients to connect to the database. This document explains the request and response format. sidebar: order: 1 --- -import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { Tabs, TabItem } from "@astrojs/starlight/components"; ## Table of Contents @@ -21,7 +21,6 @@ DiceDB supports HTTP protocol for clients to connect to the database. This allow All commands except `QWATCH` are synchronous and will return the result of the command immediately. For `QWATCH`, we use [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to be able to respond with changes to the result set of the queries. - ## API Endpoint All requests should be sent to the base URL of your server, followed by the command name: @@ -34,7 +33,7 @@ http://your-server-address:port/ - **HTTP Method**: POST for all operations - **Path**: The DiceDB command name (e.g., `/GET`, `/SET`, `/HGET`) -- **Headers**: +- **Headers**: - `Content-Type: application/json` - **Body**: JSON object containing command arguments @@ -55,6 +54,7 @@ Our HTTP API supports all DiceDB commands. Please refer to our comprehensive com ### Setting a Key-Value Pair **Request:** + ```http @@ -62,36 +62,39 @@ Our HTTP API supports all DiceDB commands. Please refer to our comprehensive com Host: your-server-address Content-Type: application/json - { - "key": "mykey", - "value": "Hello, World!" - } - ``` +{ +"key": "mykey", +"value": "Hello, World!" +} + +```` - - ```bash - curl --location 'http://your-server-address:PORT/SET' \ - --header 'Content-Type: application/json' \ - --data '{ - "key": "mykey", - "value": "Hello, World!" - }' - ``` + +```bash +curl --location 'http://your-server-address:PORT/SET' \ +--header 'Content-Type: application/json' \ +--data '{ + "key": "mykey", + "value": "Hello, World!" +}' +```` + - **Response:** + ```json { - "status": "success", - "data": "OK" + "status": "success", + "data": "OK" } ``` ### Getting a Value **Request:** + ```http @@ -99,34 +102,37 @@ Our HTTP API supports all DiceDB commands. Please refer to our comprehensive com Host: your-server-address Content-Type: application/json - { - "key": "mykey" - } - ``` +{ +"key": "mykey" +} + +```` - - ```bash - curl --location 'http://your-server-address:PORT/GET' \ - --header 'Content-Type: application/json' \ - --data '{ - "key": "mykey" - }' - ``` + +```bash +curl --location 'http://your-server-address:PORT/GET' \ +--header 'Content-Type: application/json' \ +--data '{ + "key": "mykey" +}' +```` + - **Response:** + ```json { - "status": "success", - "data": "Hello, World!" + "status": "success", + "data": "Hello, World!" } ``` ### Setting a field in Hash **Request:** + ```http @@ -135,11 +141,12 @@ Host: your-server-address Content-Type: application/json { - "key": "test", - "field": "test", - "value": "test" +"key": "test", +"field": "test", +"value": "test" } -``` + +```` ```bash @@ -150,22 +157,24 @@ Content-Type: application/json "field": "test", "value": "test" }' - ``` +```` + - **Response:** + ```json { - "status": "success", - "data": 1 + "status": "success", + "data": 1 } ``` ### Getting a field in a HashSet **Request:** + ```http @@ -174,10 +183,11 @@ Host: your-server-address Content-Type: application/json { - "key": "test", - "field": "test" +"key": "test", +"field": "test" } -``` + +```` ```bash @@ -187,15 +197,17 @@ curl --location 'http://your-server-address:PORT/HGET' \ "key": "test", "field": "test" }' -``` +```` + **Response:** + ```json { - "status": "success", - "data": "test" + "status": "success", + "data": "test" } ``` @@ -204,6 +216,7 @@ curl --location 'http://your-server-address:PORT/HGET' \ **NOTE**: The `QWATCH` command is asynchronous and requires the use of Server-Sent Events (SSE) to receive updates. The following example demonstrates how to use `QWATCH` with SSE. **Request:** + ```http @@ -212,9 +225,10 @@ Host: your-server-address Content-Type: application/json { - "query": "SELECT $key, $value WHERE $key like 'match:100:*' AND $value > 10 ORDER BY $value DESC LIMIT 3" +"query": "SELECT $key, $value WHERE $key like 'match:100:\*' AND $value > 10 ORDER BY $value DESC LIMIT 3" } -``` + +```` @@ -224,9 +238,7 @@ curl --location 'http://your-server-address:PORT/QWATCH' \ --data '{ "query": "SELECT $key, $value WHERE $key like '\''match:100:*'\'' AND $value > 10 ORDER BY $value DESC LIMIT 3" }' -``` +```` + - - - diff --git a/docs/src/content/docs/protocols/supported-protocols.mdx b/docs/src/content/docs/protocols/supported-protocols.mdx index f3ad6cfd2..5c951a461 100644 --- a/docs/src/content/docs/protocols/supported-protocols.mdx +++ b/docs/src/content/docs/protocols/supported-protocols.mdx @@ -1,4 +1,4 @@ ---- +--- title: Supported Protocols description: A guide on all the protocols that dice supports and all ways to connect to dice. sidebar: @@ -6,18 +6,18 @@ sidebar: --- DiceDB supports 3 ways to connect to the database: + 1. [TCP-RESP](#tcp-resp) 2. [HTTP](#http) 3. [WebSockets](#websockets) ## TCP-RESP -RESP is a standard protocol over TCP, developed by redis. This is the default mode of communication with dicedb and allows dice to be a drop-in replacement for Redis. +RESP is a standard protocol over TCP, developed by redis. This is the default mode of communication with dicedb and allows dice to be a drop-in replacement for Redis. - -| Name | Value | Configuration | -|-|-|-| -| Default Port | 7379 | `server.port` in config file | +| Name | Value | Configuration | +| ------------ | ----- | ---------------------------- | +| Default Port | 7379 | `server.port` in config file | To use Dice over TCP/RESP, you can use the official [DiceDB CLI](https://github.com/DiceDB/cli) or use any Redis CLI/SDKs for non-dice features. @@ -25,12 +25,11 @@ To use Dice over TCP/RESP, you can use the official [DiceDB CLI](https://github. Clients can also connect to DiceDB over HTTP. This allows clients to connect to dice over the web stack, enabling frontends to have direct access to dice. +| Name | Value | Configuration | +| ------------ | ----- | ------------------ | +| Default Port | 8082 | `--http-port` flag | -| Name | Value | Configuration | -|-|-|-| -| Default Port | 8082 | `--http-port` flag | - -For all commands except `QWATCH`, the HTTP API is synchronous and will return the result of the command immediately. +For all commands except `QWATCH`, the HTTP API is synchronous and will return the result of the command immediately. For [`QWATCH`](/commands/qwatch), we use [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to be able to respond with changes to the result set of the queries. @@ -43,21 +42,18 @@ To understand the request and response format better, please refer to the [HTTP - With small number of queries you want to `QWATCH`. - Integrate dice with other web services using HTTP Webhooks. - ### Limitations - `QWATCH` uses SSE or Server Sent Events, and current implementation of HTTP in DiceDB is based on HTTP 1.1. This means that there would be a limit to how many queries you can `QWATCH` at a time ([ref](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)). - `QWATCH` using SSE also implies that the connection is stateful and the client needs to handle reconnections in case of network failures. - ## WebSockets WebSockets protocol on DiceDB allows clients to connect to dice over a persistent websocket connection. This allows clients to connect to dice over the web while also being able to bypass the limitations of SSE. Websocket being a full-duplex protocol, allows clients to send and receive messages simultaneously. - -| Name | Value | Configuration | -|-|-|-| -| Default Port | 8379 | `--websocket-port` flag | +| Name | Value | Configuration | +| ------------ | ----- | ----------------------- | +| Default Port | 8379 | `--websocket-port` flag | To understand the request and response format better, please refer to the [WebSockets Protocol](/protocols/websockets) documentation. diff --git a/docs/src/content/docs/protocols/websockets.mdx b/docs/src/content/docs/protocols/websockets.mdx index 530a7bf75..ee2341901 100644 --- a/docs/src/content/docs/protocols/websockets.mdx +++ b/docs/src/content/docs/protocols/websockets.mdx @@ -1,13 +1,11 @@ ---- +--- title: WebSockets description: DiceDB supports WebSocket protocol for clients to connect to the database. This document explains the request and response format. sidebar: order: 2 --- -import { Tabs, TabItem } from '@astrojs/starlight/components'; - - +import { Tabs, TabItem } from "@astrojs/starlight/components"; ## Introduction @@ -16,11 +14,12 @@ DiceDB supports WebSocket for connecting to the database, allowing for real-time ## Connecting to the WebSocket Server To connect to the WebSocket server, use the following URL: + ``` ws://your-server-address:port/ ``` -Replace `your-server-address` and `port` with the appropriate values for your server. +Replace `your-server-address` and `port` with the appropriate values for your server. ## Message Format @@ -61,7 +60,7 @@ Here's a simple example of how to interact with the WebSocket server: ws.onopen = function() { console.log('Connected to WebSocket server'); - + // Set a key ws.send('SET mykey "Hello, WebSocket!"'); }; @@ -78,6 +77,7 @@ Here's a simple example of how to interact with the WebSocket server: console.log('WebSocket connection closed:', event.code, event.reason); }; ``` + @@ -90,5 +90,3 @@ Here's a simple example of how to interact with the WebSocket server: ``` - - diff --git a/docs/src/content/docs/sdk/Golang.mdx b/docs/src/content/docs/sdk/Golang.mdx index 47564e7f2..7f1c9eed6 100644 --- a/docs/src/content/docs/sdk/Golang.mdx +++ b/docs/src/content/docs/sdk/Golang.mdx @@ -76,6 +76,7 @@ result, err := watch.ZRangeWatch(ctx, "myset", "0", "-1", "REV", "WITHSCORES") Each watch command returns a `WatchResult` object containing the initial result of the watched command. #### WatchResult Structure + The `WatchResult` object contains the updated data along with the command being watched and a unique fingerprint to identify the source of the update: ```go @@ -89,6 +90,7 @@ type WatchResult struct { The `Data` field contains the result of the watched command, and can be type-asserted based on the command being watched. For example, the `Data` field for: + 1. `ZRANGE.WATCH` command will be of type `[]dicedb.Z`. 2. `GET.WATCH` command will be of type `string`. @@ -102,14 +104,15 @@ for msg := range ch { // Process msg.Data based on msg.Command } ``` + Note: The `Channel` method must be called after the initial watch command has been executed. Channel configuration options: + - `WithWChannelSize(size int)`: Set channel buffer size (default: 100) - `WithWChannelHealthCheckInterval(d time.Duration)`: Set health check interval (default: 3s) - `WithWChannelSendTimeout(d time.Duration)`: Set message send timeout (default: 60s) - ### Watching a Sorted Set ```go diff --git a/docs/src/data/benchmarks.md b/docs/src/data/benchmarks.md index a30fd40fe..58c54b6f3 100644 --- a/docs/src/data/benchmarks.md +++ b/docs/src/data/benchmarks.md @@ -1,12 +1,14 @@ # Benchmarks on Performance and Scalability -> Last updated: 10th October, 2024 +> Last updated: 4th November, 2024 -Benchmarks play a pivotal role in the world of databases. They provide measurable insights into how a system performs under different conditions, helping developers and system administrators optimize configurations, identify bottlenecks, and predict behavior under stress. For DiceDB, a high-performance in-memory key-value store, benchmarking is crucial to demonstrate its scalability, resilience, and efficiency. This article will provide the latest numbers of our benchmark and will provide the exact steps to be taken to reproduce the numbers. +Benchmarks play a pivotal role in the world of databases. They provide measurable insights into how a system performs under different conditions, helping developers optimize configurations, identify bottlenecks, and predict behavior under stress. -Redis, created over a decade ago, relies on a basic single-threaded architecture, which can make scaling deployments a challenging and time-consuming task for developers. In contrast, DiceDB offers a seamless alternative to Redis. As a modern in-memory database, DiceDB builds on the strengths of earlier systems but enhances both performance and reliability. With its multi-threaded design, DiceDB supports efficient vertical scaling, allowing you to sidestep the complexities of horizontal scaling and cluster management, all while achieving the scalability your application requires. +For DiceDB, a high-performance in-memory key-value store, benchmarking is crucial to demonstrate its scalability, resilience, and efficiency. Here's our latest benchmark that will demonstrate our numbers, compare them with Redis, and more importantly provide the exact steps to be taken to reproduce the numbers. -Because DiceDB is a drop-in replacement of Redis, we can run the standard [Memtier](https://github.com/RedisLabs/memtier_benchmark) benchmark to compare the two. +Redis, created over a decade ago, relies on a basic single-threaded architecture, which can make scaling deployments a challenging and time-consuming task for developers. In contrast, DiceDB offers a seamless alternative to Redis. As a modern in-memory database, DiceDB builds on the strengths of earlier systems but enhances both performance and reliability. + +With its multi-threaded design, DiceDB supports efficient vertical scaling, allowing you to sidestep the complexities of horizontal scaling and cluster management, all while achieving the scalability your application requires. Because DiceDB is a drop-in replacement of Redis, we can run the standard [Memtier](https://github.com/RedisLabs/memtier_benchmark) benchmark to compare the two. ## Memtier Benchmark @@ -15,10 +17,16 @@ Because DiceDB is a drop-in replacement of Redis, we can run the standard [Memti ### Machine configuration The benchmarks were run on [AWS c5.12xlarge](https://aws.amazon.com/ec2/instance-types/c5/) instance -which has 48 vCPUs, 96 GB memory, and 12 Gbps network bandwidth. The benchmarks were run on an Ubuntu machine and on the latest commit on the `master` branch of [DiceDB](https://github.com/dicedb/dice). +which has 48 vCPUs, 96 GB memory, and 12 Gbps network bandwidth. The benchmarks were run on an Ubuntu machine and the latest commit was on the `master` branch of [DiceDB](https://github.com/dicedb/dice). + +### Infrastructure Setup + +Take two AWS c5.12xlarge machines, one machine to run meatier while the other to run DiceDB. ## DiceDB Benchmark +On the machine that is designated to run DiceDB, fire the following commands to build and run DiceDB. + ```sh $ go build -o dicedb $ ./dicedb --enable-multithreading=true @@ -26,17 +34,19 @@ $ ./dicedb --enable-multithreading=true ### Running the benchmark +On the machine that is designated to run memtier, fire the following commands to start the benchmark. + ```sh -$ memtier_benchmark -s 54.167.62.216 -p 7379 \ - --clients 50 --threads 24 \ - --ratio=1:1 --hide-histogram \ - --data-size 256 --requests=100000 +$ memtier_benchmark -s 54.204.230.210 -p 7379 \ + --clients 50 --threads 24 \ +    --ratio=1:1 --hide-histogram \ + --data-size 256 --requests=100000 ``` This command runs a benchmark where, - we execute benchmark using 24 threads to distribute the workload -- each thread will setup 50 clients and send requests concurrently +- each thread will set 50 clients and send requests concurrently - the benchmark consists of a balanced mix of GET and SET operations (1:1 ratio) - each request will involve 256 bytes of data, simulating small-to-medium-sized transactions - a total of 100,000 requests will be executed, and the benchmark will run until all requests are completed. @@ -46,98 +56,105 @@ This command runs a benchmark where, After running the above command on DiceDB we got the following numbers. ``` -[RUN #1 100%, 199 secs] 0 threads: 120000000 ops, 2059627 (avg: 601850) ops/sec, 338.97MB/sec (avg: 98.86MB/sec), 0.58 (avg: 1.99) msec latency +[RUN #1] Preparing benchmark client... +[RUN #1] Launching threads now... +[RUN #1 100%, 223 secs]  0 threads:   120000000 ops, 1940109 (avg:  536901) ops/sec, 319.22MB/sec (avg: 88.20MB/sec),  0.62 (avg:  2.23) msec latency + +24        Threads +50        Connections per thread +100000    Requests per client -24 Threads -50 Connections per thread -100000 Requests per client +ALL STATS ============================================================================================================================ -Type Ops/sec Hits/sec Misses/sec Avg. Latency p50 Latency p99 Latency p99.9 Latency KB/sec +Type         Ops/sec     Hits/sec   Misses/sec    Avg. Latency     p50 Latency     p99 Latency   p99.9 Latency       KB/sec ---------------------------------------------------------------------------------------------------------------------------- -Sets 310539.18 --- --- 2.04382 1.67100 8.95900 18.17500 92156.88 -Gets 310539.18 0.00 310539.18 1.94245 1.55100 8.83100 17.79100 12309.13 -Waits 0.00 --- --- --- --- --- --- --- -Totals 621078.36 0.00 310539.18 1.99313 1.61500 8.89500 17.91900 104466.01 +Sets       275447.56          ---          ---         2.26364         1.35100         8.95900        13.63100     81742.94 +Gets       275447.56         0.00    275447.56         2.20482         1.31900         8.76700        13.37500     10925.92 +Waits           0.00          ---          ---             ---             ---             ---             ---          --- +Totals     550895.11         0.00    275447.56         2.23423         1.33500         8.83100        13.50300     92668.87 ``` The benchmark run tested DiceDB with 24 threads, 50 client connections per thread, and 100,000 requests per client which turns out to be 120,000,000 operations in total. Below is a breakdown of the key metrics and their significance: -- the peak throughput DiceDB can handle is 2,059,627 ops/sec -- the average throughput was 621,078 ops/sec, evenly split between GETs and SETs +- the peak throughput DiceDB can handle is 1,940,109 ops/sec +- the average throughput was 536,901 ops/sec, evenly split between GETs and SETs - the average latency for the overall benchmark was 1.99 milliseconds, pretty fast. - - p50 latency was 1.61 ms - - p99 latency was 8.89 ms, indicating that 99% of requests were faster than this. - - p99.9 latency reached 17.91 ms, showing how the highest-latency outliers behaved. +   - p50 latency was 1.33 ms +   - p99 latency was 8.83 ms, indicating that 99% of requests were faster than this. +   - p99.9 latency reached 13.50 ms, showing how the highest-latency outliers behaved. ## Redis Benchmark +Now, you can stop the DiceDB process setup Redis, and run the server on port 6379. + ```sh -$ go build -o dicedb -$ ./dicedb --enable-multithreading=true +$ ./redis-server ``` ### Running the benchmark ```sh -$ memtier_benchmark -s 54.167.62.216 -p 6379 \ - --clients 50 --threads 24 \ - --ratio=1:1 --hide-histogram \ - --data-size 256 --requests=100000 +$ memtier_benchmark -s 3.82.51.57 -p 6379 \ + --clients 50 --threads 24 \ +    --ratio=1:1 --hide-histogram \ + --data-size 256 --requests=100000 ``` -This command runs a benchmark where, - -- we execute benchmark using 24 threads to distribute the workload -- each thread will setup 50 clients and send requests concurrently -- the benchmark consists of a balanced mix of GET and SET operations (1:1 ratio) -- each request will involve 256 bytes of data, simulating small-to-medium-sized transactions -- a total of 100,000 requests will be executed, and the benchmark will run until all requests are completed. - ### Results Observed After running the above command on Redis we got the following numbers. ``` -[RUN #1 100%, 594 secs] 0 threads: 120000000 ops, 201550 (avg: 201774) ops/sec, 33.33MB/sec (avg: 33.20MB/sec), 5.95 (avg: 5.94) msec latency +[RUN #1] Preparing benchmark client... +[RUN #1] Launching threads now... +[RUN #1 100%, 623 secs]  0 threads:   120000000 ops,  202925 (avg:  192485) ops/sec, 33.44MB/sec (avg: 31.67MB/sec),  5.91 (avg:  6.23) msec latency -24 Threads -50 Connections per thread -100000 Requests per client +24        Threads +50        Connections per thread +100000    Requests per client ALL STATS ============================================================================================================================ -Type Ops/sec Hits/sec Misses/sec Avg. Latency p50 Latency p99 Latency p99.9 Latency KB/sec +Type         Ops/sec     Hits/sec   Misses/sec    Avg. Latency     p50 Latency     p99 Latency   p99.9 Latency       KB/sec ---------------------------------------------------------------------------------------------------------------------------- -Sets 100842.84 --- --- 5.94669 5.40700 10.62300 13.56700 29926.53 -Gets 100842.84 516.32 100326.53 5.94390 5.40700 10.62300 13.56700 4058.81 -Waits 0.00 --- --- --- --- --- --- --- -Totals 201685.69 516.32 100326.53 5.94529 5.40700 10.62300 13.56700 33985.35 +Sets        96224.94          ---          ---         6.23382         5.69500        11.26300        14.01500     28556.11 +Gets        96224.94       492.67     95732.27         6.23054         5.69500        11.26300        13.95100      3872.95 +Waits           0.00          ---          ---             ---             ---             ---             ---          --- +Totals     192449.89       492.67     95732.27         6.23218         5.69500        11.26300        14.01500     32429.05 ``` The benchmark run tested Redis with 24 threads, 50 client connections per thread, and 100,000 requests per client which turns out to be 120,000,000 operations in total. Below is a breakdown of the key metrics and their significance: -- the peak throughput Redis can handle is 201,550 ops/sec -- the average throughput was 201,774 ops/sec, evenly split between GETs and SETs +- the peak throughput Redis can handle is 202,925 ops/sec +- the average throughput was 192,485 ops/sec, evenly split between GETs and SETs - the average latency for the overall benchmark was 1.99 milliseconds, pretty fast. - - p50 latency was 5.94 ms - - p99 latency was 10.62 ms, indicating that 99% of requests were faster than this. - - p99.9 latency reached 13.56 ms, showing how the highest-latency outliers behaved. +   - p50 latency was 5.69 ms +   - p99 latency was 11.26 ms, indicating that 99% of requests were faster than this. +   - p99.9 latency reached 14.01 ms, showing how the highest-latency outliers behaved. ## DiceDB vs Redis -| Metric | DiceDB | Redis | -|---------------------------|-----------------------------------|-----------------------------------| -| Peak Throughput (ops/sec) | 2,059,627 | 201,550 | -| Average Throughput (ops/sec) | 621,078 | 201,774 | -| Average Latency (ms) | 1.99 | 1.99 | -| p50 Latency (ms) | 1.61 | 5.94 | -| p99 Latency (ms) | 8.89 | 10.62 | -| p99.9 Latency (ms) | 17.91 | 13.56 | +| Metric                 | DiceDB                       | Redis                         | +| ---------------------------- | --------------------------------- | --------------------------------- | +| Peak Throughput (ops/sec) | 1,940,109                     | 202,925                           | +| Average Throughput (ops/sec) | 536,901                     | 192,485                           | +| Average Latency (ms)   | 2.23                             | 6.23                             | +| p50 Latency (ms)       | 1.33                             | 5.69                             | +| p99 Latency (ms)       | 8.83                             | 11.26                             | +| p99.9 Latency (ms)     | 13.50                             | 14.01                             | + +The benchmark results demonstrate that DiceDB significantly outperforms Redis in terms of throughput. DiceDB's peak throughput is ~9 times higher than Redis, reaching **1,940,109 ops per second** compared to Redis' 202,925 ops/sec. Additionally, DiceDB's average throughput is also much higher, clocking in at **536,901 ops/sec**, while Redis achieves 192,485 ops/sec. This indicates that DiceDB can handle far more operations in a given period, making it a better choice for applications requiring high throughput, such as real-time or reactive systems. + +In terms of latency, DiceDB also offers better average latency at **2.23 milliseconds**. However, when analyzing the different latency percentiles, DiceDB performs better across the spectrum - average, p50, p99, and p99.9 latencies. + +### DiceDB vs Redis - number of cores + +If we run the above benchmark while altering the number of cores of the underlying hardware, we can see how DiceDB is optimized for scalability. Redis exhibits stable throughput across core counts, suggesting a limit to its ability to leverage additional processing power. By contrast, DiceDB's throughput increases as more cores are added, indicating that it dynamically scales with available hardware resources. -The benchmark results clearly demonstrate that DiceDB significantly outperforms Redis in terms of throughput. DiceDB's peak throughput is over 10 times higher than Redis, reaching **2,059,627 ops per second** compared to Redis' 201,550 ops/sec. Additionally, DiceDB's average throughput is also much higher, clocking in at **621,078 ops/sec**, while Redis achieves 201,774 ops/sec. This indicates that DiceDB can handle far more operations in a given period, making it a better choice for applications requiring high throughput, such as real-time or reactive systems. +This difference showcases DiceDB's design advantage in multi-core environments, where it effectively leverages all the underlying cores to offer maximum performance. This not only highlights DiceDB's potential for high-throughput applications but also its efficiency in using hardware resources to reduce latency and improve responsiveness. -In terms of latency, both databases show similar average latency at **1.99 milliseconds**. However, when analyzing the different latency percentiles, DiceDB performs better at p50 and p99 latencies, with faster response times than Redis, particularly at p50, where DiceDB achieves **1.61 ms** compared to Redis’ 5.94 ms. Interestingly, DiceDB has a higher p99.9 latency at 17.91 ms, indicating that although most requests are faster, it has some outliers with higher latency than Redis. +![DiceDB vs Redis - Throughput vs Number of Cores](https://github.com/user-attachments/assets/367f25c8-bc59-4787-bb37-63fd5d4314e4) Overall, DiceDB offers superior throughput and generally lower latency, making it a more robust solution for high-performance, low-latency applications, especially in cases where extreme latency outliers are less critical. diff --git a/docs/src/data/roadmap.md b/docs/src/data/roadmap.md new file mode 100644 index 000000000..7c0599eb2 --- /dev/null +++ b/docs/src/data/roadmap.md @@ -0,0 +1,10 @@ +# Roadmap + +- [ ] WAL - persistence and restoration +- [ ] 50% Redis compatability +- [ ] No downtime replica creation +- [ ] Replication lag of < 1 sec at peak +- [ ] Support for Namespaces +- [ ] Support for ACL + +> This is not an exhaustive list, Please refer to the [GitHub issues](https://github.com/DiceDB/dice/issues) to find the granular items that are being worked upon. diff --git a/docs/src/layouts/BlogLayout.astro b/docs/src/layouts/BlogLayout.astro index 95c7f8fc4..93e49be7d 100644 --- a/docs/src/layouts/BlogLayout.astro +++ b/docs/src/layouts/BlogLayout.astro @@ -53,7 +53,7 @@ const JSONLD = {

{blog.data.title} diff --git a/docs/src/layouts/Layout.astro b/docs/src/layouts/Layout.astro index 53710bafb..7cd83c4df 100644 --- a/docs/src/layouts/Layout.astro +++ b/docs/src/layouts/Layout.astro @@ -17,7 +17,7 @@ const { title, description, img, blog, session, video, JSONLD } = Astro.props;