TairString commands - Product Introduction| Alibaba Cloud Documentation Center

Overview

Native Redis strings use a key-value pair structure. TairStrings contain keys, values, as well as version numbers to support scenarios including the implementation of optimistic locking. In native Redis strings, the INCRBY and INCRBYFLOAT commands are used to increase or decrease string values. In TairStrings, you can limit the range of the outputs returned by these commands. If an output is out of the specified range, an error message is returned.

Main features

A TairString contains a version number.
TairStrings allow you to limit the range of the INCRBY and INCRBYFLOAT command outputs when you run these commands to increase values.

This module is open-sourced. For more information, see TairString.

Best practices

Prerequisites

The instance is a performance-enhanced instance or persistent memory-optimized instance of the ApsaraDB for Redis Enhanced Edition (Tair). For more information about performance-enhanced instances and memory-optimized instances, see Performance-enhanced instances and Persistent memory-optimized instances.
The instance is updated to the latest minor version. For more information, see Update the minor version.

Note If your instance is a cluster instance or read/write splitting instance, the proxy nodes in your instance must also be of the latest minor version to ensure that all commands can be run as expected. For more information about cluster instances and read/write splitting instances, see Cluster master-replica instances and Read/write splitting instances.

Precautions

The TairStrings that you want to manage are stored in the performance-enhanced instance.

Note You can manage native Redis strings and TairStrings on the performance-enhanced instance at the same time. However, native Redis strings do not support the commands described in this topic.

Supported commands

Table 1. TairString commands
Command	Syntax	Description
EXSET	`EXSET <key> <value> [EX time] [PX time] [EXAT time] [PXAT time] [NX \| XX] [VER version \| ABS version]`	Creates a TairString key if the key does not exist and writes a value to the key. If the key already exists, the command overwrites the value of the key.
EXGET	`EXGET <key>`	Retrieves the value and version number of a TairString key.
EXSETVER	`EXSETVER <key> <version>`	Specifies the version number of a TairString 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 key. The value of the num parameter must be of the 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 or decreases the value of a TairString key. The value of the num parameter must be of the double type.
EXCAS	`EXCAS <key> <newvalue> <version>`	Updates the value of the specified TairString key if the current version number of the key matches the specified one. If the numbers do not match, the command returns the original value and version number of the key.
EXCAD	`EXCAD <key> <version>`	Deletes a key when the current version number of the key matches the specified one.
DEL	`DEL <key> [key ...]`	Deletes one or more TairString keys.

EXSET


Item	Description
Syntax	`EXSET <key> <value> [EX time] [PX time] [EXAT time] [PXAT time] [NX \| XX] [VER version \| ABS version]`
Time complexity	O(1)
Command description	Creates a TairString key if the key does not exist and writes a value to the key. If the key already exists, the command overwrites the value of the key.
Parameter	Key: the key that you want to manage by running this command. value: the value that you want to write to the key. EX: the relative expiration time of the key. Unit: seconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. EXAT: the absolute expiration time of the key. Unit: seconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. PX: the relative expiration time of the key. Unit: milliseconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. PXAT: the absolute expiration time of the key. Unit: milliseconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. NX: specifies that the value is written to the key only if the key does not exist. XX: specifies that the value is written to the key only if the key exists. VER: the version number of the key. If the key exists, the version number specified by this parameter is matched against the current version number. If the version numbers match, the 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 key does not exist or if the current version number of the key is 0, the specified version number does not take effect. In this case, the value is written to the key and the version number is set to 1. ABS: the absolute version number of the key. After this parameter is specified, the value is written to the key regardless of the current version number of the key. Then, the version number is overwritten with the ABS value.
Output	If the operation is successful, OK is returned. If the XX parameter is specified but the key does not exist, nil is returned. If the NX parameter is specified and the key exists, nil is returned. Otherwise, an error message is returned.
Example	Sample command: `EXSET foo bar NX ABS 100` Sample output: `OK`

EXGET


Item	Description
Syntax	`EXGET <key>`
Time complexity	O(1)
Command description	Retrieves the value and version number of a TairString key.
Parameter	Key: the key that you want to manage by running this command.
Output	If the operation is successful, the value and version number of the key are returned. Otherwise, an error message is returned.
Example	Sample command: `EXGET foo` Sample output: `1) "bar" 2) (integer) 1`

EXSETVER


Item	Description
Syntax	`EXSETVER <key> <version>`
Time complexity	O(1)
Command description	Specifies the version number of a TairString key.
Parameter	Key: the key that you want to manage by running this command. version: the version number that you want to specify.
Output	If the operation is successful, a value of 1 is returned. If the key does not exist, a value of 0 is returned. Otherwise, an error message is returned.
Example	Sample command: `EXSETVER foo 2` Sample output: `(integer) 1`

EXINCRBY


Item	Description
Syntax	`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)
Command description	Increases or decreases the value of a TairString key. The value of the num parameter must be of the long type.
Parameter	Key: the key that you want to manage by running this command. num: the value by which the key is increased or decreased. This value must be an integer. EX: the relative expiration time of the key. Unit: seconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. EXAT: the absolute expiration time of the key. Unit: seconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. PX: the relative expiration time of the key. Unit: milliseconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. PXAT: the absolute expiration time of the key. Unit: milliseconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. NX: specifies that the value is written to the key only if the key does not exist. XX: specifies that the value is written to the key only if the key exists. VER: the version number of the key. If the key exists, the version number specified by this parameter is matched against the current version number. If the version numbers match, the value of the key is increased by the num value and the version number is increased by 1. If the version numbers do not match, an error message is returned. If the key does not exist or if the current version number of the key is 0, the specified version number does not take effect. In this case, the value is increased by the num value and the version number is set to 1. ABS: the absolute version number of the key. After this parameter is specified, the value is written to the key regardless of the current version number of the key. Then, the version number is overwritten with the ABS value. MIN: the minimum value of the key. MAX: the maximum value of the key.
Output	If the operation is successful, the updated value of the key is returned. If the MAX or MIN parameter is specified and the updated value of the key is out of the value range, the "(error) ERR increment or decrement would overflow" error message is returned. Otherwise, an error message is returned.
Example	The `EXSET foo 1` command is run in advance. Sample command: `EXINCRBY foo 100 MAX 300` Sample output: `(integer) 101`

EXINCRBYFLOAT


Item	Description
Syntax	`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)
Command description	Increases or decreases the value of a TairString key. The value of the num parameter must be of the double type.
Parameter	Key: the key that you want to manage by running this command. num: the value by which the key is increased or decreased. The value must be a floating-point number. EX: the relative expiration time of the key. Unit: seconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. EXAT: the absolute expiration time of the key. Unit: seconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. PX: the relative expiration time of the key. Unit: milliseconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. PXAT: the absolute expiration time of the key. Unit: milliseconds. A value of 0 indicates that the key immediately expires. If this parameter is not specified, the key does not expire. NX: specifies that the value is written to the key only if the key does not exist. XX: specifies that the value is written to the key only if the key exists. VER: the version number of the key. If the key exists, the version number specified by this parameter is matched against the current version number. If the version numbers match, the value of the key is increased by the num value and the version number is increased by 1. If the version numbers do not match, an error message is returned. If the key does not exist or if the current version number of the key is 0, the specified version number does not take effect. In this case, the value is increased by the num value and the version number is set to 1. ABS: the absolute version number of the key. After this parameter is specified, the value is written to the key regardless of the current version number of the key. Then, the version number is overwritten with the ABS value. MIN: the minimum value of the key. MAX: the maximum value of the key.
Output	If the operation is successful, the updated value of the key is returned. If the MAX or MIN parameter is specified and the updated value of the key is out of the value range, the "(error) ERR increment or decrement would overflow" error message is returned. Otherwise, an error message is returned.
Example	The `EXSET foo 1` command is run in advance. Sample command: `EXINCRBYFLOAT foo 10.123` Sample output: `(integer) 11.123`

EXCAS


Item	Description
Syntax	`EXCAS <key> <newvalue> <version>`
Time complexity	O(1)
Command description	Updates the value of the specified TairString key if the current version number of the key matches the specified one. If the numbers do not match, the command returns the original value and version number of the key.
Parameter	Key: the key that you want to manage by running this command. newvalue: the new value that you want to use to overwrite the value of the key if the current version number of the key matches the specified one. version: the version number that you want to compare with the current version number of the key.
Output	If the operation is successful, the "["OK", "",latest version]" message is returned. The "" characters indicate empty strings that do not carry meanings. If the operation fails, the following error message is returned: ["ERR update version is stale", value, version]. value indicates the current value of the key. version indicates the current version number of the key. If the key does not exist, a value of -1 is returned. Otherwise, an error message is returned.
Example	The `EXSET foo bar` command is run in advance. Sample command: `EXCAS foo bzz 1` Sample output: `1) OK 2) 3) (integer) 2`

EXCAD


Item	Description
Syntax	`EXCAD <key> <version>`
Time complexity	O(1)
Command description	Deletes a key when the current version number of the key matches the specified one.
Parameter	Key: the key that you want to manage by running this command. version: the version number that you want to compare with the current version number of the key.
Output	If the operation is successful, a value of 1 is returned. If the operation fails, a value of 0 is returned. If the key does not exist, a value of -1 is returned. Otherwise, an error message is returned.
Example	The `EXSET foo bar` command is run in advance. Sample command: `EXCAD foo 1` Sample output: `(integer) 1`