Merge pull request #27919 from adevyatova/annadevyatova-DOCSUP-11585-datetime32

DOCSUP-11585: Document Date32 data type

docs/en/sql-reference/data-types/date.md

@@ -9,9 +9,9 @@ A date. Stored in two bytes as the number of days since 1970-01-01 (unsigned). A
 
 The date value is stored without the time zone.
 
-## Examples {#examples}
+**Example**
 
-**1.** Creating a table with a `DateTime`-type column and inserting data into it:
+Creating a table with a `Date`-type column and inserting data into it:
 
 ``` sql
 CREATE TABLE dt
@@ -23,10 +23,7 @@ ENGINE = TinyLog;
 ```
 
 ``` sql
-INSERT INTO dt Values (1546300800, 1), ('2019-01-01', 2);
+INSERT INTO dt VALUES (1546300800, 1), ('2019-01-01', 2);
-```
-
-``` sql
 SELECT * FROM dt;
 ```
 
@@ -37,11 +34,8 @@ SELECT * FROM dt;
 └────────────┴──────────┘
 ```
 
-## See Also {#see-also}
+**See Also**
 
 -   [Functions for working with dates and times](../../sql-reference/functions/date-time-functions.md)
 -   [Operators for working with dates and times](../../sql-reference/operators/index.md#operators-datetime)
 -   [`DateTime` data type](../../sql-reference/data-types/datetime.md)
-
-
-[Original article](https://clickhouse.tech/docs/en/data_types/date/) <!--hide-->

docs/en/sql-reference/data-types/date32.md

@@ -0,0 +1,40 @@
+---
+toc_priority: 48
+toc_title: Date32
+---
+
+# Date32 {#data_type-datetime32}
+
+A date. Supports the date range same with [Datetime64](../../sql-reference/data-types/datetime64.md). Stored in four bytes as the number of days since 1925-01-01. Allows storing values till 2283-11-11. 
+
+**Examples**
+
+Creating a table with a `Date32`-type column and inserting data into it:
+
+``` sql
+CREATE TABLE new
+(
+    `timestamp` Date32,
+    `event_id` UInt8
+)
+ENGINE = TinyLog;
+```
+
+``` sql
+INSERT INTO new VALUES (4102444800, 1), ('2100-01-01', 2);
+SELECT * FROM new;
+```
+
+``` text
+┌──timestamp─┬─event_id─┐
+│ 2100-01-01 │        1 │
+│ 2100-01-01 │        2 │
+└────────────┴──────────┘
+```
+
+**See Also**
+
+-   [toDate32](../../sql-reference/functions/type-conversion-functions.md#todate32)
+-   [toDate32OrZero](../../sql-reference/functions/type-conversion-functions.md#todate32-or-zero)
+-   [toDate32OrNull](../../sql-reference/functions/type-conversion-functions.md#todate32-or-null) 
+

docs/en/sql-reference/data-types/datetime64.md

@@ -17,7 +17,7 @@ DateTime64(precision, [timezone])
 
 Internally, stores data as a number of ‘ticks’ since epoch start (1970-01-01 00:00:00 UTC) as Int64. The tick resolution is determined by the precision parameter. Additionally, the `DateTime64` type can store time zone that is the same for the entire column, that affects how the values of the `DateTime64` type values are displayed in text format and how the values specified as strings are parsed (‘2020-01-01 05:00:01.000’). The time zone is not stored in the rows of the table (or in resultset), but is stored in the column metadata. See details in [DateTime](../../sql-reference/data-types/datetime.md).
 
-Supported range from January 1, 1925 till December 31, 2283.
+Supported range from January 1, 1925 till November 11, 2283.
 
 ## Examples {#examples}
 

docs/en/sql-reference/functions/type-conversion-functions.md

@@ -152,6 +152,104 @@ Alias: `DATE`.
 
 ## toDateTimeOrNull {#todatetimeornull}
 
+## toDate32 {#todate32}
+
+Converts the argument to the [Date32](../../sql-reference/data-types/date32.md) data type. If the value is outside the range returns the border values supported by `Date32`. If the argument has [Date](../../sql-reference/data-types/date.md) type, borders of `Date` are taken into account.
+
+**Syntax** 
+
+``` sql
+toDate32(expr)
+```
+
+**Arguments** 
+
+-   `expr` — The value. [String](../../sql-reference/data-types/string.md), [UInt32](../../sql-reference/data-types/int-uint.md) or [Date](../../sql-reference/data-types/date.md).
+
+**Returned value**
+
+-   A calendar date.
+
+Type: [Date32](../../sql-reference/data-types/date32.md).
+
+**Example**
+
+1. The value is within the range:
+
+``` sql
+SELECT toDate32('1955-01-01') AS value, toTypeName(value);
+```
+
+``` text
+┌──────value─┬─toTypeName(toDate32('1925-01-01'))─┐
+│ 1955-01-01 │ Date32                             │
+└────────────┴────────────────────────────────────┘
+```
+
+2. The value is outside the range:
+
+``` sql
+SELECT toDate32('1924-01-01') AS value, toTypeName(value);
+```
+
+``` text
+┌──────value─┬─toTypeName(toDate32('1925-01-01'))─┐
+│ 1925-01-01 │ Date32                             │
+└────────────┴────────────────────────────────────┘
+```
+
+3. With `Date`-type argument:
+
+``` sql
+SELECT toDate32(toDate('1924-01-01')) AS value, toTypeName(value);
+```
+
+``` text
+┌──────value─┬─toTypeName(toDate32(toDate('1924-01-01')))─┐
+│ 1970-01-01 │ Date32                                     │
+└────────────┴────────────────────────────────────────────┘
+```
+
+## toDate32OrZero {#todate32-or-zero}
+
+The same as [toDate32](#todate32) but returns the min value of [Date32](../../sql-reference/data-types/date32.md) if invalid argument is received.
+
+**Example**
+
+Query:
+
+``` sql
+SELECT toDate32OrZero('1924-01-01'), toDate32OrZero('');
+```
+
+Result:
+
+``` text
+┌─toDate32OrZero('1924-01-01')─┬─toDate32OrZero('')─┐
+│                   1925-01-01 │         1925-01-01 │
+└──────────────────────────────┴────────────────────┘
+```
+
+## toDate32OrNull {#todate32-or-null}
+
+The same as [toDate32](#todate32) but returns `NULL` if invalid argument is received.
+
+**Example**
+
+Query:
+
+``` sql
+SELECT toDate32OrNull('1955-01-01'), toDate32OrNull('');
+```
+
+Result:
+
+``` text
+┌─toDate32OrNull('1955-01-01')─┬─toDate32OrNull('')─┐
+│                   1955-01-01 │               ᴺᵁᴸᴸ │
+└──────────────────────────────┴────────────────────┘
+```
+
 ## toDecimal(32\|64\|128\|256) {#todecimal3264128256}
 
 Converts `value` to the [Decimal](../../sql-reference/data-types/decimal.md) data type with precision of `S`. The `value` can be a number or a string. The `S` (scale) parameter specifies the number of decimal places.

docs/ru/sql-reference/data-types/date.md

@@ -9,9 +9,9 @@ toc_title: Date
 
 Дата хранится без учёта часового пояса.
 
-## Примеры {#examples}
+**Пример**
 
-**1.** Создание таблицы и добавление в неё данных:
+Создание таблицы и добавление в неё данных:
 
 ``` sql
 CREATE TABLE dt
@@ -24,9 +24,6 @@ ENGINE = TinyLog;
 
 ``` sql
 INSERT INTO dt Values (1546300800, 1), ('2019-01-01', 2);
-```
-
-``` sql
 SELECT * FROM dt;
 ```
 
@@ -37,7 +34,7 @@ SELECT * FROM dt;
 └────────────┴──────────┘
 ```
 
-## Смотрите также {#see-also}
+**См. также**
 
 -   [Функции для работы с датой и временем](../../sql-reference/functions/date-time-functions.md)
 -   [Операторы для работы с датой и временем](../../sql-reference/operators/index.md#operators-datetime)

docs/ru/sql-reference/data-types/date32.md

@@ -0,0 +1,40 @@
+---
+toc_priority: 48
+toc_title: Date32
+---
+
+# Date32 {#data_type-datetime32}
+
+Дата. Поддерживается такой же диапазон дат, как для типа [Datetime64](../../sql-reference/data-types/datetime64.md). Значение хранится в четырех байтах и соответствует числу дней с 1925-01-01 по 2283-11-11. 
+
+**Пример**
+
+Создание таблицы со столбцом типа `Date32`и добавление в нее данных:
+
+``` sql
+CREATE TABLE new
+(
+    `timestamp` Date32,
+    `event_id` UInt8
+)
+ENGINE = TinyLog;
+```
+
+``` sql
+INSERT INTO new VALUES (4102444800, 1), ('2100-01-01', 2);
+SELECT * FROM new;
+```
+
+``` text
+┌──timestamp─┬─event_id─┐
+│ 2100-01-01 │        1 │
+│ 2100-01-01 │        2 │
+└────────────┴──────────┘
+```
+
+**См. также**
+
+-   [toDate32](../../sql-reference/functions/type-conversion-functions.md#todate32)
+-   [toDate32OrZero](../../sql-reference/functions/type-conversion-functions.md#todate32-or-zero)
+-   [toDate32OrNull](../../sql-reference/functions/type-conversion-functions.md#todate32-or-null) 
+

docs/ru/sql-reference/data-types/datetime64.md

@@ -17,7 +17,7 @@ DateTime64(precision, [timezone])
 
 Данные хранятся в виде количества ‘тиков’, прошедших с момента начала эпохи (1970-01-01 00:00:00 UTC), в Int64. Размер тика определяется параметром precision. Дополнительно, тип `DateTime64` позволяет хранить часовой пояс, единый для всей колонки, который влияет на то, как будут отображаться значения типа `DateTime64` в текстовом виде и как будут парситься значения заданные в виде строк (‘2020-01-01 05:00:01.000’). Часовой пояс не хранится в строках таблицы (выборки), а хранится в метаданных колонки. Подробнее см. [DateTime](datetime.md).
 
-Поддерживаются значения от 1 января 1925 г. и до 31 декабря 2283 г.
+Поддерживаются значения от 1 января 1925 г. и до 11 ноября 2283 г.
 
 ## Примеры {#examples}
 

docs/ru/sql-reference/functions/type-conversion-functions.md

@@ -152,6 +152,104 @@ Cиноним: `DATE`.
 
 ## toDateTimeOrNull {#todatetimeornull}
 
+## toDate32 {#todate32}
+
+Конвертирует аргумент в значение типа [Date32](../../sql-reference/data-types/date32.md). Если значение выходит за границы диапазона, возвращается пограничное значение `Date32`. Если аргумент имеет тип [Date](../../sql-reference/data-types/date.md), учитываются границы типа `Date`.
+
+**Синтаксис** 
+
+``` sql
+toDate32(value)
+```
+
+**Аргументы** 
+
+-   `value` — Значение даты. [String](../../sql-reference/data-types/string.md), [UInt32](../../sql-reference/data-types/int-uint.md) или [Date](../../sql-reference/data-types/date.md).
+
+**Возвращаемое значение**
+
+-   Календарная дата.
+
+Тип: [Date32](../../sql-reference/data-types/date32.md).
+
+**Пример**
+
+1. Значение находится в границах диапазона:
+
+``` sql
+SELECT toDate32('1955-01-01') AS value, toTypeName(value);
+```
+
+``` text
+┌──────value─┬─toTypeName(toDate32('1925-01-01'))─┐
+│ 1955-01-01 │ Date32                             │
+└────────────┴────────────────────────────────────┘
+```
+
+2. Значение выходит за границы диапазона:
+
+``` sql
+SELECT toDate32('1924-01-01') AS value, toTypeName(value);
+```
+
+``` text
+┌──────value─┬─toTypeName(toDate32('1925-01-01'))─┐
+│ 1925-01-01 │ Date32                             │
+└────────────┴────────────────────────────────────┘
+```
+
+3. С аргументом типа `Date`:
+
+``` sql
+SELECT toDate32(toDate('1924-01-01')) AS value, toTypeName(value);
+```
+
+``` text
+┌──────value─┬─toTypeName(toDate32(toDate('1924-01-01')))─┐
+│ 1970-01-01 │ Date32                                     │
+└────────────┴────────────────────────────────────────────┘
+```
+
+## toDate32OrZero {#todate32-or-zero}
+
+То же самое, что и  [toDate32](#todate32), но возвращает минимальное значение типа [Date32](../../sql-reference/data-types/date32.md), если получен недопустимый аргумент.
+
+**Пример**
+
+Запрос:
+
+``` sql
+SELECT toDate32OrZero('1924-01-01'), toDate32OrZero('');
+```
+
+Результат:
+
+``` text
+┌─toDate32OrZero('1924-01-01')─┬─toDate32OrZero('')─┐
+│                   1925-01-01 │         1925-01-01 │
+└──────────────────────────────┴────────────────────┘
+```
+
+## toDate32OrNull {#todate32-or-null}
+
+То же самое, что и [toDate32](#todate32), но возвращает `NULL`, если получен недопустимый аргумент.
+
+**Пример**
+
+Запрос:
+
+``` sql
+SELECT toDate32OrNull('1955-01-01'), toDate32OrNull('');
+```
+
+Результат:
+
+``` text
+┌─toDate32OrNull('1955-01-01')─┬─toDate32OrNull('')─┐
+│                   1955-01-01 │               ᴺᵁᴸᴸ │
+└──────────────────────────────┴────────────────────┘
+```
+
 ## toDecimal(32\|64\|128\|256) {#todecimal3264128}
 
 Преобразует `value` к типу данных [Decimal](../../sql-reference/functions/type-conversion-functions.md) с точностью `S`. `value` может быть числом или строкой. Параметр `S` (scale) задаёт число десятичных знаков.