diff --git a/.github/workflows/cve-scan.yml b/.github/workflows/cve-scan.yml new file mode 100644 index 000000000..72b67d994 --- /dev/null +++ b/.github/workflows/cve-scan.yml @@ -0,0 +1,21 @@ +name: Weekly Trivy Scan + +on: + schedule: + - cron: '0 0 * * 1' # Run every Monday at midnight + workflow_dispatch: + +jobs: + trivy_scan: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install Trivy + run: | + curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin v0.56.2 + + - name: Run Trivy scan + run: | + trivy fs --security-checks vuln . \ No newline at end of file diff --git a/.github/workflows/dockerhub.yml b/.github/workflows/dockerhub.yml index 1b0be560c..81c4c022d 100644 --- a/.github/workflows/dockerhub.yml +++ b/.github/workflows/dockerhub.yml @@ -17,6 +17,9 @@ jobs: - name: Check out the repo uses: actions/checkout@v4 + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Log in to Docker Hub uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a with: @@ -29,19 +32,21 @@ jobs: with: images: dicedb/dicedb - - name: Build and push Docker image + - name: Build and push Docker image (with cache) id: push - uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671 + uses: docker/build-push-action@v6 with: context: . file: ./Dockerfile push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} - + cache-from: type=gha # This tells Buildx to attempt to use the GitHub Actions cache + cache-to: type=gha,mode=max # This stores the generated cache in the GitHub Actions cache + - name: Generate artifact attestation uses: actions/attest-build-provenance@v1 with: subject-name: docker.io/dicedb/dicedb subject-digest: ${{ steps.push.outputs.digest }} - push-to-registry: true + push-to-registry: true \ No newline at end of file diff --git a/.github/workflows/full-test-suite.yml b/.github/workflows/full-test-suite.yml index 7007a4d7c..fe486d978 100644 --- a/.github/workflows/full-test-suite.yml +++ b/.github/workflows/full-test-suite.yml @@ -33,11 +33,19 @@ jobs: uses: actions/setup-go@v5 with: go-version: "1.23.x" + - name: Cache dependencies + uses: actions/cache@v3 + with: # Cache the Go modules + path: | + vendor/ + key: ${{ runner.os }}-go-${{ hashFiles('go.sum') }} + restore-keys: | + ${{ runner.os }}-go- - name: Install dependencies - run: go get . + run: go get -v . # Check if there is any version changes from the cache - name: Build run: make build - name: Run Unit tests run: make unittest - name: Run Integration tests - run: make test + run: make test \ No newline at end of file diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml index ce3c57abb..4e06d1e43 100644 --- a/.github/workflows/linter.yml +++ b/.github/workflows/linter.yml @@ -1,9 +1,15 @@ -name: linter +name: Linter + on: push: - branches: [ master ] + branches: [master] + paths: + - '*.go' + pull_request: - branches: [ master ] + branches: [master] + paths: + - '*.go' permissions: contents: read @@ -22,3 +28,4 @@ jobs: uses: golangci/golangci-lint-action@v6 with: version: v1.60.1 + \ No newline at end of file diff --git a/README.md b/README.md index ccd69c63c..80fec9258 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ DiceDB ![Docs](https://img.shields.io/badge/docs-00A1FF?style=flat-square) discord community -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, reactive, scalable, highly available, unified cache optimized for modern hardware. 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. @@ -32,7 +32,7 @@ Although DiceDB is a drop-in replacement of Redis, which means almost no learnin ## Get started -### Setting up DiceDB with Dockerc +### Setting up DiceDB with Docker The easiest way to get started with DiceDB is using [Docker](https://www.docker.com/) by running the following command. diff --git a/build_protos.sh b/build_protos.sh new file mode 100644 index 000000000..0a21e13f4 --- /dev/null +++ b/build_protos.sh @@ -0,0 +1 @@ +protoc --go_out=. ./internal/wal/wal.proto \ No newline at end of file diff --git a/config/config.go b/config/config.go index 9809c135f..e866aeab9 100644 --- a/config/config.go +++ b/config/config.go @@ -55,6 +55,11 @@ var ( EnableProfiling = false EnableWatch = true + LogDir = "" + + EnableWAL = true + RestoreFromWAL = false + WALEngine = "sqlite" ) type Config struct { 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..89e3468c3 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", @@ -36,16 +36,6 @@ export default defineConfig({ label: "Commands", autogenerate: { directory: "commands" }, }, - { - label: "Metrics", - items: [ - { - label: "Memtier Benchmark", - link: "https://dicedb.io/metrics/memtier.html", - attrs: { target: "_blank" }, - }, - ], - }, ], }), ], 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..3e0bf9fba 100644 --- a/docs/src/components/Footer.astro +++ b/docs/src/components/Footer.astro @@ -41,6 +41,12 @@ import { Github } from "lucide-astro"; > Developers +

+ Blog +

+

+ Releases +

Quickstart Commands

- + Examples

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

- + Real-time Leaderboard

@@ -88,9 +88,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..74ffb1fb1 100644 --- a/docs/src/components/Hero.astro +++ b/docs/src/components/Hero.astro @@ -4,31 +4,24 @@ 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, reactive, 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/components/RecentReleases.astro b/docs/src/components/RecentReleases.astro new file mode 100644 index 000000000..4829868f1 --- /dev/null +++ b/docs/src/components/RecentReleases.astro @@ -0,0 +1,27 @@ +--- +const { releases } = Astro.props; +--- + +
+
+
    + { + releases.map((release) => ( +
  • + + {release.data.published_at.toLocaleString("en-us", { + day: "2-digit", + month: "short", + year: "numeric", + })} + : + + + {release.data.title} + +
    • + )) + } +
+
+
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/config.ts b/docs/src/content/config.ts index 4c0a8310e..28a0c6e25 100644 --- a/docs/src/content/config.ts +++ b/docs/src/content/config.ts @@ -21,8 +21,19 @@ const authors = defineCollection({ }), }); +const releases = defineCollection({ + type: "content", + schema: z.object({ + title: z.string(), + description: z.string(), + published_at: z.coerce.date(), + author: reference("authors"), + }), +}); + export const collections = { blog, authors, + releases, docs: defineCollection({ schema: docsSchema() }), }; 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 0fe23ea73..537141c2a 100644 --- a/docs/src/content/docs/commands/AUTH.md +++ b/docs/src/content/docs/commands/AUTH.md @@ -13,16 +13,16 @@ 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 c2711100b..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,13 +36,13 @@ 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 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 4a7f2e6a8..ba6af7dc9 100644 --- a/docs/src/content/docs/commands/BGREWRITEAOF.md +++ b/docs/src/content/docs/commands/BGREWRITEAOF.md @@ -13,10 +13,10 @@ 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,6 +42,7 @@ When the `BGREWRITEAOF` command is issued, DiceDB performs the following steps: ## Example Usage ### Basic Usage + ```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 fb6fb93d6..cd65f6beb 100644 --- a/docs/src/content/docs/commands/BITCOUNT.md +++ b/docs/src/content/docs/commands/BITCOUNT.md @@ -14,27 +14,26 @@ 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/BITFIELD.md b/docs/src/content/docs/commands/BITFIELD.md new file mode 100644 index 000000000..1318f9617 --- /dev/null +++ b/docs/src/content/docs/commands/BITFIELD.md @@ -0,0 +1,157 @@ +--- +title: BITFIELD +description: The BITFIELD command in DiceDB performs complex bitwise operations on string values at specified offsets, treating them as an array of integers. It allows manipulation of individual bits or groups of bits, supporting commands like SET, GET, and INCRBY to update or retrieve bitfield values. +--- + +## Syntax + +```bash +BITFIELD key [GET type offset | [OVERFLOW ] + + [GET type offset | [OVERFLOW ] + + ...]] +``` + +## Parameters + +| Parameter | Description |Type |Required| +|--------------------|----------------------------------------------------------------------------------------------------------------------------|------|--------| +| `key` | The name of the key containing the bitfield. |String|Yes | +| `GET type offset` | Retrieves bits starting at the specified offset with the specified type. Type defines the signed/unsigned integer format. |String|Optional| +| `SET type offset value`| Sets bits at the specified offset to the given value using the specified integer type. |String|Optional| +| `INCRBY type offset increment`| Increments bits at the specified offset by the increment value and wraps around on overflow based on type. |String|Optional| +| `OVERFLOW WRAP\|SAT\|FAIL` | Defines overflow behavior. |String|Optional| + +## Return values + +| Condition | Return Value | +|----------------------------------------------------------------|-------------------------------------------------------| +| Command is successful | Array of results corresponding to each subcommand | +| Syntax or specified constraints are invalid | error | + +## Behaviour +The BITFIELD command in DiceDB allows for direct bitwise manipulation within a binary string stored in a single key. It works by treating the string as an array of integers and performs operations on specific bits or groups of bits at specified offsets: +- SET: Sets the value of bits at a specific offset. +- GET: Retrieves the value of bits at a specific offset. +- INCRBY: Increments the value at a specific offset by a given amount, useful for counters. +- OVERFLOW: Defines the overflow behavior (WRAP, SAT, FAIL) for INCRBY, determining how to handle values that exceed the bitfield’s limits. + +#### Overflow Options: +- WRAP: Cycles values back to zero on overflow (default behavior). +- SAT: Saturates to the maximum or minimum value for the bit width. +- FAIL: Prevents overflow by causing INCRBY to fail if it would exceed the limits. +
+
+- Supports unsigned (u) with bit widths between 1 and 63 and signed (i) integers with bit widths between 1 and 64. +- The offset specifies where the bitfield starts within the key’s binary string. +- If an offset is out of range (far beyond the current size), DiceDB will automatically expand the binary string to accommodate it, which can impact memory usage. + +## Errors + +1. `Syntax Error`: + - Error Message: `(error) ERR syntax error` + - Occurs if the commands syntax is incorrect. + +2. `Invalid bitfield type`: + - Error Message: `(error) ERR Invalid bitfield type. Use something like i16 u8. Note that u64 is not supported but i64 is` + - Occurs when attempting to use the command on a wrong type. + +3. `Non-integer value`: + - Error Message: `(error) ERR value is not an integer or out of range` + - Occurs when attempting to use the command on a value that contains a non-integer value. + +4. `Invalid OVERLOW type`: + - Error Message: `(error) ERR Invalid OVERFLOW type specified` + - Occurs when attempting to use a wrong OVERFLOW type. + +5. `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. + +6. `Invalid bIT offset`: + - Error Message: `(error) ERR bit offset is not an integer or out of range` + - Occurs when attempting to use the command with an invalid bit offset. + + +## Example Usage + +### Basic Usage: + +```bash +127.0.0.1:7379> BITFIELD mykey INCRBY i5 100 1 GET u4 0 +1) "1" +2) "0" +``` +### Overflow control: +```bash +127.0.0.1:7379> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1 +1) "1" +2) "1" +127.0.0.1:7379> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1 +1) "2" +2) "2" +127.0.0.1:7379> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1 +1) "3" +2) "3" +127.0.0.1:7379> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1 +1) "0" +2) "3" +``` +### Example of OVERFLOW FAIL returning nil: +```bash +127.0.0.1:7379> BITFIELD mykey OVERFLOW FAIL incrby u2 102 1 +(nil) +``` + +### Invalid usage: + +```bash +127.0.0.1:7379> BITFIELD +(error) ERR wrong number of arguments for 'bitfield' command +``` + +```bash +127.0.0.1:7379> SADD bits a b c +(integer) 3 +127.0.0.1:7379> BITFIELD bits +(error) ERR WRONGTYPE Operation against a key holding the wrong kind of value +``` + +```bash +127.0.0.1:7379> BITFIELD bits SET u8 0 255 INCRBY u8 0 100 GET u8 +(error) ERR syntax error +``` + +```bash +127.0.0.1:7379> bitfield bits set a8 0 255 incrby u8 0 100 get u8 +(error) ERR Invalid bitfield type. Use something like i16 u8. Note that u64 is not supported but i64 is +``` + +```bash +127.0.0.1:7379> bitfield bits set u8 a 255 incrby u8 0 100 get u8 +(error) ERR bit offset is not an integer or out of range +``` + +```bash +127.0.0.1:7379> bitfield bits set u8 0 255 incrby u8 0 100 overflow wraap +(error) ERR Invalid OVERFLOW type specified +``` + +```bash +127.0.0.1:7379> bitfield bits set u8 0 incrby u8 0 100 get u8 288 +(error) ERR value is not an integer or out of range +``` + + +## Notes +Where an integer encoding is expected, it can be composed by prefixing with i for signed integers and u for unsigned integers with the number of bits of our integer encoding. So for example u8 is an unsigned integer of 8 bits and i16 is a signed integer of 16 bits. + +The supported encodings are up to 64 bits for signed integers, and up to 63 bits for unsigned integers. This limitation with unsigned integers is due to the fact that currently RESP is unable to return 64 bit unsigned integers as replies. + +## Subcommands +- **subcommand**: Optional. Available subcommands include: + - `GET` `` `` : Returns the specified bit field. + - `SET` `` `` `` : Set the specified bit field and - returns its old value. + - `INCRBY` `` `` `` : Increments or decrements (if a negative increment is given) the specified bit field and returns the new value. + - `OVERFLOW` [ `WRAP` | `SAT` | `FAIL` ] diff --git a/docs/src/content/docs/commands/BITFIELD_RO.md b/docs/src/content/docs/commands/BITFIELD_RO.md new file mode 100644 index 000000000..fc5a1dc0e --- /dev/null +++ b/docs/src/content/docs/commands/BITFIELD_RO.md @@ -0,0 +1,41 @@ +--- +title: BITFIELD_RO +description: Read-only variant of the BITFIELD command. It is like the original BITFIELD but only accepts GET subcommand. +--- + +## Syntax + +```bash +BITFIELD_RO key [GET type offset [GET type offset ...]] +``` + +## Parameters + +| Parameter | Description |Type |Required| +|-----------|-------------------------------------------------------------------------------------------------------------------------------------|------|--------| +| `key` | The name of the key containing the bitfield. |String|Yes | +| `GET type offset` | Retrieves bits starting at the specified offset with the specified type. Type defines the signed/unsigned integer format. |String|Optional| + + + +## Return values + +| Condition | Return Value | +|----------------------------------------------------------------|-------------------------------------------------------| +| Command is successful | Array of results corresponding to each `GET` command | +| Syntax or specified constraints are invalid | error | + +## Behaviour + +- Read-only variant of the BITFIELD command. It is like the original BITFIELD but only accepts GET subcommand. +- See original BITFIELD for more details. + +## Example Usage +### Basic Usage + +```bash +127.0.0.1:7379> SET hello "Hello World" +OK +127.0.0.1:7379> BITFIELD_RO hello GET i8 16 +1) "108" +``` diff --git a/docs/src/content/docs/commands/BITOP.md b/docs/src/content/docs/commands/BITOP.md index 239efeb3e..cae554c3d 100644 --- a/docs/src/content/docs/commands/BITOP.md +++ b/docs/src/content/docs/commands/BITOP.md @@ -12,14 +12,15 @@ BITOP operation destkey key [key ...] ``` ## Parameters +| Parameter | Description | Type | Required | +|-------------------|--------------------------------------------------------------------------------|--------------|----------| +| `AND` | Perform a bitwise AND operation. | Operation | Yes | +| `OR` | Perform a bitwise OR operation. | Operation | Yes | +| `XOR` | Perform a bitwise XOR operation. | Operation | Yes | +| `NOT` | Perform a bitwise NOT operation (only one key is allowed for this operation). | Operation | Yes | +| `destkey` | The key where the result of the bitwise operation will be stored. | String | Yes | +| `key [key ...]` | One or more keys containing the strings to be used in the bitwise operation. For the `NOT` operation, only one key is allowed.| String | Yes | -- `operation`: The bitwise operation to perform. It can be one of the following: - - `AND`: Perform a bitwise AND operation. - - `OR`: Perform a bitwise OR operation. - - `XOR`: Perform a bitwise XOR operation. - - `NOT`: Perform a bitwise NOT operation (only one key is allowed for this operation). -- `destkey`: The key where the result of the bitwise operation will be stored. -- `key [key ...]`: One or more keys containing the strings to be used in the bitwise operation. For the `NOT` operation, only one key is allowed. ## Return Value @@ -61,10 +62,14 @@ The `BITOP` command can raise errors in the following cases: ### Example 1: Bitwise AND Operation ```bash -SET key1 "foo" -SET key2 "bar" -BITOP AND result key1 key2 -GET result +127.0.0.1:7379> SET key1 "foo" +OK +127.0.0.1:7379> SET key2 "bar" +OK +127.0.0.1:7379> BITOP AND result key1 key2 +(integer) 3 +127.0.0.1:7379> GET result +"bab" ``` `Explanation`: @@ -77,10 +82,14 @@ GET result ### Example 2: Bitwise OR Operation ```bash -SET key1 "foo" -SET key2 "bar" -BITOP OR result key1 key2 -GET result +127.0.0.1:7379> SET key1 "foo" +OK +127.0.0.1:7379> SET key2 "bar" +OK +127.0.0.1:7379> BITOP OR result key1 key2 +(integer) 3 +127.0.0.1:7379> GET result +"fo\x7f" ``` `Explanation`: @@ -93,10 +102,14 @@ GET result ### Example 3: Bitwise XOR Operation ```bash -SET key1 "foo" -SET key2 "bar" -BITOP XOR result key1 key2 -GET result +127.0.0.1:7379> SET key1 "foo" +OK +127.0.0.1:7379> SET key2 "bar" +OK +127.0.0.1:7379> BITOP XOR result key1 key2 +(integer) 3 +127.0.0.1:7379> GET result +"\x04\x0e\x1d" ``` `Explanation`: @@ -109,9 +122,12 @@ GET result ### Example 4: Bitwise NOT Operation ```bash -SET key1 "foo" -BITOP NOT result key1 -GET result +127.0.0.1:7379> SET key1 "foo" +OK +127.0.0.1:7379> BITOP NOT result key1 +(integer) 3 +127.0.0.1:7379> GET result +"\x99\x90\x90" ``` `Explanation`: diff --git a/docs/src/content/docs/commands/BITPOS.md b/docs/src/content/docs/commands/BITPOS.md index 9fb738997..4aa0e4a28 100644 --- a/docs/src/content/docs/commands/BITPOS.md +++ b/docs/src/content/docs/commands/BITPOS.md @@ -13,15 +13,20 @@ BITPOS key bit [start] [end] ## Parameters -- `key`: The key of the string in which to search for the bit. -- `bit`: The bit value to search for, which can be either 0 or 1. -- `start`: (Optional) The starting byte position to begin the search. If not specified, the search starts from the beginning of the string. -- `end`: (Optional) The ending byte position to end the search. If not specified, the search continues until the end of the string. +| Parameter | Description | Type | Required | +|-----------|--------------------------------------------------------------------------------------------------------------------------------------|----------|----------| +| `key` | The key of the string in which to search for the bit. | String | Yes | +| `bit` | The value to be set for the key. | Bit | Yes | +| `start` | (Optional) The starting byte position to begin the search. If not specified, the search starts from the beginning of the string. | Integer | No | +| `end` | (Optional) The ending byte position to end the search. If not specified, the search continues until the end of the string. | Integer | No | ## Return Value -- `Integer`: The position of the first bit set to the specified value (0 or 1). The position is returned as a zero-based integer. -- `-1`: If the specified bit is not found within the specified range. +| Condition | Return Value | +|----------------------------------------------------------------|-------------------------| +| Command is successful | `Integer` | +| If the specified bit is not found within the specified range. | `-1` | +| Syntax or specified constraints are invalid | error | ## Behaviour @@ -50,14 +55,10 @@ 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`: ```bash -SET mykey "foobar" -BITPOS mykey 1 -``` - -`Output`: - -```bash -6 +127.0.0.1:7379> SET mykey "foobar" +OK +127.0.0.1:7379> BITPOS mykey 1 +(integer) 1 ``` ### Specifying a Range @@ -65,29 +66,20 @@ 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: ```bash -SET mykey "foobar" -BITPOS mykey 0 2 4 +127.0.0.1:7379> SET mykey "foobar" +OK +127.0.0.1:7379> BITPOS mykey 0 2 4 +(integer) 16 ``` - -`Output`: - -```bash -16 -``` - ### Bit Not Found If the specified bit is not found within the specified range, the command returns -1: ```bash -SET mykey "foobar" -BITPOS mykey 1 2 4 -``` - -`Output`: - -```bash --1 +127.0.0.1:7379> SET mykey "foobar" +OK +127.0.0.1:7379> BITPOS mykey 1 2 4 +(integer) -1 ``` ### Error Cases @@ -97,13 +89,9 @@ BITPOS mykey 1 2 4 Attempting to use `BITPOS` on a key that holds a non-string value: ```bash -LPUSH mylist "item" -BITPOS mylist 1 -``` - -`Output`: - -```bash +127.0.0.1:7379> LPUSH mylist "item" +(integer) 1 +127.0.0.1:7379> BITPOS mylist 1 (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` @@ -112,13 +100,9 @@ BITPOS mylist 1 Using a bit value other than 0 or 1: ```bash -SET mykey "foobar" -BITPOS mykey 2 -``` - -`Output`: - -```bash +127.0.0.1:7379> SET mykey "foobar" +OK +127.0.0.1:7379> BITPOS mykey 2 (error) ERR bit is not an integer or out of range ``` @@ -127,12 +111,8 @@ BITPOS mykey 2 Using non-integer values for the `start` or `end` parameters: ```bash -SET mykey "foobar" -BITPOS mykey 1 "a" "b" -``` - -`Output`: - -```bash +127.0.0.1:7379> SET mykey "foobar" +OK +127.0.0.1:7379> BITPOS mykey 1 "a" "b" (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 ee9d0b9a6..b17c2eb41 100644 --- a/docs/src/content/docs/commands/DBSIZE.md +++ b/docs/src/content/docs/commands/DBSIZE.md @@ -37,6 +37,7 @@ The `DBSIZE` command does not take any parameters. 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. @@ -86,4 +87,4 @@ In the current implementation, both commands will return the same count as they ## 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. \ No newline at end of file +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 694ab44f8..75f583be6 100644 --- a/docs/src/content/docs/commands/DECR.md +++ b/docs/src/content/docs/commands/DECR.md @@ -13,16 +13,16 @@ 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 30b949313..6a29a6781 100644 --- a/docs/src/content/docs/commands/DECRBY.md +++ b/docs/src/content/docs/commands/DECRBY.md @@ -13,28 +13,28 @@ 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 744d1abe3..b671f1d49 100644 --- a/docs/src/content/docs/commands/DEL.md +++ b/docs/src/content/docs/commands/DEL.md @@ -1,8 +1,6 @@ --- 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. @@ -15,17 +13,17 @@ 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 a94f8f9c1..2b460dae9 100644 --- a/docs/src/content/docs/commands/ECHO.md +++ b/docs/src/content/docs/commands/ECHO.md @@ -9,24 +9,25 @@ description: The `ECHO` command in DiceDB is used to print a message 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 fcb52e8f8..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 d63efa4be..cf301c16e 100644 --- a/docs/src/content/docs/commands/EXPIRE.md +++ b/docs/src/content/docs/commands/EXPIRE.md @@ -13,21 +13,21 @@ 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 Values -| 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 @@ -45,6 +45,7 @@ EXPIRE key seconds [NX | XX | GT | LT] ## Example Usage ### Basic Usage + 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 @@ -57,6 +58,7 @@ OK ``` ### 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. ```bash @@ -69,6 +71,7 @@ OK ``` ### 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 @@ -83,6 +86,7 @@ OK ``` ### Invalid 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 diff --git a/docs/src/content/docs/commands/EXPIREAT.md b/docs/src/content/docs/commands/EXPIREAT.md index bb233202b..bb3010aa3 100644 --- a/docs/src/content/docs/commands/EXPIREAT.md +++ b/docs/src/content/docs/commands/EXPIREAT.md @@ -24,10 +24,10 @@ EXPIREAT key timestamp [NX|XX|GT|LT] ## Return Values -| 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 @@ -39,10 +39,12 @@ EXPIREAT key timestamp [NX|XX|GT|LT] ## Errors 1. `Syntax Error`: + - Error Message: `(error) ERROR wrong number of arguments for 'expireat' command` - Returned if the command is issued with an incorrect number of arguments. 2. `Invalid Timestamp`: + - Error Message: `(error) ERROR value is not an integer or out of range` - Returned if the timestamp is not a valid integer. @@ -53,6 +55,7 @@ EXPIREAT key timestamp [NX|XX|GT|LT] ## Example Usage ### Basic Usage + This example demonstrates setting a key to expire at a specific Unix timestamp. ```bash @@ -92,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 ``` @@ -107,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 ``` @@ -122,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 @@ -141,4 +144,4 @@ OK ## Alternatives -- Use `EXPIRE` command for simpler expiration control based on relative time \ No newline at end of file +- 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 da46e3a23..0774ab7d5 100644 --- a/docs/src/content/docs/commands/EXPIRETIME.md +++ b/docs/src/content/docs/commands/EXPIRETIME.md @@ -13,17 +13,17 @@ 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 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 | +| 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 @@ -70,6 +70,7 @@ In this example, the key `mykey` is set with a value "Hello" but no expiration t 127.0.0.1:7379> EXPIRETIME nonExistentKey (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 diff --git a/docs/src/content/docs/commands/FLUSHDB.md b/docs/src/content/docs/commands/FLUSHDB.md index cb82cec8d..8db708ccb 100644 --- a/docs/src/content/docs/commands/FLUSHDB.md +++ b/docs/src/content/docs/commands/FLUSHDB.md @@ -17,12 +17,12 @@ The `FLUSHDB` command does not take any parameters. ## Return Values -| Condition | Return Value | -|--------------------------|--------------| -| Command is successful | `OK` | -| Authentication required | Error: `NOAUTH Authentication required` | +| 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` | +| Read-only mode | Error: `READONLY You can't write against a read-only replica` | ## Behaviour @@ -37,10 +37,12 @@ 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. `Authentication Issues`: + - Error Message: `(error) NOAUTH Authentication required` - Occurs when authentication is required but not provided 2. `Permission Issues`: + - 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 @@ -89,4 +91,4 @@ OK - 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. \ No newline at end of file +- 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 c1306bae0..3bc809199 100644 --- a/docs/src/content/docs/commands/GETBIT.md +++ b/docs/src/content/docs/commands/GETBIT.md @@ -13,17 +13,17 @@ 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 1ea5b2a8b..f08f87dee 100644 --- a/docs/src/content/docs/commands/GETDEL.md +++ b/docs/src/content/docs/commands/GETDEL.md @@ -13,16 +13,16 @@ 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 @@ -57,8 +57,14 @@ OK (nil) ``` +<<<<<<< HEAD +`Explanation:` +======= + ### Using `GETDEL` on a Non-Existent Key +> > > > > > > d43577926873d0df0c8f189cdde6afa65c515ccb + Trying to retrieve and delete a key `nonexistingkey` that does not exist. ```bash @@ -66,13 +72,27 @@ Trying to retrieve and delete a key `nonexistingkey` that does not exist. (nil) ``` +<<<<<<< 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 + 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 -(error) WRONGTYPE Operation against a key holding the wrong kind of value -``` \ No newline at end of file +ERROR WRONGTYPE Operation against a key holding the wrong kind of value +``` + +`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. + (error) WRONGTYPE Operation against a key holding the wrong kind of value diff --git a/docs/src/content/docs/commands/GETEX.md b/docs/src/content/docs/commands/GETEX.md index e841b3540..26ced9427 100644 --- a/docs/src/content/docs/commands/GETEX.md +++ b/docs/src/content/docs/commands/GETEX.md @@ -13,22 +13,22 @@ GETEX key [EX seconds|PX milliseconds|EXAT timestamp|PXAT milliseconds-timestamp ## 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 @@ -120,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 24bd71090..0c3bf9058 100644 --- a/docs/src/content/docs/commands/GETSET.md +++ b/docs/src/content/docs/commands/GETSET.md @@ -13,20 +13,17 @@ 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 @@ -78,8 +74,8 @@ 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 + ```bash 127.0.0.1:7379> SET newkey "test" OK @@ -99,7 +95,6 @@ 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 ```bash @@ -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 index 64e2bfbc0..3046d5b2f 100644 --- a/docs/src/content/docs/commands/HDEL.md +++ b/docs/src/content/docs/commands/HDEL.md @@ -4,6 +4,7 @@ description: The HDEL command in DiceDB deletes a specified field within a hash --- # 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 @@ -14,20 +15,20 @@ 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 | +| 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` | +| 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 @@ -122,11 +123,10 @@ 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/src/content/docs/commands/HEXISTS.md b/docs/src/content/docs/commands/HEXISTS.md index 5e0641394..beff229fa 100644 --- a/docs/src/content/docs/commands/HEXISTS.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 41066ea10..442d99e46 100644 --- a/docs/src/content/docs/commands/HGET.md +++ b/docs/src/content/docs/commands/HGET.md @@ -13,19 +13,19 @@ HGET key field ## Parameters -| 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 | +| 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 Values -| 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` | +| 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 @@ -96,6 +96,7 @@ 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. @@ -108,6 +109,7 @@ 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 ``` + - **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. @@ -116,4 +118,3 @@ Wrong Number of Arguments for HGET Command - The `HGET` command is a read-only command and does not modify the hash or any other data in the DiceDB database. 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 b3b2da145..974146341 100644 --- a/docs/src/content/docs/commands/HGETALL.md +++ b/docs/src/content/docs/commands/HGETALL.md @@ -13,18 +13,16 @@ 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,6 +40,7 @@ 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 @@ -76,6 +75,7 @@ The `HGETALL` command can raise the following errors: ``` ### Error Example: + Key is not a hash ```bash @@ -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 ```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/src/content/docs/commands/HKEYS.md b/docs/src/content/docs/commands/HKEYS.md index 6c993206a..36367bab0 100644 --- a/docs/src/content/docs/commands/HKEYS.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 6e8168995..2a2b8747f 100644 --- a/docs/src/content/docs/commands/HLEN.md +++ b/docs/src/content/docs/commands/HLEN.md @@ -13,17 +13,16 @@ 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,10 +43,10 @@ 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`. ```bash @@ -59,6 +58,7 @@ Creating hash `myhash` with two fields `field1` and `field2`. Getting hash lengt ``` ### Invalid Usage on non-existent key + Getting hash length from a non-existent hash key `nonExistentHash`. ```bash @@ -67,6 +67,7 @@ Getting hash length from a non-existent hash key `nonExistentHash`. ``` ### Invalid Usage on non-hash key + Getting hash length from a key `mystring` associated with a non-hash type. ```bash @@ -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 index 186daebde..7186db9b4 100644 --- a/docs/src/content/docs/commands/HMGET.md +++ b/docs/src/content/docs/commands/HMGET.md @@ -13,21 +13,21 @@ 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 | +| 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` | +| 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 @@ -64,6 +64,7 @@ The `HMGET` command can raise errors in the following scenarios: 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. @@ -74,6 +75,7 @@ The `HMGET` command can raise errors in the following scenarios: 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`. @@ -100,6 +102,7 @@ Missing Key or Field Arguments 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. diff --git a/docs/src/content/docs/commands/HMSET.md b/docs/src/content/docs/commands/HMSET.md index 4b07238e7..d40534fab 100644 --- a/docs/src/content/docs/commands/HMSET.md +++ b/docs/src/content/docs/commands/HMSET.md @@ -13,23 +13,22 @@ 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 | +| 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` | - +| 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 @@ -64,6 +63,7 @@ The `HMSET` command can raise errors in the following scenarios: 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` @@ -73,6 +73,7 @@ OK 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` @@ -99,6 +100,7 @@ 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. diff --git a/docs/src/content/docs/commands/HRANDFIELD.md b/docs/src/content/docs/commands/HRANDFIELD.md index 2fe1fdc55..24138be64 100644 --- a/docs/src/content/docs/commands/HRANDFIELD.md +++ b/docs/src/content/docs/commands/HRANDFIELD.md @@ -13,33 +13,35 @@ 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,10 +51,13 @@ 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:7379> HSET keys field1 value1 field2 value2 field3 value3 (integer) 3 @@ -61,7 +66,9 @@ Executing `HRANDFIELD` on a key without any parameters ``` ### Usage with `count` parameter + Executing `HRANDFIELD` on a key with a `count` parameter of 2 + ```bash 127.0.0.1:7379> HRANDFIELD keys 2 1) "field2" @@ -69,7 +76,9 @@ Executing `HRANDFIELD` on a key with a `count` parameter of 2 ``` ### Usage with `WITHVALUES` parameter + Executing `HRANDFIELD` with the `WITHVALUES` parameter + ```bash 127.0.0.1:7379> HRANDFIELD keys 2 WITHVALUES 1) "field2" @@ -79,6 +88,7 @@ Executing `HRANDFIELD` with the `WITHVALUES` parameter ``` ### Invalid key usage + Executing `hrandfield` on a non-hash key ```bash @@ -89,7 +99,8 @@ OK ``` ### Invalid count parameter -Non-integer value passed as `count` + +Non-integer value passed as `count` ```bash 127.0.0.1:7379> HRANDFIELD keys hello @@ -97,19 +108,24 @@ Non-integer value passed as `count` ``` ### Invalid number of arguments + Passing invalid number of arguments to the `hrandfield` command + ```bash 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 b6254bac7..8e416e8b1 100644 --- a/docs/src/content/docs/commands/HSCAN.md +++ b/docs/src/content/docs/commands/HSCAN.md @@ -13,13 +13,12 @@ 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,6 +47,7 @@ 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 @@ -71,7 +71,9 @@ Creating a hash `myhash` with two fields `field1` and `field2`. Getting `HSCAN` 2) 1) "field2" 2) "value2" ``` + ### Invalid Usage on non-existent key + Getting `HSCAN` on `nonExistentHash`. ```bash diff --git a/docs/src/content/docs/commands/HSET.md b/docs/src/content/docs/commands/HSET.md index d3eeed0a0..23b3acef6 100644 --- a/docs/src/content/docs/commands/HSET.md +++ b/docs/src/content/docs/commands/HSET.md @@ -13,22 +13,22 @@ HSET 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 ...]` | Optional additional field-value pairs to set in the hash. | String | No | +| 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 Values -| 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` | +| 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 @@ -63,6 +63,7 @@ The `HSET` command can raise errors in the following scenarios: 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). @@ -122,6 +123,7 @@ Wrong Number of Arguments for HSET Command 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. @@ -132,4 +134,4 @@ Wrong Number of Arguments for HSET Command ## Notes - `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. + 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 index 994e4c2a8..a6aa84d61 100644 --- a/docs/src/content/docs/commands/HSETNX.md +++ b/docs/src/content/docs/commands/HSETNX.md @@ -1,6 +1,6 @@ --- 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. +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. @@ -13,20 +13,20 @@ 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 | +| 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` | +| 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 @@ -61,6 +61,7 @@ The `HSETNX` command can raise errors in the following scenarios: 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). @@ -97,6 +98,7 @@ 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. diff --git a/docs/src/content/docs/commands/HSTRLEN.md b/docs/src/content/docs/commands/HSTRLEN.md index 77add9437..635441237 100644 --- a/docs/src/content/docs/commands/HSTRLEN.md +++ b/docs/src/content/docs/commands/HSTRLEN.md @@ -3,7 +3,7 @@ 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 @@ -13,18 +13,18 @@ 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,6 +48,7 @@ HSTRLEN key field ## Example Usage ### Basic Usage + Creating hash `myhash` with two fields `field1` and `field2`. Getting string length of value in `field1`. ```bash @@ -59,6 +60,7 @@ Creating hash `myhash` with two fields `field1` and `field2`. Getting string len ``` ### Invalid Usage on non-existent key + Getting string length from a non-existent key `nonExistentHash`. ```bash @@ -67,6 +69,7 @@ Getting string length from a non-existent key `nonExistentHash`. ``` ### Invalid Usage on non-hash key + Getting string length from a key `mystring` associated with a non-hash type. ```bash diff --git a/docs/src/content/docs/commands/HVALS.md b/docs/src/content/docs/commands/HVALS.md index 8ab5dc3ae..c21bef414 100644 --- a/docs/src/content/docs/commands/HVALS.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 7fceadd83..1be0bfa53 100644 --- a/docs/src/content/docs/commands/INCR.md +++ b/docs/src/content/docs/commands/INCR.md @@ -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 526ae9e7f..7c2c893d1 100644 --- a/docs/src/content/docs/commands/INCRBY.md +++ b/docs/src/content/docs/commands/INCRBY.md @@ -13,28 +13,28 @@ 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 5053a93f3..c93fc898d 100644 --- a/docs/src/content/docs/commands/INCRBYFLOAT.md +++ b/docs/src/content/docs/commands/INCRBYFLOAT.md @@ -13,28 +13,28 @@ 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 9ae4716c6..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. @@ -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 fa4729543..652316c53 100644 --- a/docs/src/content/docs/commands/JSON.ARRINSERT.md +++ b/docs/src/content/docs/commands/JSON.ARRINSERT.md @@ -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 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 446bfc776..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. diff --git a/docs/src/content/docs/commands/JSON.ARRTRIM.md b/docs/src/content/docs/commands/JSON.ARRTRIM.md index 9b3d10e9a..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 diff --git a/docs/src/content/docs/commands/JSON.CLEAR.md b/docs/src/content/docs/commands/JSON.CLEAR.md index c34653656..44d4d4186 100644 --- a/docs/src/content/docs/commands/JSON.CLEAR.md +++ b/docs/src/content/docs/commands/JSON.CLEAR.md @@ -13,17 +13,17 @@ 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.DEL.md b/docs/src/content/docs/commands/JSON.DEL.md index 83344d7b2..5a6905fbe 100644 --- a/docs/src/content/docs/commands/JSON.DEL.md +++ b/docs/src/content/docs/commands/JSON.DEL.md @@ -12,17 +12,18 @@ 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` @@ -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 77f1b4b46..e84f2f470 100644 --- a/docs/src/content/docs/commands/JSON.FORGET.md +++ b/docs/src/content/docs/commands/JSON.FORGET.md @@ -13,18 +13,18 @@ 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 ef60d33b4..80f15eb02 100644 --- a/docs/src/content/docs/commands/JSON.GET.md +++ b/docs/src/content/docs/commands/JSON.GET.md @@ -13,20 +13,19 @@ 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.NUMINCRBY.md b/docs/src/content/docs/commands/JSON.NUMINCRBY.md index 0c5118b94..45773f252 100644 --- a/docs/src/content/docs/commands/JSON.NUMINCRBY.md +++ b/docs/src/content/docs/commands/JSON.NUMINCRBY.md @@ -14,7 +14,7 @@ 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,13 +35,13 @@ 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 diff --git a/docs/src/content/docs/commands/JSON.OBJKEYS.md b/docs/src/content/docs/commands/JSON.OBJKEYS.md index 88b2f37e6..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,7 +59,6 @@ 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 @@ -118,4 +116,3 @@ Error When Key Does Not Exist 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 cf9d58fb2..051443180 100644 --- a/docs/src/content/docs/commands/JSON.STRLEN.md +++ b/docs/src/content/docs/commands/JSON.STRLEN.md @@ -13,18 +13,17 @@ 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.TYPE.md b/docs/src/content/docs/commands/JSON.TYPE.md index 467d97be2..d2f8be358 100644 --- a/docs/src/content/docs/commands/JSON.TYPE.md +++ b/docs/src/content/docs/commands/JSON.TYPE.md @@ -13,22 +13,21 @@ 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 f35772f02..dc35f923d 100644 --- a/docs/src/content/docs/commands/KEYS.md +++ b/docs/src/content/docs/commands/KEYS.md @@ -13,25 +13,26 @@ 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 diff --git a/docs/src/content/docs/commands/LATENCY.md b/docs/src/content/docs/commands/LATENCY.md index 78cbab6ea..3c59a5cfe 100644 --- a/docs/src/content/docs/commands/LATENCY.md +++ b/docs/src/content/docs/commands/LATENCY.md @@ -2,6 +2,7 @@ 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. @@ -14,26 +15,26 @@ 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/LINSERT.md b/docs/src/content/docs/commands/LINSERT.md new file mode 100644 index 000000000..50ad0c8de --- /dev/null +++ b/docs/src/content/docs/commands/LINSERT.md @@ -0,0 +1,102 @@ +--- +title: LINSERT +description: Inserts element in the list stored at key either before or after the reference value pivot. When key does not exist, it is considered an empty list and no operation is performed. An error is returned when key exists but does not hold a list value. +--- + +The `LINSERT` command in DiceDB inserts an element in the list stored at key either before or after the reference value pivot. When key does not exist, it is considered an empty list and no operation is performed. An error is returned when key exists but does not hold a list value. + +## Syntax + +``` +LINSERT key pivot element +``` + +## Parameters + +| Parameter | Description | Type | Required | +|-----------------------|---------------------------------------------------------------------------|---------|----------| +| `key` | The key associated with the list whose length you want to retrieve. | String | Yes | +| `` | Tells whether to insert the element before or after the pivot. | String | Yes | +| `pivot` | The pivot element. | String | Yes | +| `element` | The element to be inserted. | String | Yes | + + +## Return values + +| Condition | Return Value | +|------------------------------------------------|-----------------------------------------------------------------| +| Command is successful | Integer reply: Number of elements in the list after insertion. | +| If the key does not exist | 0 | +| Syntax or specified constraints are invalid | error | + +## Behaviour + + - If the key exists and is associated with a list, the `LINSERT` command returns the list length after insertion. + - If the key does not exist, the `LINSERT` command returns 0. + - If the key exists but is not associated with a list, an error is returned. + +## Errors + +1. `Wrong type of value or key`: + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if the key exists but is not associated with a list. + +2. `Wrong number of arguments`: + + - Error Message: `(error) wrong number of arguments for LINSERT` + - Occurs when invalid arguments are passed to the command. + + +## Example Usage + +### Basic Usage + +Performing the `LINSERT` on a list `mylist` with values `["one", "two"]`. + +```bash +127.0.0.1:7379> RPUSH mylist "one" +(integer) 1 +127.0.0.1:7379> RPUSH mylist "two" +(integer) 2 +127.0.0.1:7379> LINSERT mylist after "two" "four" +(integer) 3 +127.0.0.1:7379> LRANGE mylist 0 100 +1) "one" +2) "two" +3) "four" +127.0.0.1:7379> LINSERT mylist before "four" "three" +(integer) 4 +127.0.0.1:7379> LRANGE mylist 0 100 +1) "one" +2) "two" +3) "three" +4) "four" +``` + +### Non-Existent Key + +Getting the `LINSERT` on a list `nonExistentList` which does not exist. + +```bash +127.0.0.1:7379> LINSERT nonExistentList before "two" "one" +(integer) 0 +``` + +### Invalid usage +Trying to perform `LINSERT` on a key `myhash` which doens't hold list data type. + +```bash +127.0.0.1:7379> HMSET myhash field1 "value1" +OK +127.0.0.1:7379> HGET myhash field1 +"value1" +127.0.0.1:7379> LINSERT myhash before pivot element +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` + +## Best Practices + +- `Check Key Type`: Before using `LINSERT`, ensure that the key is associated with a list to avoid errors. +- `Handle Non-Existent Keys`: Be prepared to handle the case where the key does not exist, as `LINSERT` will return `0` in such scenarios. +- `Use in Conjunction with Other List Commands`: The `LINSERT` command is often used alongside other list commands like `RPUSH`, `LPUSH`, `LPOP`, and `RPOP` to manage and process lists effectively. diff --git a/docs/src/content/docs/commands/LLEN.md b/docs/src/content/docs/commands/LLEN.md index f779a1097..0910ec718 100644 --- a/docs/src/content/docs/commands/LLEN.md +++ b/docs/src/content/docs/commands/LLEN.md @@ -13,23 +13,23 @@ 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 7d8783178..cdbaf3539 100644 --- a/docs/src/content/docs/commands/LPOP.md +++ b/docs/src/content/docs/commands/LPOP.md @@ -13,21 +13,17 @@ 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 e949f21e8..ef20ecc52 100644 --- a/docs/src/content/docs/commands/LPUSH.md +++ b/docs/src/content/docs/commands/LPUSH.md @@ -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. @@ -57,7 +57,8 @@ Insert the value `world` at the head of the list stored at key `mylist`. If `myl ### 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`. + ```bash @@ -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/LRANGE.md b/docs/src/content/docs/commands/LRANGE.md new file mode 100644 index 000000000..4f226c518 --- /dev/null +++ b/docs/src/content/docs/commands/LRANGE.md @@ -0,0 +1,113 @@ +--- +title: LRANGE +description: Returns the specified elements of the list stored at key. +--- + +The `LRANGE` command in DiceDB returns the specified elements of the list stored at key. + +The offsets start and stop are zero-based indexes, with 0 being the first element of the list (the head of the list), 1 being the next element and so on. + +These offsets can also be negative numbers indicating offsets starting at the end of the list. +For example, -1 is the last element of the list, -2 the penultimate, and so on. + +Out of range indexes will not produce an error. If start is larger than the end of the list, an empty list is returned. +If stop is larger than the actual end of the list it will be treated like the last element of the list. + +## Syntax + +``` +LRANGE key start stop +``` + +## Parameters + +| Parameter | Description | Type | Required | +|-----------|---------------------------------------------------------------------------|---------|----------| +| `key` | The key associated with the list whose length you want to retrieve. | String | Yes | +| `start` | The start offset. | String | Yes | +| `stop` | The stop offset. | String | Yes | + + +## Return values + +| Condition | Return Value | +|------------------------------------------------|-----------------------------------------------------------------| +| Command is successful | Array reply: a list of elements in the specified range | +| If the key does not exist | An empty array if the key doesn't exist. | +| Syntax or specified constraints are invalid | error | + +## Behaviour + + - If the key exists and is associated with a list, the `LRANGE` command returns the specified elements of the list stored at key. + - If the key does not exist, the `LRANGE` command returns an empty array. + - If the key exists but is not associated with a list, an error is returned. + +## Errors + +1. `Wrong type of value or key`: + + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - Occurs if the key exists but is not associated with a list. + +2. `Wrong number of arguments`: + + - Error Message: `(error) wrong number of arguments for LRANGE` + - Occurs when invalid arguments are passed to the command. + +3. `Invalid start or stop offsets`: + + - Error Message: `(error) ERR value is not an integer or out of range` + - Occurs when the start/stop offset is not valid. + +## Example Usage + +### Basic Usage + +Getting the `LRANGE` of a list `mylist` with values `["one", "two"]`. + +```bash +127.0.0.1:7379> RPUSH mylist "one" +(integer) 1 +127.0.0.1:7379> RPUSH mylist "two" +(integer) 2 +127.0.0.1:7379> LRANGE mylist 0 100 +1) "one" +2) "two" +127.0.0.1:7379> LRANGE mylist -1 10 +1) "two" +``` + +### Non-Existent Key + +Getting the `LRANGE` of a list `nonExistentList` which does not exist. + +```bash +127.0.0.1:7379> LRANGE nonexistentlist 0 100 +(empty array) +``` + +### Invalid start/stop offset +Trying to get the `LRANGE` on a key `mylist` with invalid stop offset. + +```bash +127.0.0.1:7379> LRANGE mylist 0 10ff +(error) ERR value is not an integer or out of range +``` + +### Invalid usage +Trying to get the `LRANGE` on a key `myhash` which doens't hold list data type. + +```bash +127.0.0.1:7379> HMSET myhash field1 "value1" +OK +127.0.0.1:7379> HGET myhash field1 +"value1" +127.0.0.1:7379> LRANGE myhash 0 100 +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` + +## Best Practices + +- `Check Key Type`: Before using `LRANGE`, ensure that the key is associated with a list to avoid errors. +- `Handle Non-Existent Keys`: Be prepared to handle the case where the key does not exist, as `LRANGE` will return an empty array in such scenarios. +- `Use in Conjunction with Other List Commands`: The `LRANGE` command is often used alongside other list commands like `RPUSH`, `LPUSH`, `LPOP`, and `RPOP` to manage and process lists effectively. diff --git a/docs/src/content/docs/commands/MGET.md b/docs/src/content/docs/commands/MGET.md index 0b17524fb..2d92f1b2d 100644 --- a/docs/src/content/docs/commands/MGET.md +++ b/docs/src/content/docs/commands/MGET.md @@ -13,20 +13,19 @@ 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 633e52b4d..d31f63d53 100644 --- a/docs/src/content/docs/commands/MSET.md +++ b/docs/src/content/docs/commands/MSET.md @@ -13,30 +13,30 @@ 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 @@ -79,4 +79,4 @@ Attempting to set an odd number of arguments: ```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/PERSIST.md b/docs/src/content/docs/commands/PERSIST.md index 29fe4d2b7..499821264 100644 --- a/docs/src/content/docs/commands/PERSIST.md +++ b/docs/src/content/docs/commands/PERSIST.md @@ -13,16 +13,16 @@ 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 24c58db52..5428e45fb 100644 --- a/docs/src/content/docs/commands/PFADD.md +++ b/docs/src/content/docs/commands/PFADD.md @@ -13,17 +13,17 @@ 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 c38cd2de1..dabe44850 100644 --- a/docs/src/content/docs/commands/PFCOUNT.md +++ b/docs/src/content/docs/commands/PFCOUNT.md @@ -13,16 +13,16 @@ 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 8b8983e67..30c464952 100644 --- a/docs/src/content/docs/commands/PFMERGE.md +++ b/docs/src/content/docs/commands/PFMERGE.md @@ -13,20 +13,17 @@ 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: diff --git a/docs/src/content/docs/commands/PING.md b/docs/src/content/docs/commands/PING.md index 8ec596913..0570abb5c 100644 --- a/docs/src/content/docs/commands/PING.md +++ b/docs/src/content/docs/commands/PING.md @@ -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 a24ea3d9b..c1cdf42c3 100644 --- a/docs/src/content/docs/commands/PTTL.md +++ b/docs/src/content/docs/commands/PTTL.md @@ -12,23 +12,24 @@ 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 | 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` | + +| 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`: @@ -36,7 +37,6 @@ 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 ### Key with Expiration @@ -80,7 +80,9 @@ 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/RPOP.md b/docs/src/content/docs/commands/RPOP.md index b5fdaa930..a6fab6f2b 100644 --- a/docs/src/content/docs/commands/RPOP.md +++ b/docs/src/content/docs/commands/RPOP.md @@ -13,23 +13,21 @@ 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 be67c970f..cf9f5c69e 100644 --- a/docs/src/content/docs/commands/RPUSH.md +++ b/docs/src/content/docs/commands/RPUSH.md @@ -13,44 +13,42 @@ 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 efb043312..2600637a5 100644 --- a/docs/src/content/docs/commands/SADD.md +++ b/docs/src/content/docs/commands/SADD.md @@ -14,7 +14,7 @@ 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 763995e94..2ec7eb92f 100644 --- a/docs/src/content/docs/commands/SCARD.md +++ b/docs/src/content/docs/commands/SCARD.md @@ -13,19 +13,17 @@ 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 cca5b1da5..721684986 100644 --- a/docs/src/content/docs/commands/SDIFF.md +++ b/docs/src/content/docs/commands/SDIFF.md @@ -13,23 +13,21 @@ 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 18ca810ed..71825bbc2 100644 --- a/docs/src/content/docs/commands/SELECT.md +++ b/docs/src/content/docs/commands/SELECT.md @@ -15,15 +15,15 @@ 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 @@ -80,4 +80,4 @@ OK ## 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. \ No newline at end of file +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 518940b78..2ea5806ad 100644 --- a/docs/src/content/docs/commands/SET.md +++ b/docs/src/content/docs/commands/SET.md @@ -8,13 +8,13 @@ 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] +SET key value [NX | XX] [GET] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] ``` ## 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 | @@ -24,14 +24,17 @@ SET key value [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix | `NX` | Only set the key if it does not already exist. | None | No | | `XX` | Only set the key if it already exists. | None | No | | `KEEPTTL` | Retain the time-to-live associated with the key. | None | No | +| `GET` | Return the value of the key before setting it. | None | No | ## 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 | +| If the `GET` option is provided | The value of the key before setting it or error if value cannot be returned as a string | + ## Behaviour @@ -41,6 +44,7 @@ SET key value [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix - Using the `EX`, `EXAT`, `PX` or `PXAT` options together with `KEEPTTL` is not allowed and will result in an error. - 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. +- The `GET` option can be used to return the value of the key before setting it. If the key does not exist, `nil` is returned. If the key exists but does not contain a value which can be returned as a string, an error is returned. The set operation is not performed in this case. ## Errors @@ -131,3 +135,27 @@ 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 ``` + +### Set with GET option + +```bash +127.0.0.1:7379> set foo bar +OK +127.0.0.1:7379> set foo bazz get +"bar" +``` +### Set with GET option when key does not exist + +```bash +127.0.0.1:7379> set foo bazz get +(nil) +127.0.0.1:7379> get foo +(nil) +``` + +### Set with Get with wrong type of value +```bash +127.0.0.1:7379> sadd foo item1 +(integer) 1 +127.0.0.1:7379> set foo bazz get +(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/SETBIT.md b/docs/src/content/docs/commands/SETBIT.md index f4cb272ef..eabbada64 100644 --- a/docs/src/content/docs/commands/SETBIT.md +++ b/docs/src/content/docs/commands/SETBIT.md @@ -12,10 +12,11 @@ SETBIT key offset value ``` ## Parameters - -- `key`: The key of the string where the bit is to be set or cleared. If the key does not exist, a new string value is created. -- `offset`: The position of the bit to be set or cleared. The offset is a zero-based integer, meaning the first bit is at position 0. -- `value`: The value to set the bit to. This must be either 0 or 1. +| Parameter | Description | Type | Required | +|-----------|--------------------------------------------------------------------------------------------------------------------------|---------|----------| +| `key` | The key of the string where the bit is to be set or cleared. If the key does not exist, a new string value is created. | String | Yes | +| `offset` | The position of the bit to be set or cleared. The offset is a zero-based integer, meaning the first bit is at position 0.| Integer | Yes | +| `value` | The value to set the bit to. This must be either 0 or 1. | Bit | Yes | ## Return Value @@ -28,17 +29,22 @@ The command returns the original bit value stored at the specified offset before - The command only affects the bit at the specified offset and leaves all other bits unchanged. ## Error Handling +1. `Bit is not an integer or out of range`: + - Error Message: `(error) ERR bit is not an integer or out of range` + - This error is raised if the `offset` is not a valid integer or if it is negative. + - This error is also raised if the `value` is not 0 or 1. -- `ERR bit is not an integer or out of range`: This error is raised if the `offset` is not a valid integer or if it is negative. -- `ERR bit is not an integer or out of range`: This error is also raised if the `value` is not 0 or 1. -- `WRONGTYPE Operation against a key holding the wrong kind of value`: This error is raised if the key exists but does not hold a string value. +2. `WRONGTYPE Operation against a key holding the wrong kind of value`: + - Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value` + - This error is raised if the key exists but does not hold a bit string value. ## Example Usage ### Setting a Bit ```bash -SETBIT mykey 7 1 +127.0.0.1:7379> SETBIT mykey 7 1 +(integer) 0 ``` This command sets the bit at offset 7 in the string value stored at `mykey` to 1. If `mykey` does not exist, it is created and padded with zero bits up to the 7th bit. @@ -46,7 +52,8 @@ This command sets the bit at offset 7 in the string value stored at `mykey` to 1 ### Clearing a Bit ```bash -SETBIT mykey 7 0 +127.0.0.1:7379> SETBIT mykey 7 0 +(integer) 1 ``` This command clears the bit at offset 7 in the string value stored at `mykey` to 0. @@ -54,7 +61,8 @@ This command clears the bit at offset 7 in the string value stored at `mykey` to ### Checking the Original Bit Value ```bash -SETBIT mykey 7 1 +127.0.0.1:7379> SETBIT mykey 7 1 +(integer) 0 ``` If the bit at offset 7 was previously 0, this command will return 0 and then set the bit to 1. @@ -62,7 +70,8 @@ If the bit at offset 7 was previously 0, this command will return 0 and then set ### Extending the String ```bash -SETBIT mykey 100 1 +127.0.0.1:7379> SETBIT mykey 100 1 +(integer) 0 ``` If the string stored at `mykey` is shorter than 101 bits, it will be extended, and all new bits will be set to 0 except for the bit at offset 100, which will be set to 1. @@ -72,7 +81,8 @@ If the string stored at `mykey` is shorter than 101 bits, it will be extended, a ### Invalid Offset ```bash -SETBIT mykey -1 1 +127.0.0.1:7379> SETBIT mykey -1 1 +(error) ERR bit is not an integer or out of range ``` This command will raise an error: `ERR bit is not an integer or out of range` because the offset is negative. @@ -80,7 +90,8 @@ This command will raise an error: `ERR bit is not an integer or out of range` be ### Invalid Value ```bash -SETBIT mykey 7 2 +127.0.0.1:7379> SETBIT mykey 7 2 +(error) ERR bit is not an integer or out of range ``` This command will raise an error: `ERR bit is not an integer or out of range` because the value is not 0 or 1. @@ -88,8 +99,10 @@ This command will raise an error: `ERR bit is not an integer or out of range` be ### Wrong Type ```bash -SET mykey "Hello" -SETBIT mykey 7 1 +127.0.0.1:7379> SET mykey "Hello" +OK +127.0.0.1:7379> SETBIT mykey 7 1 +(error) WRONGTYPE Operation against a key holding the wrong kind of value ``` If `mykey` holds a string value that is not a bit string, the `SETBIT` command will raise an error: `WRONGTYPE Operation against a key holding the wrong kind of value`. diff --git a/docs/src/content/docs/commands/SINTER.md b/docs/src/content/docs/commands/SINTER.md index 81b9ca00a..eb854c351 100644 --- a/docs/src/content/docs/commands/SINTER.md +++ b/docs/src/content/docs/commands/SINTER.md @@ -10,19 +10,20 @@ The `SINTER` command in DiceDB is used to compute the intersection of multiple s ```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 @@ -72,6 +73,7 @@ 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 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 63e987e4c..657670968 100644 --- a/docs/src/content/docs/commands/SREM.md +++ b/docs/src/content/docs/commands/SREM.md @@ -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 f22b266aa..951edf8a1 100644 --- a/docs/src/content/docs/commands/TOUCH.md +++ b/docs/src/content/docs/commands/TOUCH.md @@ -13,20 +13,18 @@ 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. @@ -67,4 +65,4 @@ Trying to touch key `mylist` will result in a `WRONGTYPE` error because `mylist` ```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 a412d48b7..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 @@ -50,7 +50,6 @@ TTL key 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. - ### Check TTL for key without expiration ```bash @@ -81,7 +80,9 @@ In this example, the key `non_existent_key` does not exist in the DiceDB databas 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 77bba2625..34c5122e5 100644 --- a/docs/src/content/docs/commands/ZCARD.md +++ b/docs/src/content/docs/commands/ZCARD.md @@ -13,17 +13,16 @@ 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,10 +43,10 @@ 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. ```bash @@ -65,6 +64,7 @@ Creating sorted set `myzset` with two fields `one`, `two` with scores 1, 2 respe ``` ### Invalid Usage on non-existent sorted set + Getting cardinality of a non-existent sorted set `nonExistentZSet`. ```bash @@ -73,6 +73,7 @@ Getting cardinality of a non-existent sorted set `nonExistentZSet`. ``` ### Invalid Usage on a non sorted set key + Getting cardinality of a key `mystring` associated with a non sorted set type. ```bash @@ -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 4456aee9a..3b40ea265 100644 --- a/docs/src/content/docs/commands/ZCOUNT.md +++ b/docs/src/content/docs/commands/ZCOUNT.md @@ -14,21 +14,21 @@ 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 1e1343742..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. --- @@ -13,17 +13,17 @@ 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 53e8d9e22..1e6cbf2f6 100644 --- a/docs/src/content/docs/commands/ZREM.md +++ b/docs/src/content/docs/commands/ZREM.md @@ -13,19 +13,18 @@ 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,10 +45,10 @@ 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`. ```bash @@ -64,6 +63,7 @@ Creating sorted set `myzset` with fields `one`, `two`, `three`, `four`, `five` w ``` ### Invalid Usage on non-existent sorted set + Removing element from a non-existent sorted set `nonExistentZSet`. ```bash @@ -72,6 +72,7 @@ Removing element from a non-existent sorted set `nonExistentZSet`. ``` ### Invalid Usage on a non sorted set key + Getting cardinality of a key `mystring` associated with a non sorted set type. ```bash @@ -83,4 +84,4 @@ OK ## 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..75f9622b2 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, reactive, scalable, highly available, unified cache optimized for modern hardware. 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/content/blog/dicedb-0.0.1-release-notes.md b/docs/src/content/releases/dicedb-0.0.1-release-notes.md similarity index 100% rename from docs/src/content/blog/dicedb-0.0.1-release-notes.md rename to docs/src/content/releases/dicedb-0.0.1-release-notes.md diff --git a/docs/src/content/blog/dicedb-0.0.2-release-notes.md b/docs/src/content/releases/dicedb-0.0.2-release-notes.md similarity index 100% rename from docs/src/content/blog/dicedb-0.0.2-release-notes.md rename to docs/src/content/releases/dicedb-0.0.2-release-notes.md diff --git a/docs/src/content/blog/dicedb-0.0.3-release-notes.md b/docs/src/content/releases/dicedb-0.0.3-release-notes.md similarity index 100% rename from docs/src/content/blog/dicedb-0.0.3-release-notes.md rename to docs/src/content/releases/dicedb-0.0.3-release-notes.md diff --git a/docs/src/content/blog/dicedb-0.0.4-release-notes.md b/docs/src/content/releases/dicedb-0.0.4-release-notes.md similarity index 100% rename from docs/src/content/blog/dicedb-0.0.4-release-notes.md rename to docs/src/content/releases/dicedb-0.0.4-release-notes.md diff --git a/docs/src/data/benchmarks.md b/docs/src/data/benchmarks.md index a30fd40fe..9df1b3152 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 memtier 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..f2222fb0c 100644 --- a/docs/src/layouts/BlogLayout.astro +++ b/docs/src/layouts/BlogLayout.astro @@ -3,7 +3,7 @@ import { getEntry } from "astro:content"; import Layout from "./Layout.astro"; import AboutMeVertical from "../components/AboutMeVertical.astro"; -const { blog } = Astro.props; +const { blog, type } = Astro.props; const author = await getEntry("authors", blog.data.author.id); const JSONLD = { @@ -46,14 +46,24 @@ 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;