Skip to content

[FLINK-37027][docs] Translate TO_TIMESTAMP_LTZ descriptions #28513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
amwufiv wants to merge 1 commit into
base: master
Choose a base branch
from
+30 −27
Open

[FLINK-37027][docs] Translate TO_TIMESTAMP_LTZ descriptions #28513

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 30 additions & 27 deletions docs/data/sql_functions_zh.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -831,46 +831,49 @@ temporal:
- sql: TO_TIMESTAMP_LTZ(numeric[, precision])
table: toTimestampLtz(NUMERIC[, PRECISION])
description: |
Converts a numeric epoch value to a TIMESTAMP_LTZ.
将数值类型的 Unix 时间戳值转换为 TIMESTAMP_LTZ。

- numeric: the epoch value to convert. The meaning of this value depends on the precision parameter.
- precision: an integer (0-9) that determines the unit of the numeric value (default 3). The precision changes how the numeric input is interpreted:
- numeric：要转换的 Unix 时间戳值。该值的单位取决于 precision 参数。
- precision：确定 numeric 单位的整数（取值范围 0-9，默认为 3）。不同精度会按如下方式解释 numeric：

- TO_TIMESTAMP_LTZ(epochSeconds, 0) interprets the value as seconds since epoch
- TO_TIMESTAMP_LTZ(epochMillis, 3) interprets the value as milliseconds since epoch
- TO_TIMESTAMP_LTZ(epochMicros, 6) interprets the value as microseconds since epoch
- TO_TIMESTAMP_LTZ(epochNanos, 9) interprets the value as nanoseconds since epoch
- TO_TIMESTAMP_LTZ(epochSeconds, 0) 将该值解释为自 1970-01-01 00:00:00 UTC 以来的秒数
- TO_TIMESTAMP_LTZ(epochMillis, 3) 将该值解释为自 1970-01-01 00:00:00 UTC 以来的毫秒数
- TO_TIMESTAMP_LTZ(epochMicros, 6) 将该值解释为自 1970-01-01 00:00:00 UTC 以来的微秒数
- TO_TIMESTAMP_LTZ(epochNanos, 9) 将该值解释为自 1970-01-01 00:00:00 UTC 以来的纳秒数

Other precision values between 0 and 9 are also supported, where the numeric value represents units of 10^(-precision) seconds.
The output type is TIMESTAMP_LTZ(3) for precision 0-3, and TIMESTAMP_LTZ(precision) for precision 4-9.
Returns NULL if any input is NULL. Throws a runtime error if precision is outside [0, 9].
也支持 0 到 9 之间的其它 precision 值，此时 numeric 值表示以 10^(-precision) 秒为单位的时间。
当 precision 为 0-3 时，输出类型为 TIMESTAMP_LTZ(3)；当 precision 为 4-9 时，输出类型为 TIMESTAMP_LTZ(precision)。
如果任一输入参数为 NULL，则返回 NULL。如果 precision 超出 [0, 9] 范围，则抛出运行时错误。

Note: the output type is determined at plan time. If precision is supplied as a non-literal
expression (e.g., a column reference), the precision cannot be inspected at plan time and the
output defaults to TIMESTAMP_LTZ(3). The runtime still interprets the numeric input using the
row value of precision, but any sub-millisecond digits are truncated to fit the declared type.
注意：输出类型在 plan 阶段确定。如果 precision 是非字面量表达式（例如列引用），则 plan 阶段无法检查其精度，
输出类型会默认为 TIMESTAMP_LTZ(3)。运行时仍然会使用每行的 precision 值解释 numeric 输入，
但亚毫秒部分会被截断以匹配声明的类型。

E.g., TO_TIMESTAMP_LTZ(1234567890, 0) returns TIMESTAMP_LTZ(3) '2009-02-13 23:31:30.000',
TO_TIMESTAMP_LTZ(1234567890123, 3) returns TIMESTAMP_LTZ(3) '2009-02-13 23:31:30.123',
TO_TIMESTAMP_LTZ(1234567890123456789, 9) returns TIMESTAMP_LTZ(9) '2009-02-13 23:31:30.123456789'.
例如，TO_TIMESTAMP_LTZ(1234567890, 0) 返回 TIMESTAMP_LTZ(3) '2009-02-13 23:31:30.000'，
TO_TIMESTAMP_LTZ(1234567890123, 3) 返回 TIMESTAMP_LTZ(3) '2009-02-13 23:31:30.123'，
TO_TIMESTAMP_LTZ(1234567890123456789, 9) 返回 TIMESTAMP_LTZ(9) '2009-02-13 23:31:30.123456789'。
- sql: TO_TIMESTAMP_LTZ(string1[, string2[, string3]])
table: toTimestampLtz(STRING1[, STRING2[, STRING3]])
description: |
Converts a timestamp string to a TIMESTAMP_LTZ.
将时间戳字符串转换为 TIMESTAMP_LTZ。

- string1: the timestamp string to parse
- string2: the format pattern (default 'yyyy-MM-dd HH:mm:ss'). The pattern follows Java's DateTimeFormatter syntax, where 'S' represents fractional seconds (e.g., 'SSS' for milliseconds, 'SSSSSSSSS' for nanoseconds).
- string3: the time zone of the input string (default 'UTC'). Supports zone IDs such as 'UTC', 'Asia/Shanghai', or 'America/Los_Angeles'.
- string1：要解析的时间戳字符串。
- string2：格式模式（默认为 'yyyy-MM-dd HH:mm:ss'）。该模式遵循 Java 的 DateTimeFormatter 语法，其中 'S' 表示小数秒（例如，'SSS' 表示毫秒，'SSSSSSSSS' 表示纳秒）。
- string3：输入字符串所属的时区（默认为 'UTC'）。支持 'UTC'、'Asia/Shanghai' 或 'America/Los_Angeles' 等时区 ID。

The output precision is inferred from the longest run of 'S' characters in the format pattern (outside quoted literal sections), clamped to [3, 9]. E.g., format 'yyyy-MM-dd HH:mm:ss.SS' returns TIMESTAMP_LTZ(3), format 'yyyy-MM-dd HH:mm:ss.SSSSSS' returns TIMESTAMP_LTZ(6), format 'yyyy-MM-dd HH:mm:ss.SSSSSS X' also returns TIMESTAMP_LTZ(6).
输出精度根据格式模式中最长连续 'S' 字符串推断（不包括引号包围的字面量部分），并限制在 [3, 9] 范围内。
例如，格式 'yyyy-MM-dd HH:mm:ss.SS' 返回 TIMESTAMP_LTZ(3)，格式 'yyyy-MM-dd HH:mm:ss.SSSSSS' 返回 TIMESTAMP_LTZ(6)，
格式 'yyyy-MM-dd HH:mm:ss.SSSSSS X' 也返回 TIMESTAMP_LTZ(6)。

Note: this inference only applies when the format pattern is a literal at plan time. If the format is supplied as a non-literal expression (e.g., a column reference), the pattern cannot be inspected at plan time and the output defaults to TIMESTAMP_LTZ(3). The runtime still parses with the actual row pattern, but any sub-millisecond digits are truncated to fit the declared type. To get TIMESTAMP_LTZ(6) or TIMESTAMP_LTZ(9), the format argument must appear as a literal in the SQL text.
注意：只有当格式模式在 plan 阶段是字面量时，才会进行该推断。如果格式由非字面量表达式提供（例如列引用），
则在 plan 阶段无法检查该模式，输出类型会默认为 TIMESTAMP_LTZ(3)。运行时仍然会使用实际行中的模式进行解析，
但亚毫秒部分会被截断以匹配声明的类型。若要得到 TIMESTAMP_LTZ(6) 或 TIMESTAMP_LTZ(9)，format 参数必须在 SQL 文本中以字面量形式出现。

Returns NULL if any input is NULL.
如果任一输入参数为 NULL，则返回 NULL。

E.g., TO_TIMESTAMP_LTZ('2023-01-01 00:00:00') parses using default format and UTC,
TO_TIMESTAMP_LTZ('2023-01-01 12:30:00.123456789', 'yyyy-MM-dd HH:mm:ss.SSSSSSSSS') parses with nanosecond precision,
TO_TIMESTAMP_LTZ('2023-01-01 00:00:00', 'yyyy-MM-dd HH:mm:ss', 'Asia/Shanghai') parses in Shanghai time zone.
例如，TO_TIMESTAMP_LTZ('2023-01-01 00:00:00') 使用默认格式和 UTC 解析，
TO_TIMESTAMP_LTZ('2023-01-01 12:30:00.123456789', 'yyyy-MM-dd HH:mm:ss.SSSSSSSSS') 使用纳秒精度解析，
TO_TIMESTAMP_LTZ('2023-01-01 00:00:00', 'yyyy-MM-dd HH:mm:ss', 'Asia/Shanghai') 使用上海时区解析。
- sql: TO_TIMESTAMP(string1[, string2])
table: toTimestamp(STRING1[, STRING2])
description: 将格式为 string2（默认为：'yyyy-MM-dd HH:mm:ss'）的字符串 string1 转换为 timestamp，不带时区。
Expand Down