Command Routing

Valkey GLIDE can determine and route commands efficiently to nodes in a Valkey (or Redis) cluster. This section will go over how command routing works in Valkey GLIDE.

How GLIDE Routes commands

As a Valkey cluster topology can change over time, new nodes can be added or removed and the primary node owning a specific slot may change. To handle this, GLIDE clients are topology aware. They maintain a map of the cluster state and route commands to the primary node. When topology changes (e.g., due to scaling operations or failovers), GLIDE clients update their internal cluster map to ensure commands are always routed correctly.

For example, in a cluster Valkey setup, data are sharded across multiple nodes. A command like client.set("user:100", "active") will be routed only to the primary node containing the slot for the key user:100.

Read Strategy

By default, GLIDE routes all read commands to the primary nodes. This can lead to higher load especially if there are many write operations on the primary node. To optimize read performance and distribute the load, GLIDE clients support different read strategies that allow reads to be directed to replica nodes.

Reads from replicas can return stale data, including immediately after a write.

The table describes ordinary cluster reads governed by the client’s read strategy. Candidates are available connections for the key’s shard, not arbitrary nodes across the cluster. “Local” means the AZ configured for the client. Writes and commands that require a primary continue to use the primary; explicit routing options are separate from these defaults.

Strategy	Description
Primary (Default)	Always read from primary, in order to get the freshest data.
AllNodes	Rotate across available primary and replicas, without an AZ preference.
PreferReplica	Spread requests between all replicas in a round robin manner. If no replica is available, route the requests to the primary.
AZAffinity	Spread the read requests between replicas in the same client’s availability zone in a round robin manner, falling back to other available replicas, then to the primary only if no replica is available.
AzAffinityReplicaAndPrimary	Spread the read requests among nodes within the client’s Availability Zone (AZ) in a round robin manner, prioritizing local replicas, then the local primary, and falling back to any available replica, then to the primary only if no replica is available.
AZAffinityAllNodes	Spread the read requests equally among all nodes (primary and replicas) within the client’s availability zone in a round robin manner, falling back to a round robin across all nodes if no node in the client’s availability zone is available.

Primary participation with AZ affinity

With both AZ Affinity Replicas and Primary and AZ Affinity All Nodes, an available local primary receives reads if it is the only available local node, even when remote replicas are available.

AZ Affinity All Nodes differs in two cases: the local primary shares the rotation while local replicas are available, and, when no local node is available, the remote primary shares the fallback rotation with remote replicas. AZ Affinity Replicas and Primary instead prefers replicas in each of those groups. A remote primary does not join the rotation while a local node remains available.

Round-robin distributes requests, not measured CPU utilization. Concurrency, retries, and topology changes can affect the observed distribution.

Standalone fallback

In standalone mode, AZ Affinity uses local replicas, then any available replicas, then the primary. AZ Affinity Replicas and Primary uses local replicas, then the local primary, but its final fallback rotates across all available primary and replica nodes. AZ Affinity All Nodes rotates equally across local primary and replicas, then all available nodes if no local node is available. Thus, equal local-primary participation alongside local replicas is new with AZ Affinity All Nodes; including the primary in the final standalone fallback pool is not.

AZ Affinity All Nodes is included in Java and Python in 2.5.3; Go and Node support is planned for 2.6.0. The AZ-independent All Nodes strategy is available in Java, Python, Go, and Node in 2.4.0 and later. For configuration examples and AZ requirements, see Specify a Read Strategy.

Automatic Redirect Handling (MOVED and ASK)

In a Valkey cluster, slots can move between nodes during failovers, scaling operations, or rebalancing. When a command is sent to a node that no longer owns the target slot, the server responds with a redirect error rather than executing the command. GLIDE handles these redirects automatically.

MOVED Redirects

A MOVED error indicates that a slot has been permanently reassigned to a different node. When GLIDE receives a MOVED response:

1. The command is re-sent to the node specified in the redirect.
2. GLIDE updates its internal topology map so future commands for that slot go directly to the new owner.
3. A full topology refresh may be triggered to capture any other slot changes.

This commonly occurs during failovers (a replica is promoted to primary) or when the cluster is rebalanced.

ASK Redirects

An ASK error indicates that a slot is in the process of migrating to another node but the migration is not yet complete. When GLIDE receives an ASK response:

1. GLIDE sends an ASKING command to the target node (required by the Valkey protocol to access a migrating slot).
2. The original command is then re-sent to that node.
3. The topology map is not updated, since the migration may not be finalized.

Once the migration completes, subsequent requests will receive a MOVED redirect, at which point GLIDE updates its map permanently.

Circular Redirect Protection

GLIDE detects circular MOVED redirects — cases where a redirect points back to the same node (e.g., due to DNS resolution or stale routing). When detected, GLIDE triggers a topology refresh rather than retrying indefinitely.

Note

All redirect handling is transparent to the application. No special error handling or retry logic is needed in your code.

Multi-Slot Commands

In Valkey or Redis Cluster mode, certain commands can operate on multiple keys that may be spread across different hash slots. When these commands receive keys that map to multiple slots, they are called multi-slot commands. GLIDE supports efficient handling of these commands routing them across the cluster.

For more on multi-slot commands, see this section.