ExHash Commands

Highlights

• The expiration time and version number can be specified for each field.
• Efficient, flexible active and passive expiration strategies are supported for fields.
• The syntax is similar to that of native Redis HASH.

Commands

Table 1 ExHash commands

Command	Syntax	Description
EXHSET	EXHSET key field value [EX time] [EXAT time] [PX time] [PXAT time] [NX | XX] [VER | ABS | GT version] [KEEPTTL]	Adds a field to an ExHash key. If the key does not exist, it is automatically 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 an ExHash key. If the key or field does not exist, nil is returned.
EXHPTTL	EXHPTTL key field	Queries the remaining time to live (in milliseconds) of a field in an ExHash key
EXHTTL	EXHTTL key field	Queries the remaining time to live (in seconds) of a field in an ExHash key
EXHVER	EXHVER key field	Queries the current version of a field in an ExHash key.
EXHINCRBY	EXHINCRBY key field num [EX time] [EXAT time] [PX time] [PXAT time] [VER | ABS | GT version] [MIN minval] [MAX maxval] [KEEPTTL]	Increases the value of a field in an ExHash key by the num value (an integer). If the key does not exist, it is automatically 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 | GT version] [MIN minval] [MAX maxval] [KEEPTTL]	Increases the value of a field in an ExHash key by the num value (a floating-point number). If the key does not exist, it is automatically 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.
EXHMGET	EXHMGET key field [field ...]	Retrieves multiple field values from an ExHash key in each query. If the key or fields do not exist, nil is returned.
EXHLEN	EXHLEN key [NOEXP]	Retrieves the number of fields in an ExHash key. The output may include the number of expired fields that are not deleted, because this command does not trigger a passive eviction or filter out expired fields. To obtain only the number of fields that have not expired, you can set parameter NOEXP in the command.
EXHGETALL	EXHGETALL key	Retrieves all fields and their values from an ExHash key.
EXHDEL	EXHDEL key field [field ...]	Deletes a field from an ExHash key. If the key or field does not exist, 0 is returned. If the field is deleted, 1 is returned.
DEL	DEL <key> [key ...]	Deletes one or more ExHash keys.
EXISTS	EXISTS <key> [key ...]	Checks whether there is one or more ExHash data records.

Complex Commands and Options

• EXHSET

  Table 2 EXHSET commands

  Item	Description
  Syntax	EXHSET key field value [EX time] [EXAT time] [PX time] [PXAT time] [NX | XX] [VER | GT | ABS version] [KEEPTTL]
  Description	Adds a field to an ExHash key. If the key does not exist, it is automatically created. If the field already exists, this command overwrites the current value of the field. To add a field that does not expire, you can run this command to add the field without specifying an expiration time.
  Parameters	key: a piece of ExHash data that you want to manage by running this command
  	field: an element of the key. An ExHash key can have multiple fields.
  	value: value of the field. A field can have only one value.
  	EX: relative expiration time of the field, in seconds. 0 indicates that the field will expire immediately. If this parameter is not specified, the field does not expire.
  	EXAT: absolute expiration time of the field, in seconds. 0 indicates that the field will expire immediately. If this parameter is not specified, the field does not expire.
  	PX: relative expiration time of a field, in milliseconds. 0 indicates that the field will expire immediately. If this parameter is not specified, the field does not expire.
  	PXAT: absolute expiration time of the field, in milliseconds. 0 indicates that the field will expire immediately. If this parameter is not specified, the field does not expire.
  	NX: This parameter is added only when the field does not exist.
  	XX: This parameter is inserted only if the field exists.
  	VER: version number of the field. If the field exists, the version number specified by this parameter is compared with the current version number. If they are the same, the system continues to run this command and increases the version number by 1. If they are different, an error message is returned. If the field does not exist or the current version of the field is 0, the system ignores this parameter and runs the command. After the operation completes, the version number changes to 1.
  	GT: version later than the current one. If it is earlier than the current one, an error message is returned.
  	ABS: absolute version number of the field. The system forcibly writes the field to the key regardless of whether the field already exists.
  	KEEPTTL: retains the current time to live of the field if none of the EX, EXAT, PX, and PXAT parameters are specified.
  Returned values	If a field is created and a value is set for it, 1 is returned.
  	If a field already exists and the specified value overwrites the current value, 0 is returned.
  	If XX is specified and the field does not exist, -1 is returned.
  	If NX is specified and the field exists, -1 is returned.
  	If VER is specified and the value does not match the current version, the error message "ERR update version is stale" is returned.
  	Error messages are returned in other cases.

  • Example

    Setting the expiration time for a field

    127.0.0.1:6579> EXHSET k1 f1 v1 ex 10
    (integer) 1
    127.0.0.1:6579> EXHGET k1 f1
    "v1"
    127.0.0.1:6579> EXHSET k1 f2 v2 ex 10
    (integer) 1
    127.0.0.1:6579> EXHGET k1 f1
    (nil)
    127.0.0.1:6579> EXHGETALL k1
    127.0.0.1:6579> EXHGETALL k1
    (empty array)

    Setting a version number for a field

    127.0.0.1:6579> EXHSET k1 f1 v1
    (integer) 1
    127.0.0.1:6579> EXHVER k1 f1
    (integer) 1
    127.0.0.1:6579> EXHSET k1 f1 v1 ver 2
    (error) ERR update version is stale
    127.0.0.1:6579> EXHSET k1 f1 v1 ver 1
    (integer) 0
    127.0.0.1:6579> EXHVER k1 f1
    (integer) 2
    127.0.0.1:6579> EXHSET k1 f1 v1
    (integer) 0
    127.0.0.1:6579> EXHVER k1 f1
    (integer) 3
    127.0.0.1:6579> EXHSET k1 f1 v1 GT 3
    (error) ERR update version is stale
    127.0.0.1:6579> EXHSET k1 f1 v1 GT 2
    (error) ERR update version is stale
    127.0.0.1:6579> EXHSET k1 f1 v1 GT 4
    (integer) 0
    127.0.0.1:6579> EXHVER k1 f1
    (integer) 4
    127.0.0.1:6579> EXHSET k1 f1 v1 abs 2
    (integer) 0
    127.0.0.1:6579> EXHVER k1 f1
    (integer) 2
• EXHINCRBY

  Table 3 EXHINCRBY commands

  Item	Description
  Syntax	EXHINCRBY key field num [EX time] [EXAT time] [PX time] [PXAT time] [VER | GT | ABS version] [MIN minval] [MAX maxval] [KEEPTTL]
  Description	Increases the value of a field in an ExHash key by the num value (an integer). If the key does not exist, it is automatically 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. To add a field that does not expire, you can run this command to add the field without specifying an expiration time.
  Parameters	key: a piece of ExHash data that you want to manage by running this command
  	field: an element of the key. An ExHash key can have multiple fields.
  	num: an integer by which you want to increase the value of the field
  	EX: relative expiration time of the field, in seconds. 0 indicates that the field will expire immediately. If this parameter is not specified, the field does not expire.
  	EXAT: absolute expiration time of the field, in seconds. 0 indicates that the field will expire immediately. If this parameter is not specified, the field does not expire.
  	PX: relative expiration time of a field, in milliseconds. 0 indicates that the field will expire immediately. If this parameter is not specified, the field does not expire.
  	PXAT: absolute expiration time of the field, in milliseconds. 0 indicates that the field will expire immediately. If this parameter is not specified, the field does not expire.
  	VER: version number of the field. If the field exists, the version number specified by this parameter is compared with the current version number. If they are the same, the system continues to run this command and increases the version number by 1. If they are different, an error message is returned. If the field does not exist or the current version of the field is 0, ignore this parameter and run the command. After the operation completes, the version number changes to 1.
  	GT: version later than the current one. If it is earlier than the current one, an error message is returned.
  	ABS: absolute version number of the field. The system forcibly writes the field to the key regardless of whether the field already exists.
  	KEEPTTL: retains the current time to live of the field if none of the EX, EXAT, PX, and PXAT parameters are specified.
  	MIN: minimum value of the field. If the field value is less than this lower limit, an error message is returned.
  	MAX: maximum value of the field. If the field value is greater than this upper limit, an error message is returned.
  Returned values	If the operation is successful, the value increased by the num value is returned.
  	Otherwise, an error message is returned.

  • Example

    An example of using the MIN and MAX parameters

    127.0.0.1:6579> EXHINCRBY k1 f1 5 min 6
    (error) ERR increment or decrement would overflow
    127.0.0.1:6579> EXHINCRBY k1 f1 5 min 4
    (integer) 5
    127.0.0.1:6579> EXHINCRBY k1 f1 5 max 9
    (error) ERR increment or decrement would overflow
    127.0.0.1:6579> EXHINCRBY k1 f1 3 max 9
    (integer) 8

Example of ExHash Commands

JAVA(Jedis)

package nosql.cloud.huawei.jedis;

import redis.clients.jedis.*;
import redis.clients.jedis.util.SafeEncoder;

import java.util.ArrayList;

public class Main{
    public static void main(String[] args) throws InterruptedException {
        // Initialize the Jedis resource pool configuration.
        JedisPoolConfig jedisPoolConfig = new JedisPoolConfig();
        // Set the maximum number of connections in the resource pool.
        jedisPoolConfig.setMaxTotal(10);
        // Set the maximum number of idle connections allowed by the pool.
        jedisPoolConfig.setMaxIdle(10);
        // Set the minimum number of idle connections retained in the pool.
        jedisPoolConfig.setMinIdle(2);

       // Initialize the Jedis resource pool based on the configuration.
        // Note: If the version does not support Access Control List (ACL), the value of user must be null.
        JedisPool jedisPool = new JedisPool(jedisPoolConfig, "127.0.0.1", 6379, null, "******");

        // Obtain connections from the pool.
        try (Jedis jedis = jedisPool.getResource()) {
            // example for: EXHSET key field value [EX time] [EXAT time] [PX time] [PXAT time] [NX | XX] [VER | ABS | GT version] [KEEPTTL]
            jedis.sendCommand(() -> SafeEncoder.encode("exhset"), "key", "field1", "value1");
            jedis.sendCommand(() -> SafeEncoder.encode("exhset"), "key", "field2", "value2", "EX", "5");

            // example for: EXHGET key field
            byte[] byteArray = (byte[]) jedis.sendCommand(() -> SafeEncoder.encode("exhget"), "key", "field1");
            System.out.println(new String(byteArray));
            byteArray = (byte[]) jedis.sendCommand(() -> SafeEncoder.encode("exhget"), "key", "field2");
            System.out.println(new String(byteArray));

            // example for: EXHGETALL key
            ArrayList<byte[]> byteArrayList = (ArrayList<byte[]>) jedis.sendCommand(() -> SafeEncoder.encode("exhgetall"), "key");
            for (byte[] ba : byteArrayList) {
                System.out.print(new String(ba));
                System.out.print(" ");
            }
            System.out.println();

            // sleep for 5 seconds
            Thread.sleep(5000);

            // exhgetall after sleeping
            byteArrayList = (ArrayList<byte[]>) jedis.sendCommand(() -> SafeEncoder.encode("exhgetall"), "key");
            for (byte[] ba : byteArrayList) {
                System.out.print(new String(ba));
                System.out.print(" ");
            }
        }

        // Disable the pool.
        jedisPool.close();
    }
}

For details about the best practices of ExHash commands, see ExHash for Ad Frequency Control.