This topic describes the commands supported by a TairString.
Overview
A TairString is a string that includes a version number. The string data of native Redis uses a key-value pair structure and only contains keys and values. However, TairStrings consist of keys, values, and version numbers. TairStrings can be used in scenarios where optimistic locking occurs. The INCRBY and INCRBYFLOAT commands are used to increase or decrease values of Redis strings. You can use TairStrings to limit the range of results returned by these commands. If a result is out of range, an error message is returned.
Key features:
- Each TairString value includes a version number.
- TairStrings can be used to limit the range of results returned by the INCRBY and INCRBYFLOAT commands when you run these commands to increase values.
Prerequisites
The commands described in this topic take effect only if the following conditions are met:
- A performance-enhanced instance of ApsaraDB for Redis Enterprise Edition is used.
- The TairString data to be managed is stored on the performance-enhanced instance.
Note You can manage both native Redis string data and TairStrings on a performance-enhanced instance. However, Redis strings do not support the commands described in this topic.
Supported commands
Command | Syntax | Description |
---|---|---|
EXSET | EXSET <key> <value> [EX time] [PX time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] | Writes a value to a key. |
EXGET | EXGET <key> | Retrieves the value and version number of a TairString. |
EXSETVER | EXSETVER <key> <version> | Specifies the version number of a key. |
EXINCRBY | EXINCRBY <key> <num> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] [MIN minval] [MAX maxval] | Increases or decreases the value of a TairString. The value of the num parameter must be of long type. |
EXINCRBYFLOAT | EXINCRBYFLOAT <key> <num> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] [MIN minval] [MAX maxval] | Increases the value of a TairString that you want to manage. The num parameter specifies a value of double type. |
EXCAS | EXCAS <key> <newvalue> <version> | Changes the value of a specified key only if the current version number of the key matches the specified version number. The current value and version number of the key are returned if the update fails. |
EXCAD | EXCAD <key> <version> | Deletes a key if the current version number of the key matches the specified version number. An error message is returned if the operation fails. |
DEL | DEL <key> [key ...] | Deletes one or more TairStrings. |
EXSET
- Syntax
EXSET <key> <value> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version]
- Time complexity
O(1)
- Description
This command is used to write a value to a key.
- Parameters and options
Parameter/option Description key The key of the TairString that you want to manage. value The value that you want to write to the specified key. EX The relative timeout of the specified key in seconds. A value of 0 specifies that the key immediately expires. EXAT The absolute timeout of the specified key in seconds. A value of 0 specifies that the key immediately expires. PX The relative timeout of the specified key in milliseconds. A value of 0 specifies that the key immediately expires. PXAT The absolute timeout of the specified key in milliseconds. A value of 0 specifies that the key immediately expires. NX Specifies that the value is written only if the specified key does not exist. XX Specifies that the value is written only if the specified key exists. VER The version number of the specified key. - If the specified key exists, the version number specified by this parameter is compared
with the current version number:
- If the version numbers match, the specified value is written to the key and the version number is increased by 1.
- If the version numbers do not match, an error message is returned.
- If the specified key does not exist or the current version number of the key is 0, this parameter is ignored. The specified value is written to the key, and then the version number is set to 1.
ABS The absolute version number of the key. Writes the specified value to the key disregard of the current version number of the key, and then overwrites the version number with the ABS value. - If the specified key exists, the version number specified by this parameter is compared
with the current version number:
- Returned values
- OK: the operation is successful.
- Otherwise, an exception is returned.
- Example
127.0.0.1:6379> EXSET foo bar XX (nil) 127.0.0.1:6379> EXSET foo bar NX OK 127.0.0.1:6379> EXSET foo bar NX (nil) 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 1 127.0.0.1:6379> EXSET foo bar1 VER 10 (error) ERR update version is stale 127.0.0.1:6379> EXSET foo bar1 VER 1 OK 127.0.0.1:6379> EXGET foo 1) "bar1" 2) (integer) 2 127.0.0.1:6379> EXSET foo bar2 ABS 100 OK 127.0.0.1:6379> EXGET foo 1) "bar2" 2) (integer) 100
EXGET
- Syntax
EXGET <key>
- Time complexity
O(1)
- Description
This command is used to retrieve the value and version number of a TairString.
- Parameters and options
key: the key of the TairString that you want to manage.
- Returned values
- The value and version number of the TairString is returned if the operation is successful.
- Otherwise, an exception is returned.
- Example
127.0.0.1:6379> EXSET foo bar ABS 100 OK 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 100 127.0.0.1:6379> DEL foo (integer) 1 127.0.0.1:6379> EXGET foo (nil)
EXSETVER
- Syntax
EXSETVER <key> <version>
- Time complexity
O(1)
- Description
This command is used to specify the version number of a key.
- Parameters and options
Parameter/option Description key The key of the TairString that you want to manage. version The version number that you want to specify. - Returned values
- 1: the operation is successful.
- 0: the specified key does not exist.
- Otherwise, an exception is returned.
- Example
127.0.0.1:6379> EXSET foo bar OK 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 1 127.0.0.1:6379> EXSETVER foo 2 (integer) 1 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 2 127.0.0.1:6379> EXSETVER not-exists 0 (integer) 0
EXINCRBY
- Syntax
EXINCRBY |EXINCRBY <key> <num> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] [MIN minval] [MAX maxval]
- Time complexity
O(1)
- Description
This command is used to increase or decrease the value of a TairString. The value of the num parameter must be of long type.
- Parameters and options
Parameter/option Description key The key of the TairString that you want to manage. num The value by which the specified TairString is increased. The value must be an integer. EX The relative timeout of the specified key in seconds. A value of 0 specifies that the key immediately expires. EXAT The absolute timeout of the specified key in seconds. A value of 0 specifies that the key immediately expires. PX The relative timeout of the specified key in milliseconds. A value of 0 specifies that the key immediately expires. PXAT The absolute timeout of the specified key in milliseconds. A value of 0 specifies that the key immediately expires. NX Specifies that the value is written only if the specified key does not exist. XX Specifies that the value is written only if the specified key exists. VER The version number of the specified key. - If the specified key exists, the version number specified by this parameter is compared
with the current version number:
- If the version numbers match, the value of the TairString is increased by num and the version number is increased by 1.
- If the version numbers do not match, an error message is returned.
- If the specified key does not exist or the current version number of the key is 0, the specified version number does not take effect. The TairString data is increased by num, and then the version number is set to 1.
ABS The absolute version number of the key. Increases the value of the TairString disregard of the current version number of the key, and then overwrites the version number with the ABS value. MIN The minimum value of the TairString. MAX The maximum value of the TairString. - If the specified key exists, the version number specified by this parameter is compared
with the current version number:
- Returned values
- The current value of the TairString is returned if the operation is successful.
- Otherwise, an exception is returned.
- Example
127.0.0.1:6379> EXINCRBY foo 100 (integer) 100 127.0.0.1:6379> EXINCRBY foo 100 MAX 150 (error) ERR increment or decrement would overflow 127.0.0.1:6379> FLUSHALL OK 127.0.0.1:6379> EXINCRBY foo 100 (integer) 100 127.0.0.1:6379> EXINCRBY foo 100 MAX 150 (error) ERR increment or decrement would overflow 127.0.0.1:6379> EXINCRBY foo 100 MAX 300 (integer) 200 127.0.0.1:6379> EXINCRBY foo 100 MIN 500 (error) ERR increment or decrement would overflow 127.0.0.1:6379> EXINCRBY foo 100 MIN 500 MAX 100 (error) ERR min or max is specified, but not valid 127.0.0.1:6379> EXINCRBY foo 100 MIN 50 (integer) 300
EXINCRBYFLOAT
- Syntax
EXINCRBYFLOAT |EXINCRBYFLOAT <key> <num> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] [MIN minval] [MAX maxval]
- Time complexity
O(1)
- Description
This command is used to increase or decrease the value of a TairString. The value of the num parameter must be of double type.
- Parameters and options
Parameter/option Description key The key of the TairString that you want to manage. num The value by which the specified TairString is increased. The value must be a floating-point number. EX The relative timeout of the specified key in seconds. A value of 0 specifies that the key immediately expires. EXAT The absolute timeout of the specified key in seconds. A value of 0 specifies that the key immediately expires. PX The relative timeout of the specified key in milliseconds. A value of 0 specifies that the key immediately expires. PXAT The absolute timeout of the specified key in milliseconds. A value of 0 specifies that the key immediately expires. NX Specifies that the value is written only if the specified key does not exist. XX Specifies that the value is written only if the specified key exists. VER The version number of the specified key. - If the specified key exists, the version number specified by this parameter is compared
with the current version number:
- If the version numbers match, the value of the TairString is increased by num and the version number is increased by 1.
- If the version numbers do not match, an error message is returned.
- If the specified key does not exist or the current version number of the key is 0, the specified version number does not take effect. The TairString data is increased by num, and then the version number is set to 1.
ABS The absolute version number of the key. Increases the value of the TairString disregard of the current version number of the key, and then overwrites the version number with the ABS value. MIN The minimum value of the TairString. MAX The maximum value of the TairString. - If the specified key exists, the version number specified by this parameter is compared
with the current version number:
- Returned values
- The current value of the TairString is returned if the operation is successful.
- Otherwise, an exception is returned.
- Example
127.0.0.1:6379> EXSET foo 100 OK 127.0.0.1:6379> EXINCRBYFLOAT foo 10.123 "110.123" 127.0.0.1:6379> EXINCRBYFLOAT foo 20 MAX 100 (error) ERR increment or decrement would overflow 127.0.0.1:6379> EXINCRBYFLOAT foo 20 MIN 100 "130.123" 127.0.0.1:6379> EXGET foo 1) "130.123" 2) (integer) 3
EXCAS
- Syntax
EXCAS <key> <newvalue> <version>
- Time complexity
O(1)
- Description
This command is used to change the value of a specified key only if the current version number of the key matches the specified version number.
- Parameters and options
Parameter/option Description key The key of the TairString that you want to manage. newvalue The value of the newvalue parameter overwrites the value of the specified key if the current version number of the key matches the specified version number. version The version number to be matched against the current version number of the specified key. - Returned values
- ["OK", "", version] is returned if the operation is successful. The quotation marks ("") represent an empty string and version represents the current version number of the key.
- If the operation fails, an error message is returned: ["ERR update version is stale", value, version]. Value represents the current value of the key and version represents the current version number of the key.
- Otherwise, an exception is returned.
- Example
127.0.0.1:6379> EXSET foo bar OK 127.0.0.1:6379> EXCAS foo bzz 1 1) OK 2) 3) (integer) 2 127.0.0.1:6379> EXGET foo 1) "bzz" 2) (integer) 2 127.0.0.1:6379> EXCAS foo bee 1 1) ERR update version is stale 2) "bzz" 3) (integer) 2
EXCAD
- Syntax
EXCAD <key> <version>
- Time complexity
O(1)
- Description
This command is used to delete a key if the current version number of the key matches the specified version number.
- Parameters and options
Parameter/option Description key The key of the TairString that you want to manage. newvalue The value of the newvalue parameter overwrites the value of the specified key if the current version number of the key matches the specified version number. version The version number to be matched against the current version number of the specified key. - Returned values
- 1: the operation is successful.
- -1: the specified key does not exist.
- 0: the operation fails.
- Otherwise, an exception is returned.
- Example
127.0.0.1:6379> EXSET foo bar OK 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 1 127.0.0.1:6379> EXCAD not-exists 1 (integer) -1 127.0.0.1:6379> EXCAD foo 0 (integer) 0 127.0.0.1:6379> EXCAD foo 1 (integer) 1 127.0.0.1:6379> EXGET foo (nil)