Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

CLUSTER SETSLOT

Last updated 
CLUSTER SETSLOT slot IMPORTING node-id [TIMEOUT milliseconds]
CLUSTER SETSLOT slot MIGRATING node-id [TIMEOUT milliseconds]
CLUSTER SETSLOT slot NODE node-id [TIMEOUT milliseconds]
CLUSTER SETSLOT slot STABLE [TIMEOUT milliseconds]
Group
Cluster
Complexity
O(1)
Arity
-4 (at least 4 words, counting the command name)
HotKV Cloud
Not available
On-Premise
no license needed

CLUSTER SETSLOT changes the state of one hash slot on the receiving primary. Moving a slot from a source node to a target node takes these steps, which redis-cli --cluster reshard runs for you:

  1. On the target: CLUSTER SETSLOT <slot> IMPORTING <source-id>.
  2. On the source: CLUSTER SETSLOT <slot> MIGRATING <target-id>.
  3. On the source: move the keys with CLUSTER GETKEYSINSLOT and MIGRATE until none are left.
  4. On the target and the source (and optionally every other primary): CLUSTER SETSLOT <slot> NODE <target-id>.

While a slot is migrating, the source answers commands on keys that have already moved with -ASK, and the target accepts them after ASKING.

Options

Section titled “Options”
Action Effect
IMPORTING node-id This node is about to receive the slot from node-id. Refused if this node already owns the slot.
MIGRATING node-id This node is about to hand the slot to node-id. Refused unless this node owns the slot.
NODE node-id Make node-id the slot’s owner. On the source, refused while keys of the slot are still here. Closes the slot’s migrating or importing state.
STABLE Close the slot’s migrating or importing state, for example to cancel a migration.
TIMEOUT milliseconds How long a primary with connected replicas waits for them to acknowledge the change (default 2000, 0 for no limit).

On a primary with connected replicas, the change first goes to the replicas, and takes effect on the primary once they all acknowledge it. That way a replica that takes over in the middle of a migration carries on with it. If the replicas do not answer in time, nothing changes and the command replies NOREPLICAS. Inside MULTI or a script the command does not wait.

MIGRATE does not move HotKV’s AI feature data (caches, vector indexes, agent memory and the rest). HotKV moves it for you: all of the slot’s AI data goes to the target when you set the slot MIGRATING, or when you set NODE on a slot whose data is still on this node. If that copy fails, the command replies with an IOERR error, the slot stays with this node, and you can retry.

A primary that gives away its last slot becomes a replica of the new owner, as in Redis (see cluster-allow-replica-migration).

While an atomic slot migration of a slot runs (see CLUSTER MIGRATESLOTS and CLUSTER MIGRATION), CLUSTER SETSLOT for that slot is refused, and an atomic migration is refused while a slot is open by hand. Close the open slot with STABLE, or cancel the migration, first.

Return value

Section titled “Return value”

Simple string OK in RESP2 and RESP3, or one of these errors:

Case Error
Sent to a replica ERR Please use SETSLOT only with masters.
Slot not from 0 to 16383 ERR Invalid or out of range slot
Unknown action, or a missing node ID ERR Invalid CLUSTER SETSLOT action or number of arguments. Try CLUSTER HELP
MIGRATING a slot this node does not own ERR I'm not the owner of hash slot <slot>
IMPORTING a slot this node owns ERR I'm already the owner of hash slot <slot>
MIGRATING or IMPORTING with an unknown node ERR I don't know about node <node-id>
NODE with an unknown node ERR Unknown node <node-id>
The node is a replica ERR Target node is not a master
NODE while keys of the slot remain here ERR Can't assign hashslot <slot> to a different node while I still hold keys for this hash slot.
TIMEOUT without a value ERR Missing timeout value
TIMEOUT not an integer ERR timeout is not an integer or out of range
A negative TIMEOUT ERR timeout is negative
The replicas did not acknowledge in time NOREPLICAS Not enough good replicas to write.
An atomic migration of the slot is running, on the source or the target of a CLUSTER MIGRATESLOTS ERR Slot export in progress. or ERR Slot import in progress.
A CLUSTER MIGRATION IMPORT task is running for the slot ERR Slot <slot> is in an active atomic slot migration, which CLUSTER SETSLOT would disturb; CLUSTER MIGRATION CANCEL ends the task, after which a manual migration may start
The AI data could not be moved IOERR AI data migration to the target failed: <reason> (or ... to the new owner failed: <reason> for NODE)
Cluster mode is off ERR This instance has cluster support disabled

Examples

Section titled “Examples”

Move slot 1649 from node b4240b... (10.0.0.1) to node 0e2a97... (10.0.0.2):

10.0.0.2:6379> CLUSTER SETSLOT 1649 IMPORTING b4240bf759694b9ba85b3b5efd51785b86261c3e
OK
10.0.0.1:6379> CLUSTER SETSLOT 1649 MIGRATING 0e2a97d798979a2e3e5e7f940e2ac533fb36b69b
OK
10.0.0.1:6379> CLUSTER GETKEYSINSLOT 1649 100
1) "user:1000"
10.0.0.1:6379> MIGRATE 10.0.0.2 6379 "" 0 5000 KEYS user:1000
OK
10.0.0.1:6379> CLUSTER SETSLOT 1649 NODE 0e2a97d798979a2e3e5e7f940e2ac533fb36b69b
OK
10.0.0.2:6379> CLUSTER SETSLOT 1649 NODE 0e2a97d798979a2e3e5e7f940e2ac533fb36b69b
OK

Compatibility

Section titled “Compatibility”

The actions and error strings match Redis 7. The replication of the change to the replicas and the TIMEOUT option match Valkey 8; options HotKV does not know are skipped. Moving the AI feature data is HotKV’s own.

See also

Section titled “See also”

MIGRATE, ASKING, CLUSTER GETKEYSINSLOT, CLUSTER COUNTKEYSINSLOT, Scaling a cluster