Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

highlight prerequisite for TTL #2265

Merged
merged 2 commits into from
Sep 22, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs-2.0/3.ngql-guide/10.tag-statements/6.delete-tag.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@ Running the `DELETE TAG` statement requires some [privileges](../../7.data-secur
## Syntax

```ngql
DELETE TAG <tag_name_list> FROM <VID>;
DELETE TAG <tag_name_list> FROM <VID_list>;
```

- `tag_name_list`: Specifies the name of the tag. Multiple tags are separated with commas (,). `*` means all tags.
- `tag_name_list`: The names of the tags you want to delete. Multiple tags are separated with commas (,). `*` means all tags.

- `VID`: Specifies the VID of the tag to delete.
- `VID`: The VIDs of the vertices from which you want to delete the tags. Multiple VIDs are separated with commas (,).

## Example

Expand Down
2 changes: 1 addition & 1 deletion docs-2.0/3.ngql-guide/4.job-statements.md
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ The Meta Service parses a `SUBMIT JOB` request into multiple tasks and assigns t
For example:

```ngql
nebula> SHOW JOB 9;
nebula> SHOW JOB 8;
+----------------+-----------------+------------+----------------------------+----------------------------+-------------+
| Job Id(TaskId) | Command(Dest) | Status | Start Time | Stop Time | Error Code |
+----------------+-----------------+------------+----------------------------+----------------------------+-------------+
Expand Down
66 changes: 34 additions & 32 deletions docs-2.0/3.ngql-guide/8.clauses-and-options/ttl-options.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# TTL

TTL (Time To Live) specifies a timeout for a property. Once timed out, the property expires.
TTL (Time To Live) is a mechanism in NebulaGraph that defines the lifespan of data. Once the data reaches its predefined lifespan, it is automatically deleted from the database. This feature is particularly suitable for data that only needs temporary storage, such as temporary sessions or cached data.

## OpenCypher Compatibility

Expand All @@ -22,7 +22,7 @@ The native nGQL TTL feature has the following options.

|Option|Description|
|:---|:---|
|`ttl_col`|Specifies the property to set a timeout on. The data type of the property must be `int` or `timestamp`.|
|`ttl_col`|Specifies an existing property to set a lifespan on. The data type of the property must be `int` or `timestamp`.|
|`ttl_duration`|Specifies the timeout adds-on value in seconds. The value must be a non-negative int64 number. A property expires if the sum of its value and the `ttl_duration` value is smaller than the current timestamp. If the `ttl_duration` value is `0`, the property never expires.<br/>You can set `ttl_use_ms` to `true` in the configuration file `nebula-storaged.conf` (default path: `/usr/local/nightly/etc/`) to set the default unit to milliseconds.|

!!! caution
Expand All @@ -31,39 +31,13 @@ The native nGQL TTL feature has the following options.

- After setting `ttl_use_ms` to `true`, which sets the default TTL unit to milliseconds, the data type of the property specified by `ttl_col` must be `int`, and the property value needs to be manually converted to milliseconds. For example, when setting `ttl_col` to `a`, you need to convert the value of `a` to milliseconds, such as when the value of `a` is `now()`, you need to set the value of `a` to `now() * 1000`.

## Use TTL options

## Data expiration and deletion

!!! caution

- When the TTL options are set for a property of a tag or an edge type and the property's value is `NULL`, the property never expires.
- If a property with a default value of `now()` is added to a tag or an edge type and the TTL options are set for the property, the history data related to the tag or the edge type will never expire because the value of that property for the history data is the current timestamp.

### Vertex property expiration

Vertex property expiration has the following impact.

* If a vertex has only one tag, once a property of the vertex expires, the vertex expires.

* If a vertex has multiple tags, once a property of the vertex expires, properties bound to the same tag with the expired property also expire, but the vertex does not expire and other properties of it remain untouched.

### Edge property expiration

Since an edge can have only one edge type, once an edge property expires, the edge expires.

### Data deletion

The expired data are still stored on the disk, but queries will filter them out.

NebulaGraph automatically deletes the expired data and reclaims the disk space during the next [compaction](../../8.service-tuning/compaction.md).

!!! note

If TTL is [disabled](#remove_a_timeout), the corresponding data deleted after the last compaction can be queried again.
You must use the TTL options together to set a lifespan on a property.

## Use TTL options
Before using the TTL feature, you must first create a timestamp or integer property and specify it in the TTL options. NebulaGraph will not automatically create or manage this timestamp property for you.

You must use the TTL options together to set a valid timeout on a property.
When inserting the value of the timestamp or integer property, it is recommended to use the `now()` function or the current timestamp to represent the present time.

### Set a timeout if a tag or an edge type exists

Expand Down Expand Up @@ -91,6 +65,34 @@ nebula> CREATE TAG IF NOT EXISTS t2(a int, b int, c string) TTL_DURATION= 100, T
# Insert a vertex with tag t2. The timeout timestamp is 1648197238 (1648197138 + 100).
nebula> INSERT VERTEX t2(a, b, c) VALUES "102":(1648197138, 30, "Hello");
```
## Data expiration and deletion

!!! caution

- When the TTL options are set for a property of a tag or an edge type and the property's value is `NULL`, the property never expires.
- If a property with a default value of `now()` is added to a tag or an edge type and the TTL options are set for the property, the history data related to the tag or the edge type will never expire because the value of that property for the history data is the current timestamp.

### Vertex property expiration

Vertex property expiration has the following impact.

* If a vertex has only one tag, once a property of the vertex expires, the vertex expires.

* If a vertex has multiple tags, once a property of the vertex expires, properties bound to the same tag with the expired property also expire, but the vertex does not expire and other properties of it remain untouched.

### Edge property expiration

Since an edge can have only one edge type, once an edge property expires, the edge expires.

### Data deletion

The expired data are still stored on the disk, but queries will filter them out.

NebulaGraph automatically deletes the expired data and reclaims the disk space during the next [compaction](../../8.service-tuning/compaction.md).

!!! note

If TTL is [disabled](#remove_a_timeout), the corresponding data deleted after the last compaction can be queried again.

## Remove a timeout

Expand Down