diff --git a/docs/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/TTL.md b/docs/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/TTL.md index deef9f3e058..3384fb8a471 100644 --- a/docs/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/TTL.md +++ b/docs/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/TTL.md @@ -1,8 +1,8 @@ # TTL (time-to-live) -Nebula 支持 **TTL** ,在一定时间后自动从数据库中删除点或者边。过期数据会在下次 compaction 时被删除,在下次 compaction 来临前,query 会过滤掉过期的点和边。 +**Nebula Graph** 支持 **TTL** ,在一定时间后自动从数据库中删除点或者边。过期数据会在下次 compaction 时被删除,在下次 compaction 前,query 会过滤掉过期的点和边。 -ttl 功能需要 `ttl_col` 和 `ttl_duration` 一起使用。自从 `ttl_col` 指定的字段的值起,经过 `ttl_duration` 指定的秒数后,该条数据过期。即,到期阈值是 `ttl_col`指定的 property 的值加上 `ttl_duration` 设置的秒数。其中 `ttl_col` 指定的字段的类型需为 integer 或者 timestamp +ttl 功能需要 `ttl_col` 和 `ttl_duration` 一起使用。自从 `ttl_col` 指定的字段的值起,经过 `ttl_duration` 指定的秒数后,该条数据过期。即,到期阈值是 `ttl_col` 指定的 property 的值加上 `ttl_duration` 设置的秒数。其中 `ttl_col` 指定的字段的类型需为 integer 或者 timestamp。 ## TTL 配置 @@ -12,47 +12,48 @@ ttl 功能需要 `ttl_col` 和 `ttl_duration` 一起使用。自从 `ttl_col` - 当该条数据有多个 tag,每个 tag 的 ttl 单独处理。 - ## 设置 TTL -* 对已经创建的 tag,设置 TTL。 +- 对已经创建的 tag,设置 TTL。 ```ngql nebula> CREATE TAG t1(a timestamp); nebula> ALTER TAG t1 ttl_col = "a", ttl_duration = 5; -- 创建 ttl nebula> INSERT VERTEX t1(a) values 101:(now()); ``` + 点 101 的 TAG t1 属性会在 now() 之后,经过 5s 后过期。 -* 在创建 tag 时设置 TTL。 +- 在创建 tag 时设置 TTL。 ```ngql nebula> CREATE TAG t2(a int, b int, c string) ttl_duration= 100, ttl_col = "a"; -nebula> INSERT VERTEX t2(a, b, c) values 102:(1584441231, 30, "Word") +nebula> INSERT VERTEX t2(a, b, c) values 102:(1584441231, 30, "Word"); ``` -点 102 的 TAG t2 属性会在 2020年3月17日 18时33分51秒 CST (MacOS),经过 100s 后过期。 -* 当点有多个 TAG 时,各 TAG 的 TTL 相互独立。 +点 102 的 TAG t2 属性会在 2020年3月17日 18时33分51秒 CST (即时间戳为 1584441231),经过 100s 后过期。 + +- 当点有多个 TAG 时,各 TAG 的 TTL 相互独立。 ```ngql -nebula> CREATE TAG t3(a string) -nebula> INSERT VERTEX t1(a),t3(a) values 200:(now(), "hello") +nebula> CREATE TAG t3(a string); +nebula> INSERT VERTEX t1(a),t3(a) values 200:(now(), "hello"); ``` 5s 后, 点 Vertex 200 的 t1 属性过期。 ```ngql -nebula> fetch prop on t1 200 +nebula> FETCH PROP ON t1 200; Execution succeeded (Time spent: 5.945/7.492 ms) -nebula> fetch prop on t3 200 +nebula> FETCH PROP ON t3 200; ====================== | VertexID | t3.a | ====================== | 200 | hello | ---------------------- -nebula> fetch prop on * 200 +nebula> FETCH PROP ON * 200; ====================== | VertexID | t3.a | ====================== @@ -60,14 +61,12 @@ nebula> fetch prop on * 200 ---------------------- ``` - ## 删除 TTL -如果想要删除 TTL,可以 设置 `ttl_col` 字段为空,或删除配置的 `ttl_col` 字段,或者设置 `ttl_duration` 为 0 或者 -1。 - +如果想要删除 TTL,可以设置 `ttl_col` 字段为空,或删除配置的 `ttl_col` 字段,或者设置 `ttl_duration` 为 0 或者 -1。 ```ngql -nebula> ALTER TAG t1 ttl_col = ""; -- drop ttl attribute +nebula> ALTER TAG t1 ttl_col = ""; -- drop ttl attribute; ``` 删除配置的 `ttl_col` 字段: @@ -84,7 +83,7 @@ nebula> ALTER TAG t1 ttl_duration = 0; -- keep the ttl but the data never expire ## TTL 使用注意事项 -- 不能修改 `ttl_col` 所配置的字段。 +- 如果 `ttl_col` 值为非空,则不支持对 `ttl_col` 值指定的列进行更改操作。 ``` ngql nebula> CREATE TAG t1(a int, b int, c string) ttl_duration = 100, ttl_col = "a"; diff --git a/docs/manual-EN/2.query-language/4.statement-syntax/1.data-definition-statements/TTL.md b/docs/manual-EN/2.query-language/4.statement-syntax/1.data-definition-statements/TTL.md index a549c3a3982..fcb471b51c2 100644 --- a/docs/manual-EN/2.query-language/4.statement-syntax/1.data-definition-statements/TTL.md +++ b/docs/manual-EN/2.query-language/4.statement-syntax/1.data-definition-statements/TTL.md @@ -1,79 +1,111 @@ # TTL (time-to-live) -With **TTL**, **Nebula Graph** provides the ability to filter the expired data automatically when traversing vertices and edges. The system will automatically delete the expired data during the compaction phase, without a delete operation that is explicitly issued by the console. +With **TTL**, **Nebula Graph** provides the ability to delete the expired vertices or edges automatically. The system will automatically delete the expired data during the compaction phase. Before compaction, query will filter the expired data. -`ttl_col` indicates the TTL column, while `ttl_duration` indicates the duration of the TTL. When the sum of the TTL column and the ttl_duration is less than the current time, we consider the data as expired. The `ttl_col` type is integer or timestamp, and is set in seconds. `ttl_duration` is also set in seconds. +TTl requires `ttl_col` and `ttl_duration` together. `ttl_col` indicates the TTL column, while `ttl_duration` indicates the duration of the TTL. When the sum of the TTL column and the ttl_duration is less than the current time, we consider the data as expired. The `ttl_col` type is integer or timestamp, and is set in seconds. `ttl_duration` is also set in seconds. -## TTL configurations +## TTL configuration -The time to live value is set in seconds. +- The `ttl_duration` is set in seconds. If it is set to -1 or 0, the vertex properties of this tag does not expire. -- If TTL is set, when the sum of the `ttl_col` and the `ttl_duration` is less than the current time, we consider the data as expired. +- If TTL is set, when the sum of the `ttl_col` and the `ttl_duration` is less than the current time, we consider the vertex properties of this tag as expired after the specified seconds configured by `ttl_duration` has passed since the `ttl_col` field value. -- If TTL is not set or the `ttl_col` is null, then the time to live has no effect. - -- If TTL is set to -1 or 0, then data in the field does not expire. +- When the vertex has multiple tags, the TTL of each tag is processed separately. ## Setting a TTL Value -Setting a TTL value allows you to specify the living time of the data. +- Setting a TTL value for the existed tag. + +```ngql +nebula> CREATE TAG t1(a timestamp); +nebula> ALTER TAG t1 ttl_col = "a", ttl_duration = 5; -- Setting ttl +nebula> INSERT VERTEX t1(a) values 101:(now()); +``` -Creating a tag then adding TTL attribute. +The vertex 101 property in tag t1 will expire after 5 seconds since specified by now(). + +- Or you can set the TTL attribute when creating the tag. ```ngql -nebula> CREATE TAG t(a int, b int, c string); -nebula> ALTER TAG t ADD ttl_col = "a", ttl_duration = 1000; -- add ttl attribute -nebula> SHOW CREATE TAG t; +nebula> CREATE TAG t2(a int, b int, c string) ttl_duration= 100, ttl_col = "a"; +nebula> INSERT VERTEX t2(a, b, c) values 102:(1584441231, 30, "Word"); ``` -Or you can set the TTL attribute when creating the tag. +The vertex 102 property in tag t2 will expire after 100 seconds since March 17 2020 at 18:33:51 CST i.e. the timestamp is 1584441231. + +- When a vertex has multiple TAGs, the TTL of each TAG is independent from each other. ```ngql -nebula> CREATE TAG t(a int, b int, c string) ttl_duration= 100, ttl_col = "a"; +nebula> CREATE TAG t3(a string); +nebula> INSERT VERTEX t1(a),t3(a) values 200:(now(), "hello"); ``` -## Dropping TTL +The vertex 200 property in tag t1 will expire after 5 seconds. -If you have set a TTL value for a field and later decide do not want it to ever automatically expire, you can drop the TTL value or invalidate it. For example, using the previous example. +```ngql +nebula> FETCH PROP ON t1 200; +Execution succeeded (Time spent: 5.945/7.492 ms) + +nebula> FETCH PROP ON t3 200; +====================== +| VertexID | t3.a | +====================== +| 200 | hello | +---------------------- + +nebula> FETCH PROP ON * 200; +====================== +| VertexID | t3.a | +====================== +| 200 | hello | +---------------------- +``` + +## Dropping TTL -Drop the TTL attribute: +If you have set a TTL value for a field and later decide do not want it to ever automatically expire, you can drop the TTL value, set it to an empty string or invalidate it by setting it to 0 or -1. ```ngql -nebula> ALTER TAG t ttl_col = ""; -- drop ttl attribute +nebula> ALTER TAG t1 ttl_col = ""; -- drop ttl attribute; ``` Drop the field a with the ttl attribute: ```ngql -nebula> ALTER TAG t DROP a; -- drop field a with the ttl attribute +nebula> ALTER TAG t1 DROP (a); -- drop ttl_col ``` Invalidate the TTL: ```ngql -nebula> ALTER TAG t ttl_duration = 0; -- keep the ttl but the data never expires +nebula> ALTER TAG t1 ttl_duration = 0; -- keep the ttl but the data never expires ``` ## Tips on TTL -- If a field contains a TTL value, you can't make any change on the field. +- If a field contains a `ttl_col` field, you can't make any change on the field. ``` ngql -nebula> ALTER TAG t ADD ttl_col = "b", ttl_duration = 1000; -nebula> ALTER TAG t CHANGE (b string); -- failed +nebula> CREATE TAG t1(a int, b int, c string) ttl_duration = 100, ttl_col = "a"; +nebula> ALTER TAG t1 CHANGE (a string); -- failed ``` -- Note that the a tag or an edge cannot have both the TTL attribute and index at the same time. +- Note that the a tag or an edge cannot have both the TTL attribute and index at the same time, even if the `ttl_col` column is different from that of the index. ``` ngql -nebula> CREATE TAG t(a int, b int, c string) ttl_duration = 100, ttl_col = "a"; +nebula> CREATE TAG t1(a int, b int, c string) ttl_duration = 100, ttl_col = "a"; nebula> CREATE TAG INDEX id1 ON t(a); -- failed ``` +``` ngql +nebula> CREATE TAG t1(a int, b int, c string) ttl_duration = 100, ttl_col = "a"; +nebula> CREATE TAG INDEX id1 ON t(b); -- failed +``` + ```ngql nebula> CREATE TAG t1(a int, b int, c string); nebula> CREATE TAG INDEX id1 ON t1(a); -nebula> ALTER TAG t1 ADD ttl_col = "a", ttl_duration = 100; -- failed +nebula> ALTER TAG t1 ttl_col = "a", ttl_duration = 100; -- failed ``` - Adding TTL to an edge is similar to a tag.