This is an automated email from the ASF dual-hosted git repository.
wangdan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pegasus-website.git
The following commit(s) were added to refs/heads/master by this push:
new 3ce79947 Update ttl Chinese doc (#52)
3ce79947 is described below
commit 3ce7994721c825954983a53f4cc01a85822a1251
Author: Yingchun Lai <[email protected]>
AuthorDate: Tue Jan 2 14:50:30 2024 +0800
Update ttl Chinese doc (#52)
---
_docs/zh/api/ttl.md | 66 ++++++++++++++++++++++++------------------
assets/images/pegasus-ttl.png | Bin 81531 -> 244149 bytes
2 files changed, 38 insertions(+), 28 deletions(-)
diff --git a/_docs/zh/api/ttl.md b/_docs/zh/api/ttl.md
index e6355b70..a49327bc 100755
--- a/_docs/zh/api/ttl.md
+++ b/_docs/zh/api/ttl.md
@@ -3,29 +3,33 @@ permalink: api/ttl
---
# 原理
-Pegasus支持TTL（Time-To-Live）功能，即在写入数据的时候，可以指定数据的过期时间。一旦过期，数据对用户就是不可见的，通过get/multiGet等查询接口获取不到数据，就跟数据没有写入一样。
+Pegasus支持TTL（Time-To-Live）功能，即在写入数据的时候，可以指定数据的过期时间。一旦过期，数据对用户就是不可见的，通过get/multiGet等接口都不再能访问到数据。
-设置的时候，用户通常都是提供`ttl_seconds`参数，表示从当前时间开始计算，多少秒之后为过期时间。如果为0，表示不设置TTL，即数据用不过期。
+设置的时候，用户通常都是提供`ttl_seconds`参数，表示从当前时间开始计算，多少秒之后数据过期。如果为0，则表示不设置TTL，即数据永不过期。
-用户通常有疑问，数据过期后对用户不可见是怎么做到的呢？数据会被立即删除吗？实际上不是这样的，这要从TTL的实现原理说起。
+用户通常有疑问，数据过期后对用户不可见是怎么实现的呢？数据会被立即删除吗？下面来讲讲TTL的实现原理。
-Pegasus的TTL是通过在RocksDB中存储数据时记录数据的过期时间，然后在查询时对过期时间进行检查和过滤来实现的。如下图：
+简单来说，Pegasus的TTL是通过在写数据时记录数据的过期时间，在查询时对过期时间进行检查来实现的。如下图：
{:class="img-responsive"}
**写入过程：**
-* 在写入数据时，用户在客户端通过`ttl_seconds`参数设置TTL时间，客户端先计算数据的过期时间`ExpireTime = CurrentTime
+ ttl_seconds`，然后通过RPC将数据和ExpireTime一起传给ReplicaServer端执行。
-*
ReplicaServer收到写请求后，经过各种处理（包括写日志、replication复制等），最后将数据存储到RocksDB中。在存储value的时候，会将ExpireTime放在value头部固定的4个字节中。
+* 在写入数据时，用户在客户端通过`ttl_seconds`参数设置TTL时间，客户端先计算数据的过期时间`ExpireTime = CurrentTime
+ ttl_seconds`，然后通过RPC将数据和`ExpireTime`一起传给ReplicaServer端执行。
+*
ReplicaServer收到写请求后，经过各种处理（包括写WAL、replication复制等），最后将数据存储到RocksDB中。在存储value的时候，会将`ExpireTime`放在value头部。
**读取过程：**
-* 用户通过客户端查询指定key对应的value数据。
-* ReplicaServer收到读请求后，先从RocksDB获取到key对应的value，然后从value头部提取出ExpireTime：
+* 用户通过客户端查询指定key对应的value数据
+* ReplicaServer收到读请求后，先从RocksDB获取到key对应的value，然后从value头部提取出`ExpireTime`：
* 如果ExpireTime == 0，表示数据没有设置TTL，是有效的。
- * 如果ExpireTime >
0，表示数据设置了TTL，则将ExpireTime与当前时间进行对比：如果没有过期，则数据是有效的；如果已经过期，则数据是无效的，返回NotFound。
+ * 如果ExpireTime > 0，表示数据设置了TTL，则进一步比较：
+ * 如果ExpireTime > CurrentTime，则数据没有过期，返回value中的用户数据
+ * 如果ExpireTime <= CurrentTime，则数据已经过期，返回`NotFound`
**数据删除：**
-*
数据过期后，并不能立即从RocksDB中消失，而是通过compaction来进行删除的。我们定制了RocksDB的CompactionFilter，使其在compaction过程中检查数据value头部的ExpireTime，如果已经过期，则数据会被扔掉，不会出现在新生成的文件中。
-*
因为删除过程是异步的，与compaction的执行时机和频率有关，所以数据过期与数据删除通常不是同时发生的，唯一能保证的是数据删除肯定发生在数据过期之后。未删除的过期数据会占据磁盘空间，这点是需要考虑到的。
+*
数据过期后，并不是立即从RocksDB中消失，而是通过[compaction](https://github.com/facebook/rocksdb/wiki/Compaction)来进行过期数据清理的。
+*
Pegasus使用了自定义的RocksDB[CompactionFilter](https://github.com/facebook/rocksdb/wiki/Compaction-Filter)，使其在compaction过程中检查数据value头部的`ExpireTime`，如果已经过期，则将数据丢弃，它将不会出现在新生成的文件中。
+*
因为过期数据的删除过程是异步的，与compaction的执行时机和频率有关，所以数据过期与数据删除通常不是同时发生的，唯一能保证的是数据删除肯定发生在数据过期之后。
+* 已过期但未删除的数据依然会占用据磁盘空间。
# 接口
我们在客户端和Shell工具都提供了设置和查询TTL的接口。
@@ -38,32 +42,38 @@ Pegasus Java Client中以下接口可以查询和设置TTL：
*
[checkAndSet](/clients/java-client#checkandset)：在CheckAndSetOptions中提供了设置TTL的参数。
Shell工具中以下命令可以查询和设置TTL：
-* [ttl](/overview/shell#ttl)命令：获取指定数据的TTL信息。
-*
[set](/overview/shell#set)和[multi_set](/overview/shell#multi_set)命令：都提供了设置TTL的参数。
+* [ttl](/docs/tools/shell/#ttl)命令：获取指定数据的TTL信息。
+*
[set](/docs/tools/shell/#set)和[multi_set](/docs/tools/shell/#multi_set)命令：都提供了设置TTL的参数。
# 表级TTL
从v1.11.2版本开始，Pegasus支持表级TTL功能。
-实现原理：
+## 实现原理
* 用户在[Table环境变量](/administration/table-env)中设置`default_ttl`环境变量。
-*
MetaServer将环境变量异步地通知到各个ReplicaServer，使该表的每个replica都获取到该环境变量，这个过程大约有几秒到几十秒不等的延迟，但是不会超过一分钟。
-* replica获得环境变量后，解析获得default_ttl配置，并立即开始生效。生效之后：
- * 用户新写入的数据，如果TTL=0（使用默认TTL=0或者显式设置TTL=0），则将数据的实际TTL设置为default_ttl。
- *
RocksDB在进行compaction的时候，如果compact输入文件的原数据没有TTL，则将compact输出文件的新数据的TTL设置为default_ttl。这个过程依赖于compaction的触发时机，所以时间点是不确定的。
- * 如果执行[Manual
Compact](/administration/manual-compact)，那么所有文件都会经过compaction处理，原来没有TTL的数据都会设置TTL为default_ttl。
-
-考虑这样的场景：业务方在初期写入数据时没有设置TTL，后来改变需求，希望所有数据都加TTL，并且以前没有设置TTL的数据从现在开始计算TTL，那么就可以通过`表级TTL`加上`Manual
Compact`的功能实现这个目的。
+* MetaServer将环境变量异步地同步到到各个ReplicaServer，使该表的每个replica都获取到该环境变量
+* replica获得环境变量后，解析获得`default_ttl`配置，并立即生效。此后：
+ * 用户新写入的数据，如果`ExpireTime` = 0，则将数据的实际`ExpireTime`设置为`default_ttl`
+ *
RocksDB在进行compaction的时候，如果compact输入文件的原数据**没有**`ExpireTime`，则将compact输出文件的新数据的`ExpireTime`设置为`default_ttl`
+ * 由于后台compaction执行时机的不确定性，未设置TTL的数据被设置TTL为`default_ttl`的时机也是是不确定的
+ * 如果想快速设置所有数据的TTL，则可以执行[Manual
Compact](/administration/manual-compact)。那么所有数据都会被compaction处理，未设置TTL的数据都会被被设置TTL为`default_ttl`
+
+## 应用场景
+- 数据表占用的磁盘空间越来越大。想降低磁盘空间占用，或通过清理数据来提升查询速度，降低磁盘、CPU等资源消耗
+- 数据表中的所有数据或部分数据没有设置TTL
+- 未设置TTL的数据的有效性跟写入时间相关，比如写入时间超过一个月的数据就不再会有查询需求了，可以丢弃
+同时满足以上3个条件的场景，就可以通过`表级TTL`和`Manual Compact`的功能实现清理磁盘释放资源的目的。
# 通过TTL计算数据写入时间
-如果数据写入时设置了TTL，就可以通过TTL计算出数据写入时间。依据的公式是：
+如果数据写入时设置了TTL，则可以通过TTL计算出数据写入的时间。
+由于：
+```
+ExpireTime = InsertTime + TTLSeconds = now + TTLRemainingSeconds
+```
+因此：
```
-TTLExpireTime = InsertTime + TTLSeconds = now + TTLRemainingSeconds
-
- ==>
-
InsertTime = now + TTLRemainingSeconds - TTLSeconds
```
其中：
+* now：执行Shell ttl命令时的时间。
* TTLRemainingSeconds：通过[Shell的ttl命令](/overview/shell#ttl)获取。
-* now：执行Shell ttl命令的时间。
-* TTLSeconds：用户知道数据写入时设置的TTL。
+* TTLSeconds：用户写入数据时设置的TTL。
diff --git a/assets/images/pegasus-ttl.png b/assets/images/pegasus-ttl.png
index 4a19fa59..340686d8 100644
Binary files a/assets/images/pegasus-ttl.png and
b/assets/images/pegasus-ttl.png differ
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
