{ "schema_version": 2, "id": "commands/hexpire", "title": "HEXPIRE", "url": "https://redis.io/docs/latest/commands/hexpire/", "summary": "Set expiration for hash fields using relative time to expire (seconds)", "since": "7.4.0", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-09-18T09:47:41+01:00", "page_type": "content", "content_hash": "2c4d1f77320c460afcb6bf3bdc4d01ef80f347aa33b0ac2567fe9d464eb6b363", "sections": [ { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
key\n\nThe name of the key that holds the hash.\n\n
\n\n
seconds\n\nThe time to live, in seconds. Each specified field is deleted after this many seconds.\n\n
\n\n
FIELDS numfields field [field ...]\n\nThe hash fields to set expiration for. `numfields` is the number of fields, followed by that many field names.\n\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "The following options modify the command's behavior. They are mutually exclusive.\n\n
NX\n\nFor each specified field, set expiration only when the field has no expiration.\n\n
\n\n
XX\n\nFor each specified field, set expiration only when the field has an existing expiration.\n\n
\n\n
GT\n\nFor each specified field, set expiration only when the new expiration is greater than the current one. A non-volatile field is treated as an infinite TTL for the purposes of `GT`.\n\n
\n\n
LT\n\nFor each specified field, set expiration only when the new expiration is less than the current one. A non-volatile field is treated as an infinite TTL for the purposes of `LT`.\n\n
" }, { "id": "refreshing-expires", "title": "Refreshing expires", "role": "content", "text": "You can call `HEXPIRE` using as argument a field that already has an\nexisting TTL set.\nIn this case, the time to live is _updated_ to the new value." }, { "id": "redis-search-and-field-expiration", "title": "Redis Search and field expiration", "role": "content", "text": "Starting with Redis 8, Redis Search has enhanced behavior when handling expiring hash fields. For detailed information about how [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) and [`FT.AGGREGATE`](https://redis.io/docs/latest/commands/ft.aggregate) commands interact with expiring hash fields, see [Key and field expiration behavior](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/expiration)." }, { "id": "examples", "title": "Examples", "role": "example", "text": "Field expiration: Set TTL on individual hash fields using HEXPIRE with conditional options (NX, XX, GT, LT) when you need fine-grained control over field lifecycle\n\n**Difficulty:** Intermediate\n\n**Commands:** HEXPIRE, HSET, HGETALL\n\n**Complexity:**\n- HEXPIRE: O(N)\n- HSET: O(1)\n- HGETALL: O(N)\n\n**Available in:** Redis CLI, C, C#, Go, Java, Java (Asynchronous - Lettuce), Java (Reactive - Lettuce), Java (Synchronous - Jedis), JavaScript (Node.js), JavaScript (Node.js), PHP, Python, Ruby, Rust (Asynchronous), Rust (Synchronous)\n\n##### Redis CLI\n\n[code example]\n\n##### C\n\n[code example]\n\n##### C#\n\n[code example]\n\n##### Go\n\n[code example]\n\n##### Java\n\n[code example]\n\n##### Java (Asynchronous - Lettuce)\n\n[code example]\n\n##### Java (Reactive - Lettuce)\n\n[code example]\n\n##### Java (Synchronous - Jedis)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### PHP\n\n[code example]\n\n##### Python\n\n[code example]\n\n##### Ruby\n\n[code example]\n\n##### Rust (Asynchronous)\n\n[code example]\n\n##### Rust (Synchronous)\n\n[code example]" }, { "id": "redis-software-and-redis-cloud-compatibility", "title": "Redis Software and Redis Cloud compatibility", "role": "content", "text": "| Redis
Software | Redis
Cloud | Notes |\n|:----------------------|:-----------------|:------|\n| ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\nOne of the following:\n* [Array reply](../../develop/reference/protocol-spec#arrays). For each field:\n - [Integer reply](../../develop/reference/protocol-spec#integers): `-2` if no such field exists in the provided hash key, or the provided key does not exist.\n - [Integer reply](../../develop/reference/protocol-spec#integers): `0` if the specified NX | XX | GT | LT condition has not been met.\n - [Integer reply](../../develop/reference/protocol-spec#integers): `1` if the expiration time was set/updated.\n - [Integer reply](../../develop/reference/protocol-spec#integers): `2` when `HEXPIRE`/`HPEXPIRE` is called with 0 seconds/milliseconds or when `HEXPIREAT`/`HPEXPIREAT` is called with a past Unix time in seconds/milliseconds.\n* [Simple error reply](../../develop/reference/protocol-spec#simple-errors):\n - if parsing failed, mandatory arguments are missing, unknown arguments are specified, or argument values are of the wrong type or out of range.\n - if the provided key exists but is not a hash.\n\n**RESP3:**\n\nOne of the following:\n* [Array reply](../../develop/reference/protocol-spec#arrays). For each field:\n - [Integer reply](../../develop/reference/protocol-spec#integers): `-2` if no such field exists in the provided hash key, or the provided key does not exist.\n - [Integer reply](../../develop/reference/protocol-spec#integers): `0` if the specified NX | XX | GT | LT condition has not been met.\n - [Integer reply](../../develop/reference/protocol-spec#integers): `1` if the expiration time was set/updated.\n - [Integer reply](../../develop/reference/protocol-spec#integers): `2` when `HEXPIRE`/`HPEXPIRE` is called with 0 seconds/milliseconds or when `HEXPIREAT`/`HPEXPIREAT` is called with a past Unix time in seconds/milliseconds.\n* [Simple error reply](../../develop/reference/protocol-spec#simple-errors):\n - if parsing failed, mandatory arguments are missing, unknown arguments are specified, or argument values are of the wrong type or out of range.\n - if the provided key exists but is not a hash." } ], "examples": [ { "id": "examples-ex0", "language": "plaintext", "code": "> HEXPIRE no-key 20 NX FIELDS 2 field1 field2\n1) (integer) -2\n2) (integer) -2\n> HSET mykey field1 \"hello\" field2 \"world\"\n(integer) 2\n> HEXPIRE mykey 10 FIELDS 3 field1 field2 field3\n1) (integer) 1\n2) (integer) 1\n3) (integer) -2\n> HGETALL mykey", "section_id": "examples" }, { "id": "examples-ex1", "language": "c", "code": "reply = redisCommand(c, \"HSET myhash field1 Hello field2 World\");\n freeReplyObject(reply);\n\n // HEXPIRE needs the field count before the field names.\n reply = redisCommand(c, \"HEXPIRE myhash 10 FIELDS 2 field1 field2\");\n for (size_t i = 0; i < reply->elements; i++) {\n printf(\"%lld\\n\", reply->element[i]->integer);\n }\n // >>> 1\n // >>> 1\n freeReplyObject(reply);\n\n reply = redisCommand(c, \"HTTL myhash FIELDS 2 field1 field2\");\n for (size_t i = 0; i < reply->elements; i++) {\n printf(\"%lld\\n\", reply->element[i]->integer);\n }\n // >>> 10\n // >>> 10\n freeReplyObject(reply);\n\n // -2 means the field does not exist.\n reply = redisCommand(c, \"HEXPIRE myhash 10 FIELDS 1 nonexistent\");\n printf(\"%lld\\n\", reply->element[0]->integer);\n // >>> -2\n freeReplyObject(reply);", "section_id": "examples" }, { "id": "examples-ex2", "language": "csharp", "code": "// Set up hash with fields\n db.HashSet(\"myhash\",\n [\n new(\"field1\", \"Hello\"),\n new(\"field2\", \"World\")\n ]\n );\n\n ExpireResult[] hexpireRes1 = db.HashFieldExpire(\n \"myhash\",\n new RedisValue[] { \"field1\", \"field2\" },\n TimeSpan.FromSeconds(10)\n );\n Console.WriteLine(string.Join(\", \", hexpireRes1));\n // >>> Success, Success\n\n long[] hexpireRes2 = db.HashFieldGetTimeToLive(\n \"myhash\",\n new RedisValue[] { \"field1\", \"field2\" }\n );\n Console.WriteLine(string.Join(\", \", hexpireRes2));\n // >>> 10, 10 (approximately)\n\n // Try to set expiration on non-existent field\n ExpireResult[] hexpireRes3 = db.HashFieldExpire(\n \"myhash\",\n new RedisValue[] { \"nonexistent\" },\n TimeSpan.FromSeconds(10)\n );\n Console.WriteLine(string.Join(\", \", hexpireRes3));\n // >>> NoSuchField", "section_id": "examples" }, { "id": "examples-ex3", "language": "go", "code": "// Set up hash with fields\n\trdb.HSet(ctx, \"myhash\", \"field1\", \"Hello\", \"field2\", \"World\")\n\n\t// Set expiration on hash fields\n\tres1, err := rdb.HExpire(ctx, \"myhash\", 10*time.Second, \"field1\", \"field2\").Result()\n\n\tif err != nil {\n\t\tfmt.Println(err)\n\t}\n\n\tfmt.Println(res1) // >>> [1 1]\n\n\t// Check TTL of the fields\n\tres2, err := rdb.HTTL(ctx, \"myhash\", \"field1\", \"field2\").Result()\n\n\tif err != nil {\n\t\tfmt.Println(err)\n\t}\n\n\tfmt.Println(len(res2)) // >>> 2\n\n\t// Try to set expiration on non-existent field\n\tres3, err := rdb.HExpire(ctx, \"myhash\", 10*time.Second, \"nonexistent\").Result()\n\n\tif err != nil {\n\t\tfmt.Println(err)\n\t}\n\n\tfmt.Println(res3) // >>> [-2]\n\n\t// Clean up\n\trdb.Del(ctx, \"myhash\")", "section_id": "examples" }, { "id": "examples-ex4", "language": "java", "code": "// Set up a hash with two fields.\n Map hExpireFields = new HashMap<>();\n hExpireFields.put(\"field1\", \"Hello\");\n hExpireFields.put(\"field2\", \"World\");\n\n syncCommands.hset(\"myhash\", hExpireFields);\n\n // Set the expiration of both fields. `hexpire` returns a status\n // code for each field, where 1 means the expiration was set.\n List res16 = syncCommands.hexpire(\"myhash\", 10, \"field1\", \"field2\");\n System.out.println(res16); // >>> [1, 1]\n\n // Check the time to live of the fields.\n List res17 = syncCommands.httl(\"myhash\", \"field1\", \"field2\");\n System.out.println(res17); // >>> [10, 10]\n\n // Try to set the expiration of a field that doesn't exist.\n // The status code -2 means there's no such field.\n List res18 = syncCommands.hexpire(\"myhash\", 10, \"nonexistent\");\n System.out.println(res18); // >>> [-2]", "section_id": "examples" }, { "id": "examples-ex5", "language": "java", "code": "// Set up hash with fields\n Map hExpireExampleParams = new HashMap<>();\n hExpireExampleParams.put(\"field1\", \"Hello\");\n hExpireExampleParams.put(\"field2\", \"World\");\n\n CompletableFuture hExpireExample = asyncCommands.hset(\"myhash\", hExpireExampleParams).thenCompose(res1 -> {\n // Set expiration on hash fields\n return asyncCommands.hexpire(\"myhash\", 10, \"field1\", \"field2\");\n }).thenCompose(res2 -> {\n System.out.println(res2);\n // >>> [1, 1]\n // Check TTL of the fields\n return asyncCommands.httl(\"myhash\", \"field1\", \"field2\");\n }).thenCompose(res3 -> {\n System.out.println(res3.size());\n // >>> 2\n // Try to set expiration on non-existent field\n return asyncCommands.hexpire(\"myhash\", 10, \"nonexistent\");\n })\n .thenAccept(System.out::println)\n // >>> -2\n .toCompletableFuture();", "section_id": "examples" }, { "id": "examples-ex6", "language": "java", "code": "// Set up hash with fields\n Map hExpireExampleParams = new HashMap<>();\n hExpireExampleParams.put(\"field1\", \"Hello\");\n hExpireExampleParams.put(\"field2\", \"World\");\n\n Mono hExpireExample1 = reactiveCommands.hset(\"myhash\", hExpireExampleParams).doOnNext(result -> {\n });\n\n hExpireExample1.block();\n\n // Set expiration on hash fields\n Mono> hExpireExample2 = reactiveCommands.hexpire(\"myhash\", 10, \"field1\", \"field2\").collectList().doOnNext(result -> {\n System.out.println(result);\n // >>> [1, 1]\n });\n\n hExpireExample2.block();\n\n // Check TTL of the fields\n Mono> hExpireExample3 = reactiveCommands.httl(\"myhash\", \"field1\", \"field2\").collectList().doOnNext(result -> {\n System.out.println(result.size());\n // >>> 2\n });\n\n hExpireExample3.block();\n\n // Try to set expiration on non-existent field\n Mono> hExpireExample4 = reactiveCommands.hexpire(\"myhash\", 10, \"nonexistent\").collectList().doOnNext(result -> {\n System.out.println(result);\n // >>> [-2]\n });", "section_id": "examples" }, { "id": "examples-ex7", "language": "java", "code": "// Set up hash with fields\n Map hExpireExampleParams = new HashMap<>();\n hExpireExampleParams.put(\"field1\", \"Hello\");\n hExpireExampleParams.put(\"field2\", \"World\");\n jedis.hset(\"myhash\", hExpireExampleParams);\n\n // Set expiration on hash fields\n List hExpireResult1 = jedis.hexpire(\"myhash\", 10, \"field1\", \"field2\");\n System.out.println(hExpireResult1); // >>> [1, 1]\n\n // Check TTL of the fields\n List hExpireResult2 = jedis.httl(\"myhash\", \"field1\", \"field2\");\n System.out.println(hExpireResult2.size()); // >>> 2\n\n // Try to set expiration on non-existent field\n List hExpireResult3 = jedis.hexpire(\"myhash\", 10, \"nonexistent\");\n System.out.println(hExpireResult3); // >>> [-2]", "section_id": "examples" }, { "id": "examples-ex8", "language": "javascript", "code": "// Set up hash with fields\nawait client.hSet('myhash', {\n 'field1': 'Hello',\n 'field2': 'World'\n})\n\n// Set expiration on hash fields\nconst res14 = await client.hExpire('myhash', ['field1', 'field2'], 10)\nconsole.log(res14) // [1, 1]\n\n// Check TTL of the fields\nconst res15 = await client.hTTL('myhash', ['field1', 'field2'])\nconsole.log(res15) // [10, 10] (or close to 10)\n\n// Try to set expiration on non-existent field\nconst res16 = await client.hExpire('myhash', ['nonexistent'], 10)\nconsole.log(res16) // [-2]", "section_id": "examples" }, { "id": "examples-ex9", "language": "javascript", "code": "await redis.hset('myhash', { field1: 'Hello', field2: 'World' });\n\nconst hexpireRes1 = await redis.hexpire('myhash', 10, 'FIELDS', 2, 'field1', 'field2');\nconsole.log(hexpireRes1); // >>> [ 1, 1 ]\n\nconst hexpireRes2 = await redis.httl('myhash', 'FIELDS', 2, 'field1', 'field2');\nconsole.log(hexpireRes2); // >>> [ 10, 10 ]\n\n// -2 means the field does not exist.\nconst hexpireRes3 = await redis.hexpire('myhash', 10, 'FIELDS', 1, 'nonexistent');\nconsole.log(hexpireRes3); // >>> [ -2 ]", "section_id": "examples" }, { "id": "examples-ex10", "language": "javascript", "code": "// Set up hash with fields\nawait client.hSet('myhash', {\n 'field1': 'Hello',\n 'field2': 'World'\n})\n\n// Set expiration on hash fields\nconst res14 = await client.hExpire('myhash', ['field1', 'field2'], 10)\nconsole.log(res14) // [1, 1]\n\n// Check TTL of the fields\nconst res15 = await client.hTTL('myhash', ['field1', 'field2'])\nconsole.log(res15) // [10, 10] (or close to 10)\n\n// Try to set expiration on non-existent field\nconst res16 = await client.hExpire('myhash', ['nonexistent'], 10)\nconsole.log(res16) // [-2]", "section_id": "examples" }, { "id": "examples-ex11", "language": "javascript", "code": "await redis.hset('myhash', { field1: 'Hello', field2: 'World' });\n\nconst hexpireRes1 = await redis.hexpire('myhash', 10, 'FIELDS', 2, 'field1', 'field2');\nconsole.log(hexpireRes1); // >>> [ 1, 1 ]\n\nconst hexpireRes2 = await redis.httl('myhash', 'FIELDS', 2, 'field1', 'field2');\nconsole.log(hexpireRes2); // >>> [ 10, 10 ]\n\n// -2 means the field does not exist.\nconst hexpireRes3 = await redis.hexpire('myhash', 10, 'FIELDS', 1, 'nonexistent');\nconsole.log(hexpireRes3); // >>> [ -2 ]", "section_id": "examples" }, { "id": "examples-ex12", "language": "php", "code": "// Set up hash with fields\n $hExpireResult1 = $this->redis->hmset('myhash', ['field1' => 'Hello', 'field2' => 'World']);\n echo \"HMSET myhash field1 Hello field2 World: \" . ($hExpireResult1 ? 'OK' : 'FAIL') . \"\\n\"; // >>> OK\n\n // Set expiration on hash fields\n $hExpireResult2 = $this->redis->hexpire('myhash', 10, ['field1', 'field2']);\n echo \"HEXPIRE myhash 10 FIELDS field1 field2: \" . json_encode($hExpireResult2) . \"\\n\"; // >>> [1,1]\n\n // Check TTL of the fields\n $hExpireResult3 = $this->redis->httl('myhash', ['field1', 'field2']);\n echo \"HTTL myhash FIELDS field1 field2 count: \" . count($hExpireResult3) . \"\\n\"; // >>> 2\n\n // Try to set expiration on non-existent field\n $hExpireResult4 = $this->redis->hexpire('myhash', 10, ['nonexistent']);\n echo \"HEXPIRE myhash 10 FIELDS nonexistent: \" . json_encode($hExpireResult4) . \"\\n\"; // >>> [-2]", "section_id": "examples" }, { "id": "examples-ex13", "language": "python", "code": "# Set up hash with fields\nr.hset(\"myhash\", mapping={\"field1\": \"Hello\", \"field2\": \"World\"})\n\n# Set expiration on hash fields\nres12 = r.hexpire(\"myhash\", 10, \"field1\", \"field2\")\nprint(res12) # >>> [1, 1]\n\n# Check TTL of the fields\nres13 = r.httl(\"myhash\", \"field1\", \"field2\")\nprint(res13) # >>> [10, 10] (or close to 10)\n\n# Try to set expiration on non-existent field\nres14 = r.hexpire(\"myhash\", 10, \"nonexistent\")\nprint(res14) # >>> [-2]", "section_id": "examples" }, { "id": "examples-ex14", "language": "ruby", "code": "# Set up a hash with two fields.\nr.hset('myhash', { 'field1' => 'Hello', 'field2' => 'World' })\n\n# Set an expiration on both fields.\nres16 = r.hexpire('myhash', 10, 'field1', 'field2')\nputs res16.inspect # >>> [1, 1]\n\n# Check the TTL of the fields.\nres17 = r.httl('myhash', 'field1', 'field2')\nputs res17.inspect # >>> [10, 10]\n\n# Try to set an expiration on a field that does not exist.\nres18 = r.hexpire('myhash', 10, 'nonexistent')\nputs res18.inspect # >>> [-2]", "section_id": "examples" }, { "id": "examples-ex15", "language": "rust", "code": "// Set up hash with fields\n let hash_fields = vec![(\"field1\", \"Hello\"), (\"field2\", \"World\")];\n if let Ok(res) = r.hset_multiple(\"myhash\", &hash_fields).await {\n let res: String = res;\n println!(\"{res}\"); // >>> OK\n }\n\n // Set expiration on hash fields\n match r.hexpire(\"myhash\", 10, redis::ExpireOption::NONE, &[\"field1\", \"field2\"]).await {\n Ok(res1) => {\n let res1: Vec = res1;\n println!(\"{:?}\", res1); // >>> [1, 1]\n },\n Err(e) => {\n println!(\"Error setting expiration: {e}\");\n return;\n }\n }\n\n // Check TTL of the fields\n match r.httl(\"myhash\", &[\"field1\", \"field2\"]).await {\n Ok(res2) => {\n let res2: Vec = res2;\n println!(\"{}\", res2.len()); // >>> 2\n },\n Err(e) => {\n println!(\"Error getting TTL: {e}\");\n return;\n }\n }\n\n // Try to set expiration on non-existent field\n match r.hexpire(\"myhash\", 10, redis::ExpireOption::NONE, &[\"nonexistent\"]).await {\n Ok(res3) => {\n let res3: Vec = res3;\n println!(\"{:?}\", res3); // >>> [-2]\n },\n Err(e) => {\n println!(\"Error setting expiration on non-existent field: {e}\");\n return;\n }\n }", "section_id": "examples" }, { "id": "examples-ex16", "language": "rust", "code": "// Set up hash with fields\n let hash_fields = vec![(\"field1\", \"Hello\"), (\"field2\", \"World\")];\n if let Ok(res) = r.hset_multiple(\"myhash\", &hash_fields) {\n let res: String = res;\n println!(\"{res}\"); // >>> OK\n }\n\n // Set expiration on hash fields\n match r.hexpire(\"myhash\", 10, redis::ExpireOption::NONE, &[\"field1\", \"field2\"]) {\n Ok(res1) => {\n let res1: Vec = res1;\n println!(\"{:?}\", res1); // >>> [1, 1]\n },\n Err(e) => {\n println!(\"Error setting expiration: {e}\");\n return;\n }\n }\n\n // Check TTL of the fields\n match r.httl(\"myhash\", &[\"field1\", \"field2\"]) {\n Ok(res2) => {\n let res2: Vec = res2;\n println!(\"{}\", res2.len()); // >>> 2\n },\n Err(e) => {\n println!(\"Error getting TTL: {e}\");\n return;\n }\n }\n\n // Try to set expiration on non-existent field\n match r.hexpire(\"myhash\", 10, redis::ExpireOption::NONE, &[\"nonexistent\"]) {\n Ok(res3) => {\n let res3: Vec = res3;\n println!(\"{:?}\", res3); // >>> [-2]\n },\n Err(e) => {\n println!(\"Error setting expiration on non-existent field: {e}\");\n return;\n }\n }", "section_id": "examples" } ] }