docs: improve tql reference (#2153)

Signed-off-by: Dennis Zhuang <[email protected]>

Author: killme2008

docs/reference/sql/tql.md

@@ -5,23 +5,24 @@ description: Covers the TQL keyword for executing Time-Series Query Language in
 
 # TQL
 
-The `TQL` keyword executes TQL language in SQL. The TQL is Time-Series Query Language, which is an extension for Prometheus's [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) in GreptimeDB.
+The `TQL` keyword executes TQL language in SQL. The TQL is Telemetry Query Language, which is an extension for Prometheus's [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) in GreptimeDB.
 
 ## EVAL
 
 ### Syntax
 
 ```sql
-TQL [EVAL | EVALUATE] (start, end, step) expr
+TQL [EVAL | EVALUATE] (start, end, step, [lookback]) expr
 ```
 
 The `start`, `end` and `step` are the query parameters just like [Prometheus Query API](https://prometheus.io/docs/prometheus/latest/querying/api/):
 
-- `start`: `<rfc3339 | unix_timestamp>`: Start timestamp, inclusive.
-- `end`: `<rfc3339 | unix_timestamp>`: End timestamp, inclusive.
-- `step`: `<duration | float>`: Query resolution step width in `duration` format or float number of seconds.
+- `start`: `<rfc3339 | unix_timestamp | expression>`: The start timestamp of the query; the range is inclusive of this value.
+- `end`: `<rfc3339 | unix_timestamp | expression>`: The end timestamp of the query; the range is inclusive of this value.
+- `step`: `<duration | float>`: The query resolution step, specified as a `duration` or a floating-point number of seconds.
+- `lookback`: `<duration | float>`: The maximum lookback duration for evaluation, default is 5 minutes and optional.
 
-The `expr` is the TQL expression query string.
+`expr` is the TQL (PromQL) query string.
 
 ### Examples
 
@@ -33,6 +34,28 @@ TQL eval (1677057993, 1677058993, '1m') rate(prometheus_http_requests_total{job=
 
 will get a result just like other normal SQL queries.
 
+`start` and `end` can also be time expressions that evaluate to constants. For example, to query the past 3 hours:
+
+```sql
+TQL EVAL (now() - interval '3' hours, now(), '1m')
+  sum by (namespace, pod) (
+    increase(kube_pod_container_status_restarts_total[10m:30s])
+  );
+```
+
+To query data for the past day:
+
+```sql
+TQL EVAL (
+  date_trunc('day', now() - interval '1' day),
+  date_trunc('day', now()),
+  '1m'
+)
+  sum by (namespace) (
+    rate(http_requests_total[5m:30s])
+  );
+```
+
 ## EXPLAIN
 
 `EXPLAIN` displays both the logical plan and execution plan for a given PromQL query. The syntax is as follows:
@@ -47,7 +70,7 @@ For example, to explain the PromQL `sum by (instance) (rate(node_disk_written_by
 TQL EXPLAIN sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50;
 ```
 
-Notice that since the given query won't be actually executed, the triple `(start, end, step)` is not necessary. But you can still provide it like in `TQL EVAL`:
+Notice that since the given query won't be actually executed, the triple `(start, end, step, [lookback])` is not necessary. But you can still provide it like in `TQL EVAL`:
 
 ```
 TQL EXPLAIN (0, 100, '10s') sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50;

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

@@ -5,34 +5,58 @@ description: 介绍了 `TQL` 关键字及其在 GreptimeDB 中的用法，包括
 
 # TQL
 
-`TQL` 关键字在 SQL 中执行 TQL 语言。TQL 是 Time-Series Query Language 的缩写，是 GreptimeDB 中对 Prometheus 的 [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) 的扩展。
+`TQL` 关键字在 SQL 中执行 TQL 语言。TQL 是 Telemetry Query Language 的缩写，是 GreptimeDB 中对 Prometheus 的 [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) 的扩展。
 
 ## EVAL
 
 ### Syntax
 
 ```sql
-TQL [EVAL | EVALUATE] (start, end, step) expr
+TQL [EVAL | EVALUATE] (start, end, step, [lookback]) expr
 ```
 
 `start`, `end` 和 `step` 是查询参数，就像 [Prometheus Query API](https://prometheus.io/docs/prometheus/latest/querying/api/) 一样：
 
-- `start`: `<rfc3339 | unix_timestamp>`: Start 时间戳，范围中包含该值。
-- `end`: `<rfc3339 | unix_timestamp>`: End 时间戳，范围中包含该值。
+- `start`: `<rfc3339 | unix_timestamp | expression >`: 查询的起始时间戳，范围中包含该值。
+- `end`: `<rfc3339 | unix_timestamp | expression>`: 查询的截止时间戳，范围中包含该值。
 - `step`: `<duration | float>`: 查询分辨率步长，采用 `duration` 格式或浮点秒数。
+- `lookback`: `<duration | float>`: 查询评估的最大过去持续时间，默认 5 分钟，可选参数。
 
-`expr` 是 TQL 表达式查询字符串。
+`expr` 是 TQL (PromQL) 的查询字符串。
 
 ### 示例
 
 返回过去 5 分钟内 `http_requests_total` 指标的所有时间序列的每秒值：
 
 ```sql
-TQL eval (1677057993, 1677058993, '1m') rate(prometheus_http_requests_total{job="prometheus"}[5m]);
+TQL EVAL (1677057993, 1677058993, '1m')
+  rate(prometheus_http_requests_total{job="prometheus"}[5m]);
 ```
 
 其查询结果和 SQL 查询结果类似。
 
+`start` 和 `end` 还可以是可以被求值为常量的时间表达式，例如查询过去 3 个小时：
+
+```sql
+TQL EVAL (now() - interval '3' hours, now(), '1m')
+  sum by (namespace, pod) (
+    increase(kube_pod_container_status_restarts_total[10m:30s])
+  );
+```
+
+查询过去一天的数据：
+```sql
+TQL EVAL (
+  date_trunc('day', now() - interval '1' day),
+  date_trunc('day', now()),
+  '1m'
+)
+  sum by (namespace) (
+    rate(http_requests_total[5m:30s])
+  );
+```
+
+
 ## EXPLAIN
 
 `EXPLAIN` 展示特定 PromQL 查询的逻辑计划和执行计划，其语法如下：
@@ -47,7 +71,7 @@ TQL EXPLAIN expr;
 TQL EXPLAIN sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50;
 ```
 
-注意该查询实际上没有被执行，所以 `(start, end, step)` 不是必需的，但你仍然可以像在 `TQL EVAL` 中一样提供这些参数：
+注意该查询实际上没有被执行，所以 `(start, end, step, [lookback])` 不是必需的，但你仍然可以像在 `TQL EVAL` 中一样提供这些参数：
 
 ```
 TQL EXPLAIN (0, 100, '10s') sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50;