DOCS-163: INTERVAL. EN review, RU translation for #7452 (#7740)

* Update operators.md (#70) * Update operators.md (#71) * CLICKHOUSEDOCS-163: EN review, RU translation. * CLICKHOUSEDOCS-163: Fix * Update docs/ru/data_types/special_data_types/interval.md Co-Authored-By: Ivan Blinkov <github@blinkov.ru> * Update docs/ru/query_language/operators.md Co-Authored-By: Ivan Blinkov <github@blinkov.ru> * Update docs/ru/data_types/special_data_types/interval.md Co-Authored-By: Ivan Blinkov <github@blinkov.ru> * CLICKHOUSEDOCS-163: Clarification.
2024-11-21 15:12:02 +00:00 · 2019-12-06 15:22:55 +03:00 · 2019-12-06 15:22:55 +03:00 · fe926f3c06
commit fe926f3c06
parent aeaac4d573
7 changed files with 215 additions and 39 deletions
--- a/docs/en/data_types/special_data_types/interval.md
+++ b/docs/en/data_types/special_data_types/interval.md
@ -3,11 +3,11 @@
 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.
+    You can't use `Interval` data types for storing values in tables.

 Structure:

- Time interval as unsigned integer value.
+- Time interval as an unsigned integer value.
 - Type of an interval.

 Supported interval types:
@ -21,7 +21,7 @@ Supported interval types:
 - `QUARTER`
 - `YEAR`

-For each interval type, there is the separated data type. For example, the `DAY` interval is expressed as the `IntervalDay` data type:
+For each interval type, there is a separate data type. For example, the `DAY` interval is expressed as the `IntervalDay` data type:

 ```sql
 SELECT toTypeName(INTERVAL 4 DAY)
@ -45,9 +45,9 @@ SELECT now() as current_date_time, current_date_time + INTERVAL 4 DAY
 └─────────────────────┴───────────────────────────────┘
 ```

-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`.
+Intervals with different types can't be combined. You can't use intervals like `4 DAY 1 HOUR`. Express intervals in units that are smaller or equal to the smallest unit of the interval, for example, the interval `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:
+You can't perform arithmetical operations with `Interval`-type values, but you can add intervals of different types consequently to values in `Date` or `DateTime` data types. For example:

 ```sql
 SELECT now() AS current_date_time, current_date_time + INTERVAL 4 DAY + INTERVAL 3 HOUR
@ -58,7 +58,7 @@ SELECT now() AS current_date_time, current_date_time + INTERVAL 4 DAY + INTERVAL
 └─────────────────────┴────────────────────────────────────────────────────────┘
 ```

-The following query causes the exception:
+The following query causes an exception:

 ```sql
 select now() AS current_date_time, current_date_time + (INTERVAL 4 DAY + INTERVAL 3 HOUR)
--- a/docs/en/query_language/functions/type_conversion_functions.md
+++ b/docs/en/query_language/functions/type_conversion_functions.md
@ -351,8 +351,30 @@ SELECT toTypeName(CAST(x, 'Nullable(UInt16)')) FROM t_null

 ## 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:
+Converts a Number type argument to an [Interval](../../data_types/special_data_types/interval.md) data type.
+
+**Syntax**
+
+```sql
+toIntervalSecond(number)
+toIntervalMinute(number)
+toIntervalHour(number)
+toIntervalDay(number)
+toIntervalWeek(number)
+toIntervalMonth(number)
+toIntervalQuarter(number)
+toIntervalYear(number)
+```
+
+**Parameters**
+
+- `number` — Duration of interval. Positive integer number.
+
+**Returned values**
+
+- The value in `Interval` data type.
+
+**Example**

 ```sql
 WITH
--- a/docs/en/query_language/operators.md
+++ b/docs/en/query_language/operators.md
@ -1,13 +1,13 @@
 # Operators

-All operators are transformed to the corresponding functions at the query parsing stage, in accordance with their precedence and associativity.
+All operators are transformed to their corresponding functions at the query parsing stage in accordance with their precedence and associativity.
 Groups of operators are listed in order of priority (the higher it is in the list, the earlier the operator is connected to its arguments).

 ## Access Operators

-`a[N]` Access to an element of an array; ` arrayElement(a, N) function`.
+`a[N]` – Access to an element of an array. The `arrayElement(a, N)` function.

-`a.N` – Access to a tuple element; `tupleElement(a, N)` function.
+`a.N` – Access to a tuple element. The `tupleElement(a, N)` function.

 ## Numeric Negation Operator

@ -15,55 +15,55 @@ Groups of operators are listed in order of priority (the higher it is in the lis

 ## Multiplication and Division Operators

-`a * b`  – The `multiply (a, b) function.`
+`a * b` – The `multiply (a, b)` function.

-`a / b`  – The ` divide(a, b) function.`
+`a / b` – The `divide(a, b)` function.

-`a % b` – The `modulo(a, b) function.`
+`a % b` – The `modulo(a, b)` function.

 ## Addition and Subtraction Operators

-`a + b` – The `plus(a, b) function.`
+`a + b` – The `plus(a, b)` function.

-`a - b`  – The `minus(a, b) function.`
+`a - b` – The `minus(a, b)` function.

 ## Comparison Operators

-`a = b` – The `equals(a, b) function.`
+`a = b` – The `equals(a, b)` function.

-`a == b` – The ` equals(a, b) function.`
+`a == b` – The `equals(a, b)` function.

-`a != b` – The `notEquals(a, b) function.`
+`a != b` – The `notEquals(a, b)` function.

-`a <> b` – The `notEquals(a, b) function.`
+`a <> b` – The `notEquals(a, b)` function.

-`a <= b` – The `lessOrEquals(a, b) function.`
+`a <= b` – The `lessOrEquals(a, b)` function.

-`a >= b` – The `greaterOrEquals(a, b) function.`
+`a >= b` – The `greaterOrEquals(a, b)` function.

-`a < b` – The `less(a, b) function.`
+`a < b` – The `less(a, b)` function.

-`a > b` – The `greater(a, b) function.`
+`a > b` – The `greater(a, b)` function.

-`a LIKE s` – The `like(a, b) function.`
+`a LIKE s` – The `like(a, b)` function.

-`a NOT LIKE s` – The `notLike(a, b) function.`
+`a NOT LIKE s` – The `notLike(a, b)` function.

-`a BETWEEN b AND c` – The same as `a >= b AND a <= c.`
+`a BETWEEN b AND c` – The same as `a >= b AND a <= c`.

-`a NOT BETWEEN b AND c` – The same as `a < b OR a > c.`
+`a NOT BETWEEN b AND c` – The same as `a < b OR a > c`.

 ## Operators for Working With Data Sets

-*See the section [IN operators](select.md#select-in-operators).*
+*See [IN operators](select.md#select-in-operators).*

-`a IN ...` – The `in(a, b) function`
+`a IN ...` – The `in(a, b)` function.

-`a NOT IN ...` – The `notIn(a, b) function.`
+`a NOT IN ...` – The `notIn(a, b)` function.

-`a GLOBAL IN ...` – The `globalIn(a, b) function.`
+`a GLOBAL IN ...` – The `globalIn(a, b)` function.

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

 ## Operators for Working with Dates and Times {#operators-datetime}

@ -144,7 +144,7 @@ Types of intervals:
 - `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.
+    Intervals with different types can't be combined. You can't use expressions like `INTERVAL 4 DAY 1 HOUR`. Express intervals in units that are smaller or equal the the smallest unit of the interval, for example `INTERVAL 25 HOUR`. You can use consequtive operations like in the example below.

 Example:

@ -164,19 +164,19 @@ SELECT now() AS current_date_time, current_date_time + INTERVAL 4 DAY + INTERVAL

 ## Logical Negation Operator

-`NOT a` The `not(a) function.`
+`NOT a` – The `not(a)` function.

 ## Logical AND Operator

-`a AND b` – The`and(a, b) function.`
+`a AND b` – The`and(a, b)` function.

 ## Logical OR Operator

-`a OR b` – The `or(a, b) function.`
+`a OR b` – The `or(a, b)` function.

 ## Conditional Operator

-`a ? b : c` – The `if(a, b, c) function.`
+`a ? b : c` – The `if(a, b, c)` function.

 Note:

--- a/docs/ru/data_types/special_data_types/interval.md
+++ b/docs/ru/data_types/special_data_types/interval.md
@ -0,0 +1,74 @@
+# Interval {#data-type-interval}
+
+Семейство типов данных, представляющих интервалы дат и времени. Оператор [INTERVAL](../../query_language/operators.md#operator-interval) возвращает значения этих типов.
+
+!!! warning "Внимание"
+    Нельзя использовать типы данных `Interval` для хранения данных в таблице.
+
+Структура:
+
+- Интервал времени в виде положительного целого числа.
+- Тип интервала.
+
+Поддержанные типы интервалов:
+
+- `SECOND`
+- `MINUTE`
+- `HOUR`
+- `DAY`
+- `WEEK`
+- `MONTH`
+- `QUARTER`
+- `YEAR`
+
+Каждому типу интервала соответствует отдельный тип данных. Например, тип данных `IntervalDay` соответствует интервалу `DAY`:
+
+```sql
+SELECT toTypeName(INTERVAL 4 DAY)
+```
+```text
+┌─toTypeName(toIntervalDay(4))─┐
+│ IntervalDay                  │
+└──────────────────────────────┘
+```
+
+## Использование {#data-type-interval-usage-remarks}
+
+Значения типов `Interval` можно использовать в арифметических операциях со значениями типов [Date](../../data_types/date.md) и [DateTime](../../data_types/datetime.md). Например, можно добавить 4 дня к текущей дате:
+
+```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 │
+└─────────────────────┴───────────────────────────────┘
+```
+
+Нельзя объединять интервалы различных типов. Нельзя использовать интервалы вида `4 DAY 1 HOUR`. Вместо этого выражайте интервал в единицах меньших или равных минимальной единице интервала, например, интервал "1 день и 1 час" можно выразить как `25 HOUR` или `90000 SECOND`.
+
+Арифметические операции со значениями типов `Interval` не доступны, однако можно последовательно добавлять различные интервалы к значениям типов `Date` и `DateTime`. Например:
+
+```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 │
+└─────────────────────┴────────────────────────────────────────────────────────┘
+```
+
+Следующий запрос приведёт к генерированию исключения:
+
+```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.. 
+```
+
+## Смотрите также
+
+- Оператор[INTERVAL](../../query_language/operators.md#operator-interval)
+- Функция приведения типа [toInterval](../../query_language/functions/type_conversion_functions.md#function-tointerval)
--- a/docs/ru/query_language/functions/type_conversion_functions.md
+++ b/docs/ru/query_language/functions/type_conversion_functions.md
@ -349,4 +349,48 @@ SELECT toTypeName(CAST(x, 'Nullable(UInt16)')) FROM t_null
 └─────────────────────────────────────────┘
 ```

+## toInterval(Year|Quarter|Month|Week|Day|Hour|Minute|Second) {#function-tointerval}
+
+Приводит аргумент из числового типа данных к типу данных [IntervalType](../../data_types/special_data_types/interval.md).
+
+**Синтксис**
+
+```sql
+toIntervalSecond(number)
+toIntervalMinute(number)
+toIntervalHour(number)
+toIntervalDay(number)
+toIntervalWeek(number)
+toIntervalMonth(number)
+toIntervalQuarter(number)
+toIntervalYear(number)
+```
+
+**Параметры**
+
+- `number` — длительность интервала. Положительное целое число.
+
+**Возвращаемые значения**
+
+- Значение с типом данных `Interval`.
+
+**Пример**
+
+```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
+```
+
+```text
+┌─plus(date, interval_week)─┬─plus(date, interval_to_week)─┐
+│                2019-01-08 │                   2019-01-08 │
+└───────────────────────────┴──────────────────────────────┘
+```
+
+
 [Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/functions/type_conversion_functions/) <!--hide-->
--- a/docs/ru/query_language/operators.md
+++ b/docs/ru/query_language/operators.md
@ -67,6 +67,8 @@

 ## Оператор для работы с датами и временем {#operators-datetime}

+### EXTRACT
+
 ```sql
 EXTRACT(part FROM date);
 ```
@ -128,6 +130,39 @@ FROM test.Orders;

 Больше примеров приведено в [тестах](https://github.com/ClickHouse/ClickHouse/blob/master/dbms/tests/queries/0_stateless/00619_extract.sql).

+### INTERVAL {#operator-interval}
+
+Создаёт значение типа [Interval](../data_types/special_data_types/interval.md) которое должно использоваться в арифметических операциях со значениями типов [Date](../data_types/date.md) и [DateTime](../data_types/datetime.md).
+
+Типы интервалов:
+- `SECOND`
+- `MINUTE`
+- `HOUR`
+- `DAY`
+- `WEEK`
+- `MONTH`
+- `QUARTER`
+- `YEAR`
+
+!!! warning "Внимание"
+    Интервалы различных типов нельзя объединять. Нельзя использовать выражения вида `INTERVAL 4 DAY 1 HOUR`. Вместо этого интервалы можно выразить в единицах меньших или равных наименьшей единице интервала, Например, `INTERVAL 25 HOUR`. Также можно выполнять последовательные операции как показано в примере ниже.
+
+Пример:
+
+```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 │
+└─────────────────────┴────────────────────────────────────────────────────────┘
+```
+
+**Смотрите также**
+
+- Тип данных [Interval](../data_types/special_data_types/interval.md)
+- Функции преобразования типов [toInterval](functions/type_conversion_functions.md#function-tointerval)
+
 ## Оператор логического отрицания

 `NOT a` - функция `not(a)`
--- a/docs/toc_ru.yml
+++ b/docs/toc_ru.yml
@ -174,6 +174,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'