docs: add time durations to reference (#1403)

docs/reference/sql/alter.md

@@ -116,7 +116,7 @@ The modified column cannot be a tag (primary key) or time index, and it must be
 
 Currently following options are supported:
 - `ttl`: the retention time of data in table.
-- `compaction.twcs.time_window`: the time window parameter of TWCS compaction strategy.
+- `compaction.twcs.time_window`: the time window parameter of TWCS compaction strategy. The value should be a [time duration string](/reference/time-durations.md).
 - `compaction.twcs.max_output_file_size`: the maximum allowed output file size of TWCS compaction strategy.
 - `compaction.twcs.max_active_window_runs`: the maximum allowed sorted runs in the active window of TWCS compaction strategy.
 - `compaction.twcs.max_inactive_window_runs`: the maximum allowed sorted runs in the inactive windows of TWCS compaction strategy.

docs/reference/sql/create.md

@@ -127,17 +127,7 @@ CREATE TABLE IF NOT EXISTS temperatures(
 
 The `ttl` value can be one of the following:
 
-- A duration like `1hour 12min 5s`, The duration object is a concatenation of time spans. Where each time span is an integer number and a suffix. Supported suffixes:
-    - `nsec`, `ns` – nanoseconds
-    - `usec`, `us` – microseconds
-    - `msec`, `ms` – milliseconds
-    - `seconds`, `second`, `sec`, `s`
-    - `minutes`, `minute`, `min`, `m`
-    - `hours`, `hour`, `hr`, `h`
-    - `days`, `day`, `d`
-    - `weeks`, `week`, `w`
-    - `months`, `month`, `M` – defined as 30.44 days
-    - `years`, `year`, `y` – defined as 365.25 days
+- A [duration](/reference/time-durations.md) like `1hour 12min 5s`.
 - `forever`, `NULL`, an empty string `''` and `0s` (or any zero length duration, like `0d`), means the data will never be deleted.
 - `instant`, note that database's TTL can't be set to `instant`. `instant` means the data will be deleted instantly when inserted, useful if you want to send input to a flow task without saving it, see more details in [flow management documents](/user-guide/flow-computation/manage-flow.md#manage-flows).
 - Unset, `ttl` can be unset by using `ALTER TABLE <table-name> UNSET 'ttl'`, which means the table will inherit the database's ttl policy (if any).

docs/reference/time-durations.md

@@ -0,0 +1,47 @@
+---
+keywords: [time durations, time spans, time units]
+description: Learn how GreptimeDB utilizes time durations to represent time spans in SQL queries, configuration files, and API requests with supported suffixes and examples.
+---
+
+# Time Durations
+
+GreptimeDB utilizes time durations to represent time spans in various contexts,
+including SQL queries, configuration files, and API requests.
+A time duration is expressed as a string composed of concatenated time spans,
+each represented by a sequence of decimal numbers followed by a unit suffix.
+These suffixes are case-insensitive and support both singular and plural forms. For example, `1hour 12min 5s`.
+
+Each time span consists of an integer and a suffix.
+The supported suffixes are:
+
+- `nsec`, `ns`: nanoseconds
+- `usec`, `us`: microseconds
+- `msec`, `ms`: milliseconds
+- `seconds`, `second`, `sec`, `s`
+- `minutes`, `minute`, `min`, `m`
+- `hours`, `hour`, `hr`, `h`
+- `days`, `day`, `d`
+- `weeks`, `week`, `w`
+- `months`, `month`, `M`: defined as 30.44 days
+- `years`, `year`, `y`: defined as 365.25 days
+
+Appending a decimal integer with one of the above units represents the equivalent number of seconds as a bare float literal.
+Examples:
+
+- `1s`: Equivalent to 1 second
+- `2m`: Equivalent to 120 seconds
+- `1ms`: Equivalent to 0.001 seconds
+- `2h`: Equivalent to 7200 seconds
+
+The following examples are invalid:
+
+- `0xABm`: Hexadecimal numbers are not supported
+- `1.5h`: Floating point numbers are not supported
+- `+Infd`: `±Inf` or `NaN` values are not supported
+
+
+The following are some valid time duration examples:
+
+- `1h`: one hour
+- `1h30m`, `1h 30m`: one hour and thirty minutes
+- `1h30m10s`, `1h 30m 10s`: one hour, thirty minutes, and ten seconds

i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/alter.md

@@ -120,7 +120,7 @@ ALTER TABLE monitor MODIFY COLUMN load_15 STRING;
 `ALTER TABLE` 语句也可以用来更改表的选项。
 当前支持修改以下表选项：
 - `ttl`: 表数据的保留时间。
-- `compaction.twcs.time_window`: TWCS compaction 策略的时间窗口。
+- `compaction.twcs.time_window`: TWCS compaction 策略的时间窗口，其值是一个[时间范围字符段](/reference/time-durations.md)。
 - `compaction.twcs.max_output_file_size`: TWCS compaction 策略的最大允许输出文件大小。
 - `compaction.twcs.max_active_window_runs`: TWCS compaction 策略的活跃窗口中最多允许的有序组数量。
 - `compaction.twcs.max_inactive_window_runs`: TWCS compaction 策略的非活跃窗口中最多允许的有序组数量。

i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/create.md

@@ -128,17 +128,7 @@ CREATE TABLE IF NOT EXISTS temperatures(
 ```
 `ttl` 值是一个字符串，支持以下类型的值：
 
-- 一个时间范围字符串，如 `1hour 12min 5s`，时间范围对象是时间段的连接。每个时间段由一个整数和一个后缀组成。支持的后缀有：
-    - `nsec`, `ns` – 纳秒（nanoseconds）
-    - `usec`, `us` – 微秒（microseconds）
-    - `msec`, `ms` – 毫秒（milliseconds）
-    - `seconds`, `second`, `sec`, `s` - 秒
-    - `minutes`, `minute`, `min`, `m` - 分钟
-    - `hours`, `hour`, `hr`, `h` - 小时
-    - `days`, `day`, `d` - 天
-    - `weeks`, `week`, `w` - 周
-    - `months`, `month`, `M` – 月，定义为 30.44 天
-    - `years`, `year`, `y` – 年，定义为 365.25 天
+- [时间范围字符串](/reference/time-durations.md)，如 `1hour 12min 5s`。
 - `forever`, `NULL`, `0s` （或任何长度为 0 的时间范围，如 `0d`）或空字符串 `''`，表示数据永远不会被删除。
 - `instant`, 注意数据库的 TTL 不能设置为 `instant`。`instant` 表示数据在插入时立即删除，如果你想将输入发送到流任务而不保存它，可以使用 `instant`，请参阅[流管理文档](/user-guide/flow-computation/manage-flow.md#manage-flows)了解更多细节。
 - 未设置，可以使用 `ALTER TABLE <table-name> UNSET 'ttl'` 来取消表的 `ttl` 设置，这样表将继承数据库的 `ttl` 策略（如果有的话）。

i18n/zh/docusaurus-plugin-content-docs/current/reference/time-durations.md

@@ -0,0 +1,46 @@
+---
+keywords: [时间范围, 时间跨度, 时间单位]
+description: 了解 GreptimeDB 中时间范围对象的表示方法，包括支持的时间单位和示例。
+---
+
+# 时间范围对象
+
+GreptimeDB 使用时间范围对象来表示各种上下文中的时间跨度，
+包括 SQL 查询、配置文件和 API 请求。
+时间持续时间表示为由连接的时间跨度组成的字符串，
+每个时间跨度由一个十进制数字序列和一个单位后缀表示。
+这些后缀不区分大小写，并且支持单数和复数形式。例如，`1hour 12min 5s`。
+
+每个时间跨度由一个整数和一个后缀组成。支持的后缀有：
+
+- `nsec`, `ns`: 纳秒
+- `usec`, `us`: 微秒
+- `msec`, `ms`: 毫秒
+- `seconds`, `second`, `sec`, `s`: 秒
+- `minutes`, `minute`, `min`, `m`: 分钟
+- `hours`, `hour`, `hr`, `h`: 小时
+- `days`, `day`, `d`: 天
+- `weeks`, `week`, `w`: 周
+- `months`, `month`, `M`: 定义为 30.44 天
+- `years`, `year`, `y`: 定义为 365.25 天
+
+在十进制整数后附加上述单位之一，表示等值的秒数。
+例如：
+
+- `1s`: 等效于 1 秒
+- `2m`: 等效于 120 秒
+- `1ms`: 等效于 0.001 秒
+- `2h`: 等效于 7200 秒
+
+以下写法无效：
+
+- `0xABm`: 不支持十六进制数字
+- `1.5h`: 不支持浮点数
+- `+Infd`: 不支持 `±Inf` 或 `NaN` 值
+
+以下是一些有效的时间范围示例：
+
+- `1h`: 一小时
+- `1h30m`, `1h 30m`: 一小时三十分钟
+- `1h30m10s`, `1h 30m 10s`: 一小时三十分钟十秒
+

sidebars.ts

@@ -378,6 +378,7 @@ const sidebars: SidebarsConfig = {
       items: [
         'reference/command-lines',
         'reference/sql-tools',
+        'reference/time-durations',
         {
           type: 'category',
           label: 'SQL',