|
| 1 | +--- |
| 2 | +categories: |
| 3 | +- docs |
| 4 | +- develop |
| 5 | +- stack |
| 6 | +- oss |
| 7 | +- rs |
| 8 | +- rc |
| 9 | +- oss |
| 10 | +- kubernetes |
| 11 | +- clients |
| 12 | +description: How the Redis Query Engine handles expiring keys and hash fields |
| 13 | +linkTitle: Key and field expiration |
| 14 | +title: Key and field expiration behavior |
| 15 | +weight: 8 |
| 16 | +--- |
| 17 | + |
| 18 | +The Redis Query Engine behavior with expiring keys and hash fields has been enhanced starting with Redis 8 to provide more consistent and predictable results. |
| 19 | + |
| 20 | +## Key expiration |
| 21 | + |
| 22 | +### Expiration times |
| 23 | + |
| 24 | +**Before Redis 8**: Expiration times were not taken into account when computing the result set. |
| 25 | + |
| 26 | +**Redis 8 and later**: The query engine returns only documents that are valid (not expired) at the time when the query or cursor read started. |
| 27 | + |
| 28 | +### Active expiration |
| 29 | + |
| 30 | +Active expiration can affect the number of results returned. For example, if a user requests 100 documents but 10 are actively expired during query execution, only 90 documents will be returned. |
| 31 | + |
| 32 | +**Note**: This behavior did not change in Redis 8 - active expiration has always affected result counts. |
| 33 | + |
| 34 | +### Passive expiration |
| 35 | + |
| 36 | +**Before Redis 8**: A query could return `nil` as a document name in the result set for a key that was passively expired. |
| 37 | + |
| 38 | +**Redis 8 and later**: Only valid document names will be returned. Passively expired keys are filtered out from the result set. |
| 39 | + |
| 40 | +## Field expiration |
| 41 | + |
| 42 | +Field expiration was introduced in Redis 7.4 and provides fine-grained control over hash field lifecycles. |
| 43 | + |
| 44 | +### Expiration times |
| 45 | + |
| 46 | +**Before Redis 8**: Field expiration times were not taken into account when computing the result set. |
| 47 | + |
| 48 | +**Redis 8 and later**: The query engine returns only documents that are valid (fields not expired) at the time when the query or cursor read started. |
| 49 | + |
| 50 | +### Active expiration |
| 51 | + |
| 52 | +Similar to key expiration, active field expiration can affect the number of results returned. If fields that match query criteria are actively expired during execution, fewer results will be returned than requested. |
| 53 | + |
| 54 | +**Note**: This behavior did not change in Redis 8 - active expiration has always affected result counts. |
| 55 | + |
| 56 | +### Passive expiration |
| 57 | + |
| 58 | +**Before Redis 8**: The query engine could return documents without fields that were passively expired, even if the expired field caused the document to match the query. This behavior depended to some degree on the `SORTABLE` keyword usage. |
| 59 | + |
| 60 | +**Redis 8 and later**: Documents will return with all fields that existed when the query or cursor read started. Passively expired fields are handled consistently. |
| 61 | + |
| 62 | +## Best practices |
| 63 | + |
| 64 | +* **Consistent timing**: Be aware that query results are based on the state at query start time, not when individual documents are processed. |
| 65 | + |
| 66 | +* **Result count expectations**: Be aware that when you use expiring keys or fields, the actual number of results may be less than you expected due to active expiration during the execution of the query. |
| 67 | + |
| 68 | +* **Field-level expiration**: Use hash field expiration (available since Redis 7.4) for fine-grained control over document field lifecycles without affecting the entire document. |
| 69 | + |
| 70 | +* **Query planning**: Consider expiration patterns when designing queries, especially for time-sensitive applications where expired data should not appear in results. |
| 71 | + |
| 72 | +## Related commands |
| 73 | + |
| 74 | +The following commands are directly related to key and field expiration: |
| 75 | + |
| 76 | +- [`EXPIRE`]({{< relref "/commands/expire" >}}) - Set expiration time for keys |
| 77 | +- [`HEXPIRE`]({{< relref "/commands/hexpire" >}}) - Set expiration time for hash fields |
| 78 | +- [`FT.SEARCH`]({{< relref "/commands/ft.search" >}}) - Search queries affected by expiration behavior |
| 79 | +- [`FT.AGGREGATE`]({{< relref "/commands/ft.aggregate" >}}) - Aggregation queries affected by expiration behavior |
0 commit comments