Merge pull request #68498 from Blargian/docs_toInterval

[Docs] Update `toInterval*` functions
2024-09-19 16:20:50 +00:00 · 2024-08-20 12:10:07 +00:00 · 2024-08-20 12:10:07 +00:00 · d80b37001c
commit d80b37001c
parent c25ddba0b4 0407171fce
2 changed files with 404 additions and 21 deletions
--- a/docs/en/sql-reference/functions/type-conversion-functions.md
+++ b/docs/en/sql-reference/functions/type-conversion-functions.md
@ -6103,30 +6103,23 @@ Result:
 └───────┴───────────────┴──────┴──────────────┴──────────────┴──────────────────────┘
 ```

-## toInterval(Year\|Quarter\|Month\|Week\|Day\|Hour\|Minute\|Second)
+## toIntervalYear

-Converts a Number type argument to an [Interval](../data-types/special-data-types/interval.md) data type.
+Returns an interval of `n` years of data type [IntervalYear](../data-types/special-data-types/interval.md).

 **Syntax**

 ``` sql
-toIntervalSecond(number)
-toIntervalMinute(number)
-toIntervalHour(number)
-toIntervalDay(number)
-toIntervalWeek(number)
-toIntervalMonth(number)
-toIntervalQuarter(number)
-toIntervalYear(number)
+toIntervalYear(n)
 ```

 **Arguments**

- `number` — Duration of interval. Positive integer number.
+- `n` — Number of years. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).

 **Returned values**

- The value in `Interval` data type.
+- Interval of `n` years. [IntervalYear](../data-types/special-data-types/interval.md).

 **Example**

@ -6134,20 +6127,387 @@ Query:

 ``` sql
 WITH
-    toDate('2019-01-01') AS date,
-    INTERVAL 1 WEEK AS interval_week,
-    toIntervalWeek(1) AS interval_to_week
-SELECT
-    date + interval_week,
-    date + interval_to_week;
+    toDate('2024-06-15') AS date,
+    toIntervalYear(1) AS interval_to_year
+SELECT date + interval_to_year AS result
 ```

 Result:

 ```response
-┌─plus(date, interval_week)─┬─plus(date, interval_to_week)─┐
-│                2019-01-08 │                   2019-01-08 │
-└───────────────────────────┴──────────────────────────────┘
+┌─────result─┐
+│ 2025-06-15 │
+└────────────┘
+```
+
+## toIntervalQuarter
+
+Returns an interval of `n` quarters of data type [IntervalQuarter](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalQuarter(n)
+```
+
+**Arguments**
+
+- `n` — Number of quarters. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` quarters. [IntervalQuarter](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDate('2024-06-15') AS date,
+    toIntervalQuarter(1) AS interval_to_quarter
+SELECT date + interval_to_quarter AS result
+```
+
+Result:
+
+```response
+┌─────result─┐
+│ 2024-09-15 │
+└────────────┘
+```
+
+## toIntervalMonth
+
+Returns an interval of `n` months of data type [IntervalMonth](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalMonth(n)
+```
+
+**Arguments**
+
+- `n` — Number of months. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` months. [IntervalMonth](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDate('2024-06-15') AS date,
+    toIntervalMonth(1) AS interval_to_month
+SELECT date + interval_to_month AS result
+```
+
+Result:
+
+```response
+┌─────result─┐
+│ 2024-07-15 │
+└────────────┘
+```
+
+## toIntervalWeek
+
+Returns an interval of `n` weeks of data type [IntervalWeek](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalWeek(n)
+```
+
+**Arguments**
+
+- `n` — Number of weeks. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` weeks. [IntervalWeek](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDate('2024-06-15') AS date,
+    toIntervalWeek(1) AS interval_to_week
+SELECT date + interval_to_week AS result
+```
+
+Result:
+
+```response
+┌─────result─┐
+│ 2024-06-22 │
+└────────────┘
+```
+
+## toIntervalDay
+
+Returns an interval of `n` days of data type [IntervalDay](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalDay(n)
+```
+
+**Arguments**
+
+- `n` — Number of days. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` days. [IntervalDay](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDate('2024-06-15') AS date,
+    toIntervalDay(5) AS interval_to_days
+SELECT date + interval_to_days AS result
+```
+
+Result:
+
+```response
+┌─────result─┐
+│ 2024-06-20 │
+└────────────┘
+```
+
+## toIntervalHour
+
+Returns an interval of `n` hours of data type [IntervalHour](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalHour(n)
+```
+
+**Arguments**
+
+- `n` — Number of hours. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` hours. [IntervalHour](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDate('2024-06-15') AS date,
+    toIntervalHour(12) AS interval_to_hours
+SELECT date + interval_to_hours AS result
+```
+
+Result:
+
+```response
+┌──────────────result─┐
+│ 2024-06-15 12:00:00 │
+└─────────────────────┘
+```
+
+## toIntervalMinute
+
+Returns an interval of `n` minutes of data type [IntervalMinute](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalMinute(n)
+```
+
+**Arguments**
+
+- `n` — Number of minutes. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` minutes. [IntervalMinute](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDate('2024-06-15') AS date,
+    toIntervalMinute(12) AS interval_to_minutes
+SELECT date + interval_to_minutes AS result
+```
+
+Result:
+
+```response
+┌──────────────result─┐
+│ 2024-06-15 00:12:00 │
+└─────────────────────┘
+```
+
+## toIntervalSecond
+
+Returns an interval of `n` seconds of data type [IntervalSecond](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalSecond(n)
+```
+
+**Arguments**
+
+- `n` — Number of seconds. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` seconds. [IntervalSecond](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDate('2024-06-15') AS date,
+    toIntervalSecond(30) AS interval_to_seconds
+SELECT date + interval_to_seconds AS result
+```
+
+Result:
+
+```response
+┌──────────────result─┐
+│ 2024-06-15 00:00:30 │
+└─────────────────────┘
+```
+
+## toIntervalMillisecond
+
+Returns an interval of `n` milliseconds of data type [IntervalMillisecond](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalMillisecond(n)
+```
+
+**Arguments**
+
+- `n` — Number of milliseconds. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` milliseconds. [IntervalMilliseconds](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDateTime('2024-06-15') AS date,
+    toIntervalMillisecond(30) AS interval_to_milliseconds
+SELECT date + interval_to_milliseconds AS result
+```
+
+Result:
+
+```response
+┌──────────────────result─┐
+│ 2024-06-15 00:00:00.030 │
+└─────────────────────────┘
+```
+
+## toIntervalMicrosecond
+
+Returns an interval of `n` microseconds of data type [IntervalMicrosecond](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalMicrosecond(n)
+```
+
+**Arguments**
+
+- `n` — Number of microseconds. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` microseconds. [IntervalMicrosecond](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDateTime('2024-06-15') AS date,
+    toIntervalMicrosecond(30) AS interval_to_microseconds
+SELECT date + interval_to_microseconds AS result
+```
+
+Result:
+
+```response
+┌─────────────────────result─┐
+│ 2024-06-15 00:00:00.000030 │
+└────────────────────────────┘
+```
+
+## toIntervalNanosecond
+
+Returns an interval of `n` nanoseconds of data type [IntervalNanosecond](../data-types/special-data-types/interval.md).
+
+**Syntax**
+
+``` sql
+toIntervalNanosecond(n)
+```
+
+**Arguments**
+
+- `n` — Number of nanoseconds. Integer numbers or string representations thereof, and float numbers. [(U)Int*](../data-types/int-uint.md)/[Float*](../data-types/float.md)/[String](../data-types/string.md).
+
+**Returned values**
+
+- Interval of `n` nanoseconds. [IntervalNanosecond](../data-types/special-data-types/interval.md).
+
+**Example**
+
+Query:
+
+``` sql
+WITH
+    toDateTime('2024-06-15') AS date,
+    toIntervalNanosecond(30) AS interval_to_nanoseconds
+SELECT date + interval_to_nanoseconds AS result
+```
+
+Result:
+
+```response
+┌────────────────────────result─┐
+│ 2024-06-15 00:00:00.000000030 │
+└───────────────────────────────┘
 ```

 ## parseDateTime
--- a/utils/check-style/aspell-ignore/en/aspell-dict.txt
+++ b/utils/check-style/aspell-ignore/en/aspell-dict.txt
@ -385,6 +385,18 @@ IntelliJ
 IntelliSense
 InterserverConnection
 InterserverThreads
+IntervalDay
+IntervalHour
+IntervalMicrosecond
+IntervalMillisecond
+IntervalMilliseconds
+IntervalMinute
+IntervalMonth
+IntervalNanosecond
+IntervalQuarter
+IntervalSecond
+IntervalWeek
+IntervalYear
 IsPentagon
 IsResClassIII
 IsValid
@ -2740,6 +2752,17 @@ toISOWeek
 toISOYear
 toInt
 toInterval
+toIntervalDay
+toIntervalHour
+toIntervalMicrosecond
+toIntervalMillisecond
+toIntervalMinute
+toIntervalMonth
+toIntervalNanosecond
+toIntervalQuarter
+toIntervalSecond
+toIntervalWeek
+toIntervalYear
 toJSONString
 toLastDayOfMonth
 toLastDayOfWeek