# Redis Commands

Reference for the Redis (RESP) commands ParticleDB supports, with syntax and examples.

Source: https://particledb.ai/connectivity/redis-commands/

This page lists the Redis commands ParticleDB supports, with syntax and examples
run with `redis-cli`. For how to enable and connect, authentication, durability,
memory reporting, SQL access to the key space and the differences from Redis, see
[Redis Compatibility](/connectivity/redis/).

```bash
redis-cli -p 6379 --user postgres --pass your_password
```

Commands that are not listed here are either not supported or accepted only for
client compatibility; the [overview](/connectivity/redis/#differences-from-redis) lists
the notable ones.

---

## Strings

String commands operate on simple key-value pairs. Values can be strings, integers, or
arbitrary byte sequences.

### SET

Set the value of a key, with optional expiration and conditional flags.

**Syntax:**
```
SET key value [EX seconds] [PX milliseconds] [NX | XX]
```

| Option | Description                                  |
|--------|----------------------------------------------|
| `EX`   | Set expiration in seconds                    |
| `PX`   | Set expiration in milliseconds               |
| `NX`   | Only set if the key does not already exist   |
| `XX`   | Only set if the key already exists           |

**Return value:** `OK` on success, `nil` if the condition (NX/XX) was not met.

```bash
127.0.0.1:6379> SET user:1:name "Alice"
OK
127.0.0.1:6379> SET session:abc token123 EX 3600
OK
127.0.0.1:6379> SET lock:order worker-1 NX EX 30
OK
```

### GET

Get the value of a key.

**Syntax:**
```
GET key
```

**Return value:** The value of the key, or `nil` if the key does not exist.

```bash
127.0.0.1:6379> GET user:1:name
"Alice"
127.0.0.1:6379> GET nonexistent
(nil)
```

### SETNX

Set the value of a key only if it does not already exist. Equivalent to `SET key value NX`.

**Syntax:**
```
SETNX key value
```

**Return value:** `1` if the key was set, `0` if it already existed.

```bash
127.0.0.1:6379> SETNX mykey "Hello"
(integer) 1
127.0.0.1:6379> SETNX mykey "World"
(integer) 0
127.0.0.1:6379> GET mykey
"Hello"
```

### SETEX

Set the value and expiration (in seconds) of a key. Equivalent to `SET key value EX seconds`.

**Syntax:**
```
SETEX key seconds value
```

**Return value:** `OK`.

```bash
127.0.0.1:6379> SETEX cache:page:home 300 "<html>...</html>"
OK
127.0.0.1:6379> TTL cache:page:home
(integer) 299
```

### GETSET

Atomically set a key to a new value and return its old value.

**Syntax:**
```
GETSET key value
```

**Return value:** The old value of the key, or `nil` if it did not exist.

```bash
127.0.0.1:6379> SET counter "10"
OK
127.0.0.1:6379> GETSET counter "0"
"10"
127.0.0.1:6379> GET counter
"0"
```

### MGET

Get the values of multiple keys in a single round trip.

**Syntax:**
```
MGET key [key ...]
```

**Return value:** An array of values (or `nil` for keys that do not exist).

```bash
127.0.0.1:6379> SET key1 "a"
OK
127.0.0.1:6379> SET key2 "b"
OK
127.0.0.1:6379> MGET key1 key2 key3
1) "a"
2) "b"
3) (nil)
```

### MSET

Set multiple key-value pairs in a single atomic operation.

**Syntax:**
```
MSET key value [key value ...]
```

**Return value:** `OK` (always succeeds).

```bash
127.0.0.1:6379> MSET user:1:name "Alice" user:1:email "alice@example.com"
OK
127.0.0.1:6379> MGET user:1:name user:1:email
1) "Alice"
2) "alice@example.com"
```

### INCR

Increment the integer value of a key by one. If the key does not exist, it is set to 0
before the operation.

**Syntax:**
```
INCR key
```

**Return value:** The value after the increment.

```bash
127.0.0.1:6379> SET visits 100
OK
127.0.0.1:6379> INCR visits
(integer) 101
127.0.0.1:6379> INCR visits
(integer) 102
```

### DECR

Decrement the integer value of a key by one.

**Syntax:**
```
DECR key
```

**Return value:** The value after the decrement.

```bash
127.0.0.1:6379> SET stock 50
OK
127.0.0.1:6379> DECR stock
(integer) 49
```

### INCRBY

Increment the integer value of a key by a specified amount.

**Syntax:**
```
INCRBY key increment
```

**Return value:** The value after the increment.

```bash
127.0.0.1:6379> SET counter 10
OK
127.0.0.1:6379> INCRBY counter 5
(integer) 15
```

### DECRBY

Decrement the integer value of a key by a specified amount.

**Syntax:**
```
DECRBY key decrement
```

**Return value:** The value after the decrement.

```bash
127.0.0.1:6379> SET counter 100
OK
127.0.0.1:6379> DECRBY counter 25
(integer) 75
```

### APPEND

Append a value to an existing string. If the key does not exist, it is created with the
given value.

**Syntax:**
```
APPEND key value
```

**Return value:** The length of the string after the append.

```bash
127.0.0.1:6379> SET greeting "Hello"
OK
127.0.0.1:6379> APPEND greeting " World"
(integer) 11
127.0.0.1:6379> GET greeting
"Hello World"
```

### STRLEN

Get the length of the string stored at a key.

**Syntax:**
```
STRLEN key
```

**Return value:** The length of the string, or `0` if the key does not exist.

```bash
127.0.0.1:6379> SET name "ParticleDB"
OK
127.0.0.1:6379> STRLEN name
(integer) 10
```

### More string commands

| Command | What it does | Example | Reply |
|---|---|---|---|
| `GETRANGE key start end` (alias `SUBSTR`) | Substring by byte offsets (inclusive, negative from the end) | `GETRANGE s1 0 4` on `"Hello World"` | `"Hello"` |
| `SETRANGE key offset value` | Overwrite part of a string; returns the new length | `SETRANGE s1 6 Redis` | `(integer) 11` |
| `GETDEL key` | Get the value and delete the key | `GETDEL s1` | `"Hello Redis"` |
| `GETEX key [EX s \| PX ms \| PERSIST]` | Get the value and set or clear its expiry | `GETEX s2 EX 100` | `"v"` |
| `MSETNX key value [key value ...]` | Set all keys only if none exists | `MSETNX m1 a m2 b` | `(integer) 1` |
| `COPY source destination [REPLACE]` | Copy a key; `0` if the destination exists and `REPLACE` is not given | `COPY k2 k3` | `(integer) 1` |

`INCRBYFLOAT` is not supported.

---

## Lists

Lists are ordered sequences of strings. Elements can be pushed and popped from both
ends, making them suitable for queues, stacks, and recent-activity feeds.

### LPUSH

Insert one or more values at the head (left) of a list.

**Syntax:**
```
LPUSH key value [value ...]
```

**Return value:** The length of the list after the push.

```bash
127.0.0.1:6379> LPUSH tasks "send email" "write report"
(integer) 2
127.0.0.1:6379> LRANGE tasks 0 -1
1) "write report"
2) "send email"
```

### RPUSH

Insert one or more values at the tail (right) of a list.

**Syntax:**
```
RPUSH key value [value ...]
```

**Return value:** The length of the list after the push.

```bash
127.0.0.1:6379> RPUSH queue "job1" "job2" "job3"
(integer) 3
```

### LPOP

Remove and return the first element of a list.

**Syntax:**
```
LPOP key
```

**Return value:** The removed element, or `nil` if the list is empty or does not exist.

```bash
127.0.0.1:6379> RPUSH queue "a" "b" "c"
(integer) 3
127.0.0.1:6379> LPOP queue
"a"
```

### RPOP

Remove and return the last element of a list.

**Syntax:**
```
RPOP key
```

**Return value:** The removed element, or `nil` if the list is empty or does not exist.

```bash
127.0.0.1:6379> RPUSH stack "x" "y" "z"
(integer) 3
127.0.0.1:6379> RPOP stack
"z"
```

### LLEN

Get the number of elements in a list.

**Syntax:**
```
LLEN key
```

**Return value:** The length of the list, or `0` if the key does not exist.

```bash
127.0.0.1:6379> RPUSH items "a" "b" "c"
(integer) 3
127.0.0.1:6379> LLEN items
(integer) 3
```

### LRANGE

Get a range of elements from a list. Indices are zero-based; negative indices count
from the end (-1 is the last element).

**Syntax:**
```
LRANGE key start stop
```

**Return value:** An array of elements in the specified range.

```bash
127.0.0.1:6379> RPUSH colors "red" "green" "blue" "yellow"
(integer) 4
127.0.0.1:6379> LRANGE colors 0 -1
1) "red"
2) "green"
3) "blue"
4) "yellow"
127.0.0.1:6379> LRANGE colors 1 2
1) "green"
2) "blue"
```

### LINDEX

Get an element by its index in a list.

**Syntax:**
```
LINDEX key index
```

**Return value:** The element at the specified index, or `nil` if out of range.

```bash
127.0.0.1:6379> RPUSH letters "a" "b" "c"
(integer) 3
127.0.0.1:6379> LINDEX letters 0
"a"
127.0.0.1:6379> LINDEX letters -1
"c"
```

### LSET

Set the value of an element at a specific index in a list.

**Syntax:**
```
LSET key index value
```

**Return value:** `OK` on success. Returns an error if the index is out of range.

```bash
127.0.0.1:6379> RPUSH fruits "apple" "banana" "cherry"
(integer) 3
127.0.0.1:6379> LSET fruits 1 "blueberry"
OK
127.0.0.1:6379> LRANGE fruits 0 -1
1) "apple"
2) "blueberry"
3) "cherry"
```

### More list commands

| Command | What it does | Example | Reply |
|---|---|---|---|
| `LPUSHX` / `RPUSHX key value [value ...]` | Push only if the list exists | `LPUSHX nolist a` | `(integer) 0` |
| `LINSERT key BEFORE\|AFTER pivot value` | Insert next to the first `pivot` | `LINSERT l BEFORE c x` | `(integer) 4` |
| `LREM key count value` | Remove up to `count` occurrences | `LREM l 1 b` | `(integer) 1` |
| `LTRIM key start stop` | Keep only the given range | `LTRIM l 0 1` | `OK` |
| `LPOS key value` | Index of the first match | `LPOS l b` on `a b c b` | `(integer) 1` |
| `LMOVE src dst LEFT\|RIGHT LEFT\|RIGHT` | Pop from one list, push to another | `LMOVE l l2 LEFT RIGHT` | `"a"` |
| `RPOPLPUSH src dst` | Same as `LMOVE src dst RIGHT LEFT` | `RPOPLPUSH l l2` | `"z"` |
| `BLPOP` / `BRPOP key [key ...] timeout`, `BLMOVE`, `BRPOPLPUSH` | Same as the non-blocking form, but **do not wait**: they return `nil` at once when the list is empty | `BLPOP l2 1` | `1) "l2"  2) "z"` |

`LPOP` and `RPOP` remove one element; the optional `count` argument is not supported.

---

## Sets

Sets are unordered collections of unique strings. They support membership tests,
intersections, unions, and differences.

### SADD

Add one or more members to a set.

**Syntax:**
```
SADD key member [member ...]
```

**Return value:** The number of members that were added (excluding already-present members).

```bash
127.0.0.1:6379> SADD tags "rust" "database" "olap"
(integer) 3
127.0.0.1:6379> SADD tags "rust"
(integer) 0
```

### SMEMBERS

Get all members of a set.

**Syntax:**
```
SMEMBERS key
```

**Return value:** An array of all members, in no particular order.

```bash
127.0.0.1:6379> SADD colors "red" "blue" "green"
(integer) 3
127.0.0.1:6379> SMEMBERS colors
1) "green"
2) "blue"
3) "red"
```

### SISMEMBER

Test if a value is a member of a set.

**Syntax:**
```
SISMEMBER key member
```

**Return value:** `1` if the member exists, `0` otherwise.

```bash
127.0.0.1:6379> SADD fruits "apple" "banana"
(integer) 2
127.0.0.1:6379> SISMEMBER fruits "apple"
(integer) 1
127.0.0.1:6379> SISMEMBER fruits "cherry"
(integer) 0
```

### SREM

Remove one or more members from a set.

**Syntax:**
```
SREM key member [member ...]
```

**Return value:** The number of members that were removed.

```bash
127.0.0.1:6379> SADD myset "a" "b" "c"
(integer) 3
127.0.0.1:6379> SREM myset "b"
(integer) 1
127.0.0.1:6379> SMEMBERS myset
1) "c"
2) "a"
```

### SCARD

Get the number of members in a set.

**Syntax:**
```
SCARD key
```

**Return value:** The cardinality (number of elements) of the set.

```bash
127.0.0.1:6379> SADD otherset "a" "b" "c"
(integer) 3
127.0.0.1:6379> SCARD otherset
(integer) 3
```

### SUNION

Return the union of multiple sets.

**Syntax:**
```
SUNION key [key ...]
```

**Return value:** An array of members in the resulting union.

```bash
127.0.0.1:6379> SADD set1 "a" "b" "c"
(integer) 3
127.0.0.1:6379> SADD set2 "b" "c" "d"
(integer) 3
127.0.0.1:6379> SUNION set1 set2
1) "c"
2) "a"
3) "b"
4) "d"
```

### SINTER

Return the intersection of multiple sets.

**Syntax:**
```
SINTER key [key ...]
```

**Return value:** An array of members present in all given sets.

```bash
127.0.0.1:6379> SADD set1 "a" "b" "c"
(integer) 3
127.0.0.1:6379> SADD set2 "b" "c" "d"
(integer) 3
127.0.0.1:6379> SINTER set1 set2
1) "c"
2) "b"
```

### SDIFF

Return the difference between the first set and all subsequent sets.

**Syntax:**
```
SDIFF key [key ...]
```

**Return value:** An array of members in the first set that are not in any other set.

```bash
127.0.0.1:6379> SADD set1 "a" "b" "c"
(integer) 3
127.0.0.1:6379> SADD set2 "b" "c" "d"
(integer) 3
127.0.0.1:6379> SDIFF set1 set2
1) "a"
```

### More set commands

| Command | What it does | Example | Reply |
|---|---|---|---|
| `SMISMEMBER key member [member ...]` | Membership of several members | `SMISMEMBER sa a z` | `1) (integer) 1  2) (integer) 0` |
| `SPOP key [count]` | Remove and return random members | `SPOP sp 2` | two members |
| `SRANDMEMBER key [count]` | Random members without removing them | `SRANDMEMBER sb` | one member |
| `SMOVE src dst member` | Move a member between sets | `SMOVE sa sb a` | `(integer) 1` |
| `SUNIONSTORE` / `SINTERSTORE dst key [key ...]` | Store the union / intersection; returns its size | `SINTERSTORE si sa sb` | `(integer) 2` |
| `SINTERCARD numkeys key [key ...]` | Size of the intersection | `SINTERCARD 2 sa sb` | `(integer) 2` |
| `SSCAN key cursor [MATCH pattern] [COUNT n]` | Iterate members with a cursor | `SSCAN sb 0` | `1) "0"  2) members` |

`SDIFFSTORE` is not supported.

---

## Sorted Sets

Sorted sets associate a floating-point **score** with each member. Members are unique
and ordered by score, enabling range queries and leaderboard-style access patterns.

### ZADD

Add one or more members with scores to a sorted set.

**Syntax:**
```
ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member ...]
```

- `NX` only adds new members; `XX` only updates existing ones.
- `GT` / `LT` update an existing member only if the new score is greater / less
  (new members are still added).
- `CH` makes the reply count changed members as well as added ones.
- `INCR` adds the score to the member's current score (one pair only) and
  returns the new score, or `nil` if a flag prevented the update.

Scores accept decimal or scientific notation (`1.5E3`) and `-inf` / `+inf`;
`NaN` is refused.

**Return value:** The number of members added (plus changed ones with `CH`), or the
new score with `INCR`.

```bash
127.0.0.1:6379> ZADD leaderboard 100 "alice" 85 "bob" 92 "charlie"
(integer) 3
127.0.0.1:6379> ZADD leaderboard NX 1 "alice" 70 "dave"
(integer) 1
127.0.0.1:6379> ZADD leaderboard XX CH 101 "alice"
(integer) 1
```

### ZSCORE

Get the score of a member in a sorted set.

**Syntax:**
```
ZSCORE key member
```

**Return value:** The score as a string, or `nil` if the member does not exist.

```bash
127.0.0.1:6379> ZSCORE leaderboard "alice"
"100"
```

### ZRANK

Get the rank (zero-based index) of a member, ordered from lowest to highest score.

**Syntax:**
```
ZRANK key member
```

**Return value:** The rank as an integer, or `nil` if the member does not exist.

```bash
127.0.0.1:6379> ZADD leaderboard 100 "alice" 85 "bob" 92 "charlie"
(integer) 3
127.0.0.1:6379> ZRANK leaderboard "bob"
(integer) 0
127.0.0.1:6379> ZRANK leaderboard "alice"
(integer) 2
```

### ZRANGE

Get a range of members by index (low to high score). Use `WITHSCORES` to include scores
in the output.

**Syntax:**
```
ZRANGE key start stop [WITHSCORES]
```

Only the index form is supported. The `BYSCORE`, `BYLEX`, `REV` and `LIMIT`
options are not supported; use `ZRANGEBYSCORE`, `ZREVRANGEBYSCORE` and `ZREVRANGE`.

**Return value:** An array of members (and optionally their scores).

```bash
127.0.0.1:6379> ZADD leaderboard 100 "alice" 85 "bob" 92 "charlie"
(integer) 3
127.0.0.1:6379> ZRANGE leaderboard 0 -1
1) "bob"
2) "charlie"
3) "alice"
127.0.0.1:6379> ZRANGE leaderboard 0 -1 WITHSCORES
1) "bob"
2) "85"
3) "charlie"
4) "92"
5) "alice"
6) "100"
```

### ZRANGEBYSCORE

Get members with scores within a given range. Use `-inf` and `+inf` for unbounded
ranges. Prefix a value with `(` for an exclusive bound.

**Syntax:**
```
ZRANGEBYSCORE key min max [WITHSCORES] [LIMIT offset count]
```

**Return value:** An array of members in the score range.

```bash
127.0.0.1:6379> ZADD temps 32.5 "NYC" 28.1 "LA" 35.0 "Phoenix" 22.3 "Seattle"
(integer) 4
127.0.0.1:6379> ZRANGEBYSCORE temps 25 33
1) "LA"
2) "NYC"
127.0.0.1:6379> ZRANGEBYSCORE temps -inf +inf WITHSCORES
1) "Seattle"
2) "22.3"
3) "LA"
4) "28.1"
5) "NYC"
6) "32.5"
7) "Phoenix"
8) "35"
```

### ZREVRANGEBYSCORE

Like `ZRANGEBYSCORE`, highest score first. Note the bounds are given `max` then `min`.

**Syntax:**
```
ZREVRANGEBYSCORE key max min [WITHSCORES] [LIMIT offset count]
```

```bash
127.0.0.1:6379> ZREVRANGEBYSCORE temps +inf (30 LIMIT 0 1
1) "Phoenix"
```

### ZCOUNT

Count the members with a score in a range (same bound syntax as `ZRANGEBYSCORE`).

**Syntax:**
```
ZCOUNT key min max
```

```bash
127.0.0.1:6379> ZCOUNT temps (22.3 +inf
(integer) 3
```

### ZREMRANGEBYSCORE

Remove every member with a score in a range.

**Syntax:**
```
ZREMRANGEBYSCORE key min max
```

**Return value:** The number of members removed.

```bash
127.0.0.1:6379> ZREMRANGEBYSCORE temps -inf (25
(integer) 1
```

### ZREMRANGEBYRANK

Remove every member in a rank range (zero-based, negative counts from the highest).

**Syntax:**
```
ZREMRANGEBYRANK key start stop
```

**Return value:** The number of members removed.

```bash
127.0.0.1:6379> ZREMRANGEBYRANK temps -1 -1
(integer) 1
```

### ZREM

Remove one or more members from a sorted set.

**Syntax:**
```
ZREM key member [member ...]
```

**Return value:** The number of members removed.

```bash
127.0.0.1:6379> ZADD scores 10 "a" 20 "b" 30 "c"
(integer) 3
127.0.0.1:6379> ZREM scores "b"
(integer) 1
```

### ZCARD

Get the number of members in a sorted set.

**Syntax:**
```
ZCARD key
```

**Return value:** The cardinality of the sorted set.

```bash
127.0.0.1:6379> ZADD scores 10 "a" 20 "b" 30 "c"
(integer) 3
127.0.0.1:6379> ZCARD scores
(integer) 3
```

### More sorted-set commands

| Command | What it does | Example (`z` = `a:1 b:2 c:3`) | Reply |
|---|---|---|---|
| `ZINCRBY key increment member` | Add to a member's score | `ZINCRBY z 5 a` | `"6"` |
| `ZMSCORE key member [member ...]` | Scores of several members | `ZMSCORE z a b nope` | `"6"`, `"2"`, `(nil)` |
| `ZREVRANK key member` | Rank from the highest score | `ZREVRANK z a` | `(integer) 0` |
| `ZREVRANGE key start stop [WITHSCORES]` | Index range, highest score first | `ZREVRANGE z 0 -1` | `"a"`, `"c"`, `"b"` |
| `ZPOPMIN` / `ZPOPMAX key [count]` | Remove and return the lowest / highest members | `ZPOPMIN z` | `1) "b"  2) "2"` |
| `ZRANDMEMBER key` | A random member | `ZRANDMEMBER z` | one member |
| `ZLEXCOUNT key min max` | Count members in a lexical range (equal scores) | `ZLEXCOUNT zl [a [b` | `(integer) 2` |
| `ZUNIONSTORE` / `ZINTERSTORE dst numkeys key [key ...]` | Store the union / intersection; returns its size | `ZINTERSTORE zi 2 z z2` | `(integer) 1` |
| `ZINTERCARD numkeys key [key ...]` | Size of the intersection | `ZINTERCARD 2 z z2` | `(integer) 1` |
| `ZSCAN key cursor [MATCH pattern] [COUNT n]` | Iterate members and scores with a cursor | `ZSCAN z 0` | `1) "0"  2) members and scores` |

`ZRANGEBYLEX`, `ZUNION` and `ZDIFF` are not supported.

---

## Hashes

Hashes map field names to values within a single key. They are ideal for representing
objects (e.g., user profiles, configuration entries).

### HSET

Set one or more fields in a hash.

**Syntax:**
```
HSET key field value [field value ...]
```

**Return value:** The number of fields that were added (not updated).

```bash
127.0.0.1:6379> HSET user:1 name "Alice" email "alice@example.com" age "30"
(integer) 3
```

### HGET

Get the value of a single field in a hash.

**Syntax:**
```
HGET key field
```

**Return value:** The value of the field, or `nil` if the field or key does not exist.

```bash
127.0.0.1:6379> HGET user:1 name
"Alice"
127.0.0.1:6379> HGET user:1 nonexistent
(nil)
```

### HGETALL

Get all fields and values in a hash.

**Syntax:**
```
HGETALL key
```

**Return value:** An array of alternating field names and values.

```bash
127.0.0.1:6379> HSET user:1 name "Alice" email "alice@example.com"
(integer) 2
127.0.0.1:6379> HGETALL user:1
1) "name"
2) "Alice"
3) "email"
4) "alice@example.com"
```

### HDEL

Delete one or more fields from a hash.

**Syntax:**
```
HDEL key field [field ...]
```

**Return value:** The number of fields that were removed.

```bash
127.0.0.1:6379> HSET user:1 name "Alice" tmp "delete_me"
(integer) 2
127.0.0.1:6379> HDEL user:1 tmp
(integer) 1
```

### HEXISTS

Check if a field exists in a hash.

**Syntax:**
```
HEXISTS key field
```

**Return value:** `1` if the field exists, `0` otherwise.

```bash
127.0.0.1:6379> HSET user:1 name "Alice"
(integer) 1
127.0.0.1:6379> HEXISTS user:1 name
(integer) 1
127.0.0.1:6379> HEXISTS user:1 phone
(integer) 0
```

### HKEYS

Get all field names in a hash.

**Syntax:**
```
HKEYS key
```

**Return value:** An array of field names.

```bash
127.0.0.1:6379> HSET config host "localhost" port "6379"
(integer) 2
127.0.0.1:6379> HKEYS config
1) "host"
2) "port"
```

### HVALS

Get all values in a hash.

**Syntax:**
```
HVALS key
```

**Return value:** An array of values.

```bash
127.0.0.1:6379> HSET config host "localhost" port "6379"
(integer) 2
127.0.0.1:6379> HVALS config
1) "localhost"
2) "6379"
```

### HLEN

Get the number of fields in a hash.

**Syntax:**
```
HLEN key
```

**Return value:** The number of fields.

```bash
127.0.0.1:6379> HSET user:1 name "Alice" email "alice@example.com" age "30"
(integer) 3
127.0.0.1:6379> HLEN user:1
(integer) 3
```

### HINCRBY

Increment the integer value of a hash field by a given amount.

**Syntax:**
```
HINCRBY key field increment
```

**Return value:** The value after the increment.

```bash
127.0.0.1:6379> HSET user:1 login_count 10
(integer) 1
127.0.0.1:6379> HINCRBY user:1 login_count 1
(integer) 11
```

### HMSET

Set multiple fields in a hash. Functionally identical to `HSET` with multiple
field-value pairs (provided for compatibility).

**Syntax:**
```
HMSET key field value [field value ...]
```

**Return value:** `OK`.

```bash
127.0.0.1:6379> HMSET user:2 name "Bob" email "bob@example.com"
OK
```

### HMGET

Get the values of multiple fields in a hash.

**Syntax:**
```
HMGET key field [field ...]
```

**Return value:** An array of values (or `nil` for fields that do not exist).

```bash
127.0.0.1:6379> HSET user:1 name "Alice" email "alice@example.com" age "30"
(integer) 3
127.0.0.1:6379> HMGET user:1 name age phone
1) "Alice"
2) "30"
3) (nil)
```

### HSETNX

Set the value of a hash field only if the field does not already exist.

**Syntax:**
```
HSETNX key field value
```

**Return value:** `1` if the field was set, `0` if it already existed.

```bash
127.0.0.1:6379> HSETNX user:1 name "Alice"
(integer) 1
127.0.0.1:6379> HSETNX user:1 name "Bob"
(integer) 0
127.0.0.1:6379> HGET user:1 name
"Alice"
```

### More hash commands

| Command | What it does | Example | Reply |
|---|---|---|---|
| `HSTRLEN key field` | Length of a field's value | `HSTRLEN h a` | `(integer) 1` |
| `HRANDFIELD key [count [WITHVALUES]]` | Random fields | `HRANDFIELD hh 2 WITHVALUES` | two fields and values |
| `HSCAN key cursor [MATCH pattern] [COUNT n]` | Iterate fields and values with a cursor | `HSCAN hh 0 MATCH f*` | `1) "0"  2) "f1" "1" "f2" "2"` |

`HINCRBYFLOAT` is not supported.

---

## Streams

Streams are append-only logs. Each entry has an ID and a set of field-value pairs.
Streams support appends, range queries, reads and trimming. Consumer groups are not supported.

**Not supported:** `XREAD … BLOCK` returns immediately instead of waiting; poll from the last ID you processed. `XCLAIM`, `XAUTOCLAIM`, `XINFO GROUPS` and `XINFO CONSUMERS` return an error.

### XADD

Append an entry to a stream. Use `*` to auto-generate the entry ID.

**Syntax:**
```
XADD key [NOMKSTREAM] [MAXLEN|MINID [=|~] threshold [LIMIT count]] id field value [field value ...]
```

A stream is never trimmed unless you pass `MAXLEN` or `MINID`; with neither it
keeps every entry you add. Trimming works as in [`XTRIM`](#xtrim).

**Return value:** The ID of the added entry.

```bash
127.0.0.1:6379> XADD events * action "click" page "/home"
"1679012345678-0"
127.0.0.1:6379> XADD events * action "scroll" page "/about"
"1679012345679-0"
```

### XLEN

Get the number of entries in a stream.

**Syntax:**
```
XLEN key
```

**Return value:** The number of entries.

```bash
127.0.0.1:6379> XLEN events
(integer) 2
```

### XRANGE

Get entries in a stream within an ID range. Use `-` for the minimum ID and `+` for the
maximum.

**Syntax:**
```
XRANGE key start end [COUNT count]
```

**Return value:** An array of entries, each containing its ID and field-value pairs.

```bash
127.0.0.1:6379> XRANGE events - +
1) 1) "1679012345678-0"
   2) 1) "action"
      2) "click"
      3) "page"
      4) "/home"
2) 1) "1679012345679-0"
   2) 1) "action"
      2) "scroll"
      3) "page"
      4) "/about"
127.0.0.1:6379> XRANGE events - + COUNT 1
1) 1) "1679012345678-0"
   2) 1) "action"
      2) "click"
      3) "page"
      4) "/home"
```

### XREVRANGE

Get entries in reverse order (highest to lowest ID).

**Syntax:**
```
XREVRANGE key end start [COUNT count]
```

**Return value:** An array of entries in reverse order.

```bash
127.0.0.1:6379> XREVRANGE events + - COUNT 1
1) 1) "1679012345679-0"
   2) 1) "action"
      2) "scroll"
      3) "page"
      4) "/about"
```

### XREAD

Read entries from one or more streams with an ID greater than the one given.

**Syntax:**
```
XREAD [COUNT count] [BLOCK milliseconds] STREAMS key [key ...] id [id ...]
```

`BLOCK` is accepted but does not wait: when no entry is newer than the given ID, the
command returns `nil` at once. To follow a stream, poll with the last ID you have read.

**Return value:** An array of stream results, each containing the stream key and its
entries, or `nil` if there are no newer entries.

```bash
# Read up to 10 entries from "events" starting after ID 0
127.0.0.1:6379> XREAD COUNT 10 STREAMS events 0
1) 1) "events"
   2) 1) 1) "1679012345678-0"
         2) 1) "action"
            2) "click"
            3) "page"
            4) "/home"
      2) 1) "1679012345679-0"
         2) 1) "action"
            2) "scroll"
            3) "page"
            4) "/about"
```

### XTRIM

Trim a stream, removing the oldest entries.

**Syntax:**
```
XTRIM key MAXLEN|MINID [=|~] threshold [LIMIT count]
```

`MAXLEN n` keeps the newest `n` entries; `MINID id` removes every entry with an
ID lower than `id`. `~` is accepted, but ParticleDB always trims exactly to the
threshold (Redis may keep a few more). `LIMIT count` caps how many entries one
call removes and is only accepted together with `~`.

**Return value:** The number of entries removed.

```bash
127.0.0.1:6379> XTRIM events MAXLEN 1000
(integer) 0
127.0.0.1:6379> XTRIM events MAXLEN ~ 1000
(integer) 0
```

### XINFO STREAM

Get information about a stream.

**Syntax:**
```
XINFO STREAM key
```

**Return value:** The stream's length and its first and last entries. Other `XINFO`
subcommands (`GROUPS`, `CONSUMERS`) are not supported.

```bash
127.0.0.1:6379> XINFO STREAM events
1) "length"
2) (integer) 2
3) "first-entry"
4) 1) "1679012345678-0"
   2) 1) "action"
      2) "click"
      3) "page"
      4) "/home"
5) "last-entry"
6) 1) "1679012345679-0"
   2) 1) "action"
      2) "scroll"
      3) "page"
      4) "/about"
```

### XDEL

Delete entries by ID.

**Syntax:**
```
XDEL key id [id ...]
```

**Return value:** The number of entries deleted.

### Consumer groups

`XGROUP`, `XREADGROUP`, `XACK`, `XPENDING`, `XCLAIM` and `XAUTOCLAIM` are not supported. Read with `XREAD` or `XRANGE` and store your application's last processed entry ID. Reconcile the processing result and checkpoint in your application; there is no server-managed consumer-group acknowledgement state.

---

## HyperLogLog

Use HyperLogLog commands to estimate distinct element counts. Validate the estimate and error tolerance for your dataset before relying on it.

| Command | What it does | Example | Reply |
|---|---|---|---|
| `PFADD key element [element ...]` | Add elements; `1` if the estimate changed | `PFADD hll a b c` | `(integer) 1` |
| `PFCOUNT key [key ...]` | Estimated distinct count (of the union, for several keys) | `PFCOUNT hll` | `(integer) 3` |
| `PFMERGE dest key [key ...]` | Merge into `dest` | `PFMERGE hllm hll hll2` | `OK` |

---

## Geo

Geo commands store named longitude/latitude points in a sorted set. Coordinates are longitude first, then latitude; keep units explicit when requesting a distance.

| Command | What it does |
|---|---|
| `GEOADD key longitude latitude member [...]` | Add points; returns how many were new. |
| `GEODIST key member1 member2 [m\|km\|mi\|ft]` | Distance between two members (default meters). |
| `GEOPOS key member [member ...]` | Coordinates of members. |

```bash
127.0.0.1:6379> GEOADD geo 13.361389 38.115556 Palermo 15.087269 37.502669 Catania
(integer) 2
127.0.0.1:6379> GEODIST geo Palermo Catania km
"166.2742"
```

`GEOSEARCH`, `GEORADIUS`, `GEORADIUSBYMEMBER` and `GEOHASH` are not supported.

`GEOPOS geo Palermo Catania` reads the stored coordinates. A geodesic distance is not a road-route distance; validate coordinate ranges and null handling at the application boundary.

The SQL interface does not provide the PostGIS extension: `ST_Point` and `ST_Distance` are not available. For location calculations in SQL, use a tested [Python Particle](/particles/overview/).

---

## Keys

Key commands operate on keys regardless of the underlying data type.

### DEL

Delete one or more keys.

**Syntax:**
```
DEL key [key ...]
```

**Return value:** The number of keys that were deleted.

```bash
127.0.0.1:6379> SET a 1
OK
127.0.0.1:6379> SET b 2
OK
127.0.0.1:6379> DEL a b nonexistent
(integer) 2
```

### EXISTS

Check if one or more keys exist.

**Syntax:**
```
EXISTS key [key ...]
```

**Return value:** The number of specified keys that exist.

```bash
127.0.0.1:6379> SET mykey "hello"
OK
127.0.0.1:6379> EXISTS mykey
(integer) 1
127.0.0.1:6379> EXISTS mykey otherkey
(integer) 1
```

### TYPE

Get the data type of a key.

**Syntax:**
```
TYPE key
```

**Return value:** One of `string`, `list`, `set`, `zset`, `hash`, `stream`, or `none`.

```bash
127.0.0.1:6379> SET name "Alice"
OK
127.0.0.1:6379> TYPE name
string
127.0.0.1:6379> LPUSH mylist "a"
(integer) 1
127.0.0.1:6379> TYPE mylist
list
```

### KEYS

Find all keys matching a glob-style pattern. Use `*` to match all keys.

**Syntax:**
```
KEYS pattern
```

**Return value:** An array of matching keys.

```bash
127.0.0.1:6379> SET user:1 "Alice"
OK
127.0.0.1:6379> SET user:2 "Bob"
OK
127.0.0.1:6379> SET order:1 "pending"
OK
127.0.0.1:6379> KEYS user:*
1) "user:1"
2) "user:2"
127.0.0.1:6379> KEYS *
1) "user:1"
2) "user:2"
3) "order:1"
```

`KEYS` scans every key. On large datasets use `SCAN` for incremental iteration instead.

### SCAN

Incrementally iterate over keys using a cursor. Returns a new cursor and a batch of
keys; pass the returned cursor to the next call until the cursor is `0`.

**Syntax:**
```
SCAN cursor [MATCH pattern] [COUNT hint]
```

**Return value:** A two-element array: the next cursor and an array of keys.

```bash
127.0.0.1:6379> SCAN 0 MATCH user:* COUNT 100
1) "0"
2) 1) "user:1"
   2) "user:2"
```

### TTL

Get the remaining time to live (in seconds) for a key with an expiration.

**Syntax:**
```
TTL key
```

**Return value:** TTL in seconds, `-1` if the key has no expiration, `-2` if the key
does not exist.

```bash
127.0.0.1:6379> SET session "abc" EX 300
OK
127.0.0.1:6379> TTL session
(integer) 299
127.0.0.1:6379> SET permanent_key "value"
OK
127.0.0.1:6379> TTL permanent_key
(integer) -1
```

### PTTL

Get the remaining time to live in **milliseconds**.

**Syntax:**
```
PTTL key
```

**Return value:** TTL in milliseconds, `-1` if no expiration, `-2` if key does not exist.

```bash
127.0.0.1:6379> SET session "abc" PX 60000
OK
127.0.0.1:6379> PTTL session
(integer) 59985
```

### EXPIRE

Set an expiration (in seconds) on an existing key.

**Syntax:**
```
EXPIRE key seconds
```

**Return value:** `1` if the timeout was set, `0` if the key does not exist.

`EXPIRE`, `PEXPIRE`, `EXPIREAT` and `PEXPIREAT` work on keys of every type (string,
list, set, sorted set, hash, stream), and the expiry is durable. A time in the past
deletes the key. The Redis 7 options `NX`, `XX`, `GT` and `LT` are not supported and
return an error.

```bash
127.0.0.1:6379> SET mykey "hello"
OK
127.0.0.1:6379> EXPIRE mykey 60
(integer) 1
127.0.0.1:6379> TTL mykey
(integer) 59
```

### PERSIST

Remove the expiration from a key, making it persist indefinitely.

**Syntax:**
```
PERSIST key
```

**Return value:** `1` if the timeout was removed, `0` if the key does not exist or had
no timeout.

```bash
127.0.0.1:6379> SET temp "data" EX 100
OK
127.0.0.1:6379> PERSIST temp
(integer) 1
127.0.0.1:6379> TTL temp
(integer) -1
```

### RENAME

Rename a key. If the destination key already exists, it is overwritten.

**Syntax:**
```
RENAME key newkey
```

**Return value:** `OK` on success. Returns an error if the source key does not exist.

```bash
127.0.0.1:6379> SET old_name "value"
OK
127.0.0.1:6379> RENAME old_name new_name
OK
127.0.0.1:6379> GET new_name
"value"
```

### RANDOMKEY

Return a random key from the current database.

**Syntax:**
```
RANDOMKEY
```

**Return value:** A random key, or `nil` if the database is empty.

```bash
127.0.0.1:6379> RANDOMKEY
"user:1"
```

### More key commands

| Command | What it does | Example | Reply |
|---|---|---|---|
| `UNLINK key [key ...]` | Same as `DEL` | `UNLINK kx` | `(integer) 1` |
| `TOUCH key [key ...]` | Number of the keys that exist | `TOUCH kx` | `(integer) 1` |
| `PEXPIRE key milliseconds` | Set a timeout in milliseconds | `PEXPIRE kx 100000` | `(integer) 1` |
| `EXPIREAT` / `PEXPIREAT key unix-time` | Expire at a Unix time (seconds / milliseconds) | `EXPIREAT kx 4102444800` | `(integer) 1` |
| `EXPIRETIME` / `PEXPIRETIME key` | The absolute expiry time; `-1` none, `-2` missing key | `EXPIRETIME kx` | `(integer) 4102444800` |

`RENAMENX`, `SORT`, `DUMP` and `RESTORE` are not supported.

---

## Pub/Sub

Publish/Subscribe messaging allows clients to subscribe to channels and receive
messages published by other clients in real time.

### SUBSCRIBE

Subscribe to one or more channels. The client enters a subscription mode and receives
messages as they are published.

**Syntax:**
```
SUBSCRIBE channel [channel ...]
```

**Return value:** Subscription confirmation messages, then incoming messages as they arrive.

A subscriber that does not read its messages fast enough is disconnected once more
than 32 MB of messages are queued for it (the same policy as Redis's
`client-output-buffer-limit pubsub`). Pattern and shard subscriptions (`PSUBSCRIBE`,
`SSUBSCRIBE`) and `PUBSUB` are not supported.

```bash
127.0.0.1:6379> SUBSCRIBE notifications alerts
Reading messages... (press Ctrl-C to quit)
1) "subscribe"
2) "notifications"
3) (integer) 1
1) "subscribe"
2) "alerts"
3) (integer) 2
```

### PUBLISH

Publish a message to a channel. All clients subscribed to that channel will receive it.

**Syntax:**
```
PUBLISH channel message
```

**Return value:** The number of clients that received the message.

```bash
127.0.0.1:6379> PUBLISH notifications "New order received"
(integer) 2
```

### UNSUBSCRIBE

Unsubscribe from one or more channels. If no channels are specified, unsubscribe from
all channels.

**Syntax:**
```
UNSUBSCRIBE [channel [channel ...]]
```

**Return value:** Unsubscription confirmation messages.

```bash
127.0.0.1:6379> UNSUBSCRIBE notifications
1) "unsubscribe"
2) "notifications"
3) (integer) 0
```

---

## Scripting

ParticleDB does not embed a Lua interpreter. `EVAL`, `EVALSHA`, `SCRIPT LOAD` and
`SCRIPT EXISTS` accept a fixed set of built-in scripts, recognized by their exact text
(or its SHA1) and executed natively and atomically:

- the Orkes Conductor Redis queue's `pop_batch.lua` (orkes-redis-queues 1.0.9);
- the Redisson 3.13.3 `RLock` scripts (lock, renew, unlock, force-unlock).

Any other script is refused with `ERR unknown script` (`EVALSHA` of an unknown SHA
returns `NOSCRIPT`). `EVAL_RO`, `EVALSHA_RO`, `SCRIPT FLUSH` and `FUNCTION` are not
supported.

```bash
127.0.0.1:6379> EVAL "return 1" 0
(error) ERR unknown script: ParticleDB does not run Lua; ...
```

---

## Transactions

Redis transactions allow grouping multiple commands into an atomic unit. All commands
between `MULTI` and `EXEC` are queued and executed together. As in Redis, a command
that fails at run time (for example `INCR` on a non-integer) returns its error in
the `EXEC` reply while the other commands still apply. `WATCH` and `UNWATCH` are not
supported.

### MULTI

Start a transaction. Subsequent commands are queued until `EXEC` or `DISCARD`.

**Syntax:**
```
MULTI
```

**Return value:** `OK`.

```bash
127.0.0.1:6379> MULTI
OK
127.0.0.1:6379(TX)> SET balance:alice 100
QUEUED
127.0.0.1:6379(TX)> SET balance:bob 200
QUEUED
127.0.0.1:6379(TX)> EXEC
1) OK
2) OK
```

### EXEC

Execute all queued commands in the transaction.

**Syntax:**
```
EXEC
```

**Return value:** An array of results, one per queued command.

```bash
127.0.0.1:6379> MULTI
OK
127.0.0.1:6379(TX)> INCR counter
QUEUED
127.0.0.1:6379(TX)> INCR counter
QUEUED
127.0.0.1:6379(TX)> EXEC
1) (integer) 1
2) (integer) 2
```

### DISCARD

Discard all queued commands and exit the transaction.

**Syntax:**
```
DISCARD
```

**Return value:** `OK`.

```bash
127.0.0.1:6379> MULTI
OK
127.0.0.1:6379(TX)> SET key "value"
QUEUED
127.0.0.1:6379(TX)> DISCARD
OK
```

---

## Server

Server commands provide administrative and diagnostic capabilities.

### PING

Test connectivity. Returns `PONG` or echoes the provided message.

**Syntax:**
```
PING [message]
```

**Return value:** `PONG`, or the provided message.

```bash
127.0.0.1:6379> PING
PONG
127.0.0.1:6379> PING "hello"
"hello"
```

### ECHO

Echo the given message back to the client.

**Syntax:**
```
ECHO message
```

**Return value:** The message.

```bash
127.0.0.1:6379> ECHO "ParticleDB"
"ParticleDB"
```

### QUIT

Close the connection.

**Syntax:**
```
QUIT
```

**Return value:** `OK`.

```bash
127.0.0.1:6379> QUIT
OK
```

### SELECT

Select the database by index. ParticleDB has a **single** logical database,
database `0`. `SELECT 0` is accepted (many clients send it on connect); any other
index returns an error, as do `MOVE` and `SWAPDB`. Use a key prefix to separate
applications that share one server.

**Syntax:**
```
SELECT index
```

**Return value:** `OK` for index `0`, otherwise an error.

```bash
127.0.0.1:6379> SELECT 0
OK
127.0.0.1:6379> SELECT 1
(error) ERR DB index is out of range: ParticleDB has a single logical database (0)
```

### DBSIZE

Return the number of keys in the currently selected database.

**Syntax:**
```
DBSIZE
```

**Return value:** The number of keys.

```bash
127.0.0.1:6379> DBSIZE
(integer) 42
```

### FLUSHDB

Delete all keys in the currently selected database.

**Syntax:**
```
FLUSHDB
```

**Return value:** `OK`.

```bash
127.0.0.1:6379> FLUSHDB
OK
127.0.0.1:6379> DBSIZE
(integer) 0
```

### FLUSHALL

Delete all keys. ParticleDB has one database, so this is the same as `FLUSHDB`.

**Syntax:**
```
FLUSHALL
```

**Return value:** `OK`.

```bash
127.0.0.1:6379> FLUSHALL
OK
```

### INFO

Return server information: `Server`, `Persistence` and `Keyspace` sections. A
section argument is accepted but does not change the output; there is no `Memory`
section (see [Memory reporting](/connectivity/redis/#memory-reporting)).

**Syntax:**
```
INFO [section]
```

**Return value:** A bulk string of server information.

```bash
127.0.0.1:6379> INFO
# Server
redis_version:7.0.0
...

# Persistence
aof_enabled:1
aof_last_write_status:ok
pdb_resp_commit_mode:async
...

# Keyspace
db0:keys=42,expires=7
```

`redis_version` is the Redis version the server reports compatibility with. `pdb_resp_commit_mode`
reports the current [KV durability](/connectivity/redis/#durability) (`sync` or `async`).

### CONFIG GET

Get the value of a configuration parameter.

**Syntax:**
```
CONFIG GET parameter
```

**Return value:** An array of parameter name and value pairs. Supports glob patterns.
Most values are fixed for client compatibility and do not reflect the server's
configuration; `pdb-kv-durability` is the live
[KV durability setting](/connectivity/redis/#durability).

```bash
127.0.0.1:6379> CONFIG GET maxmemory
1) "maxmemory"
2) "0"
127.0.0.1:6379> CONFIG GET pdb-kv-durability
1) "pdb-kv-durability"
2) "async"
```

### CONFIG SET

`CONFIG SET pdb-kv-durability sync|async` changes KV durability until the next
restart; the startup value comes from `--kv-durability` (default `async`). Other parameters are accepted and ignored.

```bash
127.0.0.1:6379> CONFIG SET pdb-kv-durability async
OK
127.0.0.1:6379> CONFIG SET pdb-kv-durability bogus
(error) ERR invalid value 'bogus' for pdb-kv-durability: expected sync|async
```

### TIME

Return the current server time as a two-element array: Unix timestamp in seconds and
microseconds.

**Syntax:**
```
TIME
```

**Return value:** A two-element array of strings.

```bash
127.0.0.1:6379> TIME
1) "1679012345"
2) "678901"
```

### HELLO

Accepted for client compatibility. The server always answers in RESP2 with its
server information, and ignores the `AUTH` and `SETNAME` options: authenticate
with `AUTH`.

```bash
127.0.0.1:6379> HELLO 3
 1) "server"
 2) "particledb"
 ...
 5) "proto"
 6) (integer) 2
 ...
```

### WAIT

`WAIT numreplicas timeout` returns `0` at once (there are no Redis replicas).

### RESET

Reset the connection state (leave `MULTI`, unsubscribe). Replies `RESET`.

### AUTH

Authenticate as a ParticleDB user. Required when the server runs with
authentication. The one-argument form authenticates as a user named `default`,
so it succeeds only if such a user exists; use the two-argument form with your
user name.

**Syntax:**
```
AUTH password
AUTH username password
```

**Return value:** `OK` on success. Returns an error if the credentials are invalid.

```bash
127.0.0.1:6379> AUTH admin my_secret_password
OK
127.0.0.1:6379> AUTH admin wrong
(error) WRONGPASS invalid username-password pair or user is disabled.
```

---

## Notes

- For production workloads, use `SCAN` instead of `KEYS` to avoid blocking the server
  on large keyspaces.
- Redis keys are durable and visible to SQL; see
  [Redis Compatibility](/connectivity/redis/).

## Related

[Documentation home](/docs/) · [Troubleshooting](/guides/troubleshooting/)
