A TairString is a string that includes a version number. This topic describes the commands that are supported by the TairString data structure.

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