Command Usage Guidelines

ダウンロード

フォーカスモード

フォントサイズ

最終更新日: 2026-09-07 14:45:19

AI翻訳

Distributed Cache processes command requests based on a single-threaded model. Improper command usage may block the entire instance and affect all workloads. This document defines the specifications and guidelines for command usage, covering aspects such as high-complexity commands, prohibited commands, database selection, batch operations, transactions, Lua scripts, the Monitor command, Hashtag usage, and message queue limitations.
I. Focusing on N in O(N) Commands
Commands such as hgetall, lrange, smembers, zrange, and sinter have a time complexity of O(N). When using these commands, you must specify the value of N. If N is large, these commands occupy the single thread for a long time, blocking other requests.
Command
Risk Description
Alternative
HGETALL
Returns all fields of a hash at once, causing severe blocking when there are too many fields within the Key.
Use HSCAN cursor for batch traversal.
SMEMBERS
Returns all members of a set at once.
Use SSCAN cursor for batch traversal.
ZRANGE
Returns all members of a specified range in a sorted set at once.
Use ZSCAN cursor for batch traversal or narrow the query scope.
LRANGE
Returns all elements of a specified range in a list at once.
Narrow the scope or obtain data in pages.
SINTER
Performing intersection on multiple sets, with execution time increasing as the number of elements grows.
Perform intersection operations on the application side.
Note:
When using the HSCAN, SSCAN, or ZSCAN command, specify an appropriate COUNT parameter. Returning around 1,000 elements per iteration is a suitable choice. Adjust the specific number based on your instance configuration and business scenario.
II. Disabled Commands
The following commands are prohibited or restricted in production environments. Redis operates on a single-threaded model. If these commands take too long to execute or pose high operational risks, they can easily cause command execution blocking or data loss. We recommend that you disable them by configuring the disable-command-list parameter.
Command
Risk Description
Alternative
KEYS
Scans all keys matching a pattern, blocking the Redis server.
Use SCAN cursor for progressive matching.
FLUSHDB
Empties all data in the current database, with no possibility of restoration.
Perform progressive deletion via SCAN + DEL
FLUSHALL
Empties all data in all databases of the instance, with no possibility of restoration.
Perform progressive deletion via SCAN + DEL
SHUTDOWN
Shuts down the Redis server, causing service interruption and data loss.
Manage the instance lifecycle via the console.
CONFIG
Modifies the runtime configuration of the server, and improper operation may cause a crash.
Modify instance parameters via the console.
The following commands are not recommended for frequent use in production environments:
Command
Risk Description
Usage recommendations
RANDOMKEY
Randomly returns a key and blocks the Redis server.
Use only in test environments.
INFO
Returns server statistics and blocks other requests during execution.
Use only for short periods during troubleshooting.
BGREWRITEAOF
Asynchronously rewrites the AOF file and consumes a large amount of system resources.
Triggered automatically by the system. Avoid manual execution.
BGSAVE
Asynchronously generates an RDB snapshot and consumes a large amount of system resources.
Triggered automatically by the system. Avoid manual execution.
Note:
In Ops scenarios, if you must use the INFO or CONFIG command for troubleshooting, perform the operation briefly during off-peak hours and exit promptly after completing it.
III. Using Select Appropriately
Redis supports multiple databases (Multi-DB). Database indexes start from 0. You can switch between databases at any time using the SELECT command.
Architecture
Usage recommendations
Standard Edition
Data can be isolated using Multi-DB, but since Redis is single-threaded, requests across different DBs may interfere with each other.
Cluster Edition
It is recommended to prioritize using DB 0. Non-0 DBs do not support capacity expansion.
Note:
In cluster edition scenarios, when a client requests DB 0, it can skip executing SELECT 0 to reduce unnecessary network interactions.
IV. Using Batch Operations Appropriately
When an application accesses Redis, a significant portion of the latency comes from network RTT. If you need to perform a large number of GET or SET operations, you can use batch commands to reduce network overhead.
Method
Description
Application scenarios
Native Batch Commands (MGET/MSET)
Atomic operation, executed by the server in a single batch.
Batch read and write operations on keys of the same type
Pipeline
Non-atomic operation, where the client packages and sends multiple commands.
Batch execution of commands of different types
Negative example: If a single batch operation contains more than 500 elements, the request takes too long to complete. This can significantly impact your business during backend jitter or capacity expansion.
MGET key1 key2 key3 ... key1000
Correct example: Split the batch operation into multiple iterations, each containing no more than 500 elements.
# First Batch
MGET key1 key2 ... key500
﻿
# Second Batch
MGET key501 key502 ... key800
Note:
Limit the number of elements in a single batch operation to 500 or fewer. Also, check whether any big keys exist among the elements in the batch operation.
Native batch commands are atomic operations, while Pipeline is a non-atomic operation.
Pipeline can package different commands, while native batch commands are not supported.
Pipeline requires support from both the client and server sides.
V. Not Recommending the Use of Transactions
Redis transaction feature is weak and does not support rollback. In cluster edition scenarios, all keys involved in a single transaction must reside on the same Slot; otherwise, the transaction execution will fail.
Note:
If your business requires transactional guarantees, we recommend using Lua scripts as an alternative. Lua scripts are executed atomically on the server side. However, this also requires that all keys involved in the operation reside on the same node in the cluster edition.
VI. Special Requirements for Using Lua in Cluster Edition
6.1 Keys Must Be Passed via the KEYS Array
For Redis commands invoked within redis.call / redis.pcall, the Key positions must come from the KEYS array. Otherwise, an error is returned:
-ERR bad lua script for redis cluster, all the keys that the script uses should be passed using the KEYS array
6.2 Keys to Be Operated Must Be on the Same Node
Keys operated by a single Lua script must reside on the same node. Otherwise, an error is returned:
Lua script attempted to access a non local key in a cluster node
Note:
If you need to operate multiple keys within a Lua script, you can use Hashtag to allocate the relevant keys to the same hash slot. Before using it, see the usage recommendations for Hashtag in Section 8 of this document.
VII. About the Monitor Command
The Monitor command is used to output the stream of commands received by the Redis server in real time, which has a certain impact on server performance.
Scenario
Usage recommendations
Daily operation
Do not enable Monitor.
Issue Troubleshooting
You can enable it for a short period to analyze command execution. Disable it promptly after troubleshooting.
Note:
Keeping the Monitor command enabled for a long time continuously consumes server resources and occupies the output buffer, leading to performance degradation. Do not enable it unless you need to perform troubleshooting.
VIII. Recommendations for Using Hashtags
Hashtag is a special mechanism provided by Redis Cluster that uses specific syntax to force multiple different keys to be assigned to the same Hash Slot, thereby supporting cross-key operations. If used improperly, it can cause severe data and request skew issues, which cannot be resolved by scaling up the cluster.
8.1 Risks of Improper Hashtag Usage
Risk Type
Description
Data Skew (Memory Skew)
Keys that heavily use the same Hashtag gather on a single node, causing memory utilization on that node to be significantly higher than on other nodes, which may prematurely trigger a memory alarm or cause it to become full.
Request Skew (Hotspot)
All read and write requests targeting these keys hit the same node, making it a performance bottleneck, which leads to increased latency and may even bring down the entire cluster.
Non-Scalability
Hash slot calculation relies on a fixed Hashtag, and the resulting skew issues cannot be mitigated by adding more nodes to the cluster.
8.2 Guidelines for Using Hashtags
Guideline
Description
Minimize and Split
Do not use a single, unified Hashtag for all related data. Instead, use different fine-grained hashtags based on business type or functional module.
Ensure Uniform Distribution.
Ensure Hashtag values are evenly distributed overall. You can append suffixes to the original ID for manual sharding.
Use Only When Necessary.
Use Hashtags only when transactions, Lua scripts, or multi-key commands are required. Do not misuse this feature for unrelated keys.
Negative Example: Using a uniform Hashtag for all user data causes all data to be concentrated on a single node.
SET {global}:user:1001 "data1"
SET {global}:user:1002 "data2"
SET {global}:order:5001 "order_data"
Correct Example: Split Hashtags by business type, and the data is distributed across different nodes.
SET {user:1001}:profile "data1"
SET {user:1001}:session "session_data"
SET {order:5001}:detail "order_data"
Note:
We recommend reviewing the Hashtag usage plan during the system design phase. Making adjustments after the system goes live requires migrating existing data, which incurs high costs.
IX. Prohibition of Using Redis as a Message Queue
Do not use Redis as a message queue. Redis Pub/Sub and List structures lack the core capabilities of a message queue and have multiple limitations in terms of capacity, network, efficiency, and features.
Limit
Description
Message Persistence
Redis Pub/Sub does not persist messages, and messages during consumer offline periods will be lost.
Message Acknowledgment
Does not support the consumption acknowledgment mechanism (ACK), and cannot guarantee that messages are reliably consumed.
Backlog Capacity
When the List structure is used as a queue, message backlog can consume a large amount of memory, affecting cache performance.
Consumption Model
Does not support advanced features such as consumer groups and message partitioning.
Note:
If you have a message queue requirement, we recommend using a dedicated message middleware, such as CKafka or TDMQ.

ヘルプとサポート

この記事はお役に立ちましたか？

営業担当者にお問い合わせいただくかチケットを提出してサポートを求めることができます。

フィードバック

tencent cloud

Tencent Cloud Distributed Cache (Redis OSS-Compatible)

Command Usage Guidelines

I. Focusing on N in O(N) Commands

II. Disabled Commands

III. Using Select Appropriately

IV. Using Batch Operations Appropriately

V. Not Recommending the Use of Transactions

VI. Special Requirements for Using Lua in Cluster Edition

6.1 Keys Must Be Passed via the KEYS Array

6.2 Keys to Be Operated Must Be on the Same Node

VII. About the Monitor Command

VIII. Recommendations for Using Hashtags

8.1 Risks of Improper Hashtag Usage

8.2 Guidelines for Using Hashtags

IX. Prohibition of Using Redis as a Message Queue

ヘルプとサポート

Command	Risk Description	Alternative
`HGETALL`	Returns all fields of a hash at once, causing severe blocking when there are too many fields within the Key.	Use `HSCAN` cursor for batch traversal.
`SMEMBERS`	Returns all members of a set at once.	Use `SSCAN` cursor for batch traversal.
`ZRANGE`	Returns all members of a specified range in a sorted set at once.	Use `ZSCAN` cursor for batch traversal or narrow the query scope.
`LRANGE`	Returns all elements of a specified range in a list at once.	Narrow the scope or obtain data in pages.
`SINTER`	Performing intersection on multiple sets, with execution time increasing as the number of elements grows.	Perform intersection operations on the application side.

Command	Risk Description	Usage recommendations
`RANDOMKEY`	Randomly returns a key and blocks the Redis server.	Use only in test environments.
`INFO`	Returns server statistics and blocks other requests during execution.	Use only for short periods during troubleshooting.
`BGREWRITEAOF`	Asynchronously rewrites the AOF file and consumes a large amount of system resources.	Triggered automatically by the system. Avoid manual execution.
`BGSAVE`	Asynchronously generates an RDB snapshot and consumes a large amount of system resources.	Triggered automatically by the system. Avoid manual execution.

Architecture	Usage recommendations
Standard Edition	Data can be isolated using Multi-DB, but since Redis is single-threaded, requests across different DBs may interfere with each other.
Cluster Edition	It is recommended to prioritize using DB 0. Non-0 DBs do not support capacity expansion.

Method	Description	Application scenarios
Native Batch Commands (`MGET`/`MSET`)	Atomic operation, executed by the server in a single batch.	Batch read and write operations on keys of the same type
Pipeline	Non-atomic operation, where the client packages and sends multiple commands.	Batch execution of commands of different types

Scenario	Usage recommendations
Daily operation	Do not enable Monitor.
Issue Troubleshooting	You can enable it for a short period to analyze command execution. Disable it promptly after troubleshooting.

Risk Type	Description
Data Skew (Memory Skew)	Keys that heavily use the same Hashtag gather on a single node, causing memory utilization on that node to be significantly higher than on other nodes, which may prematurely trigger a memory alarm or cause it to become full.
Request Skew (Hotspot)	All read and write requests targeting these keys hit the same node, making it a performance bottleneck, which leads to increased latency and may even bring down the entire cluster.
Non-Scalability	Hash slot calculation relies on a fixed Hashtag, and the resulting skew issues cannot be mitigated by adding more nodes to the cluster.

Guideline	Description
Minimize and Split	Do not use a single, unified Hashtag for all related data. Instead, use different fine-grained hashtags based on business type or functional module.
Ensure Uniform Distribution.	Ensure Hashtag values are evenly distributed overall. You can append suffixes to the original ID for manual sharding.
Use Only When Necessary.	Use Hashtags only when transactions, Lua scripts, or multi-key commands are required. Do not misuse this feature for unrelated keys.

Limit	Description
Message Persistence	Redis Pub/Sub does not persist messages, and messages during consumer offline periods will be lost.
Message Acknowledgment	Does not support the consumption acknowledgment mechanism (ACK), and cannot guarantee that messages are reliably consumed.
Backlog Capacity	When the List structure is used as a queue, message backlog can consume a large amount of memory, affecting cache performance.
Consumption Model	Does not support advanced features such as consumer groups and message partitioning.