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数据类型类似。

使用前提

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

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

TairHash内存消耗与淘汰策略

TairHash支持高效的主动淘汰策略，但也会在一定程度上增加内存消耗，详细说明和使用建议请参见TairHash内存消耗与淘汰策略最佳实践。

命令列表

EXHSET

• 语法

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

• 时间复杂度

  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，忽略传入的版本号并继续操作，成功后版本号变为1。
  ABS	绝对版本号，不论field是否存在，可以在插入field时设置为本参数所指定的版本号。
  NOACTIVE	在指定EX、EXAT、PX或PXAT选项时，设置NOACTIVE表示该field不使用active expiration策略，这样可以降低内存占用。

• 返回值
  • 新建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(N)

• 命令描述

  同时向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> [VER/ABS version] [NOACTIVE]

• 时间复杂度

  O(1)

• 命令描述

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

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。
  field	TairHash中的一个元素，一个TairHash key可以有多个field。
  milliseconds-timestamp	精确到毫秒的时间戳。
  VER	版本号。 如果field存在，和当前版本号做比较： 如果相等，继续操作，且版本号加1。 如果不相等，返回异常。 如果field不存在或者field当前版本为0，忽略传入的版本号并继续操作，成功后版本号变为1。
  ABS	绝对版本号，不论field是否存在，继续操作并将field的版本号设置为本参数所指定的值。
  NOACTIVE	在指定EX、EXAT、PX或PXAT选项时，设置NOACTIVE表示该field不使用active expiration策略，这样可以降低内存占用。

• 返回值
  • field存在且设置成功：1。
  • field不存在：0。
  • 其它情况返回相应的异常信息。

EXHPEXPIRE

• 语法

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

• 时间复杂度

  O(1)

• 命令描述

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

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。
  field	TairHash中的一个元素，一个TairHash key可以有多个field。
  milliseconds	相对过期时间，单位为毫秒。
  VER	版本号。 如果field存在，和当前版本号做比较： 如果相等，继续操作，且版本号加1。 如果不相等，返回异常。 如果field不存在或者field当前版本为0，忽略传入的版本号并继续操作，成功后版本号变为1。
  ABS	绝对版本号，不论field是否存在，继续操作并将field的版本号设置为本参数所指定的值。
  NOACTIVE	在指定EX、EXAT、PX或PXAT选项时，设置NOACTIVE表示该field不使用active expiration策略，这样可以降低内存占用。

• 返回值
  • field存在且设置成功：1。
  • field不存在：0。
  • 其它情况返回相应的异常信息。

EXHEXPIREAT

• 语法

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

• 时间复杂度

  O(1)

• 命令描述

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

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。
  field	TairHash中的一个元素，一个TairHash key可以有多个field。
  timestamp	精确到秒的时间戳。
  VER	版本号。 如果field存在，和当前版本号做比较： 如果相等，继续操作，且版本号加1。 如果不相等，返回异常。 如果field不存在或者field当前版本为0，忽略传入的版本号并继续操作，成功后版本号变为1。
  ABS	绝对版本号，不论field是否存在，继续操作并将field的版本号设置为本参数所指定的值。
  NOACTIVE	在指定EX、EXAT、PX或PXAT选项时，设置NOACTIVE表示该field不使用active expiration策略，这样可以降低内存占用。

• 返回值
  • field存在且设置成功：1。
  • field不存在：0。
  • 其它情况返回相应的异常信息。

EXHEXPIRE

• 语法

  EXHEXPIRE <key> <field> <seconds>

• 时间复杂度

  O(1)

• 命令描述

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

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。
  field	TairHash中的一个元素，一个TairHash key可以有多个field。
  seconds	相对过期时间，单位为秒。
  VER	版本号。 如果field存在，和当前版本号做比较： 如果相等，继续操作，且版本号加1。 如果不相等，返回异常。 如果field不存在或者field当前版本为0，忽略传入的版本号并继续操作，成功后版本号变为1。
  ABS	绝对版本号，不论field是否存在，继续操作并将field的版本号设置为本参数所指定的值。
  NOACTIVE	在指定EX、EXAT、PX或PXAT选项时，设置NOACTIVE表示该field不使用active expiration策略，这样可以降低内存占用。

• 返回值
  • 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

• 语法

  EXHTTL <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] [VER/ABS version] [MIN minval] [MAX maxval]

• 时间复杂度

  O(1)

• 命令描述

  将key指定的TairHash中一个field的value增加num，num为一个整数。如果TairHash不存在则自动新创建一个，如果指定的field不存在，则在加之前插入该field并将其值设置为0。该命令会触发对field的被动淘汰检查。

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。
  field	TairHash中的一个元素，一个TairHash key可以有多个field。
  num	需要为field的value增加的整数值。
  EX	指定field的相对过期时间，单位为秒，为0表示不过期。
  EXAT	指定field的绝对过期时间，单位为秒，为0表示不过期。
  PX	指定field的相对过期时间，单位为毫秒，为0表示不过期。
  PXAT	指定field的绝对过期时间，单位为毫秒 ，为0表示不过期。
  VER	版本号。 如果field存在，和当前版本号做比较： 如果相等，完成递增，且版本号加1。 如果不相等，返回异常。 如果VER选项所携带的版本号为0，则不进行版本校验。
  ABS	绝对版本号，不论field是否存在，完成递增并将field的版本号设置为本参数所指定的值，该值不能为0。
  MIN	value的最小值，小于该值则提示异常。
  MAX	value的最大值，大于该值则提示异常。
  NOACTIVE	在设置了EX、EXAT、PX或PXAT选项的同时，如果设置了NOACTIVE，则该field不使用active expiration策略，内存占用较小。

  说明 为Key的field设置了超时时间后，再次执行该命令时如果没有设置超时时间，该field将被设置为永不过期。
• 返回值
  • 成功：与num相加后value的值。
  • 其它情况返回异常。

EXHINCRBYFLOAT

• 语法

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

• 时间复杂度

  O(1)

• 命令描述

  将key指定的TairHash中一个field的value增加num，num为一个浮点数。如果TairHash不存在则自动新创建一个，如果指定的field不存在，则在加之前插入该field并将其值设置为0。该命令会触发对field的被动淘汰检查。

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。
  field	TairHash中的一个元素，一个TairHash key可以有多个field。
  num	需要为field的value增加的值，类型为浮点。
  EX	指定field的相对过期时间，单位为秒，为0表示不过期。
  EXAT	指定field的绝对过期时间，单位为秒，为0表示不过期。
  PX	指定field的相对过期时间，单位为毫秒，为0表示不过期。
  PXAT	指定field的绝对过期时间，单位为毫秒 ，为0表示不过期。
  VER	版本号。 如果field存在，和当前版本号做比较： 如果相等，完成递增，且版本号加1。 如果不相等，返回异常。 如果VER选项所携带的版本号为0，则不进行版本校验。
  ABS	绝对版本号，不论field是否存在，完成递增并将field的版本号设置为本参数所指定的值，该值不能为0。
  MIN	value的最小值，小于该值则提示异常。
  MAX	value的最大值，大于该值则提示异常。
  NOACTIVE	在设置了EX、EXAT、PX或PXAT选项的同时，如果设置了NOACTIVE，则该field不使用active expiration策略，内存占用较小。

  说明 为Key的field设置了超时时间后，再次执行该命令时如果没有设置超时时间，该field将被设置为永不过期。
• 返回值
  • 成功：与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(N)

• 命令描述

  同时获取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> [noexp]

• 时间复杂度

  O(1)

• 命令描述

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

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。
  noexp	EXHLEN默认不会触发对过期field的被动淘汰，也不会将其过滤掉，所以结果中可能包含已经过期但还未被删除的field。如果只想返回当前没有过期的field个数，可以在命令中设置noexp选项。在设置noexp时： 因为要遍历整条TairHash数据，EXHLEN命令的响应时间将受到Tairhash大小的影响。 EXHLEN命令的返回结果中会过滤掉过期的field，但过期field不会被淘汰。

• 返回值
  • 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(N)

• 命令描述

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

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。

• 返回值
  • key不存在：返回一个空数组。
  • key存在：返回一个数组，数组的每一位对应TairHash中的每一个field。
  • 其它情况返回相应的异常信息。

EXHVALS

• 语法

  EXHVALS <key>

• 时间复杂度

  O(N)

• 命令描述

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

• 参数及选项说明

  参数或选项	说明
  key	TairHash的key，用于指定作为命令调用对象的TairHash。

• 返回值
  • key不存在：返回一个空数组。
  • key存在：返回一个数组，数组的每个元素对应TairHash中的一个field的value。
  • 其它情况返回相应的异常信息。

EXHGETALL

• 语法

  EXHGETALL <key>

• 时间复杂度

  O(N)

• 命令描述

  获取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。
  • 其它情况返回相应的异常信息。