DOCS-163: Docs for the Interval data type and the INTERVAL operator. (#7452)

* Typo fix. * Links fix. * Fixed links in docs. * More fixes. * Link fixes. * CLICKHOUSEDOCS-163: INTERVAL related articles * CLICKHOUSEDOCS-163: build fixes. * Update docs/en/data_types/special_data_types/interval.md Co-Authored-By: Ivan Blinkov <github@blinkov.ru> * CLICKHOUSEDOCS-163: Update after the review.
2024-11-24 08:32:02 +00:00 · 2019-11-06 15:14:41 +03:00 · 2019-11-06 15:14:41 +03:00 · 6ae3998fe7
commit 6ae3998fe7
parent 233212ac68
10 changed files with 203 additions and 4 deletions
--- a/docs/en/data_types/special_data_types/interval.md
+++ b/docs/en/data_types/special_data_types/interval.md
@ -0,0 +1,74 @@
+# Interval {#data-type-interval}
+
+The family of data types representing time and date intervals. The resulting types of the [INTERVAL](../../query_language/operators.md#operator-interval) operator.
+
+!!! warning "Warning"
+    You can't use the `Interval` data types for storing values in tables.
+
+Structure:
+
+- Time interval as unsigned integer value.
+- Type of an interval.
+
+Supported interval types:
+
+- `SECOND`
+- `MINUTE`
+- `HOUR`
+- `DAY`
+- `WEEK`
+- `MONTH`
+- `QUARTER`
+- `YEAR`
+
+For each interval type, there is the separated data type. For example, the `DAY` interval is expressed as the `IntervalDay` data type:
+
+```sql
+SELECT toTypeName(INTERVAL 4 DAY)
+```
+```text
+┌─toTypeName(toIntervalDay(4))─┐
+│ IntervalDay                  │
+└──────────────────────────────┘
+```
+
+## Usage Remarks {#data-type-interval-usage-remarks}
+
+You can use `Interval`-type values in arithmetical operations with [Date](../../data_types/date.md) and [DateTime](../../data_types/datetime.md)-type values. For example, you can add 4 days to the current time:
+
+```sql
+SELECT now() as current_date_time, current_date_time + INTERVAL 4 DAY
+```
+```text
+┌───current_date_time─┬─plus(now(), toIntervalDay(4))─┐
+│ 2019-10-23 10:58:45 │           2019-10-27 10:58:45 │
+└─────────────────────┴───────────────────────────────┘
+```
+
+Intervals of different types can't be combined. You can't use intervals like `4 DAY 1 HOUR`, express intervals in the units that smaller or equal the the smallest unit of the interval. For example, `1 day and an hour` interval can be expressed as `25 HOUR` or `90000 SECOND`.
+
+You can't perform arithmetical operations with the `Interval`-type values, but you can add intervals of different types consequently to some value. For example:
+
+```sql
+SELECT now() AS current_date_time, current_date_time + INTERVAL 4 DAY + INTERVAL 3 HOUR
+```
+```text
+┌───current_date_time─┬─plus(plus(now(), toIntervalDay(4)), toIntervalHour(3))─┐
+│ 2019-10-23 11:16:28 │                                    2019-10-27 14:16:28 │
+└─────────────────────┴────────────────────────────────────────────────────────┘
+```
+
+The following query causes the exception:
+
+```sql
+select now() AS current_date_time, current_date_time + (INTERVAL 4 DAY + INTERVAL 3 HOUR)
+```
+```text
+Received exception from server (version 19.14.1):
+Code: 43. DB::Exception: Received from localhost:9000. DB::Exception: Wrong argument types for function plus: if one argument is Interval, then another must be Date or DateTime.. 
+```
+
+## See Also
+
+- [INTERVAL](../../query_language/operators.md#operator-interval) operator
+- [toInterval](../../query_language/functions/type_conversion_functions.md#function-tointerval) type convertion functions
--- a/docs/en/query_language/functions/type_conversion_functions.md
+++ b/docs/en/query_language/functions/type_conversion_functions.md
@ -321,7 +321,7 @@ SELECT toTypeName(CAST(x, 'Nullable(UInt16)')) FROM t_null
 └─────────────────────────────────────────┘
 ```

-## toInterval(Year|Quarter|Month|Week|Day|Hour|Minute|Second)
+## toInterval(Year|Quarter|Month|Week|Day|Hour|Minute|Second) {#function-tointerval}

 Converts a Number type argument to a Interval type (duration).
 The interval type is actually very useful, you can use this type of data to perform arithmetic operations directly with Date or DateTime. At the same time, ClickHouse provides a more convenient syntax for declaring Interval type data. For example:
--- a/docs/en/query_language/operators.md
+++ b/docs/en/query_language/operators.md
@ -65,7 +65,9 @@ Groups of operators are listed in order of priority (the higher it is in the lis

 `a GLOBAL NOT IN ...` – The `globalNotIn(a, b) function.`

-## Operator for Working With Dates and Times {#operators-datetime}
+## Operators for Working with Dates and Times {#operators-datetime}
+
+### EXTRACT {#operator-extract}

 ```sql
 EXTRACT(part FROM date);
@ -120,7 +122,6 @@ SELECT
 FROM test.Orders;
 ```
 ```text
-
 ┌─OrderYear─┬─OrderMonth─┬─OrderDay─┬─OrderHour─┬─OrderMinute─┬─OrderSecond─┐
 │      2008 │         10 │       11 │        13 │          23 │          44 │
 └───────────┴────────────┴──────────┴───────────┴─────────────┴─────────────┘
@ -128,6 +129,39 @@ FROM test.Orders;

 You can see more examples in [tests](https://github.com/ClickHouse/ClickHouse/blob/master/dbms/tests/queries/0_stateless/00619_extract.sql).

+### INTERVAL {#operator-interval}
+
+Creates an [Interval](../data_types/special_data_types/interval.md)-type value that should be used in arithmetical operations with [Date](../data_types/date.md) and [DateTime](../data_types/datetime.md)-type values.
+
+Types of intervals:
+- `SECOND`
+- `MINUTE`
+- `HOUR`
+- `DAY`
+- `WEEK`
+- `MONTH`
+- `QUARTER`
+- `YEAR`
+
+!!! warning "Warning"
+    Intervals of different types can't be combined. You can't use the expressions like `INTERVAL 4 DAY 1 HOUR`. Express intervals in the units that smaller or equal the the smallest unit of the interval, for example `INTERVAL 25 HOUR`. Also you can use consequtive operations like in the example below.
+
+Example:
+
+```sql
+SELECT now() AS current_date_time, current_date_time + INTERVAL 4 DAY + INTERVAL 3 HOUR
+```
+```text
+┌───current_date_time─┬─plus(plus(now(), toIntervalDay(4)), toIntervalHour(3))─┐
+│ 2019-10-23 11:16:28 │                                    2019-10-27 14:16:28 │
+└─────────────────────┴────────────────────────────────────────────────────────┘
+```
+
+**See Also**
+
+- [Interval](../data_types/special_data_types/interval.md) data type
+- [toInterval](functions/type_conversion_functions.md#function-tointerval) type convertion functions
+
 ## Logical Negation Operator

 `NOT a` The `not(a) function.`
--- a/docs/fa/data_types/special_data_types/interval.md
+++ b/docs/fa/data_types/special_data_types/interval.md
@ -0,0 +1 @@
+../../../en/data_types/special_data_types/interval.md
--- a/docs/toc_en.yml
+++ b/docs/toc_en.yml
@ -172,6 +172,7 @@ nav:
      - 'Expression': 'data_types/special_data_types/expression.md'
      - 'Set': 'data_types/special_data_types/set.md'
      - 'Nothing': 'data_types/special_data_types/nothing.md'
+      - 'Interval': 'data_types/special_data_types/interval.md'
    - 'Domains':
      - 'Overview': 'data_types/domains/overview.md'
      - 'IPv4': 'data_types/domains/ipv4.md'
--- a/docs/toc_fa.yml
+++ b/docs/toc_fa.yml
@ -57,6 +57,7 @@ nav:
    - 'Expression': 'data_types/special_data_types/expression.md'
    - 'Set': 'data_types/special_data_types/set.md'
    - 'Nothing': 'data_types/special_data_types/nothing.md'
+    - 'Interval': 'data_types/special_data_types/interval.md'    
  - 'Domains':
    - 'Overview': 'data_types/domains/overview.md'
    - 'IPv4': 'data_types/domains/ipv4.md'
--- a/docs/toc_zh.yml
+++ b/docs/toc_zh.yml
@ -56,6 +56,7 @@ nav:
    - 'Expression': 'data_types/special_data_types/expression.md'
    - 'Set': 'data_types/special_data_types/set.md'
    - 'Nothing': 'data_types/special_data_types/nothing.md'
+    - 'Interval': 'data_types/special_data_types/interval.md'    
  - 'Domain类型':
    - '介绍': 'data_types/domains/overview.md'
    - 'IPv4': 'data_types/domains/ipv4.md'
--- a/docs/zh/data_types/special_data_types/interval.md
+++ b/docs/zh/data_types/special_data_types/interval.md
@ -0,0 +1 @@
+../../../en/data_types/special_data_types/interval.md
--- a/docs/zh/query_language/functions/type_conversion_functions.md
+++ b/docs/zh/query_language/functions/type_conversion_functions.md
@ -145,7 +145,7 @@ SELECT toTypeName(CAST(x, 'Nullable(UInt16)')) FROM t_null
 └─────────────────────────────────────────┘
 ```

-## toIntervalYear, toIntervalQuarter, toIntervalMonth, toIntervalWeek, toIntervalDay, toIntervalHour, toIntervalMinute, toIntervalSecond
+## toIntervalYear, toIntervalQuarter, toIntervalMonth, toIntervalWeek, toIntervalDay, toIntervalHour, toIntervalMinute, toIntervalSecond {#function-tointerval}

 将数字类型参数转换为Interval类型（时间区间）。
 Interval类型实际上是非常有用的，您可以使用此类型的数据直接与Date或DateTime执行算术运算。同时，ClickHouse为Interval类型数据的声明提供了更方便的语法。例如：
--- a/docs/zh/query_language/operators.md
+++ b/docs/zh/query_language/operators.md
@ -82,6 +82,92 @@

 条件运算符会先计算表达式b和表达式c的值，再根据表达式a的真假，返回相应的值。如果表达式b和表达式c是 [arrayJoin()](functions/array_join.md#functions_arrayjoin) 函数，则不管表达式a是真是假，每行都会被复制展开。

+
+## Operators for Working with Dates and Times {#operators-datetime}
+
+### EXTRACT {#operator-extract}
+
+```sql
+EXTRACT(part FROM date);
+```
+
+Extracts a part from a given date. For example, you can retrieve a month from a given date, or a second from a time.
+
+The `part` parameter specifies which part of the date to retrieve. The following values are available:
+
+- `DAY` — The day of the month. Possible values: 1–31.
+- `MONTH` — The number of a month. Possible values: 1–12.
+- `YEAR` — The year.
+- `SECOND` — The second. Possible values: 0–59.
+- `MINUTE` — The minute. Possible values: 0–59.
+- `HOUR` — The hour. Possible values: 0–23.
+
+The `part` parameter is case-insensitive.
+
+The `date` parameter specifies the date or the time to process. Either [Date](../data_types/date.md) or [DateTime](../data_types/datetime.md) type is supported.
+
+Examples:
+
+```sql
+SELECT EXTRACT(DAY FROM toDate('2017-06-15'));
+SELECT EXTRACT(MONTH FROM toDate('2017-06-15'));
+SELECT EXTRACT(YEAR FROM toDate('2017-06-15'));
+```
+
+In the following example we create a table and insert into it a value with the `DateTime` type.
+
+```sql
+CREATE TABLE test.Orders
+(
+    OrderId UInt64,
+    OrderName String,
+    OrderDate DateTime
+)
+ENGINE = Log;
+```
+
+```sql
+INSERT INTO test.Orders VALUES (1, 'Jarlsberg Cheese', toDateTime('2008-10-11 13:23:44'));
+```
+```sql
+SELECT
+    toYear(OrderDate) AS OrderYear,
+    toMonth(OrderDate) AS OrderMonth,
+    toDayOfMonth(OrderDate) AS OrderDay,
+    toHour(OrderDate) AS OrderHour,
+    toMinute(OrderDate) AS OrderMinute,
+    toSecond(OrderDate) AS OrderSecond
+FROM test.Orders;
+```
+```text
+┌─OrderYear─┬─OrderMonth─┬─OrderDay─┬─OrderHour─┬─OrderMinute─┬─OrderSecond─┐
+│      2008 │         10 │       11 │        13 │          23 │          44 │
+└───────────┴────────────┴──────────┴───────────┴─────────────┴─────────────┘
+```
+
+You can see more examples in [tests](https://github.com/ClickHouse/ClickHouse/blob/master/dbms/tests/queries/0_stateless/00619_extract.sql).
+
+### INTERVAL {#operator-interval}
+
+Creates an [Interval](../data_types/special_data_types/interval.md)-type value that should be used in arithmetical operations with [Date](../data_types/date.md) and [DateTime](../data_types/datetime.md)-type values.
+
+Example:
+
+```sql
+SELECT now() AS current_date_time, current_date_time + INTERVAL 4 DAY + INTERVAL 3 HOUR
+```
+```text
+┌───current_date_time─┬─plus(plus(now(), toIntervalDay(4)), toIntervalHour(3))─┐
+│ 2019-10-23 11:16:28 │                                    2019-10-27 14:16:28 │
+└─────────────────────┴────────────────────────────────────────────────────────┘
+```
+
+**See Also**
+
+- [Interval](../data_types/special_data_types/interval.md) data type
+- [toInterval](functions/type_conversion_functions.md#function-tointerval) type convertion functions
+
+
 ## CASE条件表达式 {#operator_case}

 ``` sql
				`@ -0,0 +1 @@`
				`../../../en/data_types/special_data_types/interval.md`