From 99210b24a9000248ab275c21b84b4ac5697741e7 Mon Sep 17 00:00:00 2001 From: BayoNet Date: Wed, 6 Nov 2019 13:03:06 +0300 Subject: [PATCH] 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 | 57 +++++++++++++++++-- .../en/operations/server_settings/settings.md | 2 +- .../functions/date_time_functions.md | 2 +- 3 files changed, 53 insertions(+), 8 deletions(-) diff --git a/docs/en/data_types/datetime.md b/docs/en/data_types/datetime.md index ccaf44fa40d..967e184ba99 100644 --- a/docs/en/data_types/datetime.md +++ b/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/) diff --git a/docs/en/operations/server_settings/settings.md b/docs/en/operations/server_settings/settings.md index 9e0fbb3d1aa..97e6588fcb0 100644 --- a/docs/en/operations/server_settings/settings.md +++ b/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. diff --git a/docs/en/query_language/functions/date_time_functions.md b/docs/en/query_language/functions/date_time_functions.md index 971c4032c68..26c44a6a391 100644 --- a/docs/en/query_language/functions/date_time_functions.md +++ b/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.