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.
Warning TairStrings are different from native Redis strings. The commands that are supported by TairStrings and native Redis strings are not interchangeable.

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

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.
  • 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.
  • 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.
  • 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)