luoyuxia commented on code in PR #23109:
URL: https://github.com/apache/flink/pull/23109#discussion_r1308359868
##########
docs/content/docs/dev/table/catalogs.md:
##########
@@ -71,6 +71,44 @@ The provided factory identifier will be used for matching
against the required `
User-defined catalogs should replace
`Thread.currentThread().getContextClassLoader()` with the user class loader to
load classes. Otherwise, `ClassNotFoundException` maybe thrown. The user class
loader can be accessed via `CatalogFactory.Context#getClassLoader`.
{{< /hint >}}
+### Catalog supports time travel
+
+Starting from version 1.18, the Flink framework supports [time travel]({{< ref
"docs/dev/table/sql/queries/time-travel" >}}). To use time travel, you should
make sure the catalog implement `getTable(ObjectPath tablePath, long
timestamp)` method.
Review Comment:
To be more clear, not always catalog, but the catalog that the table belongs
to.
```suggestion
Starting from version 1.18, the Flink framework supports [time travel]({{<
ref "docs/dev/table/sql/queries/time-travel" >}}) to query historical data of a
table. To query the historical data of a table, users should implement
`getTable(ObjectPath tablePath, long timestamp)` method for the catalog that
the table belongs to.
```
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
Review Comment:
Please add a new empty line before `<span class="label
label-danger">Attention</span>`.
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
Review Comment:
Add a sentense:
`
The syntax of time travel is:
`
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
+
+```sql
+SELECT select_list FROM table_name FOR SYSTEM_TIME AS OF timestamp_expression
+```
+
+**Parameter Specification:**
+
+- `FOR SYSTEM_TIME AS OF timestamp_expression`：Used to query data before a
specific time point, this expression can only be applied to physical tables and
not views or subqueries.
+
+## Limitation
+
+<span class="label label-danger">Attention</span> The time expressions used in
`time travel` only support `TIMESTAMP` constant expressions, `TIMESTAMP`
addition and subtraction operations, as well as some built-in functions and
UDFs.
+
+### Constant Expression
+
+```sql
+SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP '2023-07-31
00:00:00'
+```
+
+### Constant Expression Addition and Subtraction
+
+```sql
+SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP '2023-07-31
00:00:00' - INTERVAL '1' DAY
+```
+
+### Time Function or UDF (Partial Supported)
+
+When `UDF` or `functions` are used in a `time expression`, due to the
limitations of the current framework,
+some expressions cannot be directly converted into a `TIMESTAMP` constant
during SQL parsing and an exception will be thrown.
+
+```sql
+SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TO_TIMESTAMP_LTZ(0, 3)
+```
+
+The corresponding exceptions are as follows:
+
+```bash
+Unsupported time travel expression: TO_TIMESTAMP_LTZ(0, 3) for the expression
can not be reduced to a constant by Flink.
+```
+
+## Time Zone Handling
+
+The data type generated by the TIMESTAMP expression is TIMESTAMP type, but
there's a special case in the time travel statement.
Review Comment:
For me, time travel is more like a clause then a statement:
```suggestion
The data type generated by the TIMESTAMP expression is TIMESTAMP type, but
there's a special case in the time travel clause.
```
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
Review Comment:
Please put the statement in `FOR SYSTEM_TIME AS OF timestamp_expression`：`
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
+
+```sql
+SELECT select_list FROM table_name FOR SYSTEM_TIME AS OF timestamp_expression
+```
+
+**Parameter Specification:**
+
+- `FOR SYSTEM_TIME AS OF timestamp_expression`：Used to query data before a
specific time point, this expression can only be applied to physical tables and
not views or subqueries.
+
+## Limitation
+
+<span class="label label-danger">Attention</span> The time expressions used in
`time travel` only support `TIMESTAMP` constant expressions, `TIMESTAMP`
addition and subtraction operations, as well as some built-in functions and
UDFs.
+
+### Constant Expression
Review Comment:
Then we can put some of the statement in `Time Function or UDF (Partial
Supported)` to `Limitation` part. WDYT?
##########
docs/content.zh/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,73 @@
+---
+title: 时间旅行
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# 时间旅行
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`时间旅行`是一种用于查询历史数据的 SQL 语法。它允许用户指定一个时间点，查询对应时间点 table 的数据。
+
+<span class="label label-danger">注意</span> 目前, `时间旅行`语法需要查询 table 所属的 catalog
实现了 {{< gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} 接口。
+
+```sql
+SELECT select_list FROM table_name FOR SYSTEM_TIME AS OF timestamp_expression
+```
+
+**参数说明：**
+
+- `FOR SYSTEM_TIME AS OF
timestamp_expression`：用于特定的时间表达式，用于查询该时间点之前的数据，该表达式只能作用于物理表，不能是 view 或者是子查询
+
+## 限制
Review Comment:
The comment in en part in also suitable in here.
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
+
+```sql
+SELECT select_list FROM table_name FOR SYSTEM_TIME AS OF timestamp_expression
+```
+
+**Parameter Specification:**
+
+- `FOR SYSTEM_TIME AS OF timestamp_expression`：Used to query data before a
specific time point, this expression can only be applied to physical tables and
not views or subqueries.
+
+## Limitation
+
+<span class="label label-danger">Attention</span> The time expressions used in
`time travel` only support `TIMESTAMP` constant expressions, `TIMESTAMP`
addition and subtraction operations, as well as some built-in functions and
UDFs.
+
+### Constant Expression
Review Comment:
I feel like `Constant Expression` & `Constant Expression Addition and
Subtraction` &
`Time Function or UDF (Partial Supported)` is a little of confused in here.
The structure is not intuitive.
Considering actually `TIMESTAMP '2023-07-31 00:00:00' - INTERVAL '1' DAY` is
a udf expression,
I'd like put all of into an `Example` part like
```sql
#use constant expression
SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP
'2023-07-31 00:00:00'
# use expression with udfs that can be reduced to constant
SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP
'2023-07-31 00:00:00' - INTERVAL '1' DAY
```
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
Review Comment:
Please put the statement in `FOR SYSTEM_TIME AS OF timestamp_expression`：`
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
Review Comment:
```suggestion
<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implementing the
{{< gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
```
##########
docs/content/docs/dev/table/catalogs.md:
##########
@@ -71,6 +71,44 @@ The provided factory identifier will be used for matching
against the required `
User-defined catalogs should replace
`Thread.currentThread().getContextClassLoader()` with the user class loader to
load classes. Otherwise, `ClassNotFoundException` maybe thrown. The user class
loader can be accessed via `CatalogFactory.Context#getClassLoader`.
{{< /hint >}}
+### Catalog supports time travel
Review Comment:
I'm still concerned about putting it under `Catalog Types` since it's not a
kind of catalog. I'd like to put it under `User-Defined Catalog`.
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
+
+```sql
+SELECT select_list FROM table_name FOR SYSTEM_TIME AS OF timestamp_expression
+```
+
+**Parameter Specification:**
+
+- `FOR SYSTEM_TIME AS OF timestamp_expression`：Used to query data before a
specific time point, this expression can only be applied to physical tables and
not views or subqueries.
+
+## Limitation
+
+<span class="label label-danger">Attention</span> The time expressions used in
`time travel` only support `TIMESTAMP` constant expressions, `TIMESTAMP`
addition and subtraction operations, as well as some built-in functions and
UDFs.
Review Comment:
```suggestion
<span class="label label-danger">Attention</span> The `timestamp_expression
` used in `time travel` only support `TIMESTAMP` constant expressions,
`TIMESTAMP` addition and subtraction operations, as well as some built-in
functions and UDFs.
```
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
+
+```sql
+SELECT select_list FROM table_name FOR SYSTEM_TIME AS OF timestamp_expression
+```
+
+**Parameter Specification:**
+
+- `FOR SYSTEM_TIME AS OF timestamp_expression`：Used to query data before a
specific time point, this expression can only be applied to physical tables and
not views or subqueries.
+
+## Limitation
+
+<span class="label label-danger">Attention</span> The time expressions used in
`time travel` only support `TIMESTAMP` constant expressions, `TIMESTAMP`
addition and subtraction operations, as well as some built-in functions and
UDFs.
+
+### Constant Expression
+
+```sql
+SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP '2023-07-31
00:00:00'
+```
+
+### Constant Expression Addition and Subtraction
+
+```sql
+SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP '2023-07-31
00:00:00' - INTERVAL '1' DAY
+```
+
+### Time Function or UDF (Partial Supported)
+
+When `UDF` or `functions` are used in a `time expression`, due to the
limitations of the current framework,
Review Comment:
```suggestion
When `UDFs` are used in a `timestamp_expression `, due to the limitations of
the current framework,
```
##########
docs/content.zh/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,73 @@
+---
+title: 时间旅行
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# 时间旅行
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`时间旅行`是一种用于查询历史数据的 SQL 语法。它允许用户指定一个时间点，查询对应时间点 table 的数据。
+
+<span class="label label-danger">注意</span> 目前, `时间旅行`语法需要查询 table 所属的 catalog
实现了 {{< gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} 接口。
+
+```sql
+SELECT select_list FROM table_name FOR SYSTEM_TIME AS OF timestamp_expression
+```
+
+**参数说明：**
+
+- `FOR SYSTEM_TIME AS OF
timestamp_expression`：用于特定的时间表达式，用于查询该时间点之前的数据，该表达式只能作用于物理表，不能是 view 或者是子查询
Review Comment:
Add a explanation for `timestamp_expression?
##########
docs/content/docs/dev/table/sql/queries/time-travel.md:
##########
@@ -0,0 +1,77 @@
+---
+title: Time Travel
+weight: 18
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Time Travel
+
+{{< label Batch >}} {{< label Streaming >}}
+
+`Time travel` is a SQL syntax used for querying historical data. It allows
users to specify a point in time and query the corresponding table data.
+<span class="label label-danger">Attention</span> Currently, `time travel`
requires the corresponding catalog that the table belongs to implements the {{<
gh_link
file="flink-table/flink-table-common/src/main/java/org/apache/flink/table/catalog/Catalog.java"
name="getTable(ObjectPath tablePath, long timestamp)" >}} method.
+
+The `timestamp_expression` represents the historical point in time you're
interested in. This can be a specific timestamp or an expression related to
time, such as relative time or a function.
+
+```sql
+SELECT select_list FROM table_name FOR SYSTEM_TIME AS OF timestamp_expression
+```
+
+**Parameter Specification:**
+
+- `FOR SYSTEM_TIME AS OF timestamp_expression`：Used to query data before a
specific time point, this expression can only be applied to physical tables and
not views or subqueries.
+
+## Limitation
+
+<span class="label label-danger">Attention</span> The time expressions used in
`time travel` only support `TIMESTAMP` constant expressions, `TIMESTAMP`
addition and subtraction operations, as well as some built-in functions and
UDFs.
+
+### Constant Expression
+
+```sql
+SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP '2023-07-31
00:00:00'
+```
+
+### Constant Expression Addition and Subtraction
+
+```sql
+SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP '2023-07-31
00:00:00' - INTERVAL '1' DAY
+```
+
+### Time Function or UDF (Partial Supported)
+
+When `UDF` or `functions` are used in a `time expression`, due to the
limitations of the current framework,
+some expressions cannot be directly converted into a `TIMESTAMP` constant
during SQL parsing and an exception will be thrown.
+
+```sql
+SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TO_TIMESTAMP_LTZ(0, 3)
+```
+
+The corresponding exceptions are as follows:
+
+```bash
+Unsupported time travel expression: TO_TIMESTAMP_LTZ(0, 3) for the expression
can not be reduced to a constant by Flink.
+```
+
+## Time Zone Handling
+
+The data type generated by the TIMESTAMP expression is TIMESTAMP type, but
there's a special case in the time travel statement.
+When executing the time travel statement, the framework will convert the
TIMESTAMP type to the LONG type based on the local time zone.
Review Comment:
```suggestion
When encountering the time travel clause, the framework will convert the
TIMESTAMP type to the LONG type based on the local time zone.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@flink.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
