From 16562158de20091f8a005d6565b95f1c6200af29 Mon Sep 17 00:00:00 2001
From: Atul Prakash <atul.prakash.work@gmail.com>
Date: Sun, 31 May 2026 22:49:26 +0530
Subject: [PATCH] Document HUMAN_READABLE_SECONDS function

Adds documentation for the HUMAN_READABLE_SECONDS function, detailing its behavior, syntax, parameters, return value, special cases, and examples.
---
 .../human_readable_seconds.md                 | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 docs/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..68f2337f54a14
--- /dev/null
+++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/human_readable_seconds.md
@@ -0,0 +1,116 @@
+---
+
+{
+"title": "HUMAN_READABLE_SECONDS",
+"language": "en"
+}
+
+---
+
+## Description
+
+Converts a number of seconds into a human-readable duration string using weeks, days, hours, minutes, and seconds.
+
+Behavior matches Presto/Trino semantics:
+
+* values are rounded to whole seconds
+* negative values use their absolute value
+* milliseconds are not emitted
+* `NaN` and `Infinity` inputs are rejected
+
+## Syntax
+
+```sql
+HUMAN_READABLE_SECONDS(<x>)
+```
+
+## Parameters
+
+| Parameter | Description                                                                |
+| --------- | -------------------------------------------------------------------------- |
+| `<x>`     | Any numeric SQL type representing a number of seconds                      |
+
+## Return Value
+
+Returns a `VARCHAR` string representing the formatted duration.
+
+## Special Cases
+
+* When `<x>` is `NULL`, returns `NULL`
+* Fractional values are rounded to the nearest whole second
+* Negative values are converted using absolute value
+* `NaN` and `Infinity` values raise an error: `Invalid argument value ... for function human_readable_seconds`
+
+## 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          |
++--------------------------------+
+```
+
+```sql
+select human_readable_seconds(0.9);
+```
+
+```text
++-----------------------------+
+| human_readable_seconds(0.9) |
++-----------------------------+
+| 1 second                    |
++-----------------------------+
+```
+
+```sql
+select human_readable_seconds(-96);
+```
+
+```text
++------------------------------+
+| human_readable_seconds(-96)  |
++------------------------------+
+| 1 minute, 36 seconds         |
++------------------------------+
+```
+
+```sql
+select human_readable_seconds(56363463);
+```
+
+```text
++----------------------------------------------------------+
+| human_readable_seconds(56363463)                         |
++----------------------------------------------------------+
+| 93 weeks, 1 day, 8 hours, 31 minutes, 3 seconds          |
++----------------------------------------------------------+
+```
+
+```sql
+select human_readable_seconds(NULL);
+```
+
+```text
++------------------------------+
+| human_readable_seconds(NULL) |
++------------------------------+
+| NULL                         |
++------------------------------+
+```