TairString commands

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

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)