This is an automated email from the ASF dual-hosted git repository.
PragmaTwice pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/kvrocks-website.git
The following commit(s) were added to refs/heads/main by this push:
new 13f01e13 docs: update hash field expiration encoding (#385)
13f01e13 is described below
commit 13f01e137f2a110326c28b4d36f05b50d9b9298e
Author: Twice <[email protected]>
AuthorDate: Sat Jun 13 15:09:26 2026 +0800
docs: update hash field expiration encoding (#385)
---
community/data-structure-on-rocksdb.md | 22 +++++++++++++++++++++-
1 file changed, 21 insertions(+), 1 deletion(-)
diff --git a/community/data-structure-on-rocksdb.md
b/community/data-structure-on-rocksdb.md
index 598c079f..a2840d0e 100644
--- a/community/data-structure-on-rocksdb.md
+++ b/community/data-structure-on-rocksdb.md
@@ -78,29 +78,49 @@ Redis hashmap(dict) is like the hashmap in many programming
languages, it is use
#### hash metadata
```text
+legacy encoding:
+----------+------------+-----------+-----------+
key => | flags | expire | version | size |
| (1byte) | (Ebyte) | (8byte) | (Sbyte) |
+----------+------------+-----------+-----------+
+
+field expiration encoding:
+
+----------+------------+-----------+-----------+---------+-----------+-----------+-----------+
+key => | flags | expire | version | size | mode | persist
| lower | upper |
+ | (1byte) | (Ebyte) | (8byte) | (Sbyte) | (1byte) | (8byte)
| (8byte) | (8byte) |
+
+----------+------------+-----------+-----------+---------+-----------+-----------+-----------+
```
+Field expiration encoding appends the hash field expiration fields after the
legacy metadata fields.
+
The value of key we call it metadata here, it stored the metadata of hash key
includes:
- `flags` like the string, the field shows what type this key is
- `expire` is the same as the string type, record the expiration time
- `version` is used to accomplish fast delete when the number of sub
keys/values grew bigger
-- `size` records the number sub keys/values in this hash key
+- `size` records the number sub keys/values in this hash key; in field
expiration encoding, it records the approximate number of field candidates
+- `mode` records the hash subkey value format: `0` means legacy encoding, and
`1` means field expiration encoding
+- `persist` records the number of persistent physical fields whose field
expiration is `0`
+- `lower` and `upper` record the lower and upper bound hints of TTL candidate
expiration timestamps in milliseconds
#### hash sub keys-values
We use extra keys-values to store the hash keys-values, the format is like
below:
```text
+legacy encoding:
+---------------+
key|version|field => | value |
+---------------+
+
+field expiration encoding:
+ +----------------+---------------+
+key|version|field => | expire (8byte) | value |
+ +----------------+---------------+
```
+In field expiration encoding, each hash field value is prefixed with an 8-byte
expiration timestamp in milliseconds, and `0` means the field is persistent.
+
We prepend the hash `key` and `version` before the hash field, the value of
`version` is from the metadata. For example, when the request `hget h1 f1` is
received, Kvrocks fetches the metadata by hash key(here is `h1`), then
concatenate the hash key, version, field as new key, then fetches the value
with the new key.
:::note Why store version in the metadata?
