tencent cloud

Tencent Cloud Distributed Cache (Redis OSS-Compatible)

DokumentasiTencent Cloud Distributed Cache (Redis OSS-Compatible)

Commands with Limited Support in the Redis/Valkey Edition

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-08-11 11:12:00
Diterjemahkan oleh AI

Overview

The distributed cache database cluster architecture provides services externally through the Proxy layer, hiding the actual network topology of the backend shards. To ensure compatibility with the connection discovery mechanisms of smart clients such as Jedis Cluster and Lettuce Cluster, the cluster architecture provides partial support for certain Cluster commands. These commands can be executed normally, but the returned node IP addresses are uniformly replaced with the instance's Proxy VIP address (that is, the instance's private IPv4 access address), rather than the real internal IPs of the backend shard nodes. This design ensures that smart clients do not attempt to directly connect to backend shards during the connection discovery phase (as backend shards are unreachable to clients), while maintaining compatibility at the protocol layer.

CLUSTER NODES

Command Description

CLUSTER NODES returns the node configuration information of the current cluster. The output is in text format, with each line representing a node.

Return Value Format

The fields in each line of node information are separated by spaces. The structure is as follows:
<node-id> <ip:port@cport[,hostname]> <flags> <master-id> <ping-sent> <pong-recv> <config-epoch> <link-state> <slot> <slot> ... <slot>
Field Descriptions:
Field
Description
node-id
Unique node identifier (40-character hexadecimal string)
ip:port@cport
Node client connection address and cluster bus port
flags
Node flags, comma-separated (for example, myself,master, slave)
master-id
If the node is a replica node, this field displays the ID of its master node. For a master node, this field displays -.
ping-sent
The Unix millisecond timestamp when the last active PING message was sent. The value is 0 if there is no pending PING.
pong-recv
Unix millisecond timestamp of the last PONG message received
config-epoch
Configuration epoch number of the node
link-state
Cluster bus connection status: connected or disconnected
slot
The hash slot number or range that this node is responsible for (for example, 0-5460). This field is not present for replica nodes.

Example

127.0.0.1:6379> CLUSTER NODES
Return Value Example:
4c5bef442ee294489c57cdd1**************** 10.0.0.5:6379@16379 myself,master - 0 1691234567000 1 connected 0-5460
a1b2c3d4e5f6a7b8c9d0e1f2**************** 10.0.0.5:6379@16379 master - 0 1691234567000 2 connected 5461-10922
f0e1d2c3b4a5f6e7d8c9b0a1**************** 10.0.0.5:6379@16379 master - 0 1691234567000 3 connected 10923-16383

Common Flags

Flag
Description
myself
The node itself that is currently connected.
master
Primary Node
slave
Replica node
fail?
Suspected failure state (PFAIL), where the node is unreachable in the view of the majority of master nodes.
fail
Confirmed failure state (FAIL), where the cluster has performed a failover on this node.
handshake
A node in the handshake phase, which has not yet completed the join process.
noaddr
Address unknown
nofailover
A replica node enters the takeover state.
noflags
No flags

CLUSTER SLOTS

Command Description

CLUSTER SLOTS returns the mapping of hash slots to nodes. It outputs each slot range and its corresponding node in an array format.
Note:
The CLUSTER SLOTS command has been deprecated since Redis 7.0.0 / Valkey 7.0. Use the CLUSTER SHARDS command instead. For details, see the CLUSTER SHARDS description below.

Return Value Format

It returns a nested array, where each element represents the mapping information for a slot range:
No.
Content
Description
1
Starting slot
An integer, the starting slot number (inclusive) of the slot range
2
Ending slot
An integer, the ending slot number (inclusive) of the slot range
3
Primary node information
An array: [IP, port, node ID]
4
First replica information
An array: [IP, port, node ID]
5+
Subsequent replica information
An array: [IP, port, node ID] (if multiple replicas exist)

Example

127.0.0.1:6379> CLUSTER SLOTS
Return Value Example:
1) 1) (integer) 0
   2) (integer) 5460
   3) 1) "10.0.0.5"
         2) (integer) 6379
         3) "4c5bef442ee294489c57cdd1****************"
   4) 1) "10.0.0.5"
         2) (integer) 6379
         3) "d4e5f6a7b8c9d0e1f2a3b4c5****************"
2) 1) (integer) 5461
   2) (integer) 10922
   3) 1) "10.0.0.5"
         2) (integer) 6379
         3) "a1b2c3d4e5f6a7b8c9d0e1f2****************"
   4) 1) "10.0.0.5"
         2) (integer) 6379
         3) "e5f6a7b8c9d0e1f2a3b4c5d6****************"
3) 1) (integer) 10923
   2) (integer) 16383
   3) 1) "10.0.0.5"
         2) (integer) 6379
         3) "f0e1d2c3b4a5f6e7d8c9b0a1****************"
   4) 1) "10.0.0.5"
         2) (integer) 6379
         3) "b8c9d0e1f2a3b4c5d6e7f8a9****************"

CLUSTER SHARDS (Recommended Alternative)

Command Description

CLUSTER SHARDS was introduced in Redis 7.0.0 / Valkey 7.0. It returns cluster topology information organized by Shard, serving as a modern replacement for CLUSTER SLOTS. Compared to CLUSTER SLOTS, this command provides a clearer return structure and richer node metadata.
Version Requirements: Redis Engine version 7.0 or later, or Valkey Engine version 8.0 or later.

Return Value Format

It returns an array of shards, where each shard contains the following fields:
Field
Description
slots
The list of slot ranges for this shard service (start-end integer pairs)
nodes
An array of node information, with each node containing detailed attributes.
Node Attributes:
Attribute
Description
id
Unique node ID
endpoint
Client connection endpoint (IP address or hostname)
ip
Node IP address
port
TCP port.
tls-port
TLS port (if enabled).
role
Replication role: master or replica.
replication-offset
Replication offset
health
Health status: online, failed, or loading.

Example

127.0.0.1:6379> CLUSTER SHARDS
Return Value Example:
1) 1) "slots"
   2) 1) (integer) 0
      2) (integer) 5460
   3) "nodes"
   4) 1) 1) "id"
            2) "4c5bef442ee294489c57cdd1****************"
         3) "port"
            4) (integer) 6379
         5) "ip"
            6) "10.0.0.5"
         7) "endpoint"
            8) "10.0.0.5"
         9) "role"
           10) "master"
        11) "replication-offset"
           12) (integer) 1234
        13) "health"
           14) "online"
      2) 1) "id"
            2) "d4e5f6a7b8c9d0e1f2a3b4c5****************"
         3) "port"
            4) (integer) 6379
         5) "ip"
            6) "10.0.0.5"
         7) "endpoint"
            8) "10.0.0.5"
         9) "role"
           10) "replica"
        11) "replication-offset"
           12) (integer) 1234
        13) "health"
           14) "online"
Note:
Consistent with CLUSTER NODES and CLUSTER SLOTS, the ip and endpoint fields for all nodes return the instance's Proxy VIP address.

Must-Knows

Smart Client Behavior

Smart clients (such as Jedis Cluster, Lettuce Cluster, and redis-py Cluster) call CLUSTER SLOTS or CLUSTER SHARDS during initialization to obtain topology information and establish direct connections to each shard accordingly. In a distributed cache database cluster architecture, because the returned IP addresses are all Proxy VIPs, all connections established by clients are directed to the Proxy layer. The Proxy is responsible for routing requests to the correct shard.
This approach is transparent to clients. Business code can use smart client libraries normally without requiring any modifications.

Differences from Open-Source Redis Cluster

Comparison Item
Open Source Redis Cluster
Distributed Cache Database Cluster Architecture
Returned node IP address
Real IP address of each shard
Uniformly set to the Proxy VIP address
Client directly connecting to shards
Supported
Not supported (traffic is uniformly routed through the Proxy)
-MOVED redirection
Points to the target shard IP address
Points to the Proxy VIP
-ASK redirection
Points to the migration target IP address
Points to the Proxy VIP

Version and Architecture Applicability

Command
Redis Edition
Valkey Edition
Architecture Requirement
CLUSTER NODES
All versions
8.0+
Cluster Architecture
CLUSTER SLOTS
All versions (deprecated in 7.0+)
8.0+ (deprecated)
Cluster Architecture
CLUSTER SHARDS
7.0+
8.0+
Cluster Architecture

Usage Recommendations

New Application Integration: Use CLUSTER SHARDS (7.0+/Valkey 8.0+) to obtain richer node metadata and a clearer return structure.
Legacy Application Compatibility: Clients already using CLUSTER SLOTS can continue to use it, and their features remain unaffected.
Management and Debugging: CLUSTER NODES is suitable for viewing cluster node status and topology overview, but note that the IP address information has been replaced.
Client Library Selection: Mainstream client libraries (Jedis 4.0+, Lettuce 6.0+, redis-py 4.0+) all support CLUSTER SHARDS. It is recommended to upgrade to a newer version.

References

Documentation
Description
Overview of command support and cluster architecture limitations
How to use custom commands with the node-id parameter in a cluster architecture
Complete compatibility list for all command families
New and changed commands in Redis 6.x/7.x and Valkey 8.0
Topik selanjutnya: Catatan Rilis

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan