This topic describes the limits on commands supported by cluster instances. Cluster instances and standard instances use different architectures and follow different rules to run Redis commands.

Supported commands

Note ApsaraDB for Redis cluster instances support the direct connection mode and the proxy mode. For more information, see Enable the direct connection mode and Features of proxy servers. If you want to run the MULTI or EXEC command by using the JedisCluster client, you must use the proxy mode.

Unsupported commands

  • SWAPDB
  • CLIENT ID
  • SORT, which is used together with the BY and GET options

Limited commands

Note To run the following commands on cluster instances, use hash tags to ensure that all keys involved in the commands are distributed in one hash slot. For more information about hash tags, see Redis Cluster Specification.
Command group Command
HyperLogLog PFMERGE and PFCOUNT
Keys RENAME, RENAMENX, and SORT
Lists RPOPLPUSH, BRPOP, BLPOP, and BRPOPLPUSH
Scripting EVAL, EVALSHA, SCRIPT EXISTS, SCRIPT FLUSH, SCRIPT KILL, and SCRIPT LOAD
Strings MSETNX
Transaction DISCARD, EXEC, MULTI, UNWATCH, and WATCH

Limits on the SELECT command

Connection mode Description
Proxy mode The proxy mode supports the SELECT command. Note that some Redis clients such as stackExchange.redis cannot distinguish the SELECT command. To resolve this issue, you can set the cluster_compat_enable parameter to 0 for these clients to disable their compatibility with the Redis Cluster syntax. Then, you can restart these clients and run the SELECT command again. For more information, see Modify the parameters of an ApsaraDB for Redis instance. You can also use other clients that support this command, such as the Jedis client. For more information about the Jedis client, see Jedis client.
Direct connection mode The direct connection mode does not support the SELECT command due to some limits of common clients such as the Jedis client. For more information about the Jedis client, see Jedis client.

Limits imposed on Lua scripts by the cluster architecture

Warning The cluster architecture imposes limits on Lua scripts. When you change the architecture of an instance to the cluster architecture by performing a configuration change, the Lua scripts may be lost because the script content does not meet the requirements. You must back up the Lua scripts in advance. For more information about configuration changes, see Change specifications.

Redis clusters impose limits on the usage of Lua scripts. The following additional limits exist for ApsaraDB for Redis cluster instances:

Note If an error message indicating that the EVAL command fails to run is returned, such as ERR command eval not support for normal user, update the minor version of the ApsaraDB for Redis instance to the latest version. For more information, see Update the minor version.
  • All keys that a script uses must be allocated to the same hash slot. Otherwise, the following error message is returned:
    -ERR eval/evalsha command keys must be in same slot\r\n
    Note You can run the CLUSTER KEYSLOT command to obtain the hash slot of a key.
  • A Lua script may not be stored in other nodes when you run the SCRIPT LOAD command on one node.
  • The following Pub/Sub commands are not supported: PSUBSCRIBE, PUBSUB, PUBLISH, PUNSUBSCRIBE, SUBSCRIBE, and UNSUBSCRIBE.
  • The UNPACK function is not supported.

If all the operations can be performed in the same hash slot and you want to break through the limits that the cluster architecture imposes on your Lua script, you can set the script_check_enable parameter to 0 in the ApsaraDB for Redis console. This way, the system does not check your Lua script at the backend. In this case, you still need to specify at least one key in the KEYS array so that proxy nodes can route commands in the Lua script. If you cannot make sure that all the operations are performed in the same hash clot, an error is returned. For more information, see Modify the parameters of an ApsaraDB for Redis instance.

Additional limits on the proxy mode

  • Lua scripts use the redis.call or redis.pcall function to run Redis commands. For Redis commands, all keys must be specified by using the KEYS array, which cannot be replaced by Lua variables. If you do not use the KEYS array to specify the keys, the following error message is returned:
    -ERR bad lua script for redis cluster, all the keys that the script uses should be passed using the KEYS array\r\n
    Examples of valid and invalid usage:
    # The following two commands must be run in advance.
    SET foo foo_value
    SET {foo}bar bar_value
    
    # Example of valid usage
    EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo {foo}bar
    
    # Examples of invalid usage
    EVAL "return redis.call('mget', KEYS[1], '{foo}bar')" 1 foo
    EVAL "return redis.call('mget', KEYS[1], ARGV[1])" 1 foo {foo}bar
  • Keys must be included in all the commands that you want to run. Otherwise, the following error message is returned:
    -ERR for redis cluster, eval/evalsha number of keys can't be negative or zero\r\n
    Examples of valid and invalid usage:
    # Example of valid usage
    EVAL "return redis.call('get', KEYS[1])" 1 foo
    
    # Example of invalid usage
    EVAL "return redis.call('get', 'foo')" 0
  • You cannot run the EVAL, EVALSHA, or SCRIPT command in the MULTI or EXEC transactions.
Note If you want to use the features that are unavailable for the proxy mode, you can enable the direction connection mode for an ApsaraDB for Redis cluster instance. However, migrations or configuration changes fail for cluster instances when Lua scripts that do not conform to the requirements of the proxy mode are executed in direct connection mode. This is because cluster instances rely on proxy nodes to migrate data during migrations and configuration changes.

To prevent subsequent migrations and configuration changes based on Lua scripts from failing, we recommend that you conform to the usage limits of Lua scripts in proxy mode when you use Lua scripts in direct connection mode.

Other limits

  • You can run the CLIENT LIST command to retrieve information about the connections to the specified proxy node. The following list describes the fields in the command output:
    • The following fields have the same meaning as the fields in open source Redis: id, age, idle, addr, fd, name, db, multi, omem, and cmd.
    • The values of the sub and psub fields are the same. The values are 1 or 0.
    • The qbuf, qbuf-free, obl, and oll fields are reserved. You can ignore these fields.
  • You can run the CLIENT KILL command in the client kill ip:port or client kill addr ip:port format.
  • If you run commands on a cluster instance in proxy mode, a transaction can be split into multiple sub-transactions to ensure compatibility with the master-replica architecture. In this case, the atomicity of the transaction cannot be ensured. If you run commands on a cluster instance in direct connection mode, the keys involved in a transaction must be in the same hash slot. This requirement is the same as that of open source Redis Cluster.
    Notice In proxy mode, if you run the WATCH command or a transaction involves commands that process multiple keys, such as the MSET command, the transaction is not split. If all keys involved in the transaction are in the same hash slot, the atomicity of the transaction can be ensured.
    • The commands that process multiple keys include DEL, SORT, MGET, MSET, BITOP, EXISTS, MSETNX, RENAME, RENAMENX, BLPOP, BRPOP, RPOPLPUSH, BRPOPLPUSH, SMOVE, SUNION, SINTER, SDIFF, SUNIONSTORE, SINTERSTORE, SDIFFSTORE, ZUNIONSTORE, ZINTERSTORE, PFMERGE, and PFCOUNT.
    • The commands that are not supported in transactions include WATCH, UNWATCH, RANDOMKEY, KEYS, SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE, PUBLISH, PUBSUB, SCRIPT, EVAL, EVALSHA, SCAN, ISCAN, DBSIZE, ADMINAUTH, AUTH, PING, ECHO, FLUSHDB, FLUSHALL, MONITOR, IMONITOR, RIMONITOR, INFO, IINFO, RIINFO, CONFIG, SLOWLOG, TIME, and CLIENT.