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.
This topic applies to native nGQL only.
- You CANNOT modify a property schema with TTL options on it.
TTL options and indexes have coexistence issues.
- TTL options and indexes CANNOT coexist on a tag or an edge type. If there is an index on a property, you cannot set TTL options on other properties.
- If there are TTL options on a tag, an edge type, or a property, you can still add an index on them.
The native nGQL TTL feature has the following options.
||Specifies an existing property to set a lifespan on. The data type of the property must be
||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
You can set
- Before setting
true, make sure that no TTL has been set for any property, as shortening the expiration time may cause data to be erroneously deleted.
- After setting
true, which sets the default TTL unit to milliseconds, the data type of the property specified by
int, and the property value needs to be manually converted to milliseconds. For example, when setting
a, you need to convert the value of
ato milliseconds, such as when the value of
now(), you need to set the value of
now() * 1000.
Use TTL options¶
You must use the TTL options together to set a lifespan on a property.
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.
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¶
If a tag or an edge type is already created, to set a timeout on a property bound to the tag or edge type, use
ALTER to update the tag or edge type.
# Create a tag. nebula> CREATE TAG IF NOT EXISTS t1 (a timestamp); # Use ALTER to update the tag and set the TTL options. nebula> ALTER TAG t1 TTL_COL = "a", TTL_DURATION = 5; # Insert a vertex with tag t1. The vertex expires 5 seconds after the insertion. nebula> INSERT VERTEX t1(a) VALUES "101":(now());
Set a timeout when creating a tag or an edge type¶
# Create a tag and set the TTL options. nebula> CREATE TAG IF NOT EXISTS t2(a int, b int, c string) TTL_DURATION= 100, TTL_COL = "a"; # 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¶
- 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.
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.
If TTL is disabled, the corresponding data deleted after the last compaction can be queried again.
Remove a timeout¶
To disable TTL and remove the timeout on a property, you can use the following approaches.
- Drop the property with the timeout.
nebula> ALTER TAG t1 DROP (a);
ttl_colto an empty string.
nebula> ALTER TAG t1 TTL_COL = "";
0. This operation keeps the TTL options and prevents the property from expiring and the property schema from being modified.
nebula> ALTER TAG t1 TTL_DURATION = 0;