Skip to content

Commit

Permalink
Add documentation for ZRANGE command
Browse files Browse the repository at this point in the history
Related to DiceDB#1284

Add documentation for the `ZRANGE` command in DiceDB.

* Create a new file `docs/src/content/docs/commands/ZRANGE.md`.
* Add an introduction paragraph about the `ZRANGE` command.
* Include the syntax for the `ZRANGE` command.
* List all parameters the `ZRANGE` command accepts in a table.
* List all possible return values and under what condition in a table.
* Describe the behavior of the `ZRANGE` command.
* List all possible errors the `ZRANGE` command can throw and under what condition.
* Add examples of the `ZRANGE` command and the expected output.
  • Loading branch information
vishwamartur committed Dec 16, 2024
1 parent e8f2573 commit 24c15b7
Showing 1 changed file with 107 additions and 0 deletions.
107 changes: 107 additions & 0 deletions docs/src/content/docs/commands/ZRANGE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
---
title: ZRANGE
description: The `ZRANGE` command in DiceDB is used to return a range of members in a sorted set, by index. The members are ordered from the lowest to the highest score.
---

The `ZRANGE` command in DiceDB is used to return a range of members in a sorted set, by index. The members are ordered from the lowest to the highest score.

## Syntax

```bash
ZRANGE key start stop [WITHSCORES] [REV]
```

## Parameters

| Parameter | Description | Type | Required |
| ----------- | --------------------------------------------------------------------------- | ------- | -------- |
| `key` | The name of the sorted set. | String | Yes |
| `start` | The starting index of the range. | Integer | Yes |
| `stop` | The ending index of the range. | Integer | Yes |
| `WITHSCORES`| Optional. Returns the scores of the elements in the result. | None | No |
| `REV` | Optional. Returns the elements in reverse order, from highest to lowest. | None | No |

## Return values

| Condition | Return Value |
| -------------------------------------- | ------------ |
| If the key exists and the range is valid | Array of elements in the specified range |
| If the key does not exist | Empty array |
| If the key is not a sorted set | Error |

## Behaviour

- The `ZRANGE` command returns the specified range of elements in the sorted set stored at `key`.
- The elements are considered to be ordered from the lowest to the highest score.
- Both `start` and `stop` are 0-based indexes, where 0 is the first element, 1 is the next element, and so on.
- These indexes can also be negative numbers indicating offsets from the end of the sorted set, with -1 being the last element of the sorted set, -2 the penultimate element, and so on.
- If `WITHSCORES` is specified, the command returns the elements and their scores.
- If `REV` is specified, the command returns the elements in reverse order, from highest to lowest score.

## 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-sorted set value.

2. `Invalid syntax or conflicting options`:
- Error Message: `(error) ERR syntax error`
- Occurs if the command's syntax is incorrect, such as incompatible options like `WITHSCORES` and `REV` used together, or a missing required parameter.

## Example Usage

### Basic Usage

Retrieving a range of elements from a sorted set `leaderboard` from index 0 to 2

```bash
127.0.0.1:7379> ZADD leaderboard 50 "Alice" 70 "Bob" 60 "Charlie"
(integer) 3
127.0.0.1:7379> ZRANGE leaderboard 0 2
1) "Alice"
2) "Charlie"
3) "Bob"
```

### Using `WITHSCORES`

Retrieving a range of elements from a sorted set `leaderboard` from index 0 to 2 with scores

```bash
127.0.0.1:7379> ZRANGE leaderboard 0 2 WITHSCORES
1) "Alice"
2) "50"
3) "Charlie"
4) "60"
5) "Bob"
6) "70"
```

### Using `REV`

Retrieving a range of elements from a sorted set `leaderboard` from index 0 to 2 in reverse order

```bash
127.0.0.1:7379> ZRANGE leaderboard 0 2 REV
1) "Bob"
2) "Charlie"
3) "Alice"
```

### Invalid usage

Trying to use `ZRANGE` on a key that is not a sorted set

```bash
127.0.0.1:7379> SET foo bar
OK
127.0.0.1:7379> ZRANGE foo 0 2
(error) WRONGTYPE Operation against a key holding the wrong kind of value
```

Trying to use `ZRANGE` with invalid syntax

```bash
127.0.0.1:7379> ZRANGE leaderboard 0
(error) ERR syntax error
```

0 comments on commit 24c15b7

Please sign in to comment.