This topic describes the commands supported by TairHashes.

Overview

A TairHash is a hash that allows you to specify the expiration time and version number of a field. Similar to native Redis hashes, TairHash supports multiple commands and high performance in data processing. For native Redis hashes, you can only specify the expiration time of keys. However, TairHash allows you to specify the expiration time of both keys and fields and specify versions of fields. The improved TairHash features help you simplify the development in most scenarios. TairHash uses an efficient Active Expire algorithm to check the expiration time of fields and delete expired fields. This process does not increase the database response time.

Key features:

  • You can set the expiration time and version number for each field.
  • Fields support the Active Expire and Passive Expire algorithms.
  • TairHash and native Redis hash use similar syntax.
Warning TairHashes are different from native Redis hashes. The commands that are supported by TairStrings and native Redis hashes 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 TairHash to be managed is stored on the performance-enhanced instance.
    Note You can manage both native Redis hashes and TairHashes on a performance-enhanced instance. The commands described in this topic are not applicable to native Redis hashes.

Memory consumption and expiration policies of TairHash.

TairHash supports efficient and active expiration policies. However, this can increase the memory consumption to some extent. For more information, see TairHash memory consumption and expiration policies.

Commands

EXHSET

  • Syntax

    EXHSET <key> <field> <value> [EX time] [EXAT time] [PX time] [PXAT time] [NX | XX] [VER/ABS version] [NOACTIVE]

  • Time complexity

    O(1)

  • Description

    This command is used to add a field to a specified TairHash. If the key does not exist, a new key holding a TairHash is created. If the specified field exists, this command overwrites the value of the field.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
    value The value of the specified field. Each field can have only one value.
    EX The relative expiration time of the specified field in seconds. A value of 0 specifies that the field does not expire.
    EXAT The absolute expiration time of the specified field in seconds. A value of 0 specifies that the field does not expire.
    PX The relative expiration time of the specified field in milliseconds. A value of 0 specifies that the field does not expire.
    PXAT The absolute expiration time of the specified field in milliseconds. A value of 0 specifies that the field does not expire.
    NX Specifies that the value is written only if the field does not exist.
    XX Specifies that the value is written only if the field exists.
    VER The version number of the specified field.
    • If the specified field exists, the version number specified by this parameter is matched against the current version number:
      • If the version numbers match, the TairHash 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 field does not exist or the current version number of the field is 0, this parameter is ignored. The specified value is written to the field, and then the version number is set to 1.
    ABS The absolute version number of the field. If you specify this parameter, the system forcibly writes the specified value to the field regardless whether the field exists. Then, the version number is overwritten with the specified ABS value.
    NOACTIVE When you specify the EX/EXAT/PX/PXAT parameters, you can specify the NOACTIVE parameter to disable the active expiration policy for the field. This allows you to reduce the memory consumption.
  • Returned values
    • 1: a new field is created and a value is set.
    • 0: the field exists and the specified value overwrites the current value.
    • -1: the XX parameter is specified and the specified field does not exist.
    • -1: the NX parameter is specified and the specified field exists.
    • An error message of "ERR update version is stale" is returned. The message indicates that the value of the VER parameter does not match the current version number.
    • Otherwise, an exception is returned.

EXHGET

  • Syntax

    EXHGET <key> <field>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve a value associated with the specified field in a TairHash.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • The value of the field is returned if the field exists and the operation is successful.
    • nil: the key or field does not exist.
    • Otherwise, an exception is returned.

EXHMSET

  • Syntax

    EXHMSET <key> <field> <value> [field value...]

  • Time complexity

    O(1)

  • Description

    This command is used to set specified fields to respective values in the TairHash. If the key does not exist, a new key holding a TairHash is created. If the field already exists, this command overwrites the value of the field.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
    value The value of the specified field. Each field can have only one value.
  • Returned values
    • OK: the operation is successful.
    • Otherwise, an exception is returned.

EXHPEXPIREAT

  • Syntax

    EXHPEXPIREAT <key> <field> <milliseconds-timestamp> [VER/ABS version] [NOACTIVE]

  • Time complexity

    O(1)

  • Description

    This command is used to specify the absolute expiration time of a field in a specified TairHash. Unit: milliseconds.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
    milliseconds-timestamp The Unix timestamp. Unit: milliseconds.
    VER The version number of the specified field.
    • If the specified field exists, the version number specified by this parameter is matched against the current version number:
      • If the version numbers match, the TairHash 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 field does not exist or the current version number of the field is 0, this parameter is ignored. The specified value is written to the field, and then the version number is set to 1.
    ABS The absolute version number of the field. If you specify this parameter, the system forcibly writes the specified value to the field regardless whether the field exists. Then, the version number is overwritten with the specified ABS value.
    NOACTIVE When you specify the EX/EXAT/PX/PXAT parameters, you can specify the NOACTIVE parameter to disable the active expiration policy for the field. This allows you to reduce the memory consumption.
  • Returned values
    • 1: the field exists and a value is set.
    • 0: the field does not exist.
    • Otherwise, an exception is returned.

EXHPEXPIRE

  • Syntax

    EXHPEXPIRE <key> <field> <milliseconds> [VER/ABS version] [NOACTIVE]

  • Time complexity

    O(1)

  • Description

    This command is used to specify the relative expiration time of a filed in a specified TairHash. Unit: milliseconds.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
    milliseconds The relative expiration time of the specified field in milliseconds.
    VER The version number of the specified field.
    • If the specified field exists, the version number specified by this parameter is matched against the current version number:
      • If the version numbers match, the TairHash 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 field does not exist or the current version number of the field is 0, this parameter is ignored. The specified value is written to the field, and then the version number is set to 1.
    ABS The absolute version number of the field. If you specify this parameter, the system forcibly writes the specified value to the field regardless whether the field exists. Then, the version number is overwritten with the specified ABS value.
    NOACTIVE When you specify the EX/EXAT/PX/PXAT parameters, you can specify the NOACTIVE parameter to disable the active expiration policy for the field. This allows you to reduce the memory consumption.
  • Returned values
    • 1: the field exists and a value is set.
    • 0: the field does not exist.
    • Otherwise, an exception is returned.

EXHEXPIREAT

  • Syntax

    EXHEXPIREAT <key> <field> <timestamp> [VER/ABS version] [NOACTIVE]

  • Time complexity

    O(1)

  • Description

    This command is used to specify the absolute relative expiration time of a filed in a specified TairHash. Unit: seconds.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
    timestamp The Unix timestamp. Unit: seconds.
    VER The version number of the specified field.
    • If the specified field exists, the version number specified by this parameter is matched against the current version number:
      • If the version numbers match, the TairHash 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 field does not exist or the current version number of the field is 0, this parameter is ignored. The specified value is written to the field, and then the version number is set to 1.
    ABS The absolute version number of the field. If you specify this parameter, the system forcibly writes the specified value to the field regardless whether the field exists. Then, the version number is overwritten with the specified ABS value.
    NOACTIVE When you specify the EX/EXAT/PX/PXAT parameters, you can specify the NOACTIVE parameter to disable the active expiration policy for the field. This allows you to reduce the memory consumption.
  • Returned values
    • 1: the field exists and a value is set.
    • 0: the field does not exist.
    • Otherwise, an exception is returned.

EXHEXPIRE

  • Syntax

    EXHEXPIRE <key> <field> <seconds>

  • Time complexity

    O(1)

  • Description

    This command is used to specify the relative expiration time of a filed in a specified TairHash. Unit: seconds.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
    seconds The relative expiration time of the specified field in seconds.
    VER The version number of the specified field.
    • If the specified field exists, the version number specified by this parameter is matched against the current version number:
      • If the version numbers match, the TairHash 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 field does not exist or the current version number of the field is 0, this parameter is ignored. The specified value is written to the field, and then the version number is set to 1.
    ABS The absolute version number of the field. If you specify this parameter, the system forcibly writes the specified value to the field regardless whether the field exists. Then, the version number is overwritten with the specified ABS value.
    NOACTIVE When you specify the EX/EXAT/PX/PXAT parameters, you can specify the NOACTIVE parameter to disable the active expiration policy for the field. This allows you to reduce the memory consumption.
  • Returned values
    • 1: the field exists and a value is set.
    • 0: the field does not exist.
    • Otherwise, an exception is returned.

EXHPTTL

  • Syntax

    EXHPTTL <key> <field>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve the remaining expiration time of a field in a specified TairHash. Unit: milliseconds.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • -2: the specified key or field does not exist.
    • -1: the specified field exists but the TTL value is not specified.
    • The expiration time of the field in milliseconds is returned if the field exists and the expiration time of the field is specified.
    • Otherwise, an exception is returned.

EXHTTL

  • Syntax

    EXHTTL <key> <field>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve the remaining expiration time of a field in a specified TairHash. Unit: seconds.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • -2: the specified key or field does not exist.
    • -1: the specified field exists but the TTL value is not specified.
    • Expected result: The TTL value specified for the field is returned and displayed in seconds.
    • Otherwise, an exception is returned.

EXHVER

  • Syntax

    EXHVER <key> <field>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve the current version number of a field in a specified TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • -1: the specified key does not exist.
    • -2: the specified field does not exist.
    • The version number of the specified field is returned if the operation is successful.
    • Otherwise, an exception is returned.

EXHSETVER

  • Syntax

    EXHSETVER <key> <field> <version>

  • Time complexity

    O(1)

  • Description

    This command is used to set the current version number of a field in the specified TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • 0: the specified TairHash or field does not exist.
    • 1: the version number is specified.
    • Otherwise, an exception is returned.

EXHINCRBY

  • Syntax

    EXHINCRBY <key> <field> <num> [EX time] [EXAT time] [PX time] [PXAT time] [VER/ABS version] [MIN minval] [MAX maxval]

  • Time complexity

    O(1)

  • Description

    This command is used to increase the value of a field by num in a TairHash if the key matches the specified key. The value of the num parameter must be an integer. If the specified TairHash does not exist, a TairHash is created. If the specified field does not exist, this command adds the field and sets the value of the field to 0 before creating a TairHash. When you run this command, the system uses a passive expiration algorithm to delete expired fields.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
    num The increment (an integer) to be added to the specified value.
    EX The relative expiration time of the specified field in seconds. A value of 0 specifies that the field does not expire.
    EXAT The absolute expiration time of the specified field in seconds. A value of 0 specifies that the field does not expire.
    PX The relative expiration time of the specified field in milliseconds. A value of 0 specifies that the field does not expire.
    PXAT The absolute expiration time of the specified field in milliseconds. A value of 0 specifies that the field does not expire.
    VER The version number of the specified field.
    • If the specified field exists, the version number specified by this parameter is matched against the current version number:
      • If the version numbers match, the TairHash 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 value of the VER parameter is 0, you do not need to check the version number.
    ABS The absolute version number of the field. If you specify this parameter, the system forcibly increases the TairHash by num regardless whether the field exists. Then, the version number is overwritten with the specified ABS value. The value of this parameter must not be 0.
    MIN The minimum value of the field value. If the specified value is smaller than this lower limit, an exception is returned.
    MAX The maximum value of the field value. If the specified value is larger than this upper limit, an exception is returned.
    NOACTIVE When you specify the EX/EXAT/PX/PXAT parameters, you can specify the NOACTIVE parameter to disable the active expiration policy for the field. This allows you to reduce the memory consumption.
  • Returned values
    • The value increased by num is returned if the operation is successful.
    • Otherwise, an exception is returned.

EXHINCRBYFLOAT

  • Syntax

    EXHINCRBYFLOAT <key> <field> <num> [EX time] [EXAT time] [PX time] [PXAT time] [VER/ABS version] [MIN minval] [MAX maxval]

  • Time complexity

    O(1)

  • Description

    This command is used to increase a specified field value by num in a TairHash if the key matches the specified key. The value of the num parameter must be a floating-point number. If the specified TairHash does not exist, a TairHash is created. If the specified field does not exist, this command adds the field and sets the value of the field to 0 before creating a TairHash. When you run this command, the system uses a passive expiration algorithm to delete expired fields.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
    num The increment (a floating-point number) to be added to the specified field value.
    EX The relative expiration time of the specified field in seconds. A value of 0 specifies that the field does not expire.
    EXAT The absolute expiration time of the specified field in seconds. A value of 0 specifies that the field does not expire.
    PX The relative expiration time of the specified field in milliseconds. A value of 0 specifies that the field does not expire.
    PXAT The absolute expiration time of the specified field in milliseconds. A value of 0 specifies that the field does not expire.
    VER The version number of the specified field.
    • If the specified field exists, the version number specified by this parameter is matched against the current version number:
      • If the version numbers match, the TairHash 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 value of the VER parameter is 0, you do not need to check the version number.
    ABS The absolute version number of the field. If you specify this parameter, the system forcibly increases the TairHash by num regardless whether the field exists. Then, the version number is overwritten with the specified ABS value. The value of this parameter must not be 0.
    MIN The minimum value of the field value. If the specified value is smaller than this lower limit, an exception is returned.
    MAX The maximum value of the field value. If the specified value is larger than this upper limit, an exception is returned.
    NOACTIVE When you specify the EX/EXAT/PX/PXAT parameters, you can specify the NOACTIVE parameter to disable the active expiration policy for the field. This allows you to reduce the memory consumption.
  • Returned values
    • The value increased by num is returned if the operation is successful.
    • Otherwise, an exception is returned.

EXHGETWITHVER

  • Syntax

    EXHGETWITHVER <key> <field>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve the value and version number of a field in the specified TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • The value and version number of the field is returned if the field exists and the operation is successful.
    • nil: the key or field does not exist.
    • Otherwise, an exception is returned.

EXHMGET

  • Syntax

    EXHMGET <key> <field> [field ...]

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve multiple field values in a TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • nil: the key does not exist.
    • An array is returned if the specified key and fields exist. Each element in the array corresponds to a field value.
    • An array is returned if the specified key exists but some fields do not exist. Each element in the array corresponds to a field value. The elements of the non-existing fields are displayed as nil.
    • Otherwise, an exception is returned.

EXHMGETWITHVER

  • Syntax

    EXHMGETWITHVER <key> <field> [field ...]

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve the values and version numbers of multiple fields in a specified TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • nil: the key does not exist.
    • An array is returned if the specified key and fields exist. Each element in the array corresponds to a field value and a version number.
    • An array is returned if the specified key exists but some fields do not exist. Each element in the array corresponds to a field value and a version number. The elements of the non-existing fields are displayed as nil.
    • Otherwise, an exception is returned.

EXHDEL

  • Syntax

    EXHDEL <key> <field> <field> <field> ...

  • Time complexity

    O(1)

  • Description

    This command is used to delete a field from a specified TairHash.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • 0: the specified key or field does not exist.
    • 1: the operation is successful.
    • Otherwise, an exception is returned.

EXHLEN

  • Syntax

    EXHLEN <key> [noexp]

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve the number of fields in a TairHash if the key matches the specified key. The returned value may include the number of expired fields that have not been deleted.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    noexp By default, the EXHLEN command does not delete or filter expired fields. Therefore, the results may include the number of expired fields that have not been deleted. If you only want to query the number of fields that are not expired, you can specify the oexp parameter. When you specify the noexp parameter,
    • the response time of the EXHLEN command is based on the size of the Tairhash, because the system scans all TairHashes.
    • The result of the EXHLEN command does not include the number of expired fields that are not deleted.
  • Returned values
    • 0: the specified key or field does not exist.
    • The number of fields in the TairHash is returned if the operation is successful.
    • Otherwise, an exception is returned.

EXHEXISTS

  • Syntax

    EXHEXISTS <key> <field>

  • Time complexity

    O(1)

  • Description

    This command is used to check whether a field exists in a TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • 0: the specified key or field does not exist.
    • 1: the specified field exists.
    • Otherwise, an exception is returned.

EXHSTRLEN

  • Syntax

    EXHSTRLEN <key> <field>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve the length of a field value in the TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    field An element of the TairHash. A TairHash key can be mapped to multiple fields.
  • Returned values
    • 0: the specified key or field does not exist.
    • The length of the specified field value is returned if the operation is successful.
    • Otherwise, an exception is returned.

EXHKEYS

  • Syntax

    EXHKEYS <key>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve all fields in a TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
  • Returned values
    • An empty array is returned if the specified key does not exist.
    • An array is returned if the specified key exists. Each element in the array corresponds to a field.
    • Otherwise, an exception is returned.

EXHVALS

  • Syntax

    EXHVALS <key>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve all field values in the TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
  • Returned values
    • An empty array is returned if the specified key does not exist.
    • An array is returned if the specified key exists. Each element in the array corresponds to a field value.
    • Otherwise, an exception is returned.

EXHGETALL

  • Syntax

    EXHGETALL <key>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve all fields and their values in a TairHash if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
  • Returned values
    • An empty array is returned if the specified key does not exist.
    • An array is returned if the specified key exists. Each element in the array corresponds to a field value.
    • Otherwise, an exception is returned.

EXHSCAN

  • Syntax

    EXHSCAN <key> <op> <subkey> [MATCH pattern] [COUNT count]

  • Time complexity

    O(1) and O(N)

  • Description

    This command is used to scan TairHashes if the key matches the specified key.

  • Parameters and options
    Parameter/option Description
    key The key of the TairHash that you want to manage.
    op The position from which a scan starts. Valid values:
    • >, specifies that the scan starts from the first field with the key greater than subkey.
    • >=, specifies that the scan starts from the first field with the key greater than or equal to subkey.
    • <, specifies that the scan starts from the first field with the key less than subkey.
    • <=, specifies that the scan starts from the first field with the key less than or equal to subkey.
    • ==, specifies that the scan starts from the first field with the key equal to subkey.
    • ^, specifies that the scan starts from the first field.
    • $, specifies that the scan starts from the last field.
    subkey Specifies the position from which a scan starts. This parameter is specified together with the op parameter. If op is set to ^ or $, this parameter does not take effect.
    MATCH The criteria used to filter the scanning result.
  • Returned values
    • An empty array is returned if the specified key does not exist.
    • An array is returned if the specified key exists. Each element in the array corresponds to a field value.
    • Otherwise, an exception is returned.