DOCS-4146: Updated the description of the DateTime data type. (#7429)

* Typo fix.

* elenbaskakova-DOCSUP-52 (#66)

The article "Time Zones" has been expanded.

* DOCAPI-4146: DateTime rewrited.

* DOCAPI-4146: Update after the review.

docs/en/data_types/datetime.md

@@ -1,15 +1,60 @@
 # DateTime {#data_type-datetime}
 
-Date with time. Stored in four bytes as a Unix timestamp (unsigned). Allows storing values in the same range as for the Date type. The minimal value is output as 0000-00-00 00:00:00.
-The time is stored with accuracy up to one second (without leap seconds).
+Data structure storing Unix timestamp. Also, it can store a time zone.
 
-## Time Zones
+Syntax:
 
-The date with time is converted from text (divided into component parts) to binary and back, using the system's time zone at the time the client or server starts. In text format, information about daylight savings is lost.
+```sql
+DateTime([timezone])
+```
 
-By default, the client switches to the timezone of the server when it connects. You can change this behavior by enabling the client command-line option `--use_client_time_zone`.
+Range of values in the Unix timestamp: [1970-01-01 00:00:00, 2105-12-31 23:59:59].
 
-So when working with a textual date (for example, when saving text dumps), keep in mind that there may be ambiguity during changes for daylight savings time, and there may be problems matching data if the time zone changed.
+Resolution: 1 second.
 
+## Usage remarks
+
+ClickHouse stores date and time values in the Unix timestamp format that is independent of the time zones and daylight saving rules. The time zone value affects displaying `DateTime` values in text formats and parsing the input strings for storage. You can find the list of supported time zones in [IANA Time Zone Database](https://www.iana.org/time-zones).
+
+You can explicitly set a time zone for `DateTime`-type column when creating a table. If time zone isn't set, ClickHouse uses the value of the [timezone](../operations/server_settings/settings.md#server_settings-timezone) server configuration parameter or the operating system settings at the moment of the ClickHouse server start. 
+
+The [clickhouse-client](../interfaces/cli.md) applies the server time zone by default if a time zone isn't explicitly defined when initializing the data type. To use the client time zone, run it with the `--use_client_time_zone` parameter.
+
+ClickHouse outputs values in the `YYYY-MM-DD hh:mm:ss` text format by default. You can change the format with the [formatDateTime](../query_language/functions/date_time_functions.md#formatdatetime) function.
+
+When inserting data into ClickHouse, you can use different formats of date and time strings, depending on the [date_time_input_format](../operations/settings/settings.md#settings-date_time_input_format) setting value.
+
+## Examples
+
+Creating a table with a `DateTime`-type column:
+
+```sql
+CREATE TABLE dt(
+    timestamp DateTime('Europe/Moscow')
+)
+```
+
+Getting a time zone for a `DateTime`-type value:
+
+```sql
+SELECT
+    toDateTime(now(), 'Europe/Moscow') AS column,
+    toTypeName(column) AS x
+```
+```text
+┌──────────────column─┬─x─────────────────────────┐
+│ 2019-10-16 04:12:04 │ DateTime('Europe/Moscow') │
+└─────────────────────┴───────────────────────────┘
+```
+
+## See Also
+
+- [Type Conversion Functions](../query_language/functions/type_conversion_functions.md)
+- [Functions for Working with Dates and Times](../query_language/functions/date_time_functions.md)
+- [Functions for Working with Arrays](../query_language/functions/array_functions.md)
+- [The `date_time_input_format` setting](../operations/settings/settings.md#settings-date_time_input_format)
+- [The `timezone` server configuration parameter](../operations/server_settings/settings.md#server_settings-timezone)
+- [Operator for Working with Dates and Times](../query_language/operators.md#operators-datetime)
+- [The `Date` data type](date.md)
 
 [Original article](https://clickhouse.yandex/docs/en/data_types/datetime/) <!--hide-->

docs/en/operations/server_settings/settings.md

@@ -625,7 +625,7 @@ For the value of the `incl` attribute, see the section "[Configuration files](..
 
 - [skip_unavailable_shards](../settings/settings.md#settings-skip_unavailable_shards)
 
-## timezone
+## timezone {#server_settings-timezone}
 
 The server's time zone.
 

docs/en/query_language/functions/date_time_functions.md

@@ -334,7 +334,7 @@ For a time interval starting at 'StartTime' and continuing for 'Duration' second
 For example, `timeSlots(toDateTime('2012-01-01 12:20:00'), 600) = [toDateTime('2012-01-01 12:00:00'), toDateTime('2012-01-01 12:30:00')]`.
 This is necessary for searching for pageviews in the corresponding session.
 
-## formatDateTime(Time, Format\[, Timezone\])
+## formatDateTime(Time, Format\[, Timezone\]) {#formatdatetime}
 
 Function formats a Time according given Format string. N.B.: Format is a constant expression, e.g. you can not have multiple formats for single result column.