EXPIRE

语法

EXPIRE key seconds [NX | XX | GT | LT]

自版本可用: Redis 开源版 1.0.0
时间复杂度: O(1)
ACL 分类: @keyspace, @write, @fast,

为 key 设置超时时间。超时时间到期后，该 key 将被自动删除。在 Redis 术语中，具有关联超时的 key 通常被称为 易失的 (volatile)。

超时时间仅会被删除或覆盖 key 内容的命令清除，包括 `DEL`、`SET`、`GETSET` 以及所有 *STORE 命令。这意味着所有在概念上修改 key 中存储的值而不将其替换为新值的操作，将保留超时时间不变。例如，使用 `INCR` 增加 key 的值，使用 `LPUSH` 将新值推入列表，或使用 `HSET` 修改哈希字段的值，这些操作都不会影响超时时间。

超时时间也可以使用 `PERSIST` 命令清除，将 key 恢复为持久 key。

如果使用 `RENAME` 重命名 key，则关联的生存时间将转移到新的 key 名称上。

如果 key 被 `RENAME` 命令覆盖，例如现有 key Key_A 被调用 RENAME Key_B Key_A 覆盖，则无论原始 Key_A 是否关联有超时时间，新的 Key_A 都将继承 Key_B 的所有特性。

请注意，调用 EXPIRE/`PEXPIRE` 时使用非正数超时，或调用 `EXPIREAT`/`PEXPIREAT` 时使用过去的时间，将导致 key 被删除而非过期（相应地，发出的 key 事件将是 del，而不是 expired）。

选项

EXPIRE 命令支持一组选项

NX -- 仅当 key 不存在超时时间时才设置超时
XX -- 仅当 key 存在超时时间时才设置超时
GT -- 仅当新的超时时间大于当前超时时间时才设置
LT -- 仅当新的超时时间小于当前超时时间时才设置

对于 GT 和 LT 选项，非易失 key 被视为具有无限 TTL。GT、LT 和 NX 选项是互斥的。

刷新超时时间

可以对已经设置了超时时间的 key 调用 EXPIRE 命令。在这种情况下，key 的生存时间会被更新为新值。这有很多有用的应用场景，下文的 导航会话 模式章节中记录了一个示例。

Redis 2.1.3 版本之前差异

在 2.1.3 版本之前的 Redis 中，使用修改 key 值的命令来修改一个已设置超时时间的 key，会导致该 key 被完全移除。这种语义是由于复制层中的限制所必需的，但现在这些限制已得到修复。

EXPIRE 将返回 0，并且不会修改已设置超时时间的 key 的超时时间。

示例

>_ Redis CLI

> SET mykey "Hello"
"OK"
> EXPIRE mykey 10
(integer) 1
> TTL mykey
(integer) 10
> SET mykey "Hello World"
"OK"
> TTL mykey
(integer) -1
> EXPIRE mykey 10 XX
(integer) 0
> TTL mykey
(integer) -1
> EXPIRE mykey 10 NX
(integer) 1
> TTL mykey
(integer) 10

Python

import redis

r = redis.Redis(decode_responses=True)

res = r.set("key1", "Hello")
print(res)
# >>> True

res = r.set("key2", "World")
print(res)
# >>> True

res = r.delete("key1", "key2", "key3")
print(res)
# >>> 2

res = r.set("mykey", "Hello")
print(res)
# >>> True

res = r.expire("mykey", 10)
print(res)
# >>> True

res = r.ttl("mykey")
print(res)
# >>> 10

res = r.set("mykey", "Hello World")
print(res)
# >>> True

res = r.ttl("mykey")
print(res)
# >>> -1

res = r.expire("mykey", 10, xx=True)
print(res)
# >>> False

res = r.ttl("mykey")
print(res)
# >>> -1

res = r.expire("mykey", 10, nx=True)
print(res)
# >>> True

res = r.ttl("mykey")
print(res)
# >>> 10

res = r.set("mykey", "Hello")
print(res)
# >>> True

res = r.expire("mykey", 10)
print(res)
# >>> True

res = r.ttl("mykey")
print(res)
# >>> 10

res = r.sadd("myset", *set([1, 2, 3, "foo", "foobar", "feelsgood"]))
print(res)
# >>> 6

res = list(r.sscan_iter("myset", match="f*"))
print(res)
# >>> ['foobar', 'foo', 'feelsgood']


cursor, key = r.scan(cursor=0, match='*11*')
print(cursor, key)

cursor, key = r.scan(cursor, match='*11*')
print(cursor, key)

cursor, key = r.scan(cursor, match='*11*')
print(cursor, key)

cursor, key = r.scan(cursor, match='*11*')
print(cursor, key)

cursor, keys = r.scan(cursor, match='*11*', count=1000)
print(cursor, keys)


res = r.geoadd("geokey", (0, 0, "value"))
print(res)
# >>> 1

res = r.zadd("zkey", {"value": 1000})
print(res)
# >>> 1

res = r.type("geokey")
print(res)
# >>> zset

res = r.type("zkey")
print(res)
# >>> zset

cursor, keys = r.scan(cursor=0, _type="zset")
print(keys)
# >>> ['zkey', 'geokey']

res = r.hset("myhash", mapping={"a": 1, "b": 2})
print(res)
# >>> 2

cursor, keys = r.hscan("myhash", 0)
print(keys)
# >>> {'a': '1', 'b': '2'}

cursor, keys = r.hscan("myhash", 0, no_values=True)
print(keys)
# >>> ['a', 'b']

Node.js


import { createClient } from 'redis';

const client = createClient();
await client.connect().catch(console.error);

const delRes1 = await client.set('key1', 'Hello');
console.log(delRes1); // OK

const delRes2 = await client.set('key2', 'World');
console.log(delRes2); // OK

const delRes3 = await client.del(['key1', 'key2', 'key3']);
console.log(delRes3); // 2

const expireRes1 = await client.set('mykey', 'Hello');
console.log(expireRes1); // OK

const expireRes2 = await client.expire('mykey', 10);
console.log(expireRes2); // true

const expireRes3 = await client.ttl('mykey');
console.log(expireRes3); // 10

const expireRes4 = await client.set('mykey', 'Hello World');
console.log(expireRes4); // OK

const expireRes5 = await client.ttl('mykey');
console.log(expireRes5); // -1

const expireRes6 = await client.expire('mykey', 10, "XX");
console.log(expireRes6); // false

const expireRes7 = await client.ttl('mykey');
console.log(expireRes7); // -1

const expireRes8 = await client.expire('mykey', 10, "NX");
console.log(expireRes8); // true

const expireRes9 = await client.ttl('mykey');
console.log(expireRes9); // 10

const ttlRes1 = await client.set('mykey', 'Hello');
console.log(ttlRes1); // OK

const ttlRes2 = await client.expire('mykey', 10);
console.log(ttlRes2); // true

const ttlRes3 = await client.ttl('mykey');
console.log(ttlRes3); // 10

const scan1Res1 = await client.sAdd('myset', ['1', '2', '3', 'foo', 'foobar', 'feelsgood']);
console.log(scan1Res1); // 6

const scan1Res2 = [];
for await (const value of client.sScanIterator('myset', { MATCH: 'f*' })) {
    scan1Res2.push(value);
}
console.log(scan1Res2); // ['foo', 'foobar', 'feelsgood']

let cursor = '0';
let scanResult;

scanResult = await client.scan(cursor, { MATCH: '*11*' });
console.log(scanResult.cursor, scanResult.keys);

scanResult = await client.scan(scanResult.cursor, { MATCH: '*11*' });
console.log(scanResult.cursor, scanResult.keys);

scanResult = await client.scan(scanResult.cursor, { MATCH: '*11*' });
console.log(scanResult.cursor, scanResult.keys);

scanResult = await client.scan(scanResult.cursor, { MATCH: '*11*' });
console.log(scanResult.cursor, scanResult.keys);

scanResult = await client.scan(scanResult.cursor, { MATCH: '*11*', COUNT: 1000 });
console.log(scanResult.cursor, scanResult.keys);

const scan3Res1 = await client.geoAdd('geokey', { longitude: 0, latitude: 0, member: 'value' });
console.log(scan3Res1); // 1

const scan3Res2 = await client.zAdd('zkey', [{ score: 1000, value: 'value' }]);
console.log(scan3Res2); // 1

const scan3Res3 = await client.type('geokey');
console.log(scan3Res3); // zset

const scan3Res4 = await client.type('zkey');
console.log(scan3Res4); // zset

const scan3Res5 = await client.scan('0', { TYPE: 'zset' });
console.log(scan3Res5.keys); // ['zkey', 'geokey']

const scan4Res1 = await client.hSet('myhash', { a: 1, b: 2 });
console.log(scan4Res1); // 2

const scan4Res2 = await client.hScan('myhash', 0);
console.log(scan4Res2.tuples); // [{field: 'a', value: '1'}, {field: 'b', value: '2'}]

const scan4Res3 = await client.hScan('myhash', 0, { COUNT: 10 });
const items = scan4Res3.tuples.map((item) => item.field)
console.log(items); // ['a', 'b']

await client.quit();

Java-Sync


import redis.clients.jedis.UnifiedJedis;
import redis.clients.jedis.args.ExpiryOption;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class CmdsGenericExample {

    public void run() {
        UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379");


        String delResult1 = jedis.set("key1", "Hello");
        System.out.println(delResult1); // >>> OK

        String delResult2 = jedis.set("key2", "World");
        System.out.println(delResult2); // >>> OK

        long delResult3 = jedis.del("key1", "key2", "key3");
        System.out.println(delResult3); // >>> 2

        // Tests for 'del' step.


        String expireResult1 = jedis.set("mykey", "Hello");
        System.out.println(expireResult1);  // >>> OK

        long expireResult2 = jedis.expire("mykey", 10);
        System.out.println(expireResult2);  // >>> 1

        long expireResult3 = jedis.ttl("mykey");
        System.out.println(expireResult3);  // >>> 10

        String expireResult4 = jedis.set("mykey", "Hello World");
        System.out.println(expireResult4);  // >>> OK

        long expireResult5 = jedis.ttl("mykey");
        System.out.println(expireResult5);  // >>> -1

        long expireResult6 = jedis.expire("mykey", 10, ExpiryOption.XX);
        System.out.println(expireResult6);  // >>> 0

        long expireResult7 = jedis.ttl("mykey");
        System.out.println(expireResult7);  // >>> -1

        long expireResult8 = jedis.expire("mykey", 10, ExpiryOption.NX);
        System.out.println(expireResult8);  // >>> 1

        long expireResult9 = jedis.ttl("mykey");
        System.out.println(expireResult9);  // >>> 10

        // Tests for 'expire' step.


        String ttlResult1 = jedis.set("mykey", "Hello");
        System.out.println(ttlResult1); // >>> OK

        long ttlResult2 = jedis.expire("mykey", 10);
        System.out.println(ttlResult2); // >>> 1

        long ttlResult3 = jedis.ttl("mykey");
        System.out.println(ttlResult3); // >>> 10

        // Tests for 'ttl' step.

        jedis.close();
    }
}

package example_commands_test

import (
	"context"
	"fmt"
	"math"
	"time"

	"github.com/redis/go-redis/v9"
)


func ExampleClient_del_cmd() {
	ctx := context.Background()

	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // no password docs
		DB:       0,  // use default DB
	})


	delResult1, err := rdb.Set(ctx, "key1", "Hello", 0).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(delResult1) // >>> OK

	delResult2, err := rdb.Set(ctx, "key2", "World", 0).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(delResult2) // >>> OK

	delResult3, err := rdb.Del(ctx, "key1", "key2", "key3").Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(delResult3) // >>> 2

}

func ExampleClient_expire_cmd() {
	ctx := context.Background()

	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // no password docs
		DB:       0,  // use default DB
	})


	expireResult1, err := rdb.Set(ctx, "mykey", "Hello", 0).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(expireResult1) // >>> OK

	expireResult2, err := rdb.Expire(ctx, "mykey", 10*time.Second).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(expireResult2) // >>> true

	expireResult3, err := rdb.TTL(ctx, "mykey").Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(math.Round(expireResult3.Seconds())) // >>> 10

	expireResult4, err := rdb.Set(ctx, "mykey", "Hello World", 0).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(expireResult4) // >>> OK

	expireResult5, err := rdb.TTL(ctx, "mykey").Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(expireResult5) // >>> -1ns

	expireResult6, err := rdb.ExpireXX(ctx, "mykey", 10*time.Second).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(expireResult6) // >>> false

	expireResult7, err := rdb.TTL(ctx, "mykey").Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(expireResult7) // >>> -1ns

	expireResult8, err := rdb.ExpireNX(ctx, "mykey", 10*time.Second).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(expireResult8) // >>> true

	expireResult9, err := rdb.TTL(ctx, "mykey").Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(math.Round(expireResult9.Seconds())) // >>> 10

}

func ExampleClient_ttl_cmd() {
	ctx := context.Background()

	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // no password docs
		DB:       0,  // use default DB
	})


	ttlResult1, err := rdb.Set(ctx, "mykey", "Hello", 10*time.Second).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(ttlResult1) // >>> OK

	ttlResult2, err := rdb.TTL(ctx, "mykey").Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(math.Round(ttlResult2.Seconds())) // >>> 10

}


using NRedisStack.Tests;
using StackExchange.Redis;



public class CmdsGenericExample
{
    public void run()
    {
        var muxer = ConnectionMultiplexer.Connect("localhost:6379");
        var db = muxer.GetDatabase();




        // Tests for 'copy' step.


        bool delResult1 = db.StringSet("key1", "Hello");
        Console.WriteLine(delResult1);  // >>> true

        bool delResult2 = db.StringSet("key2", "World");
        Console.WriteLine(delResult2);  // >>> true

        long delResult3 = db.KeyDelete(new RedisKey[] { "key1", "key2", "key3" });
        Console.WriteLine(delResult3);  // >>> 2

        // Tests for 'del' step.




        // Tests for 'dump' step.




        // Tests for 'exists' step.

        bool expireResult1 = db.StringSet("mykey", "Hello");
        Console.WriteLine(expireResult1);   // >>> true

        bool expireResult2 = db.KeyExpire("mykey", new TimeSpan(0, 0, 10));
        Console.WriteLine(expireResult2);   // >>> true

        TimeSpan expireResult3 = db.KeyTimeToLive("mykey") ?? TimeSpan.Zero;
        Console.WriteLine(Math.Round(expireResult3.TotalSeconds));   // >>> 10

        bool expireResult4 = db.StringSet("mykey", "Hello World");
        Console.WriteLine(expireResult4);   // >>> true

        TimeSpan expireResult5 = db.KeyTimeToLive("mykey") ?? TimeSpan.Zero;
        Console.WriteLine(Math.Round(expireResult5.TotalSeconds).ToString());   // >>> 0

        bool expireResult6 = db.KeyExpire("mykey", new TimeSpan(0, 0, 10), ExpireWhen.HasExpiry);
        Console.WriteLine(expireResult6);   // >>> false

        TimeSpan expireResult7 = db.KeyTimeToLive("mykey") ?? TimeSpan.Zero;
        Console.WriteLine(Math.Round(expireResult7.TotalSeconds));   // >>> 0

        bool expireResult8 = db.KeyExpire("mykey", new TimeSpan(0, 0, 10), ExpireWhen.HasNoExpiry);
        Console.WriteLine(expireResult8);   // >>> true

        TimeSpan expireResult9 = db.KeyTimeToLive("mykey") ?? TimeSpan.Zero;
        Console.WriteLine(Math.Round(expireResult9.TotalSeconds));   // >>> 10

        // Tests for 'expire' step.




        // Tests for 'expireat' step.




        // Tests for 'expiretime' step.




        // Tests for 'keys' step.




        // Tests for 'migrate' step.




        // Tests for 'move' step.




        // Tests for 'object_encoding' step.




        // Tests for 'object_freq' step.




        // Tests for 'object_idletime' step.




        // Tests for 'object_refcount' step.




        // Tests for 'persist' step.




        // Tests for 'pexpire' step.




        // Tests for 'pexpireat' step.




        // Tests for 'pexpiretime' step.




        // Tests for 'pttl' step.




        // Tests for 'randomkey' step.




        // Tests for 'rename' step.




        // Tests for 'renamenx' step.




        // Tests for 'restore' step.




        // Tests for 'scan1' step.




        // Tests for 'scan2' step.




        // Tests for 'scan3' step.




        // Tests for 'scan4' step.




        // Tests for 'sort' step.




        // Tests for 'sort_ro' step.




        // Tests for 'touch' step.


        bool ttlResult1 = db.StringSet("mykey", "Hello");
        Console.WriteLine(ttlResult1);  // >>> true

        bool ttlResult2 = db.KeyExpire("mykey", new TimeSpan(0, 0, 10));
        Console.WriteLine(ttlResult2);

        TimeSpan ttlResult3 = db.KeyTimeToLive("mykey") ?? TimeSpan.Zero;
        string ttlRes = Math.Round(ttlResult3.TotalSeconds).ToString();
        Console.WriteLine(Math.Round(ttlResult3.TotalSeconds)); // >>> 10

        // Tests for 'ttl' step.




        // Tests for 'type' step.




        // Tests for 'unlink' step.




        // Tests for 'wait' step.




        // Tests for 'waitaof' step.


    }
}

在交互式控制台中尝试这些命令

假设你有一个 Web 服务，并且你对用户最近访问的最新 N 个页面感兴趣，要求每个相邻页面浏览操作与前一个操作之间的时间间隔不超过 60 秒。从概念上讲，你可以将这组页面浏览视为用户的 导航会话，其中可能包含有关他或她当前正在寻找什么类型产品的信息，以便你可以推荐相关产品。

可以使用以下策略在 Redis 中轻松建模此模式：每次用户执行页面浏览时，你都调用以下命令

MULTI
RPUSH pagewviews.user:<userid> http://.....
EXPIRE pagewviews.user:<userid> 60
EXEC

如果用户闲置时间超过 60 秒，则 key 将被删除，之后只有时间间隔小于 60 秒的后续页面浏览才会被记录。

此模式可以轻松修改，以使用 `INCR` 命令的计数器，而不是使用 `RPUSH` 命令的列表。

附录：Redis 过期

带过期时间的 key

通常，创建 Redis key 时不关联生存时间。除非用户通过显式方式移除它，例如使用 `DEL` 命令，否则该 key 将永久存在。

EXPIRE 命令家族能够为给定的 key 关联过期时间，代价是 key 会使用一些额外的内存。当 key 设置了过期时间后，Redis 将确保在指定时间量过后移除该 key。

key 的生存时间可以使用 EXPIRE 和 `PERSIST` 命令（或其它密切相关的命令）进行更新或完全移除。

过期精度

在 Redis 2.4 版本中，过期时间可能不是非常精确，误差在零到一秒之间。

从 Redis 2.6 版本开始，过期误差在 0 到 1 毫秒之间。

过期与持久化

key 的过期信息存储为绝对 Unix 时间戳（对于 Redis 2.6 或更高版本，以毫秒为单位）。这意味着即使 Redis 实例不活动，时间也会持续流逝。

为了使过期正常工作，计算机时间必须稳定。如果你从两台时钟严重不同步的计算机上移动 RDB 文件，可能会发生一些奇怪的事情（例如加载时所有 key 都已过期）。

即使是正在运行的实例，也会始终检查计算机时钟，例如，如果你设置一个生存时间为 1000 秒的 key，然后将计算机时间调到未来 2000 秒，该 key 将立即过期，而不是持续 1000 秒。

Redis 如何使 key 过期

Redis 通过两种方式使 key 过期：被动方式和主动方式。

当客户端尝试访问一个 key 且该 key 已超时时，该 key 会被被动过期。

然而，这还不够，因为有些已过期的 key 可能永远不会再被访问。这些 key 无论如何都应该过期，因此 Redis 会定期从设置了过期时间的 key 集合中随机测试一些 key。所有已经过期的 key 都会从 keyspace 中删除。

如何在复制链接和 AOF 文件中处理过期

为了在不牺牲一致性的情况下获得正确行为，当 key 过期时，会在 AOF 文件中合成一个 `DEL` 操作，并将其传播到所有连接的副本节点。这样，过期过程就集中在主实例上，从而避免了一致性错误的可能性。

然而，虽然连接到主节点的副本不会独立过期 key（而是等待主节点发送的 `DEL` 命令），但它们仍然会获取数据集中存在的完整过期状态，因此当副本被选举为主节点时，它将能够独立过期 key，完全扮演主节点的角色。

RESP2/RESP3 回复

以下之一

整数回复：如果未设置超时时间则返回 0；例如，key 不存在，或者由于提供的参数而跳过了操作。
整数回复：如果已设置超时时间则返回 1。

历史

从 Redis 7.0.0 版本开始：添加了选项：NX、XX、GT 和 LT。

产品

工具

获取 Redis

连接

学习

最新

了解工作原理