Sudis

# String命令

# APPEND

# 语法

APPEND key value

# 描述

将字符串 value 追加到 key 对应值的末尾。如果 key 不存在，会先创建一个空字符串再执行追加，因此此时效果等同于 SET。返回追加后字符串的长度。

# 参数

  • key

键名。

  • value

要追加的字符串。

# 示例

> EXISTS mykey
(integer) 0
> APPEND mykey "Hello"
(integer) 5
> APPEND mykey " World"
(integer) 11
> GET mykey
"Hello World"

# DECR

# 语法

DECR key

# 描述

将 key 中存储的整数值减 1。如果 key 不存在，会先将其值初始化为 0 再执行递减。若 key 的值类型不正确或无法表示为整数，则返回错误。该操作限制在 64 位有符号整数范围内。

# 参数

  • key

键名。

# 示例

> SET mykey "10"
OK
> DECR mykey
(integer) 9

> DECR nonexisting
(integer) -1

> SET mykey "234293482390480948029348230948"
OK
> DECR mykey
(error) ERR value is not an integer or out of range

# DECRBY

# 语法

DECRBY key decrement

# 描述

将 key 中存储的整数值减去指定的 decrement。如果 key 不存在，会先将其值初始化为 0 再执行操作。若 key 的值类型不正确或无法表示为整数，则返回错误。该操作限制在 64 位有符号整数范围内。

# 参数

  • key

键名。

  • decrement

要减去的整数值。

# 示例

> SET mykey "10"
OK
> DECRBY mykey 3
(integer) 7

> DECRBY counter 5
(integer) -5

# GET

# 语法

GET key

# 描述

获取 key 对应的字符串值。如果 key 不存在，返回 nil。如果 key 存储的值不是字符串类型，将返回错误，因为 GET 仅能处理字符串值。

# 参数

  • key

键名。

# 示例

> SET mykey "Hello, Redis!"
OK
> GET mykey
"Hello, Redis!"

> GET nonexisting
(nil)

> LPUSH mylist "item"
(integer) 1
> GET mylist
(error) ERR Operation against a key holding the wrong kind of value

# GETDEL

# 语法

GETDEL key

# 描述

获取 key 的字符串值，并在成功获取后删除该 key。此命令与 GET 类似，区别在于它会在成功返回字符串值后将 key 删除。如果 key 不存在，返回 nil；如果 key 存储的值不是字符串类型，返回 nil 且不会删除该 key。

# 参数

  • key

要获取并删除的键名。

# 示例

> SET mykey "Hello"
OK
> GETDEL mykey
"Hello"
> GET mykey
(nil)

# GETEX

# 语法

GETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST]

# 描述

获取 key 的字符串值，并可选择性地为其设置过期时间。GETEX 与 GET 类似，但属于写命令并支持额外的过期选项。以下可选参数互斥，不能同时使用。

# 参数

  • key

要获取的键名。

可选参数 描述
EX seconds 设置过期时间，单位为秒。
PX milliseconds 设置过期时间，单位为毫秒。
EXAT unix-time-seconds 设置 key 过期的 Unix 时间戳，单位为秒。
PXAT unix-time-milliseconds 设置 key 过期的 Unix 时间戳，单位为毫秒。
PERSIST 移除 key 的过期时间，使其持久保存。

# 示例

> SET mykey "Hello"
OK
> GETEX mykey
"Hello"
> TTL mykey
(integer) -1

> GETEX mykey EX 60
"Hello"
> TTL mykey
(integer) 60

# GETRANGE

# 语法

GETRANGE key start end

# 描述

返回 key 所存储字符串中从 start 到 end 偏移量之间的子串（两端均包含在内）。可以使用负偏移量从字符串末尾开始计数，例如 -1 表示最后一个字符，-2 表示倒数第二个字符，依此类推。对于超出字符串实际长度范围的请求，Redis 会自动将其限制为字符串的实际长度。

# 参数

  • key

键名。

  • start

起始偏移量，从 0 开始。负值表示从字符串末尾倒数。

  • end

结束偏移量，从 0 开始且包含在内。负值表示从字符串末尾倒数。

# 示例

> SET mykey "This is a string"
OK
> GETRANGE mykey 0 3
"This"
> GETRANGE mykey -3 -1
"ing"
> GETRANGE mykey 0 -1
"This is a string"
> GETRANGE mykey 10 100
"string"

# GETSET

# 语法

GETSET key value

# 描述

原子性地将 key 设置为 value，并返回 key 原来的字符串值。如果 key 存在但其值不是字符串类型，则返回错误。成功执行后，key 原有的过期时间（TTL）会被清除。自 Redis 6.2.0 起，GETSET 已被弃用，推荐使用带有 GET 选项的 SET 命令替代。

# 参数

  • key

键名。

  • value

要设置的新字符串值。

# 示例

> SET mykey "Hello"
OK
> GETSET mykey "World"
"Hello"
> GET mykey
"World"

> GETSET newkey "first"
(nil)
> GET newkey
"first"

# INCR

# 语法

INCR key

# 描述

将 key 中存储的数字值增加 1。如果 key 不存在，则先将其设置为 0，再执行自增操作。如果 key 的值类型错误，或其中存储的字符串无法表示为整数，则返回错误。该操作仅限于 64 位有符号整数。

# 参数

  • key

键名。

# 示例

> SET mykey "10"
OK
> INCR mykey
(integer) 11
> GET mykey
"11"

> INCR nokey
(integer) 1

# INCRBY

# 语法

INCRBY key increment

# 描述

将 key 中存储的数字值增加指定的 increment。如果 key 不存在，则先将其设置为 0，再执行自增操作。如果 key 的值类型错误，或其中存储的字符串无法表示为整数，则返回错误。该操作仅限于 64 位有符号整数。

# 参数

  • key

键名。

  • increment

要增加的整数值。可以使用负数以实现递减。

# 示例

> SET mykey "10"
OK
> INCRBY mykey 5
(integer) 15
> INCRBY mykey -3
(integer) 12
> GET mykey
"12"

# INCRBYFLOAT

# 语法

INCRBYFLOAT key increment

# 描述

将 key 中存储的浮点数字符串值增加指定的 increment。如果 increment 为负值，则相当于递减。如果 key 不存在，则先将其设置为 0，再执行自增操作。如果 key 的值类型错误，或当前值 / 增量无法解析为双精度浮点数，则返回错误。

命令成功执行后，新的计算结果会替换 key 的旧值，并以字符串形式返回给调用方。键值和增量均可使用指数表示法；计算结果统一存储为“整数部分 + 小数点 + 小数部分”的格式，并去除末尾的 0。输出精度固定为小数点后 17 位。

# 参数

  • key

键名。

  • increment

要增加的浮点数值。可以使用负数以实现递减。

# 示例

> SET mykey 10.50
OK
> INCRBYFLOAT mykey 0.1
"10.6"
> INCRBYFLOAT mykey -5
"5.6"
> GET mykey
"5.6"

> SET mykey 5.0e3
OK
> INCRBYFLOAT mykey 2.0e2
"5200"
> GET mykey
"5200"

# INCREX

# 语法

INCREX key [BYFLOAT increment | BYINT increment]
 [LBOUND lowerbound] [UBOUND upperbound] [SATURATE]
 [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] [ENX]

# 描述

在单次原子操作中将 key 中存储的数值按指定量增加或减少，并支持可选的上下界与过期控制。如果 key 不存在，则先将其设置为 0，再执行操作。如果 key 的值类型错误，或其中存储的字符串无法解析为数字，则返回错误。

与 INCR 和 INCRBY 不同，INCREX 返回一个包含两个元素的数组：自增后的新值，以及实际应用的增量。当计算结果超出显式指定的 LBOUND/UBOUND 或类型限制时，默认会跳过操作并回复 [current_value, 0]，保持 key 及其 TTL 不变。指定 SATURATE 标志后，结果会饱和到对应边界值。

# 参数

  • key

键名。

可选参数 描述
BYFLOAT increment 以长双精度浮点数方式增加指定数值。
BYINT increment 以 64 位有符号整数方式增加指定数值；负值表示递减。
LBOUND lowerbound 设置结果的下界。
UBOUND upperbound 设置结果的上界。
SATURATE 当结果越界时，将其饱和到 LBOUND 或 UBOUND（或类型限制）。
EX seconds 设置过期时间，单位为秒。
PX milliseconds 设置过期时间，单位为毫秒。
EXAT unix-time-seconds 设置 key 过期的指定 Unix 时间戳，单位为秒。
PXAT unix-time-milliseconds 设置 key 过期的指定 Unix 时间戳，单位为毫秒。
PERSIST 移除 key 的过期时间。
ENX 仅在 key 当前没有 TTL 时设置过期时间；必须与 EX/PX/EXAT/PXAT 一起使用，不能与 PERSIST 同时使用。

# 示例

> DEL mykey1
(integer) 0
> INCREX mykey1
1) (integer) 1
2) (integer) 1
> INCREX mykey1
1) (integer) 2
2) (integer) 1

> SET mykey2 100
OK
> INCREX mykey2 BYINT 5
1) (integer) 105
2) (integer) 5
> INCREX mykey2 BYINT -10
1) (integer) 95
2) (integer) -10

> SET mykey3 1.5
OK
> INCREX mykey3 BYFLOAT 0.25
1) "1.75"
2) "0.25"

> DEL mykey4
(integer) 0
> INCREX mykey4 BYINT 1 EX 100
1) (integer) 1
2) (integer) 1
> TTL mykey4
(integer) 100

> SET mykey5 10
OK
> INCREX mykey5 BYINT 1 EX 100 ENX
1) (integer) 11
2) (integer) 1
> TTL mykey5
(integer) 100
> SET mykey5 10 EX 500
OK
> INCREX mykey5 BYINT 1 EX 10 ENX
1) (integer) 11
2) (integer) 1
> TTL mykey5
(integer) 500

> SET mykey6 5 EX 1000
OK
> TTL mykey6
(integer) 1000
> INCREX mykey6 BYINT 1 PERSIST
1) (integer) 6
2) (integer) 1
> TTL mykey6
(integer) -1

> SET mykey7 99
OK
> INCREX mykey7 BYINT 5 UBOUND 100
1) (integer) 99
2) (integer) 0
> SET mykey7 99
OK
> INCREX mykey7 BYINT 5 UBOUND 100 SATURATE
1) (integer) 100
2) (integer) 1

# LCS

# 语法

LCS key1 key2 [LEN] [IDX] [MINMATCHLEN min-match-len] [WITHMATCHLEN]

# 描述

LCS 实现最长公共子序列（Longest Common Subsequence）算法。注意它与最长公共子串不同：匹配字符不需要在字符串中连续。该命令常用于评估两个字符串的相似度，例如 DNA 序列比较或文本差异分析。

算法时间复杂度为 O(N*M)，其中 N 和 M 分别为两个字符串的长度。因此建议在较短的字符串上使用，或在独立的 Redis 实例上运行该命令。

# 参数

  • key1

第一个键名。

  • key2

第二个键名。

可选参数 描述
LEN 返回最长公共子序列的长度，而不是子序列本身。
IDX 返回匹配位置，而不是匹配的字符串。
MINMATCHLEN min-match-len 与 IDX 一起使用，仅返回长度至少为 min-match-len 的匹配。
WITHMATCHLEN 与 IDX 一起使用，在结果中包含每个匹配的长度。

# 示例

> MSET key1 ohmytext key2 mynewtext
OK
> LCS key1 key2
"mytext"

> LCS key1 key2 LEN
(integer) 6

> LCS key1 key2 IDX
1) "matches"
2) 1) 1) 1) (integer) 4
         2) (integer) 7
      2) 1) (integer) 5
         2) (integer) 8
   2) 1) 1) (integer) 2
         2) (integer) 3
      2) 1) (integer) 0
         2) (integer) 1
3) "len"
4) (integer) 6

> LCS key1 key2 IDX MINMATCHLEN 4
1) "matches"
2) 1) 1) 1) (integer) 4
         2) (integer) 7
      2) 1) (integer) 5
         2) (integer) 8
3) "len"
4) (integer) 6

> LCS key1 key2 IDX MINMATCHLEN 4 WITHMATCHLEN
1) "matches"
2) 1) 1) 1) (integer) 4
         2) (integer) 7
      2) 1) (integer) 5
         2) (integer) 8
      3) (integer) 4
3) "len"
4) (integer) 6

# MGET

# 语法

MGET key [key ...]

# 描述

原子性地返回一个或多个 key 对应的字符串值。对于每个不存在的 key 或值不是字符串类型的 key，返回 nil。因此该命令不会失败。

# 参数

  • key

要获取值的一个或多个键名。可以指定多个 key，以空格分隔。

# 示例

> SET key1 "Hello"
OK
> SET key2 "World"
OK
> MGET key1 key2 nonexisting
1) "Hello"
2) "World"
3) (nil)

# MSET

# 语法

MSET key value [key value ...]

# 描述

原子性地为一个或多个 key 设置对应的字符串值。MSET 会覆盖已存在的值，行为与普通 SET 相同。该命令是原子的，所有给定的 key 会同时被设置，客户端不会看到部分 key 已更新而另一部分未更新的中间状态。

# 参数

  • key

键名。

  • value

要设置的字符串值。

可选参数 描述
key value ... 可以继续添加多组 key-value 对，同时设置多个键值。

# 示例

> MSET key1 "Hello" key2 "World"
OK
> GET key1
"Hello"
> GET key2
"World"

# MSETNX

# 语法

MSETNX key value [key value ...]

# 描述

原子性地为一个或多个 key 设置字符串值，但仅当所有指定的 key 都不存在时才会执行。即使只有一个 key 已经存在，MSETNX 也不会设置任何 key。由于这一语义，MSETNX 适合用来表示同一逻辑对象的不同字段，确保这些字段要么全部被设置，要么全部不被设置。

# 参数

  • key

键名。

  • value

要设置的字符串值。

可选参数 描述
key value ... 可以继续添加多组 key-value 对，同时设置多个键值。

# 示例

> MSETNX key1 "Hello" key2 "there"
1
> MSETNX key2 "new" key3 "world"
0
> MGET key1 key2 key3
1) "Hello"
2) "there"
3) (nil)

# PSETEX

# 语法

PSETEX key milliseconds value

# 描述

设置 key 的字符串值，并同时设置其过期时间（以毫秒为单位）。如果 key 不存在则会创建新 key。PSETEX 与 SETEX 功能相同，区别仅在于过期时间使用毫秒而非秒。

# 参数

  • key

键名。

  • milliseconds

生存时间，单位为毫秒（正整数）。

  • value

要设置的字符串值。

# 示例

> PSETEX mykey 1000 "Hello"
OK
> PTTL mykey
(integer) 1000
> GET mykey
"Hello"

# SET

# 语法

SET key value \[NX | XX | IFEQ ifeq-value | IFNE ifne-value | IFDEQ ifdeq-digest | IFDNE ifdne-digest] \[GET] \[EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL]

# 描述

将 key 设置为指定的字符串 value。如果 key 已经存在，无论其类型如何，旧值都会被覆盖。成功执行 SET 后，与该 key 关联的任何先前过期时间都会被丢弃。

NX/XX/IFEQ/IFNE/IFDEQ/IFDNE 等条件选项互斥，EX/PX/EXAT/PXAT/KEEPTTL 等过期选项也互斥。

# 参数

  • key

    键名。

  • value

    要设置的字符串值。

可选参数 描述
NX 仅在 key 不存在 时执行设置。
XX 仅在 key 存在 时执行设置。
IFEQ ifeq-value 仅当当前值等于 ifeq-value 时才设置值和过期时间；若 key 不存在则不创建。
IFNE ifne-value 仅当当前值不等于 ifne-value 时才设置值和过期时间；若 key 不存在则创建。
IFDEQ ifdeq-digest 仅当当前值的哈希摘要等于 ifdeq-digest 时才设置；若 key 不存在则不创建。
IFDNE ifdne-digest 仅当当前值的哈希摘要不等于 ifdne-digest 时才设置；若 key 不存在则创建。
GET 返回 key 的旧字符串值；若 key 不存在则返回 nil。若 key 的值不是字符串类型，则返回错误并中止 SET。
EX seconds 设置过期时间，单位为秒（正整数）。
PX milliseconds 设置过期时间，单位为毫秒（正整数）。
EXAT unix-time-seconds 设置 key 过期的指定 Unix 时间戳，单位为秒。
PXAT unix-time-milliseconds 设置 key 过期的指定 Unix 时间戳，单位为毫秒。
KEEPTTL 保留 key 原有的生存时间。

注意：由于 SET 命令已包含 SETNX、SETEX、PSETEX、GETSET 的功能，这些旧命令在未来可能会被弃用。

# 示例

> SET mykey "Hello"
OK
> GET mykey
"Hello"

> SET anotherkey "will expire in a minute" EX 60
OK

> SET mykey "World" GET EX 60
"Hello"
> GET mykey
"World"

> SET newkey "This will succeed" NX
OK
> SET newkey "This will fail" NX
(nil)

# SETEX

# 语法

SETEX key seconds value

# 描述

将 key 设置为字符串 value，并设置 key 在 seconds 秒后过期。

该命令等价于执行：

SET key value EX seconds

当 seconds 无效时返回错误。

# 参数

  • key

    键名。

  • seconds

    生存时间，单位为秒。

  • value

    要设置的字符串值。

# 示例

> SETEX mykey 10 "Hello"
OK
> TTL mykey
(integer) 10
> GET mykey
"Hello"

# SETNX

# 语法

SETNX key value

# 描述

仅在 key 不存在时，才将其设置为字符串 value。

若 key 已经存在，则不执行任何操作。SETNX 是“SET if Not eXists”（不存在则设置）的缩写。该命令等价于 SET key value NX。

# 参数

  • key

    键名。

  • value

    仅在 key 不存在时要设置的字符串值。

# 示例

> SETNX mykey "Hello"
(integer) 1
> SETNX mykey "World"
(integer) 0
> GET mykey
"Hello"

# SETRANGE

# 语法

SETRANGE key offset value

# 描述

覆盖 key 中存储的字符串的一部分，从指定的 offset 开始，覆盖 value 的整个长度。

如果 offset 大于当前字符串长度，则用零字节填充字符串以使其达到 offset。不存在的 key 会被视为空字符串处理，因此该命令会确保 key 保存一个足够长的字符串，以便在 offset 处设置 value。

可设置的最大偏移为 2^29 - 1（536870911），因为 Redis 字符串最大限制为 512 MB。

# 参数

  • key

    键名。

  • offset

    开始覆盖的零基偏移量。若偏移量超过当前字符串长度，则用零字节填充。

  • value

    要写入偏移位置的字符串。

# 示例

> SET key1 "Hello World"
OK
> SETRANGE key1 6 "Redis"
(integer) 11
> GET key1
"Hello Redis"

> SETRANGE key2 6 "Redis"
(integer) 11
> GET key2
"\x00\x00\x00\x00\x00\x00Redis"

# STRLEN

# 语法

STRLEN key

# 描述

返回 key 对应字符串值的长度。如果 key 不存在，返回 0。如果 key 存储的值不是字符串类型，则返回错误。

# 参数

  • key

    键名。

# 示例

> SET mykey "Hello world"
OK
> STRLEN mykey
(integer) 11
> STRLEN nonexisting
(integer) 0

# SUBSTR

# 语法

SUBSTR key start end

# 描述

返回 key 对应字符串从 start 到 end（均包含）之间的子串。可以使用负偏移量，表示从字符串末尾开始计数，例如 -1 表示最后一个字符，-2 表示倒数第二个字符，依此类推。

对于超出范围的请求，函数会自动将结果限制为字符串的实际长度。

SUBSTR 自 Redis 2.0.0 起已被弃用，建议使用 GETRANGE，二者语义相同。

# 参数

  • key

    键名。

  • start

    起始偏移量，零基。负值表示从字符串末尾开始计数。

  • end

    结束偏移量，零基且包含在内。负值表示从字符串末尾开始计数。

# 示例

> SET mykey "This is a string"
OK
> SUBSTR mykey 0 3
"This"
> SUBSTR mykey -3 -1
"ing"
> SUBSTR mykey 0 -1
"This is a string"
> SUBSTR mykey 10 100
"string"

← Hash命令 →