BZPOPMAX

Summary: Removes and returns the member with the highest score from one or more sorted sets. Blocks until a member available otherwise. Deletes the sorted set if the last element was popped.

Overview

This command's behavior varies in clustered Redis environments. See the [multi-key operations]() page for more information.

`BZPOPMAX` is the blocking variant of the sorted set [`ZPOPMAX`]() primitive.

It is the blocking version because it blocks the connection when there are no
members to pop from any of the given sorted sets.
A member with the highest score is popped from first sorted set that is
non-empty, with the given keys being checked in the order that they are given.

The `timeout` argument is interpreted as a double value specifying the maximum
number of seconds to block. A timeout of zero can be used to block indefinitely.

See the [BZPOPMIN documentation][cb] for the exact semantics, since `BZPOPMAX`
is identical to [`BZPOPMIN`]() with the only difference being that it pops members
with the highest scores instead of popping the ones with the lowest scores.

[cb]: /commands/bzpopmin

Examples

[code example]

Return information

**RESP2:**

One of the following:
* [Nil reply](../../develop/reference/protocol-spec#bulk-strings): when no element could be popped and the _timeout_ expired.
* [Array reply](../../develop/reference/protocol-spec#arrays): the keyname, popped member, and its score.

**RESP3:**

One of the following:
* [Null reply](../../develop/reference/protocol-spec#nulls): when no element could be popped and the _timeout_ expired.
* [Array reply](../../develop/reference/protocol-spec#arrays): the keyname, popped member, and its score.

redis> DEL zset1 zset2
(integer) 0
redis> ZADD zset1 0 a 1 b 2 c
(integer) 3
redis> BZPOPMAX zset1 zset2 0
1) "zset1"
2) "c"
3) "2"


BZPOPMIN

Summary: Removes and returns the member with the lowest score from one or more sorted sets. Blocks until a member is available otherwise. Deletes the sorted set if the last element was popped.

Overview

This command's behavior varies in clustered Redis environments. See the [multi-key operations]() page for more information.

`BZPOPMIN` is the blocking variant of the sorted set [`ZPOPMIN`]() primitive.

It is the blocking version because it blocks the connection when there are no
members to pop from any of the given sorted sets.
A member with the lowest score is popped from first sorted set that is
non-empty, with the given keys being checked in the order that they are given.

The `timeout` argument is interpreted as a double value specifying the maximum
number of seconds to block. A timeout of zero can be used to block indefinitely.

See the [BLPOP documentation][cl] for the exact semantics, since `BZPOPMIN` is
identical to [`BLPOP`]() with the only difference being the data structure being
popped from.

[cl]: /commands/blpop

Examples

[code example]

Redis Software and Redis Cloud compatibility

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Standard
<nobr>✅ Active-Active</nobr> | ✅ Standard
<nobr>✅ Active-Active</nobr> |  |

Return information

redis> DEL zset1 zset2
(integer) 0
redis> ZADD zset1 0 a 1 b 2 c
(integer) 3
redis> BZPOPMIN zset1 zset2 0
1) "zset1"
2) "a"
3) "0"


CF.ADD

Summary: Adds an item to a Cuckoo Filter

Overview

Adds an item to the cuckoo filter.

Cuckoo filters can contain the same item multiple times, and consider each addition as separate.
Use [`CF.ADDNX`]() to add an item only if it does not exist.

Required arguments

key

is key name for a cuckoo filter to add the item to.

If `key` does not exist - a new cuckoo filter is created.

item

is an item to add.

Complexity

O(n + i), where n is the number of `sub-filters` and i is `maxIterations`.
Adding items requires up to 2 memory accesses per `sub-filter`.
But as the filter fills up, both locations for an item might be full.
The filter attempts to `Cuckoo` swap items up to `maxIterations` times.

Examples

redis> CF.ADD cf item1
(integer) 1
redis> CF.ADD cf item1
(integer) 1

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Supported
 | <nobr>✅ Flexible & Annual</nobr>
✅ Free & Fixed</nobr> |  |

Return information

**RESP2:**

One of the following:
* [Integer reply](): `1` for successfully adding an item to the filter.
* [Simple error reply]() in these cases: invalid arguments, wrong key type, or when the filter is full.

**RESP3:**

One of the following:
* [Boolean reply](): `true` for successfully adding an item to the filter.
* [Simple error reply]() in these cases: invalid arguments, wrong key type, or when the filter is full.


CF.ADDNX

Summary: Adds an item to a Cuckoo Filter if the item did not exist previously.

Overview

Adds an item to a cuckoo filter if the item does not exist.

This command is similar to the combination of [`CF.EXISTS`]() and [`CF.ADD`](). It does not add an item into the filter if its fingerprint already exists.

<note><b>Notes:</b>

- This command is slower than [`CF.ADD`]() because it first checks whether the item exists.
- Since [`CF.EXISTS`]() can result in false positive, `CF.ADDNX` may not add an item because it is supposedly already exist, which may be wrong.

</note>

Required arguments

key

is key name for a cuckoo filter to add items to.

If `key` does not exist - a new cuckoo filter is created.

item

is an item to add.

Examples

redis> CF.ADDNX cf item
(integer) 1
redis> CF.ADDNX cf item
(integer) 0

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Supported
 | ✅ Flexible & Annual
✅ Free & Fixed</nobr> |  |

Return information

**RESP2:**

One of the following:
* [Integer reply](): `1` for successfully adding an item to the filter or `0` if the item's fingerprint already exists in the filter.
* [Simple error reply]() in these cases: invalid arguments, wrong key type, or when the filter is full.

**RESP3:**

One of the following:
* [Boolean reply](): `true` for successfully adding an item to the filter or `false` if the item's fingerprint already exists in the filter.
* [Simple error reply]() in these cases: invalid arguments, wrong key type, or when the filter is full.


CF.COUNT

Summary: Return the number of times an item might be in a Cuckoo Filter

Overview

Returns an estimation of the number of times a given item was added to a cuckoo filter.

If you just want to check that a given item was added to a cuckoo filter, use [`CF.EXISTS`]().

Required arguments

key

is key name for a cuckoo filter.

item

is an item to check.

Examples

redis> CF.INSERT cf ITEMS item1 item2 item2
1) (integer) 1
2) (integer) 1
3) (integer) 1
redis> CF.COUNT cf item1
(integer) 1
redis> CF.COUNT cf item2
(integer) 2

Return information

**RESP2:**

One of the following:
* [Integer reply](), where a positive value is an estimation of the number of times `item` was added to the filter. An overestimation is possible, but not an underestimation. `0` means that `key` does not exist or that `item` had not been added to the filter. See the note in [`CF.DEL`]().
* [Simple error]() in these cases: invalid arguments or wrong key type.

**RESP3:**

One of the following:
* [Integer reply](), where a positive value is an estimation of the number of times `item` was added to the filter. An overestimation is possible, but not an underestimation. `0` means that `key` does not exist or that `item` had not been added to the filter. See the note in [`CF.DEL`]().
* [Simple error]() in these cases: invalid arguments or wrong key type.


CF.DEL

Summary: Deletes an item from a Cuckoo Filter

Overview

Deletes an item once from the filter.

If the item exists only once, it will be removed from the filter. If the item was added multiple times, it will still be present.

Never use this command to delete an item unless you are certain you've added the item to the filter. Deleting an item you didn't previously add may corrupt the filter and cause false negatives.

Required arguments

key

is key name for a cuckoo filter.

item

is an item to delete.

Complexity

O(n), where n is the number of `sub-filters`. Both alternative locations are
checked on all `sub-filters`.

Examples

redis> CF.INSERT cf ITEMS item1 item2 item2
1) (integer) 1
2) (integer) 1
3) (integer) 1
redis> CF.DEL cf item1
(integer) 1
redis> CF.DEL cf item1
(integer) 0
redis> CF.DEL cf item2
(integer) 1
redis> CF.DEL cf item2
(integer) 1
redis> CF.DEL cf item2
(integer) 0

Return information

**RESP2:**

One of the following:
* [Integer reply]() `1` for successfully deleting an item, or `0` if no such item was found in the filter.
* [Simple error reply]() in these cases: invalid arguments or wrong key type.

**RESP3:**

One of the following:
* [Boolean reply]() `true` for successfully deleting an item, or `false` if no such item was found in the filter.
* [Simple error reply]() in these cases: invalid arguments or wrong key type.


CF.EXISTS

Summary: Checks whether one or more items exist in a Cuckoo Filter

Overview

Determines whether a given item was added to a cuckoo filter.

This command is similar to [`CF.MEXISTS`](), except that only one item can be checked.

Required arguments

Examples

redis> CF.ADD cf item1
(integer) 1
redis> CF.EXISTS cf item1
(integer) 1
redis> CF.EXISTS cf item2
(integer) 0

Return information

**RESP2:**

One of the following:
* [Integer reply](): `1` means that, with high probability, `item` was already added to the filter, and `0` means that either the `key` does not exist or that the `item` had not been added to the filter.
* [Simple error reply]() if invalid arguments are passed.

**RESP3:**

One of the following:
* [Boolean reply](): `true` means that, with high probability, `item` was already added to the filter, and `false` means that either `key` does not exist or that `item` had not been added to the filter.
* [Simple error reply]() if invalid arguments are passed or `key` is not of the correct type.


CF.INFO

Summary: Returns information about a Cuckoo Filter

Overview

Returns information about a cuckoo filter.

Required arguments

key

is key name for a cuckoo filter.

Examples

redis> CF.INFO cf
 1) Size
 2) (integer) 1080
 3) Number of buckets
 4) (integer) 512
 5) Number of filter
 6) (integer) 1
 7) Number of items inserted
 8) (integer) 0
 9) Number of items deleted
10) (integer) 0
11) Bucket size
12) (integer) 2
13) Expansion rate
14) (integer) 1
15) Max iteration
16) (integer) 20

Return information

One of the following:

**RESP2:**

* [Array reply]() with argument name ([Simple string reply]()) and value ([Integer reply]()) pairs.
* [Simple error reply]() if invalid arguments are passed, `key` does not exist, or `key` is not of the correct type.

**RESP3:**

* [Map reply]() with argument name ([Simple string reply]()) and value ([Integer reply]()) pairs.
* [Simple error reply]() if invalid arguments are passed, `key` does not exist, or `key` is not of the correct type.


CF.INSERT

Summary: Adds one or more items to a Cuckoo Filter. A filter will be created if it does not exist

Overview

Adds one or more items to a cuckoo filter, allowing the filter to be created with a custom capacity if it does not exist yet.

This command is similar to [`CF.ADD`](), except that more than one item can be added and capacity can be specified.

Required arguments

key

is key name for a cuckoo filter to add items to.

If `key` does not exist - a new cuckoo filter is created.

ITEMS item...

One or more items to add.

Optional arguments

CAPACITY capacity

Specifies the desired capacity of the new filter, if this filter does not exist yet.

If the filter already exists, then this parameter is ignored.

If the filter does not exist yet and this parameter is *not* specified, then the filter is created with the module-level default capacity which is 1024.

See [`CF.RESERVE`]() for more information on cuckoo filter capacities.

NOCREATE

If specified, prevents automatic filter creation if the filter does not exist (Instead, an error is returned).

This option is mutually exclusive with `CAPACITY`.

Examples

redis> CF.INSERT cf CAPACITY 1000 ITEMS item1 item2
1) (integer) 1
2) (integer) 1

redis> CF.INSERT cf1 CAPACITY 1000 NOCREATE ITEMS item1 item2
(error) ERR not found

redis> CF.RESERVE cf2 2 BUCKETSIZE 1 EXPANSION 0
OK
redis> CF.INSERT cf2 ITEMS 1 1 1 1
1) (integer) 1
2) (integer) 1
3) (integer) -1
4) (integer) -1

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Supported
 | ✅ Flexible & Annual
✅ Free & Fixed</nobr> |  |

Return information

**RESP2:**

One of the following:

* [Array reply](), where each element is an [Integer reply]() of `1` for successfully adding an item, or `-1` when the item cannot be added because the filter is full.
* [Simple error reply]() when the number of arguments or key type is incorrect, and also when `NOCREATE` is specified and `key` does not exist.

**RESP3:**

* [Array reply](), where each element is a [boolean reply]() of `1` for successfully adding an item, or `-1` when the item cannot be added because the filter is full.
* [Simple error reply]() when the number of arguments or key type is incorrect, and also when `NOCREATE` is specified and `key` does not exist.


CF.INSERTNX

Summary: Adds one or more items to a Cuckoo Filter if the items did not exist previously. A filter will be created if it does not exist

Overview

Adds one or more items to a cuckoo filter if they did not exist previously, allowing the filter to be created with a custom capacity if it does not exist yet.

This command is similar to [`CF.ADDNX`](), except that more than one item can be added and capacity can be specified.

<note><b>Notes:</b>

- This command is slower than [`CF.INSERT`]() because it first checks whether each item exists.
- Since [`CF.EXISTS`]() can result in false positive, `CF.INSERTNX` may not add an item because it is supposedly already exist, which may be wrong.

</note>

Required arguments

Optional arguments

Complexity

O(n + i), where n is the number of `sub-filters` and i is `maxIterations`.
Adding items requires up to 2 memory accesses per `sub-filter`.
But as the filter fills up, both locations for an item might be full. The filter attempts to `Cuckoo` swap items up to `maxIterations` times.

Examples

redis> CF.INSERTNX cf CAPACITY 1000 ITEMS item1 item2
1) (integer) 1
2) (integer) 1

redis> CF.INSERTNX cf CAPACITY 1000 ITEMS item1 item2 item3
1) (integer) 0
2) (integer) 0
3) (integer) 1

redis> CF.INSERTNX cf_new CAPACITY 1000 NOCREATE ITEMS item1 item2
(error) ERR not found

Return information

**RESP2:**

One of the following:

* [Array reply](), where each element is an [Integer reply]() of `0` means that the item's fingerprint already exists in the filter, `1` for successfully adding an item, or `-1` when the item cannot be added because the filter is full.
* [Simple error reply]() when the number of arguments or key type is incorrect, and also when `NOCREATE` is specified and `key` does not exist.

**RESP3:**

* [Array reply](), where each element is a [boolean reply]() of `1` for successfully adding an item, or `-1` when the item cannot be added because the filter is full.
* [Simple error reply]() when the number of arguments or key type is incorrect, and also when `NOCREATE` is specified and `key` does not exist.


CF.LOADCHUNK

Summary: Restores a filter previously saved using SCANDUMP

Overview

Restores a cuckoo filter previously saved using [`CF.SCANDUMP`]().

See the [`CF.SCANDUMP`]() command for example usage.

<note><b>Notes</b>

- This command overwrites the cuckoo filter stored under `key`.
- Make sure that the cuckoo filter is not changed between invocations.

</note>

Required arguments

key

is key name for a cuckoo filter to restore.

iterator

Iterator value associated with `data` (returned by [`CF.SCANDUMP`]())

data

Current data chunk (returned by [`CF.SCANDUMP`]())

Return value

Returns one of these replies:

- [Simple string reply]() - `OK` if executed correctly
- [] on error (invalid arguments, wrong key type, wrong data, etc.)

Examples

See [`CF.SCANDUMP`]() for an example.

Return information

**RESP2:**

One of the following:
* [Simple string reply](): `OK` if executed correctly.
* [Simple error reply]() in these cases: invalid arguments, wrong key type, or when invalid data was passed.

**RESP3:**

One of the following:
* [Simple string reply](): `OK` if executed correctly.
* [Simple error reply]() in these cases: invalid arguments, wrong key type, or when invalid data was passed.


CF.MEXISTS

Overview

Determines whether one or more items were added to a cuckoo filter.

This command is similar to [`CF.EXISTS`](), except that more than one item can be checked.

Required arguments

key

is key name for a cuckoo filter.

item...

One or more items to check.

Examples

redis> CF.INSERT cf ITEMS item1 item2
1) (integer) 1
2) (integer) 1
redis> CF.MEXISTS cf item1 item2 item3
1) (integer) 1
2) (integer) 1
3) (integer) 0

Return information

**RESP2:**

One of the following:
* [Array reply]() of [integer replies](), where `1` means that, with high probability, `item` was already added to the filter, and `0` means that `key` does not exist or that `item` was definitely not added to the filter. See note in [`CF.DEL`]().
* [Simple error reply]() in these cases: in these cases: invalid arguments, wrong key type, or when the key was not found.

**RESP3:**

One of the following:
* [Array reply]() of [boolean replies](), where `true` means that, with high probability, `item` was already added to the filter, and `false` means that `key` does not exist or that `item` was definitely not added to the filter.
* [Simple error reply]() in these cases: in these cases: invalid arguments, wrong key type, or when the key was not found.


CF.RESERVE

Summary: Creates a new Cuckoo Filter

Overview

Creates an empty cuckoo filter with a single sub-filter for the initial specified capacity.

According to the cuckoo filter behavior, the filter is likely to declare itself full before `capacity` is reached; therefore, the fill rate will likely never reach 100 percent.
The fill rate can be improved by using a larger `bucketsize` at the cost of a higher error rate.
When the filter self-declare itself `full`, it will auto-expand by generating additional sub-filters at the cost of reduced performance and increased error rate.
The new sub-filter is created with size of the previous sub-filter multiplied by `expansion`.
Like bucket size, additional sub-filters grow the error rate linearly.

The minimal false positive error rate is 2/255 ≈ 0.78% when bucket size of 1 is used.
Larger buckets increase the error rate linearly (for example, a bucket size of 3 yields a 2.35% error rate) but improve the fill rate of the filter.

`maxiterations` dictates the number of attempts to find a slot for the incoming fingerprint.
Once the filter gets full, high `maxIterations` value will slow down insertions.

Unused capacity in prior sub-filters is automatically used when possible.
The filter can grow up to 32 times.

Required arguments

key

is key name for the the cuckoo filter to be created.

capacity

Estimated capacity for the filter.

Capacity is rounded to the next `2^n` number.

The filter will likely not fill up to 100% of it's capacity. Make sure to reserve extra capacity if you want to avoid expansions.

Optional arguments

BUCKETSIZE bucketsize

Number of items in each bucket.

A higher bucket size value improves the fill rate but also causes a higher error rate and slightly slower performance.

`bucketsize` is an integer between 1 and 255. The default value is 2.

MAXITERATIONS maxiterations

Number of attempts to swap items between buckets before declaring filter as full and creating an additional filter.

A low value is better for performance and a higher number is better for filter fill rate.

`maxiterations` is an integer between 1 and 65535. The default value is 20.

EXPANSION expansion

When a new filter is created, its size is the size of the current filter multiplied by `expansion`.

`expansion` is an integer between 0 and 32768. The default value is 1.

Expansion is rounded to the next `2^n` number.

Examples

redis> CF.RESERVE cf 1000
OK

redis> CF.RESERVE cf 1000
(error) ERR item exists

redis> CF.RESERVE cf_params 1000 BUCKETSIZE 8 MAXITERATIONS 20 EXPANSION 2
OK

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Supported
 | ✅ Flexible & Annual
✅ Free & Fixed</nobr> |  |

Return information

**RESP2:**

One of the following:
* [Simple string reply](): `OK` if the filter was created successfully.
* [Simple error reply]() in these cases: invalid arguments or the key already exists.

**RESP3:**

One of the following:
* [Simple string reply](): `OK` if the filter was created successfully.
* [Simple error reply]() in these cases: invalid arguments or the key already exists.


CF.SCANDUMP

Summary: Begins an incremental save of the bloom filter

Overview

Begins an incremental save of the cuckoo filter.

This command is useful for large cuckoo filters that cannot fit into the [`DUMP`]() and [`RESTORE`]() model.

The first time this command is called, the value of `iter` should be 0.

This command returns successive `(iter, data)` pairs until `(0, NULL)` indicates completion.

Required arguments

key

is key name for a cuckoo filter to save.

iterator

Iterator value; either 0 or the iterator from a previous invocation of this command

Examples

redis> CF.RESERVE cf 8
OK
redis> CF.ADD cf item1
(integer) 1
redis> CF.SCANDUMP cf 0
1) (integer) 1
2) "\x01\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x02\x00\x14\x00\x01\x008\x9a\xe0\xd8\xc3\x7f\x00\x00"
redis> CF.SCANDUMP cf 1
1) (integer) 9
2) "\x00\x00\x00\x00\a\x00\x00\x00"
redis> CF.SCANDUMP cf 9
1) (integer) 0
2) (nil)
redis> DEL bf
(integer) 1
redis> CF.LOADCHUNK cf 1 "\x01\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x02\x00\x14\x00\x01\x008\x9a\xe0\xd8\xc3\x7f\x00\x00"
OK
redis> CF.LOADCHUNK cf 9 "\x00\x00\x00\x00\a\x00\x00\x00"
OK
redis> CF.EXISTS cf item1
(integer) 1

Python code:

chunks = []
iter = 0
while True:
    iter, data = CF.SCANDUMP(key, iter)
    if iter == 0:
        break
    else:
        chunks.append([iter, data])

# Load it back
for chunk in chunks:
    iter, data = chunk
    CF.LOADCHUNK(key, iter, data)

Return information

**RESP2:**

One of the following:
* [Array reply](): a two-element array of an [Integer reply]() (_Iterator_) and a [Bulk string reply]() (_Data_).
* [Simple error reply]() in these cases: invalid arguments, the key was not found, or the key is of the wrong type.

The Iterator is passed as input to the next invocation of `CF.SCANDUMP`. If _Iterator_ is 0, then it means iteration has completed.

The iterator-data pair should also be passed to [`CF.LOADCHUNK`]() when restoring the filter.

**RESP3:**

One of the following:
* [Array reply](): a two-element array of an [Integer reply]() (_Iterator_) and a [Bulk string reply]() (_Data_).
* [Simple error reply]() in these cases: invalid arguments, the key was not found, or the key is of the wrong type.

The Iterator is passed as input to the next invocation of `CF.SCANDUMP`. If _Iterator_ is 0, then it means iteration has completed.

The iterator-data pair should also be passed to [`CF.LOADCHUNK`]() when restoring the filter.


CLIENT

Summary: A container for client connection commands.

Content

This is a container command for client connection commands.

To see the list of available commands you can call [`CLIENT HELP`]().


CLIENT CACHING

Summary: Instructs the server whether to track the keys in the next request.

Overview

This command controls the tracking of the keys in the next command executed
by the connection, when tracking is enabled in `OPTIN` or `OPTOUT` mode.
Please check the
[client side caching documentation]() for
background information.

When tracking is enabled Redis, using the [`CLIENT TRACKING`]() command, it is
possible to specify the `OPTIN` or `OPTOUT` options, so that keys
in read only commands are not automatically remembered by the server to
be invalidated later. When we are in `OPTIN` mode, we can enable the
tracking of the keys in the next command by calling `CLIENT CACHING yes`
immediately before it. Similarly when we are in `OPTOUT` mode, and keys
are normally tracked, we can avoid the keys in the next command to be
tracked using `CLIENT CACHING no`.

Basically the command sets a state in the connection, that is valid only
for the next command execution, that will modify the behavior of client
tracking.

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Standard
<nobr>✅ Active-Active</nobr> | ✅ Standard
<nobr>✅ Active-Active</nobr> |  |

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` or an error if the argument is not "yes" or "no".

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` or an error if the argument is not "yes" or "no".


CLIENT GETNAME

Summary: Returns the name of the connection.

Overview

The `CLIENT GETNAME` returns the name of the current connection as set by [`CLIENT SETNAME`](). Since every new connection starts without an associated name, if no name was assigned a null bulk reply is returned.

Return information

**RESP2:**

One of the following:
* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): the connection name of the current connection.
* [Nil reply](../../develop/reference/protocol-spec#bulk-strings): the connection name was not set.

**RESP3:**

One of the following:
* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): the connection name of the current connection.
* [Null reply](../../develop/reference/protocol-spec#nulls): the connection name was not set.


CLIENT GETREDIR

Summary: Returns the client ID to which the connection's tracking notifications are redirected.

Overview

This command returns the client ID we are redirecting our
[tracking]() notifications to. We set a client
to redirect to when using [`CLIENT TRACKING`]() to enable tracking. However in
order to avoid forcing client libraries implementations to remember the
ID notifications are redirected to, this command exists in order to improve
introspection and allow clients to check later if redirection is active
and towards which client ID.

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ❌ Standard
<nobr>❌ Active-Active</nobr> | ❌ Standard
<nobr>❌ Active-Active</nobr> |  |

Return information

**RESP2:**

One of the following:
* [Integer reply](../../develop/reference/protocol-spec#integers): `0` when not redirecting notifications to any client.
* [Integer reply](../../develop/reference/protocol-spec#integers): `-1` if client tracking is not enabled.
* [Integer reply](../../develop/reference/protocol-spec#integers): the ID of the client to which notification are being redirected.

**RESP3:**

One of the following:
* [Integer reply](../../develop/reference/protocol-spec#integers): `0` when not redirecting notifications to any client.
* [Integer reply](../../develop/reference/protocol-spec#integers): `-1` if client tracking is not enabled.
* [Integer reply](../../develop/reference/protocol-spec#integers): the ID of the client to which notification are being redirected.


CLIENT HELP

Summary: Returns helpful text about the different subcommands.

Overview

The `CLIENT HELP` command returns a helpful text describing the different subcommands.

Return information

**RESP2:**

[Array reply](../../develop/reference/protocol-spec#arrays): a list of subcommands and their descriptions.

**RESP3:**

[Array reply](../../develop/reference/protocol-spec#arrays): a list of subcommands and their descriptions.


CLIENT ID

Summary: Returns the unique client ID of the connection.

Overview

The command just returns the ID of the current connection. Every connection
ID has certain guarantees:

1. It is never repeated, so if `CLIENT ID` returns the same number, the caller can be sure that the underlying client did not disconnect and reconnect the connection, but it is still the same connection.
2. The ID is monotonically incremental. If the ID of a connection is greater than the ID of another connection, it is guaranteed that the second connection was established with the server at a later time.

This command is especially useful together with [`CLIENT UNBLOCK`]() which was
introduced also in Redis 5 together with `CLIENT ID`. Check the [`CLIENT UNBLOCK`]() command page for a pattern involving the two commands.

Examples

CLIENT ID

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Standard
<nobr>✅ Active-Active</nobr> | ✅ Standard
<nobr>✅ Active-Active</nobr> | Because Redis Software clustering allows [multiple active proxies](), `CLIENT ID` cannot guarantee incremental IDs between clients that connect to different nodes under multi proxy policies. |

Return information

**RESP2:**

[Integer reply](../../develop/reference/protocol-spec#integers): the ID of the client.

**RESP3:**

[Integer reply](../../develop/reference/protocol-spec#integers): the ID of the client.


CLIENT INFO

Summary: Returns information about the connection.

Overview

The command returns information and statistics about the current client connection in a mostly human readable format.

The reply format is identical to that of [`CLIENT LIST`](), and the content consists only of information about the current client.

Examples

CLIENT INFO

Return information

**RESP2:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): a unique string for the current client, as described at the `CLIENT LIST` page.

**RESP3:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): a unique string for the current client, as described at the `CLIENT LIST` page.


CLIENT KILL

Summary: Terminates open connections.

Overview

The `CLIENT KILL` command closes a given client connection. This command support two formats, the old format:

    CLIENT KILL addr:port

The `ip:port` should match a line returned by the [`CLIENT LIST`]() command (`addr` field).

The new format:

    CLIENT KILL <filter> <value> ... ... <filter> <value>

With the new form it is possible to kill clients by different attributes
instead of killing just by address. The following filters are available:

* `CLIENT KILL ADDR ip:port`. This is exactly the same as the old three-arguments behavior.
* `CLIENT KILL LADDR ip:port`. Kill all clients connected to specified local (bind) address.
* `CLIENT KILL ID client-id`. Allows to kill a client by its unique `ID` field. Client `ID`'s are retrieved using the [`CLIENT LIST`]() command.
* `CLIENT KILL TYPE type`, where *type* is one of `normal`, `master`, `replica` and `pubsub`. This closes the connections of **all the clients** in the specified class. Note that clients blocked into the [`MONITOR`]() command are considered to belong to the `normal` class.
* `CLIENT KILL USER username`. Closes all the connections that are authenticated with the specified [ACL]() username, however it returns an error if the username does not map to an existing ACL user.
* `CLIENT KILL SKIPME yes/no`. By default this option is set to `yes`, that is, the client calling the command will not get killed, however setting this option to `no` will have the effect of also killing the client calling the command.
* `CLIENT KILL MAXAGE maxage`. Closes all the connections that are older than the specified age, in seconds. Added in Redis v7.4.

It is possible to provide multiple filters at the same time. The command will handle multiple filters via logical AND. For example:

    CLIENT KILL addr 127.0.0.1:12345 type pubsub

is valid and will kill only a pubsub client with the specified address. This format containing multiple filters is rarely useful currently.

When the new form is used the command no longer returns `OK` or an error, but instead the number of killed clients, that may be zero.

CLIENT KILL and Redis Sentinel

Recent versions of Redis Sentinel (Redis 2.8.12 or greater) use CLIENT KILL
in order to kill clients when an instance is reconfigured, in order to
force clients to perform the handshake with one Sentinel again and update
its configuration.

Notes

Due to the single-threaded nature of Redis, it is not possible to
kill a client connection while it is executing a command. From
the client point of view, the connection can never be closed
in the middle of the execution of a command. However, the client
will notice the connection has been closed only when the
next command is sent (and results in network error).

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Standard
<nobr>✅ Active-Active</nobr> | ✅ Standard
<nobr>✅ Active-Active</nobr> |  |

Return information

**RESP2:**

One of the following:
* [Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` when called in 3 argument format and the connection has been closed.
* [Integer reply](../../develop/reference/protocol-spec#integers): when called in filter/value format, the number of clients killed.

**RESP3:**

One of the following:
* [Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` when called in 3 argument format and the connection has been closed.
* [Integer reply](../../develop/reference/protocol-spec#integers): when called in filter/value format, the number of clients killed.


CLIENT LIST

Summary: Lists open connections.

Overview

The `CLIENT LIST` command returns information and statistics about the client
connections server in a mostly human readable format.

You can use one of the optional subcommands to filter the list. The `TYPE type` subcommand filters the list by clients' type, where *type* is one of `normal`, `master`, `replica`, and `pubsub`. Note that clients blocked by the [`MONITOR`]() command belong to the `normal` class.

The `ID` filter only returns entries for clients with IDs matching the `client-id` arguments.

Here is the meaning of the fields:

* `id`: a unique 64-bit client ID.
* `addr`: address/port of the client.
* `laddr`: address/port of local address client connected to (bind address).
* `fd`: file descriptor corresponding to the socket.
* `name`: the name set by the client with [`CLIENT SETNAME`]().
* `age`: total duration of the connection in seconds.
* `idle`: idle time of the connection in seconds.
* `flags`: client flags (see below).
* `db`: current database ID.
* `sub`: number of channel subscriptions.
* `psub`: number of pattern matching subscriptions.
* `ssub`: number of shard channel subscriptions. Added in Redis 7.0.3.
* `multi`: number of commands in a MULTI/EXEC context.
* `watch`: number of keys this client is currently watching. Added in Redis 7.4.
* `qbuf`: query buffer length (0 means no query pending).
* `qbuf-free`: free space of the query buffer (0 means the buffer is full).
* `argv-mem`: incomplete arguments for the next command (already extracted from query buffer).
* `multi-mem`: memory is used up by buffered multi commands. Added in Redis 7.0.
* `obl`: output buffer length.
* `oll`: output list length (replies are queued in this list when the buffer is full).
* `omem`: output buffer memory usage.
* `tot-mem`: total memory consumed by this client in its various buffers.
* `events`: file descriptor events (see below).
* `cmd`: last command played.
* `user`: the authenticated username of the client.
* `redir`: client id of current client tracking redirection.
* `resp`: client RESP protocol version. Added in Redis 7.0.
* `rbp`: peak size of the client's read buffer since the client connected. Added in Redis 7.0.
* `rbs`: current size of the client's read buffer in bytes. Added in Redis 7.0.
* `lib-name` - the name of the client library that is being used.
* `lib-ver` - the version of the client library.
* `io-thread`: id of I/O thread assigned to the client. Added in Redis 8.0
* `tot-net-in`: total network input bytes read from this client.
* `tot-net-out`: total network output bytes sent to this client.
* `tot-cmds`: total count of commands this client executed.

The client flags can be a combination of:

[code example]

The file descriptor events can be:

[code example]

Notes

New fields are regularly added for debugging purpose. Some could be removed
in the future. A version safe Redis client using this command should parse
the output accordingly (i.e. handling gracefully missing fields, skipping
unknown fields).

Return information

**RESP2:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): information and statistics about client connections.

**RESP3:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): information and statistics about client connections.

A: connection to be closed ASAP
b: the client is waiting in a blocking operation
c: connection to be closed after writing entire reply
d: a watched keys has been modified - EXEC will fail
e: the client is excluded from the client eviction mechanism
g: the client is responsible for migrating slots (atomic slot migration)
i: the client is waiting for a VM I/O (deprecated)
M: the client is a master
N: no specific flag set
o: the client is responsible for importing slots (atomic slot migration)
O: the client is a client in MONITOR mode
P: the client is a Pub/Sub subscriber
r: the client is in readonly mode against a cluster node
S: the client is a replica node connection to this instance
u: the client is unblocked
U: the client is connected via a Unix domain socket
x: the client is in a MULTI/EXEC context
t: the client enabled keys tracking in order to perform client side caching
T: the client will not touch the LRU/LFU of the keys it accesses
R: the client tracking target client is invalid
B: the client enabled broadcast tracking mode

r: the client socket is readable (event loop)
w: the client socket is writable (event loop)


CLIENT NO-EVICT

Summary: Sets the client eviction mode of the connection.

Overview

The `CLIENT NO-EVICT` command sets the [client eviction](#client-eviction) mode for the current connection.

When turned on and client eviction is configured, the current connection will be excluded from the client eviction process even if we're above the configured client eviction threshold.

When turned off, the current client will be re-included in the pool of potential clients to be evicted (and evicted if needed).

See [client eviction](#client-eviction) for more details.

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ❌ Standard
<nobr>❌ Active-Active</nobr> | ❌ Standard
<nobr>❌ Active-Active</nobr> |  |

Return information

**RESP2:**

One of the following:

* [Simple string reply](): `OK` if the command was successful.
* [Simple error reply]() in these cases: wrong number of or invalid arguments.

**RESP3:**

One of the following:

* [Simple string reply](): `OK` if the command was successful.
* [Simple error reply]() in these cases: wrong number of or invalid arguments.


CLIENT NO-TOUCH

Summary: Controls whether commands sent by the client affect the LRU/LFU of accessed keys.

Overview

The `CLIENT NO-TOUCH` command controls whether commands sent by the client will alter the LRU/LFU of the keys they access.

When turned on, the current client will not change LFU/LRU stats, unless it sends the [`TOUCH`]() command.

When turned off, the client touches LFU/LRU stats just as a normal client.

Return information


CLIENT PAUSE

Summary: Suspends commands processing.

Overview

`CLIENT PAUSE` is a connections control command able to suspend all the Redis clients for the specified amount of time (in milliseconds).

The command performs the following actions:

* It stops processing all the pending commands from normal and pub/sub clients for the given mode. However interactions with replicas will continue normally. Note that clients are formally paused when they try to execute a command, so no work is taken on the server side for inactive clients.
* However it returns OK to the caller ASAP, so the `CLIENT PAUSE` command execution is not paused by itself.
* When the specified amount of time has elapsed, all the clients are unblocked: this will trigger the processing of all the commands accumulated in the query buffer of every client during the pause.

Client pause currently supports two modes:

* `ALL`: This is the default mode. All client commands are blocked.
* `WRITE`: Clients are only blocked if they attempt to execute a write command.

For the `WRITE` mode, some commands have special behavior:

* [`EVAL`]()/[`EVALSHA`](): Will block client for all scripts.
* [`PUBLISH`](): Will block client.
* [`PFCOUNT`](): Will block client.
* [`WAIT`](): Acknowledgments will be delayed, so this command will appear blocked.

This command is useful as it makes able to switch clients from a Redis instance to another one in a controlled way. For example during an instance upgrade the system administrator could do the following:

* Pause the clients using `CLIENT PAUSE`
* Wait a few seconds to make sure the replicas processed the latest replication stream from the master.
* Turn one of the replicas into a master.
* Reconfigure clients to connect with the new master.

Since Redis 6.2, the recommended mode for client pause is `WRITE`. This mode will stop all replication traffic, can be
aborted with the [`CLIENT UNPAUSE`]() command, and allows reconfiguring the old master without risking accepting writes after the
failover. This is also the mode used during cluster failover.

For versions before 6.2, it is possible to send `CLIENT PAUSE` in a MULTI/EXEC block together with the `INFO replication` command in order to get the current master offset at the time the clients are blocked. This way it is possible to wait for a specific offset in the replica side in order to make sure all the replication stream was processed.

Since Redis 3.2.10 / 4.0.0, this command also prevents keys to be evicted or
expired during the time clients are paused. This way the dataset is guaranteed
to be static not just from the point of view of clients not being able to write, but also from the point of view of internal operations.

Behavior change history

*   `>= 3.2.0`: Client pause prevents client pause and key eviction as well.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` or an error if the timeout is invalid.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` or an error if the timeout is invalid.


CLIENT REPLY

Summary: Instructs the server whether to reply to commands.

Overview

Sometimes it can be useful for clients to completely disable replies from the Redis server. For example when the client sends fire and forget commands or performs a mass loading of data, or in caching contexts where new data is streamed constantly. In such contexts to use server time and bandwidth in order to send back replies to clients, which are going to be ignored, is considered wasteful.

The `CLIENT REPLY` command controls whether the server will reply the client's commands. The following modes are available:

* `ON`. This is the default mode in which the server returns a reply to every command.
* `OFF`. In this mode the server will not reply to client commands.
* `SKIP`. This mode skips the reply of command immediately after it.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` when called with `ON`. When called with either `OFF` or `SKIP` sub-commands, no reply is made.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` when called with `ON`. When called with either `OFF` or `SKIP` sub-commands, no reply is made.


CLIENT SETINFO

Summary: Sets information specific to the client or connection.

Overview

The `CLIENT SETINFO` command assigns various info attributes to the current connection which are displayed in the output of [`CLIENT LIST`]() and [`CLIENT INFO`]().

Client libraries are expected to pipeline this command after authentication on all connections
and ignore failures since they could be connected to an older version that doesn't support them.

Currently the supported attributes are:
* `lib-name` - meant to hold the name of the client library that's in use.
* `lib-ver` - meant to hold the client library's version.

There is no limit to the length of these attributes. However it is not possible to use spaces, newlines, or other non-printable characters that would violate the format of the [`CLIENT LIST`]() reply.

[Official client libraries](https://redis.io/docs/latest/develop/connect/clients/) allow extending `lib-name` with a custom suffix to expose additional information about the client.
For example, high-level libraries like [redis-om-spring](https://github.com/redis/redis-om-spring) can report their version.
The resulting `lib-name` would be `jedis(redis-om-spring_v1.0.0)`.
Brace characters are used to delimit the custom suffix and should be avoided in the suffix itself.
We recommend using the following format for the custom suffixes for third-party libraries `(?<custom-name>[ -~]+)[ -~]v(?<custom-version>[\d\.]+)` and use `;` to delimit multiple suffixes.

Note that these attributes are **not** cleared by the RESET command.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the attribute name was successfully set.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the attribute name was successfully set.


CLIENT SETNAME

Summary: Sets the connection name.

Overview

The `CLIENT SETNAME` command assigns a name to the current connection.

The assigned name is displayed in the output of [`CLIENT LIST`]() so that it is possible to identify the client that performed a given connection.

For instance when Redis is used in order to implement a queue, producers and consumers of messages may want to set the name of the connection according to their role.

There is no limit to the length of the name that can be assigned if not the usual limits of the Redis string type (512 MB). However it is not possible to use spaces in the connection name as this would violate the format of the [`CLIENT LIST`]() reply.

It is possible to entirely remove the connection name setting it to the empty string, that is not a valid connection name since it serves to this specific purpose.

The connection name can be inspected using [`CLIENT GETNAME`]().

Every new connection starts without an assigned name.

Tip: setting names to connections is a good way to debug connection leaks due to bugs in the application using Redis.

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Standard
<nobr>✅ Active-Active</nobr> | ✅ Standard
<nobr>✅ Active-Active</nobr> |  |

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the connection name was successfully set.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the connection name was successfully set.


CLIENT TRACKING

Summary: Controls server-assisted client-side caching for the connection.

Overview

This command enables the tracking feature of the Redis server, that is used
for [server assisted client side caching]().

When tracking is enabled Redis remembers the keys that the connection
requested, in order to send later invalidation messages when such keys are
modified. Invalidation messages are sent in the same connection (only available
when the RESP3 protocol is used) or redirected in a different connection
(available also with RESP2 and Pub/Sub). A special *broadcasting* mode is
available where clients participating in this protocol receive every
notification just subscribing to given key prefixes, regardless of the
keys that they requested. Given the complexity of the argument please
refer to [the main client side caching documentation]() for the details. This manual page is only a reference for the options of this subcommand.

In order to enable tracking, use:

    CLIENT TRACKING on ... options ...

The feature will remain active in the current connection for all its life,
unless tracking is turned off with `CLIENT TRACKING off` at some point.

The following are the list of options that modify the behavior of the
command when enabling tracking:

* `REDIRECT <id>`: send invalidation messages to the connection with the specified ID. The connection must exist. You can get the ID of a connection using [`CLIENT ID`](). If the connection we are redirecting to is terminated, when in RESP3 mode the connection with tracking enabled will receive `tracking-redir-broken` push messages in order to signal the condition.
* `BCAST`: enable tracking in broadcasting mode. In this mode invalidation messages are reported for all the prefixes specified, regardless of the keys requested by the connection. Instead when the broadcasting mode is not enabled, Redis will track which keys are fetched using read-only commands, and will report invalidation messages only for such keys.
* `PREFIX <prefix>`: for broadcasting, register a given key prefix, so that notifications will be provided only for keys starting with this string. This option can be given multiple times to register multiple prefixes. If broadcasting is enabled without this option, Redis will send notifications for every key. You can't delete a single prefix, but you can delete all prefixes by disabling and re-enabling tracking. Using this option adds the additional time complexity of O(N^2), where N is the total number of prefixes tracked.
* `OPTIN`: when broadcasting is NOT active, normally don't track keys in read only commands, unless they are called immediately after a `CLIENT CACHING yes` command.
* `OPTOUT`: when broadcasting is NOT active, normally track keys in read only commands, unless they are called immediately after a `CLIENT CACHING no` command.
* `NOLOOP`: don't send notifications about keys modified by this connection itself.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the connection was successfully put in tracking mode or if the tracking mode was successfully disabled. Otherwise, an error is returned.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the connection was successfully put in tracking mode or if the tracking mode was successfully disabled. Otherwise, an error is returned.


CLIENT TRACKINGINFO

Summary: Returns information about server-assisted client-side caching for the connection.

Overview

The command returns information about the current client connection's use of the [server assisted client side caching]() feature.

Here's the list of tracking information sections and their respective values:

* **flags**: A list of tracking flags used by the connection. The flags and their meanings are as follows:
  * `off`: The connection isn't using server assisted client side caching.
  * `on`: Server assisted client side caching is enabled for the connection.
  * `bcast`: The client uses broadcasting mode.
  * `optin`: The client does not cache keys by default.
  * `optout`: The client caches keys by default.
  * `caching-yes`: The next command will cache keys (exists only together with `optin`).
  * `caching-no`: The next command won't cache keys (exists only together with `optout`).
  * `noloop`: The client isn't notified about keys modified by itself.
  * `broken_redirect`: The client ID used for redirection isn't valid anymore.
* **redirect**: The client ID used for notifications redirection, 0 for self-redirection, or -1 when none.
* **prefixes**: A list of key prefixes for which notifications are sent to the client.

Return information

**RESP2:**

[Array reply](../../develop/reference/protocol-spec#arrays): a list of tracking information sections and their respective values.

**RESP3:**

[Map reply](../../develop/reference/protocol-spec#maps): a list of tracking information sections and their respective values.


CLIENT UNBLOCK

Summary: Unblocks a client blocked by a blocking command from a different connection.

Overview

This command can unblock, from a different connection, a client blocked in a blocking operation, such as for instance [`BRPOP`]() or [`XREAD`]() or [`WAIT`]().

By default the client is unblocked as if the timeout of the command was
reached, however if an additional (and optional) argument is passed, it is possible to specify the unblocking behavior, that can be **TIMEOUT** (the default) or **ERROR**. If **ERROR** is specified, the behavior is to unblock the client returning as error the fact that the client was force-unblocked. Specifically the client will receive the following error:

    -UNBLOCKED client unblocked via CLIENT UNBLOCK

Note: of course as usually it is not guaranteed that the error text remains
the same, however the error code will remain `-UNBLOCKED`.

This command is useful especially when we are monitoring many keys with
a limited number of connections. For instance we may want to monitor multiple
streams with [`XREAD`]() without using more than N connections. However at some
point the consumer process is informed that there is one more stream key
to monitor. In order to avoid using more connections, the best behavior would
be to stop the blocking command from one of the connections in the pool, add
the new key, and issue the blocking command again.

To obtain this behavior the following pattern is used. The process uses
an additional *control connection* in order to send the `CLIENT UNBLOCK` command
if needed. In the meantime, before running the blocking operation on the other
connections, the process runs [`CLIENT ID`]() in order to get the ID associated
with that connection. When a new key should be added, or when a key should
no longer be monitored, the relevant connection blocking command is aborted
by sending `CLIENT UNBLOCK` in the control connection. The blocking command
will return and can be finally reissued.

This example shows the application in the context of Redis streams, however
the pattern is a general one and can be applied to other cases.

Examples

[code example]

Return information

**RESP2:**

One of the following:
* [Integer reply](../../develop/reference/protocol-spec#integers): `1` if the client was unblocked successfully.
* [Integer reply](../../develop/reference/protocol-spec#integers): `0` if the client wasn't unblocked.

**RESP3:**

One of the following:
* [Integer reply](../../develop/reference/protocol-spec#integers): `1` if the client was unblocked successfully.
* [Integer reply](../../develop/reference/protocol-spec#integers): `0` if the client wasn't unblocked.

Connection A (blocking connection):
> CLIENT ID
2934
> BRPOP key1 key2 key3 0
(client is blocked)

... Now we want to add a new key ...

Connection B (control connection):
> CLIENT UNBLOCK 2934
1

Connection A (blocking connection):
... BRPOP reply with timeout ...
NULL
> BRPOP key1 key2 key3 key4 0
(client is blocked again)


CLIENT UNPAUSE

Summary: Resumes processing commands from paused clients.

Overview

`CLIENT UNPAUSE` is used to resume command processing for all clients that were paused by [`CLIENT PAUSE`]().

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ❌ Standard
<nobr>❌ Active-Active</nobr> | ❌ Standard
<nobr>❌ Active-Active</nobr> |  |

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK`.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK`.


CLUSTER

Summary: A container for Redis Cluster commands.

Content

This is a container command for Redis Cluster commands.

To see the list of available commands you can call [`CLUSTER HELP`]().


CLUSTER ADDSLOTS

Summary: Assigns new hash slots to a node.

Overview

This command is useful in order to modify a node's view of the cluster
configuration. Specifically it assigns a set of hash slots to the node
receiving the command. If the command is successful, the node will map
the specified hash slots to itself, and will start broadcasting the new
configuration.

However note that:

1. The command only works if all the specified slots are, from the point of view of the node receiving the command, currently not assigned. A node will refuse to take ownership for slots that already belong to some other node (including itself).
2. The command fails if the same slot is specified multiple times.
3. As a side effect of the command execution, if a slot among the ones specified as argument is set as `importing`, this state gets cleared once the node assigns the (previously unbound) slot to itself.

Example

For example the following command assigns slots 1 2 3 to the node receiving
the command:

    > CLUSTER ADDSLOTS 1 2 3
    OK

However trying to execute it again results into an error since the slots
are already assigned:

    > CLUSTER ADDSLOTS 1 2 3
    ERR Slot 1 is already busy

Usage in Redis Cluster

This command only works in cluster mode and is useful in the following
Redis Cluster operations:

1. To create a new `cluster ADDSLOTS` is used in order to initially setup master nodes splitting the available hash slots among them.
2. In order to fix a broken cluster where certain slots are unassigned.

Information about slots propagation and warnings

Note that once a node assigns a set of slots to itself, it will start
propagating this information in heartbeat packet headers. However the
other nodes will accept the information only if they have the slot as
not already bound with another node, or if the configuration epoch of the
node advertising the new hash slot, is greater than the node currently listed
in the table.

This means that this command should be used with care only by applications
orchestrating Redis Cluster, like `redis-cli`, and the command if used
out of the right context can leave the cluster in a wrong state or cause
data loss.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was successful. Otherwise an error is returned.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was successful. Otherwise an error is returned.


CLUSTER ADDSLOTSRANGE

Summary: Assigns new hash slot ranges to a node.

Overview

The `CLUSTER ADDSLOTSRANGE` is similar to the [`CLUSTER ADDSLOTS`]() command in that they both assign hash slots to nodes.

The difference between the two commands is that [`CLUSTER ADDSLOTS`]() takes a list of slots to assign to the node, while `CLUSTER ADDSLOTSRANGE` takes a list of slot ranges (specified by start and end slots) to assign to the node.

Example

To assign slots 1 2 3 4 5 to the node, the [`CLUSTER ADDSLOTS`]() command is:

    > CLUSTER ADDSLOTS 1 2 3 4 5
    OK

The same operation can be completed with the following `CLUSTER ADDSLOTSRANGE` command:

    > CLUSTER ADDSLOTSRANGE 1 5
    OK

Usage in Redis Cluster

This command only works in cluster mode and is useful in the following Redis Cluster operations:

1. To create a new cluster, `CLUSTER ADDSLOTSRANGE` is used to initially set up master nodes splitting the available hash slots among them.
2. In order to fix a broken cluster where certain slots are unassigned.

Return information


CLUSTER BUMPEPOCH

Summary: Advances the cluster config epoch.

Overview

Advances the cluster config epoch.

The `CLUSTER BUMPEPOCH` command triggers an increment to the cluster's config epoch from the connected node. The epoch will be incremented if the node's config epoch is zero, or if it is less than the cluster's greatest epoch.

**Note:** config epoch management is performed internally by the cluster, and relies on obtaining a consensus of nodes. The `CLUSTER BUMPEPOCH` attempts to increment the config epoch **WITHOUT** getting the consensus, so using it may violate the "last failover wins" rule. Use it with caution.

Return information

**RESP2:**

One of the following:
* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): `BUMPED` if the epoch was incremented.
* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): `STILL` if the node already has the greatest configured epoch in the cluster.

**RESP3:**

One of the following:
* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): `BUMPED` if the epoch was incremented.
* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): `STILL` if the node already has the greatest configured epoch in the cluster.


CLUSTER COUNT-FAILURE-REPORTS

Summary: Returns the number of active failure reports active for a node.

Overview

The command returns the number of *failure reports* for the specified node.
Failure reports are the way Redis Cluster uses in order to promote a
`PFAIL` state, that means a node is not reachable, to a `FAIL` state,
that means that the majority of masters in the cluster agreed within
a window of time that the node is not reachable.

A few more details:

* A node flags another node with `PFAIL` when the node is not reachable for a time greater than the configured *node timeout*, which is a fundamental configuration parameter of a Redis Cluster.
* Nodes in `PFAIL` state are provided in gossip sections of heartbeat packets.
* Every time a node processes gossip packets from other nodes, it creates (and refreshes the TTL if needed) **failure reports**, remembering that a given node said another given node is in `PFAIL` condition.
* Each failure report has a time to live of two times the *node timeout* time.
* If at a given time a node has another node flagged with `PFAIL`, and at the same time collected the majority of other master nodes *failure reports* about this node (including itself if it is a master), then it elevates the failure state of the node from `PFAIL` to `FAIL`, and broadcasts a message forcing all the nodes that can be reached to flag the node as `FAIL`.

This command returns the number of failure reports for the current node which are currently not expired (so received within two times the *node timeout* time). The count does not include what the node we are asking this count believes about the node ID we pass as argument, the count *only* includes the failure reports the node received from other nodes.

This command is mainly useful for debugging, when the failure detector of
Redis Cluster is not operating as we believe it should.


CLUSTER COUNTKEYSINSLOT

Summary: Returns the number of keys in a hash slot.

Overview

Returns the number of keys in the specified Redis Cluster hash slot. The
command only queries the local data set, so contacting a node
that is not serving the specified hash slot will always result in a count of
zero being returned.

During atomic slot migration operations (available since Redis 8.4.0), keys being imported or trimmed will be filtered out from the results.

[code example]

Return information

**RESP2:**

[Integer reply](../../develop/reference/protocol-spec#integers): The number of keys in the specified hash slot, or an error if the hash slot is invalid.

**RESP3:**

[Integer reply](../../develop/reference/protocol-spec#integers): The number of keys in the specified hash slot, or an error if the hash slot is invalid.

> CLUSTER COUNTKEYSINSLOT 7000
(integer) 50341


CLUSTER DELSLOTS

Summary: Sets hash slots as unbound for a node.

Overview

In Redis Cluster, each node keeps track of which master is serving
a particular hash slot.

The `CLUSTER DELSLOTS` command asks a particular Redis Cluster node to
forget which master is serving the hash slots specified as arguments.

In the context of a node that has received a `CLUSTER DELSLOTS` command and
has consequently removed the associations for the passed hash slots,
we say those hash slots are *unbound*. Note that the existence of
unbound hash slots occurs naturally when a node has not been
configured to handle them (something that can be done with the
[`CLUSTER ADDSLOTS`]() command) and if it has not received any information about
who owns those hash slots (something that it can learn from heartbeat
or update messages).

If a node with unbound hash slots receives a heartbeat packet from
another node that claims to be the owner of some of those hash
slots, the association is established instantly. Moreover, if a
heartbeat or update message is received with a configuration epoch
greater than the node's own, the association is re-established.

However, note that:

1. The command only works if all the specified slots are already
associated with some node.
2. The command fails if the same slot is specified multiple times.
3. As a side effect of the command execution, the node may go into
*down* state because not all hash slots are covered.

Example

The following command removes the association for slots 5000 and
5001 from the node receiving the command:

    > CLUSTER DELSLOTS 5000 5001
    OK

Usage in Redis Cluster

This command only works in cluster mode and may be useful for
debugging and in order to manually orchestrate a cluster configuration
when a new cluster is created. It is currently not used by `redis-cli`,
and mainly exists for API completeness.

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ❌ Standard
<nobr>❌ Active-Active</nobr> | ❌ Standard
<nobr>❌ Active-Active</nobr> |  |

Return information


CLUSTER DELSLOTSRANGE

Summary: Sets hash slot ranges as unbound for a node.

Overview

The `CLUSTER DELSLOTSRANGE` command is similar to the [`CLUSTER DELSLOTS`]() command in that they both remove hash slots from the node.
The difference is that [`CLUSTER DELSLOTS`]() takes a list of hash slots to remove from the node, while `CLUSTER DELSLOTSRANGE` takes a list of slot ranges (specified by start and end slots) to remove from the node.

Example

To remove slots 1 2 3 4 5 from the node, the [`CLUSTER DELSLOTS`]() command is:

    > CLUSTER DELSLOTS 1 2 3 4 5
    OK

The same operation can be completed with the following `CLUSTER DELSLOTSRANGE` command:

    > CLUSTER DELSLOTSRANGE 1 5
    OK

However, note that:

1. The command only works if all the specified slots are already associated with the node.
2. The command fails if the same slot is specified multiple times.
3. As a side effect of the command execution, the node may go into *down* state because not all hash slots are covered.

Usage in Redis Cluster

Return information


CLUSTER FAILOVER

Summary: Forces a replica to perform a manual failover of its master.

Overview

This command, that can only be sent to a Redis Cluster replica node, forces
the replica to start a manual failover of its master instance.

A manual failover is a special kind of failover that is usually executed when
there are no actual failures, but we wish to swap the current master with one
of its replicas (which is the node we send the command to), in a safe way,
without any window for data loss. It works in the following way:

1. The replica tells the master to stop processing queries from clients.
2. The master replies to the replica with the current *replication offset*.
3. The replica waits for the replication offset to match on its side, to make sure it processed all the data from the master before it continues.
4. The replica starts a failover, obtains a new configuration epoch from the majority of the masters, and broadcasts the new configuration.
5. The old master receives the configuration update: unblocks its clients and starts replying with redirection messages so that they'll continue the chat with the new master.

This way clients are moved away from the old master to the new master
atomically and only when the replica that is turning into the new master
has processed all of the replication stream from the old master.

FORCE option: manual failover when the master is down

The command behavior can be modified by two options: **FORCE** and **TAKEOVER**.

If the **FORCE** option is given, the replica does not perform any handshake
with the master, that may be not reachable, but instead just starts a
failover ASAP starting from point 4. This is useful when we want to start
a manual failover while the master is no longer reachable.

However using **FORCE** we still need the majority of masters to be available
in order to authorize the failover and generate a new configuration epoch
for the replica that is going to become master.

TAKEOVER option: manual failover without cluster consensus

There are situations where this is not enough, and we want a replica to failover
without any agreement with the rest of the cluster. A real world use case
for this is to mass promote replicas in a different data center to masters
in order to perform a data center switch, while all the masters are down
or partitioned away.

The **TAKEOVER** option implies everything **FORCE** implies, but also does
not use any cluster authorization in order to failover. A replica receiving
`CLUSTER FAILOVER TAKEOVER` will instead:

1. Generate a new `configEpoch` unilaterally, just taking the current greatest epoch available and incrementing it if its local configuration epoch is not already the greatest.
2. Assign itself all the hash slots of its master, and propagate the new configuration to every node which is reachable ASAP, and eventually to every other node.

Note that **TAKEOVER violates the last-failover-wins principle** of Redis Cluster, since the configuration epoch generated by the replica violates the normal generation of configuration epochs in several ways:

1. There is no guarantee that it is actually the higher configuration epoch, since, for example, we can use the **TAKEOVER** option within a minority, nor any message exchange is performed to generate the new configuration epoch.
2. If we generate a configuration epoch which happens to collide with another instance, eventually our configuration epoch, or the one of another instance with our same epoch, will be moved away using the *configuration epoch collision resolution algorithm*.

Because of this the **TAKEOVER** option should be used with care.

Implementation details and notes

* `CLUSTER FAILOVER`, unless the **TAKEOVER** option is specified, does not execute a failover synchronously.
  It only *schedules* a manual failover, bypassing the failure detection stage.
* An `OK` reply is no guarantee that the failover will succeed.
* A replica can only be promoted to a master if it is known as a replica by a majority of the masters in the cluster.
  If the replica is a new node that has just been added to the cluster (for example after upgrading it), it may not yet be known to all the masters in the cluster.
  To check that the masters are aware of a new replica, you can send [`CLUSTER NODES`]() or [`CLUSTER REPLICAS`]() to each of the master nodes and check that it appears as a replica, before sending `CLUSTER FAILOVER` to the replica.
* To check that the failover has actually happened you can use [`ROLE`](), `INFO REPLICATION` (which indicates "role:master" after successful failover), or [`CLUSTER NODES`]() to verify that the state of the cluster has changed sometime after the command was sent.
* To check if the failover has failed, check the replica's log for "Manual failover timed out", which is logged if the replica has given up after a few seconds.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was accepted and a manual failover is going to be attempted. An error if the operation cannot be executed, for example if the client is connected to a node that is already a master.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was accepted and a manual failover is going to be attempted. An error if the operation cannot be executed, for example if the client is connected to a node that is already a master.


CLUSTER FLUSHSLOTS

Summary: Deletes all slots information from a node.

Overview

Deletes all slots from a node.

The `CLUSTER FLUSHSLOTS` deletes all information about slots from the connected node. It can only be called when the database is empty.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK`

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK`.


CLUSTER FORGET

Summary: Removes a node from the nodes table.

Overview

The command is used in order to remove a node, specified via its node ID,
from the set of *known nodes* of the Redis Cluster node receiving the command.
In other words the specified node is removed from the *nodes table* of the
node receiving the command.

Because when a given node is part of the cluster, all the other nodes
participating in the cluster knows about it, in order for a node to be
completely removed from a cluster, the `CLUSTER FORGET` command must be
sent to all the remaining nodes, regardless of the fact they are masters
or replicas.

However the command cannot simply drop the node from the internal node
table of the node receiving the command, it also implements a ban-list, not
allowing the same node to be added again as a side effect of processing the
*gossip section* of the heartbeat packets received from other nodes.

Starting with Redis 7.2.0, the ban-list is included in cluster gossip ping/pong messages.
This means that `CLUSTER FORGET` doesn't need to be sent to all nodes in a cluster.
You can run the command on one or more nodes, after which it will be propagated to the rest of the nodes in most cases.

Details on why the ban-list is needed

In the following example we'll show why the command must not just remove
a given node from the nodes table, but also prevent it for being re-inserted
again for some time.

Let's assume we have four nodes, A, B, C and D. In order to
end with just a three nodes cluster A, B, C we may follow these steps:

1. Reshard all the hash slots from D to nodes A, B, C.
2. D is now empty, but still listed in the nodes table of A, B and C.
3. We contact A, and send `CLUSTER FORGET D`.
4. B sends node A a heartbeat packet, where node D is listed.
5. A does no longer known node D (see step 3), so it starts a handshake with D.
6. D ends re-added in the nodes table of A.

As you can see in this way removing a node is fragile, we need to send
`CLUSTER FORGET` commands to all the nodes ASAP hoping there are no
gossip sections processing in the meantime. Because of this problem the
command implements a ban-list with an expire time for each entry.

So what the command really does is:

1. The specified node gets removed from the nodes table.
2. The node ID of the removed node gets added to the ban-list, for 1 minute.
3. The node will skip all the node IDs listed in the ban-list when processing gossip sections received in heartbeat packets from other nodes.

This way we have a 60 second window to inform all the nodes in the cluster that
we want to remove a node.

Special conditions not allowing the command execution

The command does not succeed and returns an error in the following cases:

1. The specified node ID is not found in the nodes table.
2. The node receiving the command is a replica, and the specified node ID identifies its current master.
3. The node ID identifies the same node we are sending the command to.

Behavior change history

*   `>= 7.2.0`: Automatically propagate node deletion to other nodes in a cluster, allowing nodes to be deleted with a single call
  in most cases.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was executed successfully. Otherwise an error is returned.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was executed successfully. Otherwise an error is returned.


CLUSTER GETKEYSINSLOT

Summary: Returns the key names in a hash slot.

Overview

The command returns an array of keys names stored in the contacted node and
hashing to the specified hash slot. The maximum number of keys to return
is specified via the `count` argument, so that it is possible for the user
of this API to batch-processing keys.

The main usage of this command is during rehashing of cluster slots from one
node to another. The way the rehashing is performed is exposed in the Redis
Cluster specification, or in a more simple to digest form, as an appendix
of the [`CLUSTER SETSLOT`]() command documentation.

During atomic slot migration operations (available since Redis 8.4.0), keys being imported or trimmed will be filtered out from the results.

[code example]

Return information

**RESP2:**

[Array reply](../../develop/reference/protocol-spec#arrays): an array with up to count elements.

**RESP3:**

[Array reply](../../develop/reference/protocol-spec#arrays): an array with up to count elements.


CLUSTER HELP

Overview

The `CLUSTER HELP` command returns a helpful text describing the different subcommands.

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ✅ Standard
<nobr>✅ Active-Active</nobr> | ✅ Standard
<nobr>✅ Active-Active</nobr> | Only supported with the [OSS cluster API](). |

Return information

**RESP2:**

[Array reply](../../develop/reference/protocol-spec#arrays): a list of subcommands and their descriptions.

**RESP3:**

[Array reply](../../develop/reference/protocol-spec#arrays): a list of subcommands and their descriptions.


CLUSTER INFO

Summary: Returns information about the state of a node.

Overview

`CLUSTER INFO` provides [`INFO`]() style information about Redis Cluster vital parameters.
The following fields are always present in the reply:

[code example]

* `cluster_state`: State is `ok` if the node is able to receive queries. `fail` if there is at least one hash slot which is unbound (no node associated), in error state (node serving it is flagged with FAIL flag), or if the majority of masters can't be reached by this node.
* `cluster_slots_assigned`: Number of slots which are associated to some node (not unbound). This number should be 16384 for the node to work properly, which means that each hash slot should be mapped to a node.
* `cluster_slots_ok`: Number of hash slots mapping to a node not in `FAIL` or `PFAIL` state.
* `cluster_slots_pfail`: Number of hash slots mapping to a node in `PFAIL` state. Note that those hash slots still work correctly, as long as the `PFAIL` state is not promoted to `FAIL` by the failure detection algorithm. `PFAIL` only means that we are currently not able to talk with the node, but may be just a transient error.
* `cluster_slots_fail`: Number of hash slots mapping to a node in `FAIL` state. If this number is not zero the node is not able to serve queries unless `cluster-require-full-coverage` is set to `no` in the configuration.
* `cluster_known_nodes`: The total number of known nodes in the cluster, including nodes in `HANDSHAKE` state that may not currently be proper members of the cluster.
* `cluster_size`: The number of master nodes serving at least one hash slot in the cluster.
* `cluster_current_epoch`: The local `Current Epoch` variable. This is used in order to create unique increasing version numbers during fail overs.
* `cluster_my_epoch`: The `Config Epoch` of the node we are talking with. This is the current configuration version assigned to this node.
* `cluster_stats_messages_sent`: Number of messages sent via the cluster node-to-node binary bus.
* `cluster_stats_messages_received`: Number of messages received via the cluster node-to-node binary bus.
* `total_cluster_links_buffer_limit_exceeded`: Accumulated count of cluster links freed due to exceeding the `cluster-link-sendbuf-limit` configuration.

The following atomic slot migration fields may be included in the reply (available since Redis 8.4.0):

* `cluster_slot_migration_active_tasks`: Number of in-progress ASM tasks. Currently, it will be 1 or 0.
* `cluster_slot_migration_active_trim_running`: Number of active trim jobs in progress and scheduled.
* `cluster_slot_migration_active_trim_current_job_keys`: Number of keys scheduled for deletion in the current trim job.
* `cluster_slot_migration_active_trim_current_job_trimmed`: Number of keys already deleted in the current trim job.
* `cluster_slot_migration_stats_active_trim_started`: Total number of trim jobs that have started since the process began.
* `cluster_slot_migration_stats_active_trim_completed`: Total number of trim jobs completed since the process began.
* `cluster_slot_migration_stats_active_trim_cancelled`: Total number of trim jobs cancelled since the process began.

The following message-related fields may be included in the reply if the value is not 0:
Each message type includes statistics on the number of messages sent and received.
Here are the explanation of these fields:

* `cluster_stats_messages_ping_sent` and `cluster_stats_messages_ping_received`: Cluster bus PING (not to be confused with the client command [`PING`]()).
* `cluster_stats_messages_pong_sent` and `cluster_stats_messages_pong_received`: PONG (reply to PING).
* `cluster_stats_messages_meet_sent` and `cluster_stats_messages_meet_received`: Handshake message sent to a new node, either through gossip or [`CLUSTER MEET`]().
* `cluster_stats_messages_fail_sent` and `cluster_stats_messages_fail_received`: Mark node xxx as failing.
* `cluster_stats_messages_publish_sent` and `cluster_stats_messages_publish_received`: Pub/Sub Publish propagation, see [Pubsub]().
* `cluster_stats_messages_auth-req_sent` and `cluster_stats_messages_auth-req_received`: Replica initiated leader election to replace its master.
* `cluster_stats_messages_auth-ack_sent` and `cluster_stats_messages_auth-ack_received`: Message indicating a vote during leader election.
* `cluster_stats_messages_update_sent` and `cluster_stats_messages_update_received`: Another node slots configuration.
* `cluster_stats_messages_mfstart_sent` and `cluster_stats_messages_mfstart_received`: Pause clients for manual failover.
* `cluster_stats_messages_module_sent` and `cluster_stats_messages_module_received`: Module cluster API message.
* `cluster_stats_messages_publishshard_sent` and `cluster_stats_messages_publishshard_received`: Pub/Sub Publish shard propagation, see [Sharded Pubsub]().

More information about the Current Epoch and Config Epoch variables are available in the [Redis Cluster specification document]().

Return information

**RESP2:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): A map between named fields and values in the form of `<field>:<value>` lines separated by newlines composed by the two bytes `CRLF`.

**RESP3:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): A map between named fields and values in the form of <field>:<value> lines separated by newlines composed by the two bytes CRLF

cluster_state:ok
cluster_slots_assigned:16384
cluster_slots_ok:16384
cluster_slots_pfail:0
cluster_slots_fail:0
cluster_known_nodes:6
cluster_size:3
cluster_current_epoch:6
cluster_my_epoch:2
cluster_stats_messages_sent:1483972
cluster_stats_messages_received:1483968
total_cluster_links_buffer_limit_exceeded:0


CLUSTER KEYSLOT

Summary: Returns the hash slot for a key.

Overview

Returns an integer identifying the hash slot the specified key hashes to.
This command is mainly useful for debugging and testing, since it exposes
via an API the underlying Redis implementation of the hashing algorithm.
Example use cases for this command:

1. Client libraries may use Redis in order to test their own hashing algorithm, generating random keys and hashing them with both their local implementation and using Redis `CLUSTER KEYSLOT` command, then checking if the result is the same.
2. Humans may use this command in order to check what is the hash slot, and then the associated Redis Cluster node, responsible for a given key.

Example

[code example]

Note that the command implements the full hashing algorithm, including support for **hash tags**, that is the special property of Redis Cluster key hashing algorithm, of hashing just what is between `{` and `}` if such a pattern is found inside the key name, in order to force multiple keys to be handled by the same node.

Return information

**RESP2:**

[Integer reply](../../develop/reference/protocol-spec#integers): The hash slot number for the specified key

**RESP3:**

[Integer reply](../../develop/reference/protocol-spec#integers): The hash slot number for the specified key

> CLUSTER KEYSLOT somekey
(integer) 11058
> CLUSTER KEYSLOT foo{hash_tag}
(integer) 2515
> CLUSTER KEYSLOT bar{hash_tag}
(integer) 2515


CLUSTER LINKS

Summary: Returns a list of all TCP links to and from peer nodes.

Overview

Each node in a Redis Cluster maintains a pair of long-lived TCP link with each peer in the cluster: One for sending outbound messages towards the peer and one for receiving inbound messages from the peer.

`CLUSTER LINKS` outputs information of all such peer links as an array, where each array element is a map that contains attributes and their values for an individual link.

Examples

The following is an example output:

[code example]

Each map is composed of the following attributes of the corresponding cluster link and their values:

1. `direction`: This link is established by the local node `to` the peer, or accepted by the local node `from` the peer.
2. `node`: The node id of the peer.
3. `create-time`: Creation time of the link. (In the case of a `to` link, this is the time when the TCP link is created by the local node, not the time when it is actually established.)
4. `events`: Events currently registered for the link. `r` means readable event, `w` means writable event.
5. `send-buffer-allocated`: Allocated size of the link's send buffer, which is used to buffer outgoing messages toward the peer.
6. `send-buffer-used`: Size of the portion of the link's send buffer that is currently holding data(messages).

| Redis
Software | Redis
Cloud | Notes |
|:----------------------|:-----------------|:------|
| ❌ Standard
<nobr>❌ Active-Active</nobr> | ❌ Standard
<nobr>❌ Active-Active</nobr> |  |

Return information

**RESP2:**

[Array reply](../../develop/reference/protocol-spec#arrays): an array of maps where each map contains various attributes and their values of a cluster link.

**RESP3:**

[Array reply](../../develop/reference/protocol-spec#arrays): an array of [Map reply](../../develop/reference/protocol-spec#maps) where each map contains various attributes and their values of a cluster link.

> CLUSTER LINKS
1)  1) "direction"
    2) "to"
    3) "node"
    4) "8149d745fa551e40764fecaf7cab9dbdf6b659ae"
    5) "create-time"
    6) (integer) 1639442739375
    7) "events"
    8) "rw"
    9) "send-buffer-allocated"
   10) (integer) 4512
   11) "send-buffer-used"
   12) (integer) 0
2)  1) "direction"
    2) "from"
    3) "node"
    4) "8149d745fa551e40764fecaf7cab9dbdf6b659ae"
    5) "create-time"
    6) (integer) 1639442739411
    7) "events"
    8) "r"
    9) "send-buffer-allocated"
   10) (integer) 0
   11) "send-buffer-used"
   12) (integer) 0


CLUSTER MEET

Summary: Forces a node to handshake with another node.

Overview

`CLUSTER MEET` is used in order to connect different Redis nodes with cluster
support enabled, into a working cluster.

The basic idea is that nodes by default don't trust each other, and are
considered unknown, so that it is unlikely that different cluster nodes will
mix into a single one because of system administration errors or network
addresses modifications.

So in order for a given node to accept another one into the list of nodes
composing a Redis Cluster, there are only two ways:

1. The system administrator sends a `CLUSTER MEET` command to force a node to meet another one.
2. An already known node sends a list of nodes in the gossip section that we are not aware of. If the receiving node trusts the sending node as a known node, it will process the gossip section and send a handshake to the nodes that are still not known.

Note that Redis Cluster needs to form a full mesh (each node is connected with each other node), but in order to create a cluster, there is no need to send all the `CLUSTER MEET` commands needed to form the full mesh. What matter is to send enough `CLUSTER MEET` messages so that each node can reach each other node through a *chain of known nodes*. Thanks to the exchange of gossip information in heartbeat packets, the missing links will be created.

So, if we link node A with node B via `CLUSTER MEET`, and B with C, A and C will find their ways to handshake and create a link.

Another example: if we imagine a cluster formed of the following four nodes called A, B, C and D, we may send just the following set of commands to A:

1. `CLUSTER MEET B-ip B-port`
2. `CLUSTER MEET C-ip C-port`
3. `CLUSTER MEET D-ip D-port`

As a side effect of `A` knowing and being known by all the other nodes, it will send gossip sections in the heartbeat packets that will allow each other node to create a link with each other one, forming a full mesh in a matter of seconds, even if the cluster is large.

Moreover `CLUSTER MEET` does not need to be reciprocal. If I send the command to A in order to join B, I don't need to also send it to B in order to join A.

If the optional `cluster_bus_port` argument is not provided, the default of port + 10000 will be used.

Implementation details: MEET and PING packets

When a given node receives a `CLUSTER MEET` message, the node specified in the
command still does not know the node we sent the command to. So in order for
the node to force the receiver to accept it as a trusted node, it sends a
`MEET` packet instead of a [`PING`]() packet. The two packets have exactly the
same format, but the former forces the receiver to acknowledge the node as
trusted.

Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was successful. If the address or port specified are invalid an error is returned.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was successful. If the address or port specified are invalid an error is returned.


CLUSTER MIGRATION

Summary: Start, monitor, and cancel atomic slot migration tasks.

Overview

The `CLUSTER MIGRATION` command provides atomic slot migration functionality for Redis Cluster. This command allows you to import slots from other nodes, monitor the progress of migration tasks, and cancel ongoing migrations.

Required arguments

subcommand

The subcommand specifies the operation to perform:

- `IMPORT <start-slot> <end-slot> [<start-slot> <end-slot> ...]`: Executes on the destination master. Accepts multiple slot ranges and triggers atomic migration for the specified ranges. Returns a task ID that you can use to monitor the status of the task.

- `CANCEL <ID <task-id> | ALL>`: Cancels an ongoing migration task by its ID or cancels all tasks if `ALL` is specified. Note: Cancelling a task on the source node does not stop the migration on the destination node, which will continue retrying until it is also cancelled there.

- `STATUS [ID <task-id> | ALL]`: Displays the status of current and completed atomic slot migration tasks. If a specific task ID is provided, it returns detailed information for that task only. If `ALL` is specified, it returns the status of all ongoing and completed tasks.

Examples

Import slots 0-1000 and 2000-3000 to the current node:

[code example]

Check the status of all migration tasks:

[code example]

Check the status of a specific migration task:

[code example]

Cancel a specific migration task:

[code example]

Cancel all migration tasks:

[code example]

Return information

**RESP2:**

For the `IMPORT` subcommand:
[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): task ID on success, or error message on failure.

For the `CANCEL` subcommand:
[Integer reply](../../develop/reference/protocol-spec#integers): number of cancelled tasks.

For the `STATUS` subcommand:
[Array reply](../../develop/reference/protocol-spec#arrays): a list of migration task details. Each task is represented as an array containing field-value pairs:
- `id`: Task identifier
- `slots`: Slot range being imported or migrated
- `source`: Source node ID
- `dest`: Destination node ID
- `operation`: Operation type ("import" or "migrate")
- `state`: Current state ("completed", "in_progress", etc.)
- `last_error`: Last error message (empty if none)
- `retries`: Number of retry attempts
- `create_time`: Task creation timestamp
- `start_time`: Task start timestamp
- `end_time`: Task completion timestamp (if completed)
- `write_pause_ms`: Write pause duration in milliseconds

**RESP3:**

For the `IMPORT` subcommand:
[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): task ID on success, or error message on failure.

For the `CANCEL` subcommand:
[Integer reply](../../develop/reference/protocol-spec#integers): number of cancelled tasks.

For the `STATUS` subcommand:
[Array reply](../../develop/reference/protocol-spec#arrays): a list of migration task details. Each task is represented as an array containing field-value pairs:
- `id`: Task identifier
- `slots`: Slot range being migrated
- `source`: Source node ID
- `dest`: Destination node ID
- `operation`: Operation type (typically "migrate")
- `state`: Current state ("completed", "in_progress", etc.)
- `last_error`: Last error message (empty if none)
- `retries`: Number of retry attempts
- `create_time`: Task creation timestamp
- `start_time`: Task start timestamp
- `end_time`: Task completion timestamp (if completed)
- `write_pause_ms`: Write pause duration in milliseconds

Notes

- The atomic slot migration feature is available starting from Redis 8.4.0.
- Cancelling a task on the source node does not automatically stop the migration on the destination node.
- In `CLUSTER MIGRATION STATUS` output, the "state" field will show `completed` for successful operations.
- Tasks with empty "last_error" fields indicate no errors occurred during the migration process.

Key visibility during migration

During atomic slot migration operations, keys in unowned slots may be filtered out from the following commands while importing or trimming is in progress:

- [`KEYS`]()
- [`SCAN`]()
- [`RANDOMKEY`]()
- [`CLUSTER GETKEYSINSLOT`]()
- [`DBSIZE`]()
- [`CLUSTER COUNTKEYSINSLOT`]()

The [`INFO KEYSPACE`]() command will continue to reflect the actual number of keys, including those being imported.

Related configuration

- `cluster-slot-migration-handoff-max-lag-bytes`: After slot snapshot completion, if remaining replication stream size falls below this threshold, the source node pauses writes to hand off slot ownership. Higher values trigger handoff earlier but may cause longer write pauses. Lower values result in shorter write pauses but may be harder to reach with steady incoming writes (default: 1MB).
- `cluster-slot-migration-write-pause-timeout`: Maximum duration that the source node pauses writes during ASM handoff. If the destination fails to take over slots within this timeout, the source assumes migration failed and resumes writes (default: 10 seconds).

CLUSTER MIGRATION IMPORT 0 1000 2000 3000

CLUSTER MIGRATION STATUS ID 24cf41718b20f7f05901743dffc40bc9b15db339

CLUSTER MIGRATION CANCEL ID 24cf41718b20f7f05901743dffc40bc9b15db339


CLUSTER MYID

Summary: Returns the ID of a node.

Overview

Returns the node's id.

The `CLUSTER MYID` command returns the unique, auto-generated identifier that is associated with the connected cluster node.

Return information

**RESP2:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): the node ID.

**RESP3:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): the node ID.


CLUSTER MYSHARDID

Summary: Returns the shard ID of a node.

Overview

Returns the node's shard id.

The `CLUSTER MYSHARDID` command returns the unique, auto-generated identifier that is associated with the shard to which the connected cluster node belongs.

Return information

**RESP2:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): the node's shard ID.

**RESP3:**

[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): the node's shard ID.