All Products
Search
Document Center

Tair:exHash

Last Updated:Mar 04, 2024

TairHash (also known as exHash) is a hash data structure that allows you to specify expiration times and version numbers for fields. This increased flexibility of the hash data structure simplifies business development in most scenarios.

Overview

TairHashes and native Redis hashes support a variety of data interfaces and provide high performance in data processing. However, native Redis hashes allow you to specify expiration times only for keys. TairHashes allow you to specify expiration times for both keys and fields. You can also use TairHashes to specify the version numbers of fields. These improved features of TairHashes add flexibility to TairHash and simplify business development in most scenarios. TairHashes use the efficient active expiration algorithm to check the expiration times of fields and delete expired fields. This process does not increase the database response time.

Main features

  • The expiration time and version number for each field can be specified.

  • The efficient and flexible active and passive expiration strategies for fields are supported.

  • TairHashes and native Redis hashes use similar syntax.

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

Prerequisites

The instance is of one of the following Tair series types:

Note

The latest minor version provides more features and higher stability. We recommend that you update the instance to the latest minor version. For more information, see Update the minor version of an instance. If your instance is a cluster or read/write splitting instance, we recommend that you update the proxy nodes in the instance to the latest minor version. This ensures that all commands can be run as expected.

Usage notes

The TairHash data that you want to manage is stored on Tair instances.

Supported commands

Table 1. TairHash commands

Command

Syntax

Description

EXHSET

EXHSET key field value [EX time] [EXAT time] [PX time] [PXAT time] [NX | XX] [VER | ABS version] [KEEPTTL]

Adds a field to a TairHash key. If the key does not exist, the key is created. If the field already exists, this command overwrites the current value of the field.

EXHGET

EXHGET key field

Retrieves the value of a field from a TairHash key. If the key or field does not exist, nil is returned.

EXHMSET

EXHMSET key field value [field value ...]

Adds multiple fields to a TairHash key. If the key does not exist, the key is created. If these fields already exist in the key, this command overwrites the values of these fields.

EXHPEXPIREAT

EXHPEXPIREAT key field milliseconds-timestamp [VER | ABS version]

Specifies the absolute expiration time of a field in a TairHash key. Unit: milliseconds.

EXHPEXPIRE

EXHPEXPIRE key field milliseconds [VER | ABS version]

Specifies the relative expiration time of a field in a TairHash key. Unit: milliseconds.

EXHEXPIREAT

EXHEXPIREAT key field timestamp [VER | ABS version]

Specifies the absolute expiration time of a field in a TairHash key. Unit: seconds.

EXHEXPIRE

EXHEXPIRE key field seconds [VER | ABS version]

Specifies the relative expiration time of a field in a TairHash key. Unit: seconds.

EXHPTTL

EXHPTTL key field

Queries the TTL of a field in a TairHash key. Unit: milliseconds.

EXHTTL

EXHTTL key field

Queries the TTL of a field in a TairHash key. Unit: seconds.

EXHVER

EXHVER key field

Queries the current version number of a field in a TairHash key.

EXHSETVER

EXHSETVER key field version

Specifies the version number of a field in a TairHash key.

EXHINCRBY

EXHINCRBY key field num [EX time] [EXAT time] [PX time] [PXAT time] [VER | ABS version] [MIN minval] [MAX maxval] [KEEPTTL]

Increases the value of a field by the num value in a TairHash key. The num value must be an integer. If the key does not exist, the key is created. If the field does not exist, this command adds the field and sets the value of the field to 0 before increasing the value of the field.

Note

To add a field that does not expire, you can run this command to add the field without specifying an expiration time.

EXHINCRBYFLOAT

EXHINCRBYFLOAT key field num [EX time] [EXAT time] [PX time] [PXAT time] [VER | ABS version] [MIN minval] [MAX maxval] [KEEPTTL]

Increases the value of a field by the num value in a TairHash key. The num value must be a floating-point number. If the key does not exist, the key is created. If the field does not exist, this command adds the field and sets the value of the field to 0 before increasing the value of the field.

Note

To add a field that does not expire, you can run this command to add the field without specifying an expiration time.

EXHGETWITHVER

EXHGETWITHVER key field

Retrieves the value and version number of a field from a TairHash key. If the key or field does not exist, nil is returned.

EXHMGET

EXHMGET key field [field ...]

Retrieves multiple field values from a TairHash key in each query. If the key does not exist or if the fields do not exist, nil is returned.

EXHMGETWITHVER

EXHMGETWITHVER key field [field ...]

Retrieves the values and version numbers of multiple fields from a TairHash key in each query.

EXHLEN

EXHLEN key [NOEXP]

Retrieves the number of fields in a TairHash key. The output may include the number of expired fields that are not deleted because this command does not trigger a passive eviction of or filter out expired fields. If you want to retrieve only the number of fields that have not expired, you can set the NOEXP parameter in your command.

EXHEXISTS

EXHEXISTS key field

Checks whether a field exists in a TairHash key.

EXHSTRLEN

EXHSTRLEN key field

Retrieves the length of a field value from a TairHash key.

EXHKEYS

EXHKEYS key

Retrieves all fields from a specified TairHash key.

EXHVALS

EXHVALS key

Retrieves all field values from a specified TairHash key.

EXHGETALL

EXHGETALL key

Retrieves all fields from a TairHash key and their values.

EXHSCAN

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

Scans a TairHash key.

Note

This command is supported only for DRAM-based instances.

EXHSCANUNORDER

EXHSCANUNORDER key cursor [MATCH pattern] [COUNT count]

Scans a TairHash key.

Note

This command is supported only for persistent memory-optimized instances.

EXHDEL

EXHDEL key field [field ...]

Deletes a field from a TairHash key. If the key or field does not exist, a value of 0 is returned. If the field is deleted, a value of 1 is returned.

DEL

DEL <key> [key ...]

Deletes one or more TairHash keys.

Note The following list describes the conventions for the command syntax used in this topic:
  • Uppercase keyword: indicates the command keyword.
  • Italic text: indicates variables.
  • [options]: indicates that the enclosed parameters are optional. Parameters that are not enclosed by brackets must be specified.
  • A|B: indicates that the parameters separated by the vertical bars (|) are mutually exclusive. Only one of the parameters can be specified.
  • ...: indicates that the parameter preceding this symbol can be repeatedly specified.

EXHSET

Item

Description

Syntax

EXHSET key field value [EX time] [EXAT time] [PX time] [PXAT time] [NX | XX] [VER | ABS version] [KEEPTTL]

Time complexity

O(1)

Command description

Adds a field to a TairHash key. If the key does not exist, the key is created. If the field already exists, this command overwrites the current value of the field.

Note
  • To add a field that does not expire, you can run this command to add the field without specifying an expiration time.

  • You can also run the EXPIRE or EXPIREAT command to specify an expiration time for a key.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

  • value: the value of the field. A field can have only a single value.

  • EX: the relative expiration time of the field. Unit: seconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • EXAT: the absolute expiration time of the field. Unit: seconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • PX: the relative expiration time of the field. Unit: milliseconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • PXAT: the absolute expiration time of the field. Unit: milliseconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • NX: specifies that the field is added only if the field does not exist.

  • XX: specifies that the field is added only if the field exists.

  • VER: the version number of the field.

    • If the field exists, the version number specified by this parameter is matched against the current version number.

      • If the version numbers match, the system continues to run the command and increases the version number by 1.

      • If the version numbers do not match, an error message is returned.

    • If the field does not exist or the current version number of the field is 0, this parameter is ignored and this command continues to run. After the operation succeeds, the version number is set to 1.

  • ABS: the absolute version number of the field. If you set this parameter, the system forcefully adds the field to the key regardless of whether the field already exists. When the field is added, the version number is set to the specified ABS value.

  • KEEPTTL: retains the current time-to-live (TTL) of the field if none of the EX, EXAT, PX, and PXAT parameters are specified.

    Note

    By default, if the KEEPTTL parameter is not specified, the EXHSET command deletes the current TTL of the field.

Output

  • If a field is created and a value is set for the field, a value of 1 is returned.

  • If the field already exists and the specified value overwrites the current value of the field, a value of 0 is returned.

  • If the XX parameter is specified and the field does not exist, a value of -1 is returned.

  • If the NX parameter is specified and the field exists, a value of -1 is returned.

  • If the VER parameter is specified and the VER value does not match the current version number, the "ERR update version is stale" message is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHSET myhash field1 val EX 10

Sample output:

(integer) 1

EXHGET

Item

Description

Syntax

EXHGET key field

Time complexity

O(1)

Command description

Retrieves the value of a field from a TairHash key. If the key or field does not exist, nil is returned.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the field exists and the operation is successful, the value of the field is returned.

  • If the key or field does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Run the EXHSET myhash field1 val command in advance.

Sample command:

EXHGET myhash field1

Sample output:

"val"

EXHMSET

Item

Description

Syntax

EXHMSET key field value [field value ...]

Time complexity

O(N)

Command description

Adds multiple fields to a TairHash key. If the key does not exist, the key is created. If these fields already exist in the key, this command overwrites the values of these fields.

Note

After you create a key, you can run the EXHPEXPIREAT, EXHPEXPIRE, EXHEXPIREAT, or EXHEXPIRE command to specify an expiration time for the fields that are added to the key. You can also run the EXPIRE or EXPIREAT command to specify an expiration time for the key.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

  • value: the value of the field. A field can have only a single value.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHMSET myhash field1 val1 field2 val2

Sample output:

OK

EXHPEXPIREAT

Item

Description

Syntax

EXHPEXPIREAT key field milliseconds-timestamp [VER | ABS version]

Time complexity

O(1)

Command description

Specifies the absolute expiration time of a field in a TairHash key. Unit: milliseconds.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

  • milliseconds-timestamp: a timestamp, which must be accurate to the millisecond.

  • VER: the version number of the field.

    • If the field exists, the version number specified by this parameter is matched against the current version number.

      • If the version numbers match, the system continues to run the command and increases the version number by 1.

      • If the version numbers do not match, an error message is returned.

    • If the field does not exist or the current version number of the field is 0, this parameter is ignored and this command continues to run. After the operation succeeds, the version number is set to 1.

  • ABS: the absolute version number of the field. If you set this parameter, the system forcefully adds the field to the key regardless of whether the field already exists. When the field is added, the version number is set to the specified ABS value.

Output

  • If the field exists and a value is set for the field, a value of 1 is returned.

  • If the field does not exist, a value of 0 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHPEXPIREAT myhash field1 1293840000

Sample output:

(integer) 1

EXHPEXPIRE

Item

Description

Syntax

EXHPEXPIRE key field milliseconds [VER | ABS version]

Time complexity

O(1)

Command description

Specifies the relative expiration time of a field in a TairHash key. Unit: milliseconds.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

  • milliseconds: the relative expiration time. Unit: milliseconds.

  • VER: the version number of the field.

    • If the field exists, the version number specified by this parameter is matched against the current version number.

      • If the version numbers match, the system continues to run the command and increases the version number by 1.

      • If the version numbers do not match, an error message is returned.

    • If the field does not exist or the current version number of the field is 0, this parameter is ignored and this command continues to run. After the operation succeeds, the version number is set to 1.

  • ABS: the absolute version number of the field. If you set this parameter, the system forcefully adds the field to the key regardless of whether the field already exists. When the field is added, the version number is set to the specified ABS value.

Output

  • If the field exists and a value is set for the field, a value of 1 is returned.

  • If the field does not exist, a value of 0 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHPEXPIRE myhash field1 1000

Sample output:

(integer) 1

EXHEXPIREAT

Item

Description

Syntax

EXHEXPIREAT key field timestamp [VER | ABS version]

Time complexity

O(1)

Command description

Specifies the absolute expiration time of a field in a TairHash key. Unit: seconds.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

  • timestamp: a timestamp, which must be accurate to the millisecond.

  • VER: the version number of the field.

    • If the field exists, the version number specified by this parameter is matched against the current version number.

      • If the version numbers match, the system continues to run the command and increases the version number by 1.

      • If the version numbers do not match, an error message is returned.

    • If the field does not exist or the current version number of the field is 0, this parameter is ignored and this command continues to run. After the operation succeeds, the version number is set to 1.

  • ABS: the absolute version number of the field. If you set this parameter, the system forcefully adds the field to the key regardless of whether the field already exists. When the field is added, the version number is set to the specified ABS value.

Output

  • If the field exists and a value is set for the field, a value of 1 is returned.

  • If the field does not exist, a value of 0 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHEXPIREAT myhash field1 1293840000

Sample output:

(integer) 1

EXHEXPIRE

Item

Description

Syntax

EXHEXPIRE key field seconds [VER | ABS version]

Time complexity

O(1)

Command description

Specifies the relative expiration time of a field in a TairHash key. Unit: seconds.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

  • seconds: the relative expiration time. Unit: seconds.

  • VER: the version number of the field.

    • If the field exists, the version number specified by this parameter is matched against the current version number.

      • If the version numbers match, the system continues to run the command and increases the version number by 1.

      • If the version numbers do not match, an error message is returned.

    • If the field does not exist or the current version number of the field is 0, this parameter is ignored and this command continues to run. After the operation succeeds, the version number is set to 1.

  • ABS: the absolute version number of the field. If you set this parameter, the system forcefully adds the field to the key regardless of whether the field already exists. When the field is added, the version number is set to the specified ABS value.

Output

  • If the field exists and a value is set for the field, a value of 1 is returned.

  • If the field does not exist, a value of 0 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHEXPIRE myhash field1 100

Sample output:

(integer) 1

EXHPTTL

Item

Description

Syntax

EXHPTTL key field

Time complexity

O(1)

Command description

Queries the TTL of a field in a TairHash key. Unit: milliseconds.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the field exists and the field does not have a TTL configured, a value of -1 is returned.

  • If the key or field does not exist, a value of -2 is returned.

  • If the field does not exist, a value of -3 is returned.

  • If the field exists and the field has a TTL configured, the TTL is returned. Unit: milliseconds.

  • Otherwise, an error message is returned.

Example

Run the EXHSET myhash field1 val1 EX 100 command in advance.

Sample command:

EXHPTTL myhash field1

Sample output:

(integer) 97213

EXHTTL

Item

Description

Syntax

EXHTTL key field

Time complexity

O(1)

Command description

Queries the TTL of a field in a TairHash key. Unit: seconds.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the key or field does not exist, a value of -2 is returned.

  • If the field exists and the field does not have a TTL configured, a value of -1 is returned.

  • If the field exists and the field has a TTL configured, the TTL is returned. Unit: seconds.

  • Otherwise, an error message is returned.

Example

Run the EXHSET myhash field1 val1 EX 100 command in advance.

Sample command:

EXHTTL myhash field1

Sample output:

(integer) 85

EXHVER

Item

Description

Syntax

EXHVER key field

Time complexity

O(1)

Command description

Queries the current version number of a field in a TairHash key.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the key does not exist, a value of -1 is returned.

  • If the field does not exist, a value of -2 is returned.

  • If the operation is successful, the version number of the field is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHVER myhash field1

Sample output:

(integer) 1

EXHSETVER

Item

Description

Syntax

EXHSETVER key field version

Time complexity

O(1)

Command description

Specifies the version number of a field in a TairHash key.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the key or field does not exist, a value of 0 is returned.

  • If the version number is specified, a value of 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHSETVER myhash field1 3

Sample output:

(integer) 1

EXHINCRBY

Item

Description

Syntax

EXHINCRBY key field num [EX time] [EXAT time] [PX time] [PXAT time] [VER | ABS version] [MIN minval] [MAX maxval] [KEEPTTL]

Time complexity

O(1)

Command description

Increases the value of a field by the num value in a TairHash key. The num value must be an integer. If the key does not exist, the key is created. If the field does not exist, this command adds the field and sets the value of the field to 0 before increasing the value of the field.

Note

To add a field that does not expire, you can run this command to add the field without specifying an expiration time.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

  • num: the integer by which you want to increase the value of the field.

  • EX: the relative expiration time of the field. Unit: seconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • EXAT: the absolute expiration time of the field. Unit: seconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • PX: the relative expiration time of the field. Unit: milliseconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • PXAT: the absolute expiration time of the field. Unit: milliseconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • VER: the version number of the field.

    • If the field exists, the version number specified by this parameter is matched against the current version number.

      • If the version numbers match, the system continues to run the command and increases the version number by 1.

      • If the version numbers do not match, an error message is returned.

    • If the field does not exist or the current version number of the field is 0, this parameter is ignored and this command continues to run. After the operation succeeds, the version number is set to 1.

  • ABS: the absolute version number of the field. If you set this parameter, the system forcefully adds the field to the key regardless of whether the field already exists. When the field is added, the version number is set to the specified ABS value.

  • MIN: the minimum value of the field. If the field value is less than this lower limit, an error message is returned.

  • MAX: the maximum value of the field. If the field value is greater than this upper limit, an error message is returned.

  • KEEPTTL: retains the current TTL of the field if none of the EX, EXAT, PX, and PXAT parameters are specified.

Output

  • If the operation is successful, the value increased by the num value is returned.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhash field1 10 command in advance.

Sample command:

EXHINCRBY myhash field1 100

Sample output:

(integer) 110

EXHINCRBYFLOAT

Item

Description

Syntax

EXHINCRBYFLOAT key field num [EX time] [EXAT time] [PX time] [PXAT time] [VER | ABS version] [MIN minval] [MAX maxval] [KEEPTTL]

Time complexity

O(1)

Command description

Increases the value of a field by the num value in a TairHash key. The num value must be a floating-point number. If the key does not exist, the key is created. If the field does not exist, this command adds the field and sets the value of the field to 0 before increasing the value of the field.

Note

To add a field that does not expire, you can run this command to add the field without specifying an expiration time.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

  • num: the floating-point number by which you want to increase the value for the field.

  • EX: the relative expiration time of the field. Unit: seconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • EXAT: the absolute expiration time of the field. Unit: seconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • PX: the relative expiration time of the field. Unit: milliseconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • PXAT: the absolute expiration time of the field. Unit: milliseconds. A value of 0 indicates that the field immediately expires. If this parameter is not specified, the field does not expire.

  • VER: the version number of the field.

    • If the field exists, the version number specified by this parameter is matched against the current version number.

      • If the version numbers match, the system continues to run the command and increases the version number by 1.

      • If the version numbers do not match, an error message is returned.

    • If the field does not exist or the current version number of the field is 0, this parameter is ignored and this command continues to run. After the operation succeeds, the version number is set to 1.

  • ABS: the absolute version number of the field. If you set this parameter, the system forcefully adds the field to the key regardless of whether the field already exists. When the field is added, the version number is set to the specified ABS value.

  • MIN: the minimum value of the field. If the field value is less than this lower limit, an error message is returned.

  • MAX: the maximum value of the field. If the field value is greater than this upper limit, an error message is returned.

  • KEEPTTL: retains the current TTL of the field if none of the EX, EXAT, PX, and PXAT parameters are specified.

Output

  • If the operation is successful, the value increased by the num value is returned.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhash field1 10 command in advance.

Sample command:

EXHINCRBYFLOAT myhash field1 9.235

Sample output:

"19.235"

EXHGETWITHVER

Item

Description

Syntax

EXHGETWITHVER key field

Time complexity

O(1)

Command description

Retrieves the value and version number of a field from a TairHash key. If the key or field does not exist, nil is returned.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the field exists and the operation is successful, the value and version number of the field are returned.

  • If the key or field does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHGETWITHVER myhash field1

Sample output:

1) "19.235"
2) (integer) 5

EXHMGET

Item

Description

Syntax

EXHMGET key field [field ...]

Time complexity

O(1)

Command description

Retrieves multiple field values from a TairHash key in each query. If the key does not exist or if the fields do not exist, nil is returned.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the key does not exist, nil is returned.

  • If the key and fields exist, an array is returned. Each element in the array corresponds to a field value.

  • If the key exists and specific fields do not exist, an array is returned. Each element in the array corresponds to a field value. The elements that correspond to the fields that do not exist are displayed as nil.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhash field1 10 field2 var1 command in advance.

Sample command:

EXHMGET myhash field1 field2

Sample output:

1) "10"
2) "var1"

EXHMGETWITHVER

Item

Description

Syntax

EXHMGETWITHVER key field [field ...]

Time complexity

O(1)

Command description

Retrieves the values and version numbers of multiple fields from a TairHash key in each query.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the key does not exist, nil is returned.

  • If the key and fields exist, an array is returned. Each element in the array corresponds to a field value and a version number.

  • If the key exists and specific fields do not exist, an array is returned. Each element in the array corresponds to a field value and a field version number. The elements that correspond to the fields that do not exist are displayed as nil.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhash field1 10 field2 var1 command in advance.

Sample command:

 EXHMGETWITHVER myhash field1 field2

Sample output:

1) 1) "10"
   2) (integer) 1
2) 1) "var1"
   2) (integer) 1

EXHLEN

Item

Description

Syntax

EXHLEN key [NOEXP]

Time complexity

The time complexity is O(1) if the NOEXP parameter is not specified and O(N) if the NOEXP parameter is specified.

Command description

Retrieves the number of fields in a TairHash key. The output may include the number of expired fields that are not deleted because this command does not trigger a passive eviction of or filter out expired fields. If you want to retrieve only the number of fields that have not expired, you can set the NOEXP parameter in your command.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • NOEXP: specifies to return the number of fields that have not expired. By default, this command does not filter out or passively evict expired fields. For this reason, the output of this command may include the number of expired fields that are not deleted. If you want to retrieve only the number of fields that have not expired, you can set the NOEXP parameter. When you set the NOEXP parameter, take note of the following items:

    • The response time of the EXHLEN command is determined by the size of the key because the system scans all data in the key.

    • The output of the EXHLEN command does not include the number of expired fields because this command filters out expired fields but does not evict them.

Output

  • If the key or field does not exist, a value of 0 is returned.

  • If the operation is successful, the number of fields in the key is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHLEN myhash

Sample output:

(integer) 2

EXHEXISTS

Item

Description

Syntax

EXHEXISTS key field

Time complexity

O(1)

Command description

Checks whether a field exists in a TairHash key.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the key or field does not exist, a value of 0 is returned.

  • If the field exists, a value of 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHEXISTS myhash field1

Sample output:

(integer) 1

EXHSTRLEN

Item

Description

Syntax

EXHSTRLEN key field

Time complexity

O(1)

Command description

Retrieves the length of a field value from a TairHash key.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the key or field does not exist, a value of 0 is returned.

  • If the operation is successful, the length of the field value is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHSTRLEN myhash field1

Sample output:

(integer) 2

EXHKEYS

Item

Description

Syntax

EXHKEYS key

Time complexity

O(N)

Command description

Retrieves all fields from a specified TairHash key.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

Output

  • If the key does not exist, an empty array is returned.

  • If the key exists, an array is returned. Each element in the array corresponds to a field in the key.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhash field1 10 field2 var1 command in advance.

Sample command:

EXHKEYS myhash

Sample output:

1) "field1"
2) "field2"

EXHVALS

Item

Description

Syntax

EXHVALS key

Time complexity

O(N)

Command description

Retrieves all field values from a specified TairHash key.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

Output

  • If the key does not exist, an empty array is returned.

  • If the key exists, an array is returned. Each element in the array corresponds to a field value in the key.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhash field1 10 field2 var1 command in advance.

Sample command:

EXHVALS myhash

Sample output:

1) "10"
2) "var1"

EXHGETALL

Item

Description

Syntax

EXHGETALL key

Time complexity

O(N)

Command description

Retrieves all fields from a TairHash key and their values.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

Output

  • If the key does not exist, an empty array is returned.

  • If the key exists, an array is returned. Each element in the array corresponds to a field-value pair in the key.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhash field1 10 field2 var1 command in advance.

Sample command:

EXHGETALL myhash

Sample output:

1) "field1"
2) "10"
3) "field2"
4) "var1"

EXHSCAN

Item

Description

Syntax

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

Time complexity

The time complexity is O(1) for every call and O(N) for a complete iteration.

Command description

Scans a TairHash key.

Note

This command is supported only for DRAM-based instances.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • op: the position from which a scan starts. Valid values:

    • >: The scan starts from the first field that has a value greater than the subkey value.

    • >=: The scan starts from the first field that has a value greater than or equal to the subkey value.

    • <: The scan starts from the first field that has a value less than the subkey value.

    • <=: The scan starts from the first field that has a value less than or equal to the subkey value.

    • ==: The scan starts from the first field that has a value equal to the subkey value.

    • ^: The scan starts from the first field.

    • $: The scan starts from the last field.

  • subkey: a parameter that is used together with the op parameter to determine the position from which a scan starts. If the op parameter is set to ^ or $, this parameter is ignored.

  • MATCH: filters the subkeys to be scanned with regular expressions based on the specified pattern.

  • COUNT: specifies the number of fields that can be scanned in each query. The default value is 10.

    Note

    The COUNT parameter specifies the number of fields scanned in each query and does not ensure that the number of fields returned is the number of fields scanned. The number of fields returned is determined by the number of fields that exist in the key and whether the MATCH parameter is specified.

Output

  • If the key does not exist, an empty array is returned.

  • If the key exists, an array that contains two elements is returned.

    • The first element is the first field from which the next scan starts. If the key scan has been completed, this element is left empty.

    • The second element is the scan result, which includes fields and values.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhashkey field1 val1 field2 val2 field3 val3 field4 val4 field5 val5 command in advance.

Sample command:

EXHSCAN myhashkey ^ xx COUNT 3

Sample output:

1) "field4"
2) 1) "field1"
   2) "val1"
   3) "field2"
   4) "val2"
   5) "field3"
   6) "val3"

EXHSCANUNORDER

Item

Description

Syntax

EXHSCANUNORDER key cursor [MATCH pattern] [COUNT count]

Time complexity

The time complexity is O(1) for every call and O(N) for a complete iteration.

Command description

Scans a TairHash key.

Note

This command is supported only for persistent memory-optimized instances.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • cursor: the cursor used in this scan.

  • MATCH: filters the keys to be scanned with regular expressions based on the specified pattern.

  • COUNT: specifies the number of fields that can be scanned in each query. The default value is 10.

    Note

    The COUNT parameter specifies the number of fields scanned in each query and does not ensure that the number of fields returned is the number of fields scanned. The number of fields returned is determined by the number of fields that exist in the key and whether the MATCH parameter is specified.

Output

  • If the key does not exist, an empty array is returned.

  • If the key exists, an array that contains two elements is returned.

    • The first element of the array is the cursor used for the next scan. If the index is scanned, a value of 0 is returned.

    • The second element is the scan result, which includes fields and values.

  • Otherwise, an error message is returned.

Example

Run the EXHMSET myhashkey field1 val1 field2 val2 field3 val3 field4 val4 field5 val5 command in advance.

Sample command:

EXHSCANUNORDER myhashkey 0 COUNT 3

Sample output:

1) "1"
2) 1) "field5"
   2) "val5"
   3) "field2"
   4) "val2"

EXHDEL

Item

Description

Syntax

EXHDEL key field [field ...]

Time complexity

O(1)

Command description

Deletes a field from a TairHash key. If the key or field does not exist, a value of 0 is returned. If the field is deleted, a value of 1 is returned.

Parameter

  • Key: the key that specifies the piece of TairHash data that you want to manage by running this command.

  • field: an element of the key. A key can contain multiple fields.

Output

  • If the key or field does not exist, a value of 0 is returned.

  • If the operation is successful, a value of 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXHDEL myhash field1

Sample output:

(integer) 1