diff --git a/docs/data/sql_functions_zh.yml b/docs/data/sql_functions_zh.yml index 547f85ff84a77..d872151bcea53 100644 --- a/docs/data/sql_functions_zh.yml +++ b/docs/data/sql_functions_zh.yml @@ -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,不带时区。