chore: add some function doc (#2445)

regexp_split_to_table/array

age

date_add

trunc

Author: TCeason

docs/en/sql-reference/20-sql-functions/04-numeric-functions/index.md

@@ -20,12 +20,13 @@ This page provides a comprehensive overview of Numeric functions in Databend, or
 
 ## Rounding and Truncation Functions
 
-| Function | Description | Example |
-|----------|-------------|---------|
-| [ROUND](round.md) | Rounds a number to specified decimal places | `ROUND(123.456, 2)` → `123.46` |
-| [FLOOR](floor.md) | Returns the largest integer not greater than the argument | `FLOOR(123.456)` → `123` |
-| [CEIL](ceil.md) / [CEILING](ceiling.md) | Returns the smallest integer not less than the argument | `CEIL(123.456)` → `124` |
-| [TRUNCATE](truncate.md) | Truncates a number to specified decimal places | `TRUNCATE(123.456, 1)` → `123.4` |
+| Function                                | Description                                               | Example                          |
+|-----------------------------------------|-----------------------------------------------------------|----------------------------------|
+| [ROUND](round.md)                       | Rounds a number to specified decimal places               | `ROUND(123.456, 2)` → `123.46`   |
+| [FLOOR](floor.md)                       | Returns the largest integer not greater than the argument | `FLOOR(123.456)` → `123`         |
+| [CEIL](ceil.md) / [CEILING](ceiling.md) | Returns the smallest integer not less than the argument   | `CEIL(123.456)` → `124`          |
+| [TRUNCATE](truncate.md)                 | Truncates a number to specified decimal places            | `TRUNCATE(123.456, 1)` → `123.4` |
+| [TRUNC](trunc.md)                       | Truncates a number to specified decimal places            | `TRUNC(123.456, 1)` → `123.4`    |
 
 ## Exponential and Logarithmic Functions
 

docs/en/sql-reference/20-sql-functions/04-numeric-functions/trunc.md

@@ -0,0 +1,37 @@
+---
+title: TRUNC
+---
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="Introduced or updated: v1.2.756"/>
+
+Returns the number `x`, truncated to `d` decimal places. If `d` is 0, the result has no decimal point or fractional part. `d` can be negative to cause `d` digits left of the decimal point of the value `x` to become zero. The maximum absolute value for `d` is 30; any digits in excess of 30 (or -30) are truncated.
+
+If only provide `x` the default value of `d` is 0.
+
+## Syntax
+
+```sql
+TRUNC( x [, d] )
+```
+
+## Examples
+
+```sql
+SELECT TRUNC(1.223, 1);
+
+┌────────────────────┐
+│ truncate(1.223, 1) │
+├────────────────────┤
+│ 1.2                │
+└────────────────────┘
+
+SELECT TRUNC(1.223)
+    
+╭─────────────────╮
+│ truncate(1.223) │
+├─────────────────┤
+│               1 │
+╰─────────────────╯
+
+```

docs/en/sql-reference/20-sql-functions/05-datetime-functions/age.md

@@ -0,0 +1,89 @@
+---
+title: AGE
+---
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="Introduced or updated: v1.2.756"/>
+
+The age() function calculates the difference between two timestamps or the difference between a timestamp and the current date and time.
+
+## Syntax
+
+```sql
+AGE(<end_timestamp>, <start_timestamp>)
+```
+
+| Parameter            | Description                                                                 |
+|----------------------|-----------------------------------------------------------------------------|
+| `<end_timestamp>`   | The ending timestamp                                       |
+| `<start_timestamp>` | The starting timestamp                                |
+
+## Return Type
+
+Returns an INTERVAL type
+
+## Calculation Logic
+
+The function calculates:
+1. Full year differences (accounting for leap years)
+2. Remaining month differences (considering varying month lengths)
+3. Remaining day differences (including time components)
+
+Negative intervals are returned when `<end_timestamp>` is earlier than `<start_timestamp>`.
+
+## Examples
+
+### Basic Age Calculation
+```sql
+SELECT AGE('2023-03-15'::TIMESTAMP, '2020-01-20'::TIMESTAMP);
+├─────────────────────────┤
+│ 3 years 1 month 26 days │
+╰─────────────────────────╯
+```
+
+### Reverse Chronology
+```sql
+SELECT AGE('2018-12-25'::TIMESTAMP, '2022-05-10'::TIMESTAMP);
+├─────────────────────────────┤
+│ -3 years -4 months -16 days │
+╰─────────────────────────────╯
+```
+
+### With Time Components
+```sql
+SELECT AGE('2023-02-28 14:00:00'::TIMESTAMP, '2023-02-27 08:30:00'::TIMESTAMP);
+├───────────────┤
+│ 1 day 5:30:00 │
+╰───────────────╯
+```
+
+### Table Data Processing
+```sql
+CREATE TABLE projects (
+    name String,
+    start_date TIMESTAMP,
+    end_date TIMESTAMP
+);
+
+INSERT INTO projects VALUES
+    ('Alpha', '2020-06-01', '2023-09-30'),
+    ('Beta', '2022-01-15', '2022-11-01');
+
+SELECT 
+    name,
+    AGE(end_date, start_date) AS duration
+FROM projects;
+╭─────────────────────────────────────────────╮
+│       name       │         duration         │
+│ Nullable(String) │    Nullable(Interval)    │
+├──────────────────┼──────────────────────────┤
+│ Alpha            │ 3 years 3 months 29 days │
+│ Beta             │ 9 months 17 days         │
+╰─────────────────────────────────────────────╯
+```
+
+
+## See Also
+
+- [DATE_DIFF](date-diff.md): Alternative function for calculating specific time unit differences
+

docs/en/sql-reference/20-sql-functions/05-datetime-functions/date-add.md

@@ -59,4 +59,34 @@ SELECT
   DATE_ADD(HOUR, 1, now()): 2024-10-10 02:35:33.601312
 DATE_ADD(MINUTE, 1, now()): 2024-10-10 01:36:33.601312
 DATE_ADD(SECOND, 1, now()): 2024-10-10 01:35:34.601312
-```
+```
+
+:::note
+- When unit is MONTH, If date is the last day of the month or if the resulting month has fewer days than the day component of date,
+- then the result is the last day of the resulting month. Otherwise, the result has the same day component as date.
+
+When adding a month to a date that would result in an invalid date (e.g., January 31 → February 31), it returns the last valid day of the resulting month:
+
+```sql
+SELECT DATE_ADD(month, 1, '2023-01-31'::DATE) ;
+╭────────────────────────────────────────╮
+│ DATE_ADD(MONTH, 1, '2023-01-31'::DATE) │
+│                  Date                  │
+├────────────────────────────────────────┤
+│ 2023-02-28                             │
+╰────────────────────────────────────────╯
+
+```
+
+When adding a month to a date where the resulting month has sufficient days, it performs simple month arithmetic:
+
+```sql
+SELECT DATE_ADD(month, 1, '2023-02-28'::DATE);
+╭────────────────────────────────────────╮
+│ DATE_ADD(MONTH, 1, '2023-02-28'::DATE) │
+│                  Date                  │
+├────────────────────────────────────────┤
+│ 2023-03-28                             │
+╰────────────────────────────────────────╯
+
+```

docs/en/sql-reference/20-sql-functions/05-datetime-functions/index.md

@@ -45,16 +45,17 @@ This page provides a comprehensive overview of Date & Time functions in Databend
 
 ## Date & Time Arithmetic Functions
 
-| Function | Description | Example |
-|----------|-------------|---------|
-| [DATE_ADD](date-add.md) | Adds a time interval to a date | `DATE_ADD(DAY, 7, '2024-06-04')` → `2024-06-11` |
-| [DATE_SUB](date-sub.md) | Subtracts a time interval from a date | `DATE_SUB(MONTH, 1, '2024-06-04')` → `2024-05-04` |
-| [ADD INTERVAL](addinterval.md) | Adds an interval to a date | `'2024-06-04' + INTERVAL 1 DAY` → `2024-06-05` |
-| [SUBTRACT INTERVAL](subtractinterval.md) | Subtracts an interval from a date | `'2024-06-04' - INTERVAL 1 MONTH` → `2024-05-04` |
-| [DATE_DIFF](date-diff.md) | Returns the difference between two dates | `DATE_DIFF(DAY, '2024-06-01', '2024-06-04')` → `3` |
-| [TIMESTAMP_DIFF](timestamp-diff.md) | Returns the difference between two timestamps | `TIMESTAMP_DIFF(HOUR, '2024-06-04 10:00:00', '2024-06-04 15:00:00')` → `5` |
-| [MONTHS_BETWEEN](months-between.md) | Returns the number of months between two dates | `MONTHS_BETWEEN('2024-06-04', '2024-01-04')` → `5` |
-| [DATE_BETWEEN](date-between.md) | Checks if a date is between two other dates | `DATE_BETWEEN('2024-06-04', '2024-06-01', '2024-06-10')` → `true` |
+| Function                                 | Description                                                                                  | Example                                                                              |
+|------------------------------------------|----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
+| [DATE_ADD](date-add.md)                  | Adds a time interval to a date                                                               | `DATE_ADD(DAY, 7, '2024-06-04')` → `2024-06-11`                                      |
+| [DATE_SUB](date-sub.md)                  | Subtracts a time interval from a date                                                        | `DATE_SUB(MONTH, 1, '2024-06-04')` → `2024-05-04`                                    |
+| [ADD INTERVAL](addinterval.md)           | Adds an interval to a date                                                                   | `'2024-06-04' + INTERVAL 1 DAY` → `2024-06-05`                                       |
+| [SUBTRACT INTERVAL](subtractinterval.md) | Subtracts an interval from a date                                                            | `'2024-06-04' - INTERVAL 1 MONTH` → `2024-05-04`                                     |
+| [DATE_DIFF](date-diff.md)                | Returns the difference between two dates                                                     | `DATE_DIFF(DAY, '2024-06-01', '2024-06-04')` → `3`                                   |
+| [TIMESTAMP_DIFF](timestamp-diff.md)      | Returns the difference between two timestamps                                                | `TIMESTAMP_DIFF(HOUR, '2024-06-04 10:00:00', '2024-06-04 15:00:00')` → `5`           |
+| [MONTHS_BETWEEN](months-between.md)      | Returns the number of months between two dates                                               | `MONTHS_BETWEEN('2024-06-04', '2024-01-04')` → `5`                                   |
+| [DATE_BETWEEN](date-between.md)          | Checks if a date is between two other dates                                                  | `DATE_BETWEEN('2024-06-04', '2024-06-01', '2024-06-10')` → `true`                    |
+| [AGE](age.md)                            | Calculate the difference between timestamps or between a timestamp and the current date/time | `AGE('2000-01-01'::TIMESTAMP, '1990-05-15'::TIMESTAMP)` → `9 years 7 months 17 days` |
 
 ## Date & Time Truncation Functions
 

docs/en/sql-reference/20-sql-functions/06-string-functions/index.md

@@ -16,14 +16,16 @@ This page provides a comprehensive overview of String functions in Databend, org
 
 ## String Extraction
 
-| Function | Description | Example |
-|----------|-------------|---------|
-| [LEFT](left.md) | Returns leftmost characters | `LEFT('databend', 4)` → `'data'` |
-| [RIGHT](right.md) | Returns rightmost characters | `RIGHT('databend', 4)` → `'bend'` |
-| [SUBSTR](substr.md) / [SUBSTRING](substring.md) | Extracts a substring | `SUBSTR('databend', 5, 4)` → `'bend'` |
-| [MID](mid.md) | Extracts a substring (alias for SUBSTRING) | `MID('databend', 5, 4)` → `'bend'` |
-| [SPLIT](split.md) | Splits a string into an array | `SPLIT('data,bend', ',')` → `['data', 'bend']` |
-| [SPLIT_PART](split-part.md) | Returns a specific part after splitting | `SPLIT_PART('data,bend', ',', 2)` → `'bend'` |
+| Function                                        | Description                                                          | Example                                                                                |
+|-------------------------------------------------|----------------------------------------------------------------------|----------------------------------------------------------------------------------------|
+| [LEFT](left.md)                                 | Returns leftmost characters                                          | `LEFT('databend', 4)` → `'data'`                                                       |
+| [RIGHT](right.md)                               | Returns rightmost characters                                         | `RIGHT('databend', 4)` → `'bend'`                                                      |
+| [SUBSTR](substr.md) / [SUBSTRING](substring.md) | Extracts a substring                                                 | `SUBSTR('databend', 5, 4)` → `'bend'`                                                  |
+| [MID](mid.md)                                   | Extracts a substring (alias for SUBSTRING)                           | `MID('databend', 5, 4)` → `'bend'`                                                     |
+| [SPLIT](split.md)                               | Splits a string into an array                                        | `SPLIT('data,bend', ',')` → `['data', 'bend']`                                         |
+| [SPLIT_PART](split-part.md)                     | Returns a specific part after splitting                              | `SPLIT_PART('data,bend', ',', 2)` → `'bend'`                                           |
+| [REGEXP_SPLIT_TO_ARRAY](regexp-split-array.md)  | Split a string into an array of segments using the specified pattern | `regexp_split_to_array('apple,banana,orange', ',');` → `'['apple','banana','orange']'` |
+| [REGEXP_SPLIT_TO_TABLE](regexp-split-table.md)  | Split a string into a table of segments using the specified pattern  | `regexp_split_to_table('data,bend', ',', 2)`                                           |
 
 ## String Padding and Formatting
 

docs/en/sql-reference/20-sql-functions/06-string-functions/regexp-split-array.md

@@ -0,0 +1,74 @@
+---
+title: REGEXP_SPLIT_TO_ARRAY
+---
+
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="Introduced or updated: v1.2.756"/>
+
+Splits a string using a regular expression pattern and returns the segments as an array.
+
+## Syntax
+
+```sql
+REGEXP_SPLIT_TO_ARRAY(string, pattern [, flags text])
+```
+
+| Parameter    | Description                                                    |
+|--------------|----------------------------------------------------------------|
+| `string`     | The input string to split (VARCHAR type)                       |
+| `pattern`    | Regular expression pattern used for splitting (VARCHAR type)   |
+| `flags text` | A string of flags to modify the regular expression's behavior. |
+
+**Supported `flags` Parameter:**
+Provides flexible regular expression configuration options, controlling matching behavior by combining the following characters:
+*   `i` (case-insensitive): Pattern matching ignores case.
+*   `c` (case-sensitive): Pattern matching is case-sensitive (default behavior).
+*   `n` or `m` (multi-line): Enables multi-line mode. In this mode, `^` and `$` match the beginning and end of the string, respectively, as well as the beginning and end of each line; the dot `.` does not match newline characters.
+*   `s` (single-line): Enables single-line mode (also known as dot-matches-newline). In this mode, the dot `.` matches any character, including newline characters.
+*   `x` (ignore-whitespace): Ignores whitespace characters in the pattern (improves pattern readability).
+*   `q` (literal): Treats the `pattern` as a literal string rather than a regular expression.
+
+## Examples
+
+### Basic Splitting
+```sql
+SELECT REGEXP_SPLIT_TO_ARRAY('apple,orange,banana', ',');
+┌───────────────────────────────────────────┐
+│ ["apple","orange","banana"]               │
+└───────────────────────────────────────────┘
+```
+
+### Complex Delimiters
+```sql
+SELECT REGEXP_SPLIT_TO_ARRAY('2023-01-01T14:30:00', '[-T:]');
+┌───────────────────────────────────────────────────────┐
+│ ["2023","01","01","14","30","00"]                     │
+└───────────────────────────────────────────────────────┘
+```
+
+### Handling Empty Elements
+```sql
+SELECT REGEXP_SPLIT_TO_ARRAY('a,,b,,,c', ',+');
+┌───────────────────────────────────┐
+│ ["a","b","c"]                     │
+└───────────────────────────────────┘
+```
+
+### With flag text 
+
+```sql
+SELECT regexp_split_to_array('One_Two_Three', '[_-]', 'i')
+
+╭─────────────────────────────────────────────────────╮
+│ ['One','Two','Three']                               │
+╰─────────────────────────────────────────────────────╯
+
+```
+
+
+## See Also
+
+- [SPLIT](split.md): For simple string splitting
+- [REGEXP_SPLIT_TO_TABLE](regexp-split-table.md): split string to table
+