本章节介绍TairHash数据支持的命令。

TairHash简介

TairHash是一种可为field设置过期时间和版本的hash类型数据结构。TairHash不但和Redis Hash一样支持丰富的数据接口和高处理性能，还改变了hash只能为key设置过期时间的限制，可以为field设置过期时间和版本，极大地提高了hash数据结构的灵活性，简化了很多场景下的业务开发工作。TairHash使用高效的Active Expire算法，可以在不对响应时间造成明显影响的前提下，更高效的完成对field的过期判断和删除。

主要特性：

  • field支持单独设置expire和version。
  • field支持高效active expire和passivity expire。
  • 语法和原生Redis Hash数据类型类似。
警告 TairHash与Redis中的原生Hash是两种不同的数据，相关命令不可混用。

使用前提

请注意，本章节介绍的命令只有在满足以下条件时才能生效。

  • Redis实例为云Redis企业版性能增强型实例。
  • 操作对象为性能增强型实例中的TairHash数据。
    说明 性能增强型实例中可同时设置Redis Hash（即Redis原生Hash）和TairHash，本章节的命令无法对Redis Hash使用。

命令列表

表 1. TairHash命令
命令 语法 说明
EXHSET EXHSET <key> <field> <value> [EX time] [EXAT time] [PX time] [PXAT time] [NX/XX] [VER/ABS version] 向key指定的TairHash中插入一个field，如果TairHash不存在则自动创建一个，如果field已经存在则覆盖其值。
EXHSETNX EXHSETNX <key> <field> <value> 向key指定的TairHash中插入一个field，前提是这个field必须不存在，否则插入失败。
EXHMSET EXHMSET <key> <field> <value> [field value...] 同时向key指定的TairHash中插入多个field，如果TairHash不存在则自动创建一个，如果field已经存在则覆盖其值。该命令会触发对field的被动淘汰。
EXHMSETWITHOPTS EXHMSETWITHOPTS exhashkey field1 val1 ver1 expire1 [field2 val2 ver2 expire2 ...] 该命令会触发对field的被动淘汰。
EXHPEXPIREAT EXHPEXPIREAT <key> <field> <milliseconds-timestamp> 在key指定的TairHash中为一个field设置绝对过期时间，单位为毫秒。该命令会触发对field的被动淘汰。
EXHPEXPIRE EXHPEXPIRE <key> <field> <milliseconds> 在key指定的TairHash中为一个field设置相对过期时间，单位为毫秒。该命令会触发对field的被动淘汰。
EXHEXPIREAT EXHEXPIREAT <key> <field> <timestamp> 在key指定的TairHash中为一个field设置绝对过期时间，单位为秒。该命令会触发对field的被动淘汰。
EXHEXPIRE EXHEXPIRE <key> <field> <seconds> 在key指定的TairHash中为一个field设置相对过期时间，单位为秒。该命令会触发对field的被动淘汰。
EXHPTTL EXHPTTL <key> <field> 查看key指定的TairHash中一个field的剩余超时时间，单位为毫秒。该命令会触发对field的被动淘汰。
EXHTTL EXHTTL <key> <field> 查看key指定的TairHash中一个field的剩余超时时间，单位为秒。该命令会触发对field的被动淘汰。
EXHVER EXHVER <key> <field> 查看key指定的TairHash中一个field的当前版本号。该命令会触发对field的被动淘汰。该命令会触发对field的被动淘汰。
EXHSETVER EXHSETVER <key> <field> <version> 为key指定的TairHash中的一个field设置版本号。该命令会触发对field的被动淘汰。
EXHINCRBY EXHINCRBY <key> <field> <value> [EX time] [EXAT time] [PX time] [PXAT time] 将key指定的TairHash中一个field的值加上整型value。如果TairHash不存在则自动新创建一个，如果指定的field不存在，则在加之前先将field的值设置为0。同时还可以使用EX/EXAT/PX/PXAT为field设置超时时间。该命令会触发对field的被动淘汰。
EXHINCRBYFLOAT EXHINCRBYFLOAT <key> <field> <value> [EX time] [EXAT time] [PX time] [PXAT time] 将key指定的TairHash中一个field的值加上浮点型value。如果TairHash不存在则自动新创建一个，如果指定的field不存在，则在加之前先将field的值设置为0。同时还可以使用EX/EXAT/PX/PXAT为field设置超时时间。该命令会触发对field的被动淘汰。
EXHGET EXHGET <key> <field> 获取key指定的TairHash中一个field的值，如果TairHash不存在或者field不存在，则返回nil。该命令会触发对field的被动淘汰。
EXHGETWITHVER EXHGETWITHVER <key> <field> 同时获取key指定的TairHash中一个field的值和版本，如果TairHash不存在或者field不存在，则返回nil。该命令会触发对field的被动淘汰。
EXHMGET EXHMGET <key> <field> [field ...] 同时获取key指定的TairHash中多个field的值，如果TairHash不存在或者field不存在，则返回nil。该命令会触发对field的被动淘汰。
EXHMGETWITHVER EXHMGETWITHVER <key> <field> [field ...] 同时获取key指定的TairHash中多个field的值和版本，如果TairHash不存在或者field不存在，则返回nil。该命令会触发对field的被动淘汰。
EXHDEL EXHDEL <key> <field> <field> <field> ... 删除key指定的TairHash中的一个field，如果TairHash不存在或者field不存在则返回0 ，成功删除返回1。该命令会触发对field的被动淘汰。
EXHLEN EXHLEN <key> 获取key指定的TairHash中field个数，该命令不会触发对过期field的被动淘汰，也不会将其过滤掉，所以结果中可能包含已经过期但还未被删除的field。
EXHEXISTS EXHEXISTS <key> <field> 查询key指定的TairHash中是否存在对应的field。该命令会触发对field的被动淘汰。
EXHSTRLEN EXHSTRLEN <key> <field> 获取key指定的TairHash中一个field对应的value的长度。该命令会触发对field的被动淘汰。
EXHKEYS EXHKEYS <key> 获取key指定的TairHash中所有的field。该命令会过滤掉已经过期的field，但是为了尽快响应客户端，不会执行真正的删除操作。
EXHVALS EXHVALS <key> 获取key指定的TairHash中所有field的值 。该命令会过滤掉已经过期的field，但是为了尽快响应客户端，不会执行真正的删除操作。
EXHGETALL EXHGETALL <key> 获取key指定的TairHash中所有的field及其value。该命令会过滤掉已经过期的field，但是为了尽快响应客户端，不会执行真正的删除操作。
EXHSCAN EXHSCAN <key> <op> <subkey> [MATCH pattern] [COUNT count] 扫描key指定的TairHash。扫描的方式（使用op选项设置）可以为>、>=、<、<=、==、^、$。扫描的同时可以根据MATCH指定的pattern对subkey进行正则过滤，还可以使用COUNT对结果数目进行限制，如果不指定则默认值为10。该命令会过滤掉已经过期的field，但是为了尽快响应客户端，不会执行真正的删除操作。

EXHSET

  • 语法

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

  • 时间复杂度

    O(1)

  • 命令描述

    向key指定的TairHash中插入一个field。如果TairHash不存在则自动创建一个，如果field已经存在则覆盖其值。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
    value field对应的值，一个field只能有一个value。
    EX 指定field的相对过期时间，单位为秒，为0表示不过期。
    EXAT 指定field的绝对过期时间，单位为秒，为0表示不过期。
    PX 指定field的相对过期时间，单位为毫秒，为0表示不过期。
    PXAT 指定field的绝对过期时间，单位为毫秒 ，为0表示不过期。
    NX 只在field不存在时插入。
    XX 只在field存在时插入。
    VER 版本号。
    • 如果field存在，和当前版本号做比较：
      • 如果相等，插入，且版本号加1。
      • 如果不相等，不插入，返回异常。
    • 如果field不存在或者field当前版本为0，忽略传入的版本号直接插入field，成功后版本号变为1。
    ABS 绝对版本号，不论field是否存在，插入field并将field的版本号该选项中设置的值。
  • 返回值
    • 新建field并成功为它设置值：1。
    • field已经存在，成功覆盖旧值：0。
    • 指定了XX且field不存在：-1。
    • 指定了NX且field已经存在：-1。
    • 指定了VER且版本和当前版本不匹配："ERR update version is stale"。
    • 其它情况返回相应的异常信息。

EXHGET

  • 语法

    EXHGET <key> <field>

  • 时间复杂度

    O(1)

  • 命令描述

    获取指定TairHash一个field的值。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • field存在且操作成功：field对应的值。
    • key不存在或者field不存在：nil。
    • 其它情况返回相应的异常信息。

EXHMSET

  • 语法

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

  • 时间复杂度

    O(1)

  • 命令描述

    同时向key指定的TairHash中插入多个field，如果TairHash不存在则自动创建一个，如果field已经存在则覆盖其value。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
    value field对应的值，一个field只能有一个value。
  • 返回值
    • 成功：OK。
    • 其它情况返回相应的异常信息。

EXHPEXPIREAT

  • 语法

    EXHPEXPIREAT <key> <field> <milliseconds-timestamp>

  • 时间复杂度

    O(1)

  • 命令描述

    在key指定的TairHash中为一个field设置绝对过期时间，精确到毫秒。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
    milliseconds-timestamp 精确到毫秒的时间戳。
  • 返回值
    • field存在且设置成功：1。
    • field不存在：0。
    • 其它情况返回相应的异常信息。

EXHPEXPIRE

  • 语法

    EXHPEXPIRE <key> <field> <milliseconds>

  • 时间复杂度

    O(1)

  • 命令描述

    在key指定的TairHash中为一个field设置相对过期时间，单位为毫秒。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
    milliseconds 相对过期时间，单位为毫秒。
  • 返回值
    • field存在且设置成功：1。
    • field不存在：0。
    • 其它情况返回相应的异常信息。

EXHEXPIREAT

  • 语法

    EXHEXPIREAT <key> <field> <timestamp>

  • 时间复杂度

    O(1)

  • 命令描述

    在key指定的TairHash中为一个field设置绝对过期时间，精确到秒。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
    timestamp 精确到秒的时间戳。
  • 返回值
    • field存在且设置成功：1。
    • field不存在：0。
    • 其它情况返回相应的异常信息。

EXHEXPIRE

  • 语法

    EXHEXPIRE <key> <field> <seconds>

  • 时间复杂度

    O(1)

  • 命令描述

    在key指定的TairHash中为一个field设置相对过期时间，单位为秒。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
    seconds 相对过期时间，单位为秒。
  • 返回值
    • field存在且设置成功：1。
    • field不存在：0。
    • 其它情况返回相应的异常信息。

EXHPTTL

  • 语法

    EXHPTTL <key> <field>

  • 时间复杂度

    O(1)

  • 命令描述

    查看key指定的TairHash中一个field的过期时间，结果精确到毫秒。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • key或者field不存在：-2。
    • field存在但是没有设置过期时间：-1。
    • field存在且设置了过期时间：过期时间，单位为毫秒。
    • 其它情况返回相应的异常信息。

EXHTTL

  • 语法

    EXHPTTL <key> <field>

  • 时间复杂度

    O(1)

  • 命令描述

    查看key指定的TairHash中一个field的过期时间，结果精确到秒。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • key或者field不存在：-2。
    • field存在但是没有设置过期时间：-1。
    • field存在且设置了过期时间：过期时间，单位为秒。
    • 其它情况返回相应的异常信息。

EXHVER

  • 语法

    EXHVER <key> <field>

  • 时间复杂度

    O(1)

  • 命令描述

    查看key指定的TairHash中一个field的版本号。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • key不存在：-1。
    • field不存：-2。
    • 查询成功：field的版本号。
    • 其它情况返回相应的异常信息。

EXHSETVER

  • 语法

    EXHSETVER <key> <field> <version>

  • 时间复杂度

    O(1)

  • 命令描述

    设置key指定的TairHash中一个field的版本号。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • TairHash或者field不存在：0。
    • 设置成功：1。
    • 其它情况返回相应的异常信息。

EXHINCRBY

  • 语法

    EXHINCRBY <key> <field> <num> [EX time] [EXAT time] [PX time] [PXAT time]

  • 时间复杂度

    O(1)

  • 命令描述

    将key指定的TairHash中一个field的value增加num，num为一个整数。如果TairHash不存在则自动新创建一个，如果指定的field不存在，则在加之前插入该field并将其值设置为0。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
    num 需要为field的value增加的整数值。
    EX 指定field的相对过期时间，单位为秒，为0表示不过期。
    EXAT 指定field的绝对过期时间，单位为秒，为0表示不过期。
    PX 指定field的相对过期时间，单位为毫秒，为0表示不过期。
    PXAT 指定field的绝对过期时间，单位为毫秒 ，为0表示不过期。
  • 返回值
    • 成功：与num相加后value的值。
    • 其它情况返回异常。

EXHINCRBYFLOAT

  • 语法

    EXHINCRBYFLOAT <key> <field> <num> [EX time] [EXAT time] [PX time] [PXAT time]

  • 时间复杂度

    O(1)

  • 命令描述

    将key指定的TairHash中一个field的value增加num，num为一个浮点数。如果TairHash不存在则自动新创建一个，如果指定的field不存在，则在加之前插入该field并将其值设置为0。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
    num 需要为field的value增加的值，类型为浮点。
    EX 指定field的相对过期时间，单位为秒，为0表示不过期。
    EXAT 指定field的绝对过期时间，单位为秒，为0表示不过期。
    PX 指定field的相对过期时间，单位为毫秒，为0表示不过期。
    PXAT 指定field的绝对过期时间，单位为毫秒 ，为0表示不过期。
  • 返回值
    • 成功：与num相加后value的值。
    • 其它情况返回异常。

EXHGETWITHVER

  • 语法

    EXHGETWITHVER <key> <field>

  • 时间复杂度

    O(1)

  • 命令描述

    同时获取key指定的TairHash一个field的值和版本。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • field存在且操作成功：field对应的值和版本。
    • key不存在或者field不存在：nil。
    • 其它情况返回相应的异常信息。

EXHMGET

  • 语法

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

  • 时间复杂度

    O(1)

  • 命令描述

    同时获取key指定的TairHash多个field的值。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • key不存在：nil。
    • key存在且查询的所有field都存在：返回一个数组，数组的每一个元素对应一个field的value。
    • key存在且查询的field中有不存在的：返回一个数组，数组的每一个元素对应一个field的value，不存在的field对应的元素显示为nil。
    • 其它情况返回相应的异常信息。

EXHMGETWITHVER

  • 语法

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

  • 时间复杂度

    O(1)

  • 命令描述

    同时获取key指定的TairHash多个field的值和版本。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • key不存在：nil。
    • key存在且查询的所有field都存在：返回一个数组，数组的每一个元素对应一个field的value和version。
    • key存在且查询的field中有不存在的：返回一个数组，数组的每一个元素对应一个field的value和version，不存在的field对应的元素显示为nil。
    • 其它情况返回相应的异常信息。

EXHDEL

  • 语法

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

  • 时间复杂度

    O(1)

  • 命令描述

    删除key指定的TairHash一个field。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • key不存在或者field不存在：0。
    • 删除成功：1。
    • 其它情况返回相应的异常信息。

EXHLEN

  • 语法

    EXHLEN <key>

  • 时间复杂度

    O(1)

  • 命令描述

    获取key指定的TairHash中field的个数，结果中可能存在已经过期但还未被删除的field。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
  • 返回值
    • key不存在或者field不存在：0。
    • 成功：field个数。
    • 其它情况返回相应的异常信息。

EXHEXISTS

  • 语法

    EXHEXISTS <key> <field>

  • 时间复杂度

    O(1)

  • 命令描述

    查询key指定的TairHash中是否存在对应的field。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • key不存在或者field不存在：0。
    • field存在：1。
    • 其它情况返回相应的异常信息。

EXHSTRLEN

  • 语法

    EXHSTRLEN <key> <field>

  • 时间复杂度

    O(1)

  • 命令描述

    获取key指定的TairHash中一个field的value的长度。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    field TairHash中的一个元素，一个TairHash key可以有多个field。
  • 返回值
    • key不存在或者field不存在：0。
    • 查询成功：value的长度。
    • 其它情况返回相应的异常信息。

EXHKEYS

  • 语法

    EXHKEYS <key>

  • 时间复杂度

    O(1)

  • 命令描述

    获取key指定的TairHash中所有field。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
  • 返回值
    • key不存在：返回一个空数组。
    • key存在：返回一个数组，数组的每一位对应TairHash中的每一个field。
    • 其它情况返回相应的异常信息。

EXHVALS

  • 语法

    EXHVALS <key>

  • 时间复杂度

    O(1)

  • 命令描述

    获取key指定的TairHash中所有field的value。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
  • 返回值
    • key不存在：返回一个空数组。
    • key存在：返回一个数组，数组的每个元素对应TairHash中的一个field的value。
    • 其它情况返回相应的异常信息。

EXHGETALL

  • 语法

    EXHGETALL <key>

  • 时间复杂度

    O(1)

  • 命令描述

    获取key指定的TairHash中所有field和value。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
  • 返回值
    • key不存在：返回一个空数组。
    • key存在：返回一个数组，数组的每个元素对应TairHash中的一对field和value。
    • 其它情况返回相应的异常信息。

EXHSCAN

  • 语法

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

  • 时间复杂度

    O(1)、O(N)

  • 命令描述

    扫描key指定的TairHash。

  • 参数及选项说明
    参数/选项 说明
    key TairHash的key，用于指定作为命令调用对象的TairHash。
    op 用于定位扫描的起点，可选值：
    • >，表示从第一个大于subkey的field开始。
    • >=，表示从第一个大于等于subkey的field开始。
    • <，表示从第一个小于subkey的field开始。
    • <=，表示从第一个小于等于subkey的field开始。
    • ==，表示从第一个等于subkey的field开始。
    • ^，表示从第一个field开始。
    • $，表示从最后一个field开始。
    subkey 用于与op选项搭配，设置扫描起始位置，当op为^或$时该值将被忽略。
    MATCH 用于过滤扫描结果。
  • 返回值
    • key不存在：返回一个空数组。
    • key存在：返回一个数组，数组的每个元素对应TairHash中的一对field和value。
    • 其它情况返回相应的异常信息。