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 native Redis hashes use.

Commands

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 no keys exist, a key will be created. If the field has a value, this command overwrites the value. To add a field that does not expire, you can run this command to add the field without specifying an expiration time.
  Parameters	Key: Object that you want to manage by running this command.
  	field: An element in the EXHASH command. 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 the 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 will be 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 the set version number is earlier than the current one, a failure message is returned.
  	ABS: Absolute version number of the field. When a field is inserted, the version number is the version number specified by this parameter.
  	KEEPTTL: The current expiration setting of the field is retained 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 commands

    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	Adds num to the value of a field in an EXHASH key. num is an integer. If no keys are found, a key will be 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: Object that you want to manage by running this command.
  	field: An element in the EXHASH command. An EXHASH key can have multiple fields.
  	num: Integer to be added to 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 the 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, compare the version number specified by this parameter with the current version number. If they are the same, use this command and add 1 to the version number. If they are different, an error message will be displayed. 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 the set version number is earlier than the current one, a failure message will be returned.
  	ABS: Absolute version number of the field. When a field is inserted, the version number is the version number specified by this parameter.
  	KEEPTTL: The current expiration setting of the field is retained 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 the minimum value, an error message is returned.
  	MAX: Maximum value of the field. If the field value is greater than the maximum value, an error message is returned.
  Returned values	If the operation is successful, the value after num is added to is returned.
  	Otherwise, an error message is returned.

  • Example command

    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 Using 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 JedisPool.
        // 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", 8635, 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();
    }
}

Click EXHASH Solution for Ad Frequency Control to view the best practices of the EXHASH command.