From 25017f82ad13be1b5d033d7812d5520fa8ed14a7 Mon Sep 17 00:00:00 2001 From: qzr <3302371508@qq.com> Date: Sun, 29 Mar 2026 14:13:30 +0800 Subject: [PATCH] docs for new_function --- .../human_readable_seconds.md | 97 +++++++++++++++++++ .../human_readable_seconds.md | 97 +++++++++++++++++++ sidebars.ts | 1 + 3 files changed, 195 insertions(+) create mode 100644 docs/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md new file mode 100644 index 0000000000000..2311edf766b5a --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md @@ -0,0 +1,97 @@ +--- +{ + "title": "HUMAN_READABLE_SECONDS", + "language": "en" +} +--- + +## Description + +Converts a number of seconds into a human-readable duration string (weeks, days, hours, minutes, seconds, and milliseconds). + +## Syntax + +```sql +HUMAN_READABLE_SECONDS() +``` + +## Parameters + +| Parameter | Description | +| -- | -- | +| `` | The number of seconds to format (numeric input, internally cast to DOUBLE) | + +## Return Value + +Returns a `VARCHAR` string representing the duration. + +## Special Cases + +- When `` is `NULL`, returns `NULL` +- Supports negative values, prefixed with `-` +- Fractional seconds are formatted as milliseconds +- When `` is `NaN`, returns `nan` +- When `` is positive infinity, returns `inf` +- When `` is negative infinity, returns `-inf` + +## Examples + +```sql +select human_readable_seconds(3661); +``` + +```text ++------------------------------+ +| human_readable_seconds(3661) | ++------------------------------+ +| 1 hour, 1 minute, 1 second | ++------------------------------+ +``` + +```sql +select human_readable_seconds(475.33); +``` + +```text ++--------------------------------+ +| human_readable_seconds(475.33) | ++--------------------------------+ +| 7 minutes, 55 seconds, 330 milliseconds | ++--------------------------------+ +``` + +```sql +select human_readable_seconds(0.9); +``` + +```text ++-----------------------------+ +| human_readable_seconds(0.9) | ++-----------------------------+ +| 900 milliseconds | ++-----------------------------+ +``` + +```sql +select human_readable_seconds(-0.5); +``` + +```text ++------------------------------+ +| human_readable_seconds(-0.5) | ++------------------------------+ +| -500 milliseconds | ++------------------------------+ +``` + +```sql +select human_readable_seconds(NULL); +``` + +```text ++------------------------------+ +| human_readable_seconds(NULL) | ++------------------------------+ +| NULL | ++------------------------------+ +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md new file mode 100644 index 0000000000000..ef485ff23d9e1 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md @@ -0,0 +1,97 @@ +--- +{ + "title": "HUMAN_READABLE_SECONDS", + "language": "zh-CN" +} +--- + +## 描述 + +将秒数转换为可读性更高的时长字符串（包含周、天、小时、分钟、秒、毫秒）。 + +## 语法 + +```sql +HUMAN_READABLE_SECONDS() +``` + +## 参数 + +| 参数 | 说明 | +| -- | -- | +| `` | 需要格式化的秒数（数值类型输入，内部按 DOUBLE 处理） | + +## 返回值 + +返回 `VARCHAR` 类型的时长字符串。 + +## 特殊情况 + +- 当 `` 为 `NULL` 时，返回 `NULL` +- 支持负数输入，结果前会加 `-` +- 小数秒会以毫秒形式输出 +- 当 `` 为 `NaN` 时，返回 `nan` +- 当 `` 为正无穷时，返回 `inf` +- 当 `` 为负无穷时，返回 `-inf` + +## 示例 + +```sql +select human_readable_seconds(3661); +``` + +```text ++------------------------------+ +| human_readable_seconds(3661) | ++------------------------------+ +| 1 hour, 1 minute, 1 second | ++------------------------------+ +``` + +```sql +select human_readable_seconds(475.33); +``` + +```text ++--------------------------------+ +| human_readable_seconds(475.33) | ++--------------------------------+ +| 7 minutes, 55 seconds, 330 milliseconds | ++--------------------------------+ +``` + +```sql +select human_readable_seconds(0.9); +``` + +```text ++-----------------------------+ +| human_readable_seconds(0.9) | ++-----------------------------+ +| 900 milliseconds | ++-----------------------------+ +``` + +```sql +select human_readable_seconds(-0.5); +``` + +```text ++------------------------------+ +| human_readable_seconds(-0.5) | ++------------------------------+ +| -500 milliseconds | ++------------------------------+ +``` + +```sql +select human_readable_seconds(NULL); +``` + +```text ++------------------------------+ +| human_readable_seconds(NULL) | ++------------------------------+ +| NULL | ++------------------------------+ +``` \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index f50f5ab779469..61b577112380c 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1484,6 +1484,7 @@ const sidebars: SidebarsConfig = { 'sql-manual/sql-functions/scalar-functions/date-time-functions/hours-add', 'sql-manual/sql-functions/scalar-functions/date-time-functions/hours-diff', 'sql-manual/sql-functions/scalar-functions/date-time-functions/hours-sub', + 'sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds', 'sql-manual/sql-functions/scalar-functions/date-time-functions/last-day', 'sql-manual/sql-functions/scalar-functions/date-time-functions/makedate', 'sql-manual/sql-functions/scalar-functions/date-time-functions/maketime',