Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Refresh SREM and SMEMBERS documentation #116

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Refresh SREM and SMEMBERS documentation #116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
669600a
Update SREM.md
sahoss Oct 28, 2024
a6ba646
Update SREM.md
sahoss Oct 28, 2024
8c2f692
Update SMEMBERS.md
sahoss Oct 28, 2024
2bd3184
Update SMEMBERS.md
sahoss Oct 28, 2024
26618aa
Update SMEMBERS.md
sahoss Oct 28, 2024
23e089e
Update SMEMBERS.md
sahoss Oct 28, 2024
5d262dd
Update src/content/docs/commands/SMEMBERS.md
sahoss Oct 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 43 additions & 45 deletions src/content/docs/commands/SMEMBERS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,90 +2,88 @@
title: SMEMBERS
description: Documentation for the DiceDB command SMEMBERS
---

<!-- description in 2 to 3 sentences, following is an example -->
The `SMEMBERS` command in DiceDB is used to retrieve all the members of a set stored at a specified key. Sets in DiceDB are unordered collections of unique strings. This command is useful for obtaining the entire set of elements for further processing or inspection.

## Syntax

```
```bash
SMEMBERS key
```
<!-- If the command have subcommands please mention but do not consider them as arguments -->
<!-- please mention them in subcommands section and create their individual documents -->

## Parameters
<!-- please add all parameters, small description, type and required, see example for SET command-->
| Parameter | Description | Type | Required |
|-----------|---------------------------------------------------------------------------|---------|----------|
| `key` | The key of the set from which you want to retrieve all members. This parameter is required and must be a valid string. | String | Yes |

- `key`: The key of the set from which you want to retrieve all members. This parameter is required and must be a valid string.

## Return Value
## Return values
<!-- add all scenarios, see below example for SET -->

The `SMEMBERS` command returns an array of all the members in the set stored at the specified key. If the key does not exist, an empty array is returned.

## Behaviour
| Condition | Return Value |
|------------------------------------------------|---------------------------------------------------|
| if key exists | array of all the members in the set stored at the specified key |
| if key does not exist | empty array |

When the `SMEMBERS` command is executed:

## Behaviour
<!-- How does the command execute goes here, kind of explaining the underlying algorithm -->
<!-- see below example for SET command -->
<!-- Please modify for the command by going through the code -->
1. DiceDB checks if the key exists.
1. If the key exists and is of type set, DiceDB retrieves all the members of the set.
1. If the key does not exist, DiceDB returns an empty array.
1. If the key exists but is not of type set, an error is returned.

## Error Handling

The `SMEMBERS` command can raise the following errors:
## Errors
<!-- sample errors, please update for commands-->
<!-- please add all the errors here -->
<!-- incase of a dynamic error message, feel free to use variable names -->

- `WRONGTYPE Operation against a key holding the wrong kind of value`: This error occurs if the key exists but is not associated with a set. DiceDB expects the key to be of type set, and if it is not, this error is raised.
1. `Wrong type of value or key`:

## Example Usage
- 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 is of a non-set type.

### Example 1: Retrieving Members from an Existing Set

```DiceDB
SADD myset "apple" "banana" "cherry"
SMEMBERS myset
```
## Example Usage

`Output:`
### Retrieving Members from an Existing Set
<!-- examples here are for set, please update them for the command -->

```
```bash
127.0.0.1:7379> SADD myset "apple" "banana" "cherry"
127.0.0.1:7379> SMEMBERS myset
1) "apple"
2) "banana"
3) "cherry"
```
<!-- Please use detailed scenarios and edges cases if possible -->
### Retrieving Members from a Non-Existent Set

### Example 2: Retrieving Members from a Non-Existent Set

```DiceDB
SMEMBERS nonexistentset
```

`Output:`

```
```bash
127.0.0.1:7379> SMEMBERS nonexistentset
(empty array)
```

### Example 3: Error Case - Key Exists but is Not a Set

```DiceDB
SET mystring "hello"
SMEMBERS mystring
```

`Output:`

```
(error) WRONGTYPE Operation against a key holding the wrong kind of value
```

## Notes

- The order of elements returned by `SMEMBERS` is not guaranteed to be consistent. Sets in DiceDB are unordered collections, so the order of elements may vary.
- For large sets, consider using the `SSCAN` command to iterate over the set incrementally to avoid blocking the DiceDB server for a long time.

<!-- Optional -->
## Best Practices

<!-- below example from Keys command -->
- Always ensure that the key you are querying with `SMEMBERS` is of type set to avoid type errors.
- Use `EXISTS` command to check if a key exists before using `SMEMBERS` if you are unsure about the key's existence.
- For very large sets, prefer using `SSCAN` to avoid performance issues.


<!-- Optional -->
## Notes
<!-- below example from json.get command -->
- The order of elements returned by `SMEMBERS` is not guaranteed to be consistent. Sets in DiceDB are unordered collections, so the order of elements may vary.
- For large sets, consider using the `SSCAN` command to iterate over the set incrementally to avoid blocking the DiceDB server for a long time.
By following this documentation, you should be able to effectively use the `SMEMBERS` command in DiceDB to retrieve all members of a set.

140 changes: 72 additions & 68 deletions src/content/docs/commands/SREM.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,120 +2,124 @@
title: SREM
description: Documentation for the DiceDB command SREM
---

<!-- description in 2 to 3 sentences, following is an example -->
The `SREM` command is used to remove one or more members from a set stored at a specified key. If the specified members are not present in the set, they are ignored. If the key does not exist, it is treated as an empty set and the command returns 0. This command is idempotent, meaning that removing a member that does not exist in the set has no effect.

## Syntax

```
```bash
SREM key member [member ...]
```
<!-- If the command have subcommands please mention but do not consider them as arguments -->
<!-- please mention them in subcommands section and create their individual documents -->

## Parameters
<!-- please add all parameters, small description, type and required, see example for SET command-->
| Parameter | Description | Type | Required |
|-----------|---------------------------------------------------------------------------|---------|----------|
| `key` |The key of the set from which the members will be removed. This key must be of the set data type. | String | Yes |
| `member` | One or more members to be removed from the set. Multiple members can be specified, separated by spaces. | String | Yes |

- `key`: The key of the set from which the members will be removed. This key must be of the set data type.
- `member`: One or more members to be removed from the set. Multiple members can be specified, separated by spaces.
## Return values
<!-- add all scenarios, see below example for SET -->

## Return Value
| Condition | Return Value |
|------------------------------------------------|---------------------------------------------------|
| The number of members that were removed from the set, not including non-existing members. | `Integer reply` |

- `Integer reply`: The number of members that were removed from the set, not including non-existing members.

## Behaviour
<!-- How does the command execute goes here, kind of explaining the underlying algorithm -->
<!-- see below example for SET command -->
<!-- Please modify for the command by going through the code -->
- DiceDB checks if the key exists.
- If the key does not exist, it is treated as an empty set, and the command returns 0.
- If the key exists but is not of the set data type, an error is returned.
- DiceDB attempts to remove the specified members from the set.
- The command returns the number of members that were successfully removed.

When the `SREM` command is executed, the following steps occur:

1. DiceDB checks if the key exists.
1. If the key does not exist, it is treated as an empty set, and the command returns 0.
1. If the key exists but is not of the set data type, an error is returned.
1. DiceDB attempts to remove the specified members from the set.
1. The command returns the number of members that were successfully removed.
## Errors
<!-- sample errors, please update for commands-->
<!-- please add all the errors here -->
<!-- incase of a dynamic error message, feel free to use variable names -->

## Error Handling
1. `Wrong type of value or key`:

- `WRONGTYPE Operation against a key holding the wrong kind of value`: This error is returned if the key exists but is not of the set data type.
- `Syntax error`: This error is returned if the command is not used with the correct number of arguments.
- Error Message: `(error) WRONGTYPE Operation against a key holding the wrong kind of value`
- This error is returned if the key exists but is not of the set data type.

## Example Usage
2. `Invalid syntax`:

### Example 1: Removing a single member from a set
- Error Message: `(error) ERR syntax error`
- This error is returned if the command is not used with the correct number of arguments.

```DiceDB
SADD myset "one" "two" "three"
SREM myset "two"
```

`Expected Output:`

```
(integer) 1
```
## Example Usage

`Explanation:` The member "two" is removed from the set `myset`. The command returns 1 because one member was removed.
### Basic Usage
<!-- examples here are for set, please update them for the command -->

### Example 2: Removing multiple members from a set
The member "two" is removed from the set `myset`. The command returns 1 because one member was removed.

```DiceDB
SADD myset "one" "two" "three"
SREM myset "two" "three"
```bash
127.0.0.1:7379> SADD myset "one" "two" "three"
127.0.0.1:7379> SREM myset "two"
(integer) 1
```
<!-- Please use detailed scenarios and edges cases if possible -->
### Removing multiple members from a set

`Expected Output:`
The members "two" and "three" are removed from the set `myset`. The command returns 2 because two members were removed.

```
```bash
127.0.0.1:7379> SADD myset "one" "two" "three"
127.0.0.1:7379> SREM myset "two" "three"
(integer) 2
```

`Explanation:` The members "two" and "three" are removed from the set `myset`. The command returns 2 because two members were removed.

### Example 3: Removing a non-existing member from a set
### Removing a non-existing member from a set

```DiceDB
SADD myset "one" "two" "three"
SREM myset "four"
```
The member "four" does not exist in the set `myset`. The command returns 0 because no members were removed.

`Expected Output:`

```
```bash
127.0.0.1:7379> SADD myset "one" "two" "three"
127.0.0.1:7379> SREM myset "four"
(integer) 0
```

`Explanation:` The member "four" does not exist in the set `myset`. The command returns 0 because no members were removed.
### Removing members from a non-existing set

### Example 4: Removing members from a non-existing set

```DiceDB
SREM myset "one"
```
The set `myset` does not exist. The command returns 0 because no members were removed.

`Expected Output:`
```bash
127.0.0.1:7379> SET mykey "value"
127.0.0.1:7379> SREM mykey "one"
(error) WRONGTYPE Operation against a key holding the wrong kind of value

```
(integer) 0
```

`Explanation:` The set `myset` does not exist. The command returns 0 because no members were removed.
### Invalid usage

### Example 5: Error when key is not a set
Trying to set key `foo` with both `EX` and `KEEPTTL` will result in an error

```DiceDB
SET mykey "value"
SREM mykey "one"
```bash
127.0.0.1:7379> SET foo bar EX 10 KEEPTTL
(error) ERR syntax error
```
<!-- Optional: Used when additional information is to conveyed to users -->
<!-- For example warnings about usage ex: Keys * -->
<!-- OR alternatives of the commands -->
<!-- Or perhaps deprecation warning -->
<!-- anything related to the command which cannot be shared in other sections -->

`Expected Output:`

```
(error) WRONGTYPE Operation against a key holding the wrong kind of value
```

`Explanation:` The key `mykey` exists but is not of the set data type. The command returns an error.

<!-- Optional -->
## Notes
<!-- below example from json.get command -->
- The SREM command is idempotent. Removing a member that does not exist in the set has no effect and does not produce an error.

- The command can be used to remove multiple members in a single call, which can be more efficient than calling SREM multiple times for individual members.

- The `SREM` command is idempotent. Removing a member that does not exist in the set has no effect and does not produce an error.
- The command can be used to remove multiple members in a single call, which can be more efficient than calling `SREM` multiple times for individual members.
- 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.