luoyuxia commented on code in PR #23109: URL: https://github.com/apache/flink/pull/23109#discussion_r1309551853
########## docs/content/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,75 @@ +--- +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 >}} + +The syntax of `time travel` is 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 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. + +```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 point in time. `timestamp_expression` represents the historical time point you want to query. This can be a specific timestamp or a time-related expression, such as relative time or function, and this expression only applies to physical tables and not to views or subqueries. + +## Example + +```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 functions 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 + + +``` + +## Limitation + +<span class="label label-danger">Attention</span> The `timestamp_expression` used in `time travel` only supports certain types of expressions, including constant expressions of type `TIMESTAMP`, addition and subtraction operations involving timestamps, as well as some partial built-in functions and UDFs. + +When `UDFs` are used in a `timestamp_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 +--use expression with functions thant can not be reduced to constant +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 clause. +When encountering the time travel clause, the framework will convert the TIMESTAMP type to the LONG type based on the local time zone. +Therefore, the results of the same time travel query statement may vary when queried in different time zones. Review Comment: ```suggestion Therefore, the results of the same time travel query statement may vary in different time zones. ``` ########## docs/content/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,75 @@ +--- +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 >}} + +The syntax of `time travel` is 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 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. + +```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 point in time. `timestamp_expression` represents the historical time point you want to query. This can be a specific timestamp or a time-related expression, such as relative time or function, and this expression only applies to physical tables and not to views or subqueries. + +## Example + +```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 functions 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 + + +``` + +## Limitation + +<span class="label label-danger">Attention</span> The `timestamp_expression` used in `time travel` only supports certain types of expressions, including constant expressions of type `TIMESTAMP`, addition and subtraction operations involving timestamps, as well as some partial built-in functions and UDFs. Review Comment: ```suggestion <span class="label label-danger">Attention</span> The `timestamp_expression` used in `time travel` only supports certain types of expressions that can be reduced to TIMESTAMP constants, including constant expressions of type `TIMESTAMP`, addition and subtraction operations involving timestamps, as well as some partial built-in functions and UDFs. ``` ########## docs/content.zh/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,70 @@ +--- +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 >}} + +`时间旅行`语法主要用于查询历史数据。它允许用户指定一个时间点，查询对应时间点 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`：用于特定的时间表达式，用于查询该时间点之前的数据。`timestamp_expression` 用于表示需要查询的时间点。`timestamp_expression` 可以是一个具体的 TIMESTAMP 常量 或者时间计算表达式或者函数，该表达式只能作用于物理表不能是试图或者子查询。 Review Comment: ```suggestion - `FOR SYSTEM_TIME AS OF timestamp_expression`：用于特定的时间表达式，用于查询该时间点之前的数据。`timestamp_expression` 用于表示需要查询的时间点。`timestamp_expression` 可以是一个具体的 TIMESTAMP 常量 或者时间计算表达式或者函数，该表达式只能作用于物理表不能是视图或者子查询。 ``` ########## docs/content/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,75 @@ +--- +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 >}} + +The syntax of `time travel` is 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 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. + Review Comment: nit: add a new sentence before the sql ` The syntax with time travel clause is: ` ########## docs/content.zh/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,70 @@ +--- +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 >}} + +`时间旅行`语法主要用于查询历史数据。它允许用户指定一个时间点，查询对应时间点 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`：用于特定的时间表达式，用于查询该时间点之前的数据。`timestamp_expression` 用于表示需要查询的时间点。`timestamp_expression` 可以是一个具体的 TIMESTAMP 常量 或者时间计算表达式或者函数，该表达式只能作用于物理表不能是试图或者子查询。 Review Comment: ```suggestion - `FOR SYSTEM_TIME AS OF timestamp_expression`：用于特定的时间表达式，用于查询该时间点之前的数据。`timestamp_expression` 用于表示需要查询的时间点。`timestamp_expression` 可以是一个具体的 TIMESTAMP 常量 或者时间计算表达式或者函数，该表达式只能作用于物理表不能是视图或者子查询。 ``` ########## docs/content.zh/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,70 @@ +--- +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 >}} + +`时间旅行`语法主要用于查询历史数据。它允许用户指定一个时间点，查询对应时间点 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`：用于特定的时间表达式，用于查询该时间点之前的数据。`timestamp_expression` 用于表示需要查询的时间点。`timestamp_expression` 可以是一个具体的 TIMESTAMP 常量 或者时间计算表达式或者函数，该表达式只能作用于物理表不能是试图或者子查询。 + +## 示例 + +```sql +--使用时间常量 +SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP '2023-07-31 00:00:00' + +--使用可以转换为时间常量时间函数 Review Comment: ```suggestion --使用可以转换为时间常量的时间函数 ``` ########## docs/content/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,75 @@ +--- +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 >}} + +The syntax of `time travel` is 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 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. + +```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 point in time. `timestamp_expression` represents the historical time point you want to query. This can be a specific timestamp or a time-related expression, such as relative time or function, and this expression only applies to physical tables and not to views or subqueries. + +## Example + +```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 functions that can be reduced to constant Review Comment: ```suggestion --use expression with functions that can be reduced to a constant ``` ########## docs/content/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,75 @@ +--- +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 >}} + +The syntax of `time travel` is 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 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. + +```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 point in time. `timestamp_expression` represents the historical time point you want to query. This can be a specific timestamp or a time-related expression, such as relative time or function, and this expression only applies to physical tables and not to views or subqueries. Review Comment: ```suggestion - `FOR SYSTEM_TIME AS OF timestamp_expression`：Used to query data at a specific point in time, the `timestamp_expression` represents the historical time point you want to query. The `timestamp_expression` can be a specific timestamp or a time-related expression that can be reduced to a constant, and this expression can only apply to physical tables and not to views or subqueries. ``` ########## docs/content/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,75 @@ +--- +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 >}} + +The syntax of `time travel` is 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 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. + +```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 point in time. `timestamp_expression` represents the historical time point you want to query. This can be a specific timestamp or a time-related expression, such as relative time or function, and this expression only applies to physical tables and not to views or subqueries. + +## Example + +```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 functions 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 + Review Comment: please remove these two blank lines.. ########## docs/content/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,75 @@ +--- +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 >}} + +The syntax of `time travel` is 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 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. + +```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 point in time. `timestamp_expression` represents the historical time point you want to query. This can be a specific timestamp or a time-related expression, such as relative time or function, and this expression only applies to physical tables and not to views or subqueries. Review Comment: ```suggestion - `FOR SYSTEM_TIME AS OF timestamp_expression`：Used to query data at a specific point in time, the `timestamp_expression` represents the historical time point you want to query. The `timestamp_expression` can be a specific timestamp or a time-related expression that can be reduced to a constant, and this expression can only apply to physical tables and not to views or subqueries. ``` ########## docs/content.zh/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,70 @@ +--- +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 >}} + +`时间旅行`语法主要用于查询历史数据。它允许用户指定一个时间点，查询对应时间点 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`：用于特定的时间表达式，用于查询该时间点之前的数据。`timestamp_expression` 用于表示需要查询的时间点。`timestamp_expression` 可以是一个具体的 TIMESTAMP 常量 或者时间计算表达式或者函数，该表达式只能作用于物理表不能是试图或者子查询。 + +## 示例 + +```sql +--使用时间常量 +SELECT select_list FROM paimon_tb FOR SYSTEM_TIME AS OF TIMESTAMP '2023-07-31 00:00:00' + +--使用可以转换为时间常量时间函数 Review Comment: ```suggestion --使用可以转换为时间常量的时间函数 ``` ########## docs/content.zh/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,70 @@ +--- +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. +--> + +# 时间旅行 Review Comment: The comments in english version is also suitable for chinese version ########## docs/content/docs/dev/table/sql/queries/time-travel.md: ########## @@ -0,0 +1,75 @@ +--- +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 >}} + +The syntax of `time travel` is 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 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. + +```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 point in time. `timestamp_expression` represents the historical time point you want to query. This can be a specific timestamp or a time-related expression, such as relative time or function, and this expression only applies to physical tables and not to views or subqueries. + +## Example + +```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 functions 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 + + +``` + +## Limitation + +<span class="label label-danger">Attention</span> The `timestamp_expression` used in `time travel` only supports certain types of expressions, including constant expressions of type `TIMESTAMP`, addition and subtraction operations involving timestamps, as well as some partial built-in functions and UDFs. + +When `UDFs` are used in a `timestamp_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 +--use expression with functions thant can not be reduced to constant Review Comment: ```suggestion --use expression with functions that can not be reduced to a constant ``` -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
