ClickHouse/docs/en/sql-reference/functions/date-time-functions.md

1232 lines
40 KiB
Markdown
Raw Normal View History

2020-04-03 13:23:32 +00:00
---
toc_priority: 39
2020-06-19 10:04:32 +00:00
toc_title: Dates and Times
2020-04-03 13:23:32 +00:00
---
# Functions for Working with Dates and Times {#functions-for-working-with-dates-and-times}
2017-04-03 19:49:50 +00:00
2021-04-23 21:37:54 +00:00
Support for time zones.
2017-04-03 19:49:50 +00:00
All functions for working with the date and time that have a logical use for the time zone can accept a second optional time zone argument. Example: Asia/Yekaterinburg. In this case, they use the specified time zone instead of the local (default) one.
CLICKHOUSE-2720: progress on website (#865) * update presentations * CLICKHOUSE-2936: redirect from clickhouse.yandex.ru and clickhouse.yandex.com * update submodule * lost files * CLICKHOUSE-2981: prefer sphinx docs over original reference * CLICKHOUSE-2981: docs styles more similar to main website + add flags to switch language links * update presentations * Less confusing directory structure (docs -> doc/reference/) * Minify sphinx docs too * Website release script: fail fast + pass docker hash on deploy * Do not underline links in docs * shorter * cleanup docker images * tune nginx config * CLICKHOUSE-3043: get rid of habrastorage links * Lost translation * CLICKHOUSE-2936: temporary client-side redirect * behaves weird in test * put redirect back * CLICKHOUSE-3047: copy docs txts to public too * move to proper file * remove old pages to avoid confusion * Remove reference redirect warning for now * Refresh README.md * Yellow buttons in docs * Use svg flags instead of unicode ones in docs * fix test website instance * Put flags to separate files * wrong flag * Copy Yandex.Metrica introduction from main page to docs * Yet another home page structure change, couple new blocks (CLICKHOUSE-3045) * Update Contacts section * CLICKHOUSE-2849: more detailed legal information * CLICKHOUSE-2978 preparation - split by files * More changes in Contacts block * Tune texts on index page * update presentations * One more benchmark * Add usage sections to index page, adapted from slides * Get the roadmap started, based on slides from last ClickHouse Meetup * CLICKHOUSE-2977: some rendering tuning * Get rid of excessive section in the end of getting started * Make headers linkable * CLICKHOUSE-2981: links to editing reference - https://github.com/yandex/ClickHouse/issues/849 * CLICKHOUSE-2981: fix mobile styles in docs * Ban crawling of duplicating docs * Open some external links in new tab * Ban old docs too * Lots of trivial fixes in english docs * Lots of trivial fixes in russian docs * Remove getting started copies in markdown * Add Yandex.Webmaster * Fix some sphinx warnings * More warnings fixed in english docs * More sphinx warnings fixed * Add code-block:: text * More code-block:: text * These headers look not that well * Better switch between documentation languages * merge use_case.rst into ya_metrika_task.rst * Edit the agg_functions.rst texts * Add lost empty lines
2017-06-13 04:15:47 +00:00
2020-03-20 10:10:48 +00:00
``` sql
SELECT
toDateTime('2016-06-15 23:00:00') AS time,
toDate(time) AS date_local,
toDate(time, 'Asia/Yekaterinburg') AS date_yekat,
toString(time, 'US/Samoa') AS time_samoa
```
CLICKHOUSE-2720: progress on website and reference (#886) * update presentations * CLICKHOUSE-2936: redirect from clickhouse.yandex.ru and clickhouse.yandex.com * update submodule * lost files * CLICKHOUSE-2981: prefer sphinx docs over original reference * CLICKHOUSE-2981: docs styles more similar to main website + add flags to switch language links * update presentations * Less confusing directory structure (docs -> doc/reference/) * Minify sphinx docs too * Website release script: fail fast + pass docker hash on deploy * Do not underline links in docs * shorter * cleanup docker images * tune nginx config * CLICKHOUSE-3043: get rid of habrastorage links * Lost translation * CLICKHOUSE-2936: temporary client-side redirect * behaves weird in test * put redirect back * CLICKHOUSE-3047: copy docs txts to public too * move to proper file * remove old pages to avoid confusion * Remove reference redirect warning for now * Refresh README.md * Yellow buttons in docs * Use svg flags instead of unicode ones in docs * fix test website instance * Put flags to separate files * wrong flag * Copy Yandex.Metrica introduction from main page to docs * Yet another home page structure change, couple new blocks (CLICKHOUSE-3045) * Update Contacts section * CLICKHOUSE-2849: more detailed legal information * CLICKHOUSE-2978 preparation - split by files * More changes in Contacts block * Tune texts on index page * update presentations * One more benchmark * Add usage sections to index page, adapted from slides * Get the roadmap started, based on slides from last ClickHouse Meetup * CLICKHOUSE-2977: some rendering tuning * Get rid of excessive section in the end of getting started * Make headers linkable * CLICKHOUSE-2981: links to editing reference - https://github.com/yandex/ClickHouse/issues/849 * CLICKHOUSE-2981: fix mobile styles in docs * Ban crawling of duplicating docs * Open some external links in new tab * Ban old docs too * Lots of trivial fixes in english docs * Lots of trivial fixes in russian docs * Remove getting started copies in markdown * Add Yandex.Webmaster * Fix some sphinx warnings * More warnings fixed in english docs * More sphinx warnings fixed * Add code-block:: text * More code-block:: text * These headers look not that well * Better switch between documentation languages * merge use_case.rst into ya_metrika_task.rst * Edit the agg_functions.rst texts * Add lost empty lines * Lost blank lines * Add new logo sizes * update presentations * Next step in migrating to new documentation * Fix all warnings in en reference * Fix all warnings in ru reference * Re-arrange existing reference * Move operation tips to main reference * Fix typos noticed by milovidov@ * Get rid of zookeeper.md * Looks like duplicate of tutorial.html * Fix some mess with html tags in tutorial * No idea why nobody noticed this before, but it was completely not clear whet to get the data * Match code block styling between main and tutorial pages (in favor of the latter) * Get rid of some copypaste in tutorial * Normalize header styles * Move example_datasets to sphinx * Move presentations submodule to website * Move and update README.md * No point in duplicating articles from habrahabr here * Move development-related docs as is for now * doc/reference/ -> docs/ (to match the URL on website) * Adapt links to match the previous commit * Adapt development docs to rst (still lacks translation and strikethrough support) * clean on release * blacklist presentations in gulp * strikethrough support in sphinx * just copy development folder for now * fix weird introduction in style article * Style guide translation (WIP) * Finish style guide translation to English * gulp clean separately * Update year in LICENSE * Initial CONTRIBUTING.md * Fix remaining links to old docs in tutorial * Some tutorial fixes * Typo * Another typo * Update list of authors from yandex-team accoding to git log
2017-06-20 14:19:03 +00:00
2020-03-20 10:10:48 +00:00
``` text
┌────────────────time─┬─date_local─┬─date_yekat─┬─time_samoa──────────┐
│ 2016-06-15 23:00:00 │ 2016-06-15 │ 2016-06-16 │ 2016-06-15 09:00:00 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘
```
CLICKHOUSE-2720: progress on website (#865) * update presentations * CLICKHOUSE-2936: redirect from clickhouse.yandex.ru and clickhouse.yandex.com * update submodule * lost files * CLICKHOUSE-2981: prefer sphinx docs over original reference * CLICKHOUSE-2981: docs styles more similar to main website + add flags to switch language links * update presentations * Less confusing directory structure (docs -> doc/reference/) * Minify sphinx docs too * Website release script: fail fast + pass docker hash on deploy * Do not underline links in docs * shorter * cleanup docker images * tune nginx config * CLICKHOUSE-3043: get rid of habrastorage links * Lost translation * CLICKHOUSE-2936: temporary client-side redirect * behaves weird in test * put redirect back * CLICKHOUSE-3047: copy docs txts to public too * move to proper file * remove old pages to avoid confusion * Remove reference redirect warning for now * Refresh README.md * Yellow buttons in docs * Use svg flags instead of unicode ones in docs * fix test website instance * Put flags to separate files * wrong flag * Copy Yandex.Metrica introduction from main page to docs * Yet another home page structure change, couple new blocks (CLICKHOUSE-3045) * Update Contacts section * CLICKHOUSE-2849: more detailed legal information * CLICKHOUSE-2978 preparation - split by files * More changes in Contacts block * Tune texts on index page * update presentations * One more benchmark * Add usage sections to index page, adapted from slides * Get the roadmap started, based on slides from last ClickHouse Meetup * CLICKHOUSE-2977: some rendering tuning * Get rid of excessive section in the end of getting started * Make headers linkable * CLICKHOUSE-2981: links to editing reference - https://github.com/yandex/ClickHouse/issues/849 * CLICKHOUSE-2981: fix mobile styles in docs * Ban crawling of duplicating docs * Open some external links in new tab * Ban old docs too * Lots of trivial fixes in english docs * Lots of trivial fixes in russian docs * Remove getting started copies in markdown * Add Yandex.Webmaster * Fix some sphinx warnings * More warnings fixed in english docs * More sphinx warnings fixed * Add code-block:: text * More code-block:: text * These headers look not that well * Better switch between documentation languages * merge use_case.rst into ya_metrika_task.rst * Edit the agg_functions.rst texts * Add lost empty lines
2017-06-13 04:15:47 +00:00
2021-05-28 09:14:28 +00:00
## timeZone {#timezone}
Returns the timezone of the server.
2021-06-16 18:33:44 +00:00
**Syntax**
2021-05-28 09:14:28 +00:00
``` sql
timeZone()
```
2021-06-16 18:33:44 +00:00
Alias: `timezone`.
2021-05-28 09:14:28 +00:00
**Returned value**
2021-06-16 18:33:44 +00:00
- Timezone.
2021-05-28 09:14:28 +00:00
Type: [String](../../sql-reference/data-types/string.md).
2020-03-20 10:10:48 +00:00
## toTimeZone {#totimezone}
2021-05-28 09:14:28 +00:00
Converts time or date and time to the specified time zone. The time zone is an attribute of the `Date` and `DateTime` data types. The internal value (number of seconds) of the table field or of the resultset's column does not change, the column's type changes and its string representation changes accordingly.
2021-06-16 18:33:44 +00:00
**Syntax**
2021-05-28 09:14:28 +00:00
``` sql
toTimezone(value, timezone)
```
Alias: `toTimezone`.
2021-06-16 18:33:44 +00:00
**Arguments**
2021-05-28 09:14:28 +00:00
- `value` — Time or date and time. [DateTime64](../../sql-reference/data-types/datetime64.md).
- `timezone` — Timezone for the returned value. [String](../../sql-reference/data-types/string.md).
**Returned value**
2021-06-16 18:33:44 +00:00
- Date and time.
2021-05-28 09:14:28 +00:00
Type: [DateTime](../../sql-reference/data-types/datetime.md).
**Example**
Query:
2020-12-01 02:07:16 +00:00
```sql
2021-05-28 09:14:28 +00:00
SELECT toDateTime('2019-01-01 00:00:00', 'UTC') AS time_utc,
2020-12-01 02:07:16 +00:00
toTypeName(time_utc) AS type_utc,
toInt32(time_utc) AS int32utc,
toTimeZone(time_utc, 'Asia/Yekaterinburg') AS time_yekat,
toTypeName(time_yekat) AS type_yekat,
toInt32(time_yekat) AS int32yekat,
toTimeZone(time_utc, 'US/Samoa') AS time_samoa,
toTypeName(time_samoa) AS type_samoa,
toInt32(time_samoa) AS int32samoa
FORMAT Vertical;
```
2021-06-29 00:59:19 +00:00
2021-05-28 09:14:28 +00:00
Result:
2020-12-01 02:07:16 +00:00
```text
Row 1:
──────
time_utc: 2019-01-01 00:00:00
type_utc: DateTime('UTC')
int32utc: 1546300800
time_yekat: 2019-01-01 05:00:00
type_yekat: DateTime('Asia/Yekaterinburg')
int32yekat: 1546300800
time_samoa: 2018-12-31 13:00:00
type_samoa: DateTime('US/Samoa')
int32samoa: 1546300800
```
2020-12-01 02:19:26 +00:00
`toTimeZone(time_utc, 'Asia/Yekaterinburg')` changes the `DateTime('UTC')` type to `DateTime('Asia/Yekaterinburg')`. The value (Unixtimestamp) 1546300800 stays the same, but the string representation (the result of the toString() function) changes from `time_utc: 2019-01-01 00:00:00` to `time_yekat: 2019-01-01 05:00:00`.
2021-05-28 09:14:28 +00:00
## timeZoneOf {#timezoneof}
Returns the timezone name of [DateTime](../../sql-reference/data-types/datetime.md) or [DateTime64](../../sql-reference/data-types/datetime64.md) data types.
2021-06-16 18:33:44 +00:00
**Syntax**
2021-05-28 09:14:28 +00:00
``` sql
timeZoneOf(value)
```
2021-06-16 18:33:44 +00:00
Alias: `timezoneOf`.
2021-05-28 09:14:28 +00:00
**Arguments**
2021-06-16 18:33:44 +00:00
- `value` — Date and time. [DateTime](../../sql-reference/data-types/datetime.md) or [DateTime64](../../sql-reference/data-types/datetime64.md).
2021-05-28 09:14:28 +00:00
**Returned value**
2021-06-16 18:33:44 +00:00
- Timezone name.
2021-05-28 09:14:28 +00:00
Type: [String](../../sql-reference/data-types/string.md).
**Example**
Query:
``` sql
SELECT timezoneOf(now());
```
Result:
``` text
┌─timezoneOf(now())─┐
│ Etc/UTC │
└───────────────────┘
```
## timeZoneOffset {#timezoneoffset}
Returns a timezone offset in seconds from [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time). The function takes into account [daylight saving time](https://en.wikipedia.org/wiki/Daylight_saving_time) and historical timezone changes at the specified date and time.
[IANA timezone database](https://www.iana.org/time-zones) is used to calculate the offset.
**Syntax**
``` sql
timeZoneOffset(value)
```
Alias: `timezoneOffset`.
**Arguments**
2021-06-16 18:33:44 +00:00
- `value` — Date and time. [DateTime](../../sql-reference/data-types/datetime.md) or [DateTime64](../../sql-reference/data-types/datetime64.md).
2021-05-28 09:14:28 +00:00
**Returned value**
2021-06-16 18:33:44 +00:00
- Offset from UTC in seconds.
2021-05-28 09:14:28 +00:00
Type: [Int32](../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT toDateTime('2021-04-21 10:20:30', 'America/New_York') AS Time, toTypeName(Time) AS Type,
timeZoneOffset(Time) AS Offset_in_seconds, (Offset_in_seconds / 3600) AS Offset_in_hours;
```
Result:
``` text
┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │ -14400 │ -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘
```
2020-03-20 10:10:48 +00:00
## toYear {#toyear}
CLICKHOUSE-2720: progress on website (#865) * update presentations * CLICKHOUSE-2936: redirect from clickhouse.yandex.ru and clickhouse.yandex.com * update submodule * lost files * CLICKHOUSE-2981: prefer sphinx docs over original reference * CLICKHOUSE-2981: docs styles more similar to main website + add flags to switch language links * update presentations * Less confusing directory structure (docs -> doc/reference/) * Minify sphinx docs too * Website release script: fail fast + pass docker hash on deploy * Do not underline links in docs * shorter * cleanup docker images * tune nginx config * CLICKHOUSE-3043: get rid of habrastorage links * Lost translation * CLICKHOUSE-2936: temporary client-side redirect * behaves weird in test * put redirect back * CLICKHOUSE-3047: copy docs txts to public too * move to proper file * remove old pages to avoid confusion * Remove reference redirect warning for now * Refresh README.md * Yellow buttons in docs * Use svg flags instead of unicode ones in docs * fix test website instance * Put flags to separate files * wrong flag * Copy Yandex.Metrica introduction from main page to docs * Yet another home page structure change, couple new blocks (CLICKHOUSE-3045) * Update Contacts section * CLICKHOUSE-2849: more detailed legal information * CLICKHOUSE-2978 preparation - split by files * More changes in Contacts block * Tune texts on index page * update presentations * One more benchmark * Add usage sections to index page, adapted from slides * Get the roadmap started, based on slides from last ClickHouse Meetup * CLICKHOUSE-2977: some rendering tuning * Get rid of excessive section in the end of getting started * Make headers linkable * CLICKHOUSE-2981: links to editing reference - https://github.com/yandex/ClickHouse/issues/849 * CLICKHOUSE-2981: fix mobile styles in docs * Ban crawling of duplicating docs * Open some external links in new tab * Ban old docs too * Lots of trivial fixes in english docs * Lots of trivial fixes in russian docs * Remove getting started copies in markdown * Add Yandex.Webmaster * Fix some sphinx warnings * More warnings fixed in english docs * More sphinx warnings fixed * Add code-block:: text * More code-block:: text * These headers look not that well * Better switch between documentation languages * merge use_case.rst into ya_metrika_task.rst * Edit the agg_functions.rst texts * Add lost empty lines
2017-06-13 04:15:47 +00:00
2017-04-26 19:16:38 +00:00
Converts a date or date with time to a UInt16 number containing the year number (AD).
2017-04-03 19:49:50 +00:00
2021-05-28 09:14:28 +00:00
Alias: `YEAR`.
2020-03-20 10:10:48 +00:00
## toQuarter {#toquarter}
Converts a date or date with time to a UInt8 number containing the quarter number.
2021-05-28 09:14:28 +00:00
Alias: `QUARTER`.
2020-03-20 10:10:48 +00:00
## toMonth {#tomonth}
2017-04-26 19:16:38 +00:00
Converts a date or date with time to a UInt8 number containing the month number (1-12).
2017-04-03 19:49:50 +00:00
2021-05-28 09:14:28 +00:00
Alias: `MONTH`.
2020-03-20 10:10:48 +00:00
## toDayOfYear {#todayofyear}
2019-05-05 17:38:05 +00:00
Converts a date or date with time to a UInt16 number containing the number of the day of the year (1-366).
2021-05-28 09:14:28 +00:00
Alias: `DAYOFYEAR`.
2020-03-20 10:10:48 +00:00
## toDayOfMonth {#todayofmonth}
Converts a date or date with time to a UInt8 number containing the number of the day of the month (1-31).
2021-05-28 09:14:28 +00:00
Aliases: `DAYOFMONTH`, `DAY`.
2020-03-20 10:10:48 +00:00
## toDayOfWeek {#todayofweek}
2017-04-03 19:49:50 +00:00
2017-04-26 19:16:38 +00:00
Converts a date or date with time to a UInt8 number containing the number of the day of the week (Monday is 1, and Sunday is 7).
2017-04-03 19:49:50 +00:00
2021-05-28 09:14:28 +00:00
Alias: `DAYOFWEEK`.
2020-03-20 10:10:48 +00:00
## toHour {#tohour}
2017-04-26 19:16:38 +00:00
Converts a date with time to a UInt8 number containing the number of the hour in 24-hour time (0-23).
This function assumes that if clocks are moved ahead, it is by one hour and occurs at 2 a.m., and if clocks are moved back, it is by one hour and occurs at 3 a.m. (which is not always true even in Moscow the clocks were twice changed at a different time).
2021-05-28 09:14:28 +00:00
Alias: `HOUR`.
2020-03-20 10:10:48 +00:00
## toMinute {#tominute}
2017-04-03 19:49:50 +00:00
2017-04-26 19:16:38 +00:00
Converts a date with time to a UInt8 number containing the number of the minute of the hour (0-59).
2017-04-03 19:49:50 +00:00
2021-05-28 09:14:28 +00:00
Alias: `MINUTE`.
2020-03-20 10:10:48 +00:00
## toSecond {#tosecond}
2017-04-26 19:16:38 +00:00
Converts a date with time to a UInt8 number containing the number of the second in the minute (0-59).
Leap seconds are not accounted for.
2021-05-28 09:14:28 +00:00
Alias: `SECOND`.
## toUnixTimestamp {#to-unix-timestamp}
2020-11-27 20:18:08 +00:00
For DateTime argument: converts value to the number with type UInt32 -- Unix Timestamp (https://en.wikipedia.org/wiki/Unix_time).
For String argument: converts the input string to the datetime according to the timezone (optional second argument, server timezone is used by default) and returns the corresponding unix timestamp.
2020-03-20 10:10:48 +00:00
**Syntax**
2019-10-23 11:28:08 +00:00
2020-03-20 10:10:48 +00:00
``` sql
2020-02-02 21:20:56 +00:00
toUnixTimestamp(datetime)
toUnixTimestamp(str, [timezone])
```
**Returned value**
- Returns the unix timestamp.
Type: `UInt32`.
**Example**
Query:
2020-03-20 10:10:48 +00:00
``` sql
SELECT toUnixTimestamp('2017-11-05 08:07:47', 'Asia/Tokyo') AS unix_timestamp
```
Result:
2020-03-20 10:10:48 +00:00
``` text
┌─unix_timestamp─┐
│ 1509836867 │
└────────────────┘
```
2021-04-09 15:37:14 +00:00
!!! attention "Attention"
2021-06-02 11:45:26 +00:00
The return type `toStartOf*` functions described below is `Date` or `DateTime`. Though these functions can take `DateTime64` as an argument, passing them a `DateTime64` that is out of the normal range (years 1925 - 2283) will give an incorrect result.
2021-04-09 15:37:14 +00:00
2020-03-20 10:10:48 +00:00
## toStartOfYear {#tostartofyear}
2017-04-03 19:49:50 +00:00
Rounds down a date or date with time to the first day of the year.
2017-04-26 19:16:38 +00:00
Returns the date.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toStartOfISOYear {#tostartofisoyear}
Rounds down a date or date with time to the first day of ISO year.
Returns the date.
2020-03-20 10:10:48 +00:00
## toStartOfQuarter {#tostartofquarter}
Rounds down a date or date with time to the first day of the quarter.
The first day of the quarter is either 1 January, 1 April, 1 July, or 1 October.
Returns the date.
2020-03-20 10:10:48 +00:00
## toStartOfMonth {#tostartofmonth}
2017-04-26 19:16:38 +00:00
Rounds down a date or date with time to the first day of the month.
Returns the date.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
!!! attention "Attention"
The behavior of parsing incorrect dates is implementation specific. ClickHouse may return zero date, throw an exception or do “natural” overflow.
2020-03-20 10:10:48 +00:00
## toMonday {#tomonday}
Rounds down a date or date with time to the nearest Monday.
Returns the date.
2020-03-20 10:10:48 +00:00
## toStartOfWeek(t\[,mode\]) {#tostartofweektmode}
Rounds down a date or date with time to the nearest Sunday or Monday by mode.
Returns the date.
2020-03-20 10:10:48 +00:00
The mode argument works exactly like the mode argument to toWeek(). For the single-argument syntax, a mode value of 0 is used.
2020-03-20 10:10:48 +00:00
## toStartOfDay {#tostartofday}
2017-04-03 19:49:50 +00:00
Rounds down a date with time to the start of the day.
2020-03-20 10:10:48 +00:00
## toStartOfHour {#tostartofhour}
Rounds down a date with time to the start of the hour.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toStartOfMinute {#tostartofminute}
2017-04-26 19:16:38 +00:00
Rounds down a date with time to the start of the minute.
2017-04-03 19:49:50 +00:00
## toStartOfSecond {#tostartofsecond}
Truncates sub-seconds.
**Syntax**
``` sql
toStartOfSecond(value[, timezone])
```
2021-05-28 09:14:28 +00:00
**Arguments**
- `value` — Date and time. [DateTime64](../../sql-reference/data-types/datetime64.md).
- `timezone` — [Timezone](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-timezone) for the returned value (optional). If not specified, the function uses the timezone of the `value` parameter. [String](../../sql-reference/data-types/string.md).
**Returned value**
- Input value without sub-seconds.
Type: [DateTime64](../../sql-reference/data-types/datetime64.md).
**Examples**
Query without timezone:
``` sql
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);
```
Result:
``` text
┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘
```
Query with timezone:
``` sql
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Europe/Moscow');
```
Result:
``` text
┌─toStartOfSecond(dt64, 'Europe/Moscow')─┐
│ 2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘
```
**See also**
- [Timezone](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-timezone) server configuration parameter.
2020-03-20 10:10:48 +00:00
## toStartOfFiveMinute {#tostartoffiveminute}
2019-01-18 13:29:12 +00:00
Rounds down a date with time to the start of the five-minute interval.
2020-03-20 10:10:48 +00:00
## toStartOfTenMinutes {#tostartoftenminutes}
Rounds down a date with time to the start of the ten-minute interval.
2020-03-20 10:10:48 +00:00
## toStartOfFifteenMinutes {#tostartoffifteenminutes}
2018-03-25 02:04:22 +00:00
Rounds down the date with time to the start of the fifteen-minute interval.
2020-10-13 17:23:29 +00:00
## toStartOfInterval(time_or_data, INTERVAL x unit \[, time_zone\]) {#tostartofintervaltime-or-data-interval-x-unit-time-zone}
2020-03-20 10:10:48 +00:00
This is a generalization of other functions named `toStartOf*`. For example,
`toStartOfInterval(t, INTERVAL 1 year)` returns the same as `toStartOfYear(t)`,
`toStartOfInterval(t, INTERVAL 1 month)` returns the same as `toStartOfMonth(t)`,
`toStartOfInterval(t, INTERVAL 1 day)` returns the same as `toStartOfDay(t)`,
`toStartOfInterval(t, INTERVAL 15 minute)` returns the same as `toStartOfFifteenMinutes(t)` etc.
2018-02-25 04:01:13 +00:00
2020-03-20 10:10:48 +00:00
## toTime {#totime}
Converts a date with time to a certain fixed date, while preserving the time.
2020-03-20 10:10:48 +00:00
## toRelativeYearNum {#torelativeyearnum}
2017-04-03 19:49:50 +00:00
2017-04-26 19:16:38 +00:00
Converts a date with time or date to the number of the year, starting from a certain fixed point in the past.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toRelativeQuarterNum {#torelativequarternum}
Converts a date with time or date to the number of the quarter, starting from a certain fixed point in the past.
2020-03-20 10:10:48 +00:00
## toRelativeMonthNum {#torelativemonthnum}
2017-04-26 19:16:38 +00:00
Converts a date with time or date to the number of the month, starting from a certain fixed point in the past.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toRelativeWeekNum {#torelativeweeknum}
2017-04-26 19:16:38 +00:00
Converts a date with time or date to the number of the week, starting from a certain fixed point in the past.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toRelativeDayNum {#torelativedaynum}
2017-04-26 19:16:38 +00:00
Converts a date with time or date to the number of the day, starting from a certain fixed point in the past.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toRelativeHourNum {#torelativehournum}
2017-04-26 19:16:38 +00:00
Converts a date with time or date to the number of the hour, starting from a certain fixed point in the past.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toRelativeMinuteNum {#torelativeminutenum}
2017-04-26 19:16:38 +00:00
Converts a date with time or date to the number of the minute, starting from a certain fixed point in the past.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toRelativeSecondNum {#torelativesecondnum}
2017-04-26 19:16:38 +00:00
Converts a date with time or date to the number of the second, starting from a certain fixed point in the past.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toISOYear {#toisoyear}
Converts a date or date with time to a UInt16 number containing the ISO Year number.
2020-03-20 10:10:48 +00:00
## toISOWeek {#toisoweek}
Converts a date or date with time to a UInt8 number containing the ISO Week number.
2020-03-20 10:10:48 +00:00
## toWeek(date\[,mode\]) {#toweekdatemode}
This function returns the week number for date or datetime. The two-argument form of toWeek() enables you to specify whether the week starts on Sunday or Monday and whether the return value should be in the range from 0 to 53 or from 1 to 53. If the mode argument is omitted, the default mode is 0.
2020-03-20 10:10:48 +00:00
`toISOWeek()`is a compatibility function that is equivalent to `toWeek(date,3)`.
2019-06-09 15:19:15 +00:00
The following table describes how the mode argument works.
2020-03-20 10:10:48 +00:00
| Mode | First day of week | Range | Week 1 is the first week … |
|------|-------------------|-------|-------------------------------|
2020-03-20 10:10:48 +00:00
| 0 | Sunday | 0-53 | with a Sunday in this year |
| 1 | Monday | 0-53 | with 4 or more days this year |
| 2 | Sunday | 1-53 | with a Sunday in this year |
| 3 | Monday | 1-53 | with 4 or more days this year |
| 4 | Sunday | 0-53 | with 4 or more days this year |
| 5 | Monday | 0-53 | with a Monday in this year |
| 6 | Sunday | 1-53 | with 4 or more days this year |
| 7 | Monday | 1-53 | with a Monday in this year |
| 8 | Sunday | 1-53 | contains January 1 |
| 9 | Monday | 1-53 | contains January 1 |
2019-06-09 15:19:15 +00:00
For mode values with a meaning of “with 4 or more days this year,” weeks are numbered according to ISO 8601:1988:
- If the week containing January 1 has 4 or more days in the new year, it is week 1.
2019-06-09 15:19:15 +00:00
- Otherwise, it is the last week of the previous year, and the next week is week 1.
2019-06-09 15:19:15 +00:00
2021-05-27 19:44:11 +00:00
For mode values with a meaning of “contains January 1”, the week contains January 1 is week 1. It does not matter how many days in the new year the week contained, even if it contained only one day.
2019-05-07 11:27:20 +00:00
2020-03-20 10:10:48 +00:00
``` sql
toWeek(date, [, mode][, Timezone])
2019-05-07 11:27:20 +00:00
```
2020-03-20 10:10:48 +00:00
2021-05-28 09:14:28 +00:00
**Arguments**
2019-05-07 11:27:20 +00:00
- `date` Date or DateTime.
- `mode` Optional parameter, Range of values is \[0,9\], default is 0.
- `Timezone` Optional parameter, it behaves like any other conversion function.
2019-05-07 11:27:20 +00:00
**Example**
2020-03-20 10:10:48 +00:00
``` sql
SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9;
2019-05-07 11:27:20 +00:00
```
2020-03-20 10:10:48 +00:00
``` text
2019-06-09 15:19:15 +00:00
┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │ 52 │ 52 │ 1 │
└────────────┴───────┴───────┴───────┘
2019-05-07 11:27:20 +00:00
```
2020-03-20 10:10:48 +00:00
## toYearWeek(date\[,mode\]) {#toyearweekdatemode}
2019-06-09 15:19:15 +00:00
Returns year and week for a date. The year in the result may be different from the year in the date argument for the first and the last week of the year.
2020-03-20 10:10:48 +00:00
The mode argument works exactly like the mode argument to toWeek(). For the single-argument syntax, a mode value of 0 is used.
2019-06-09 15:19:15 +00:00
2020-03-20 10:10:48 +00:00
`toISOYear()`is a compatibility function that is equivalent to `intDiv(toYearWeek(date,3),100)`.
2019-06-14 03:04:01 +00:00
2019-06-09 15:19:15 +00:00
**Example**
2019-05-07 11:27:20 +00:00
2020-03-20 10:10:48 +00:00
``` sql
SELECT toDate('2016-12-27') AS date, toYearWeek(date) AS yearWeek0, toYearWeek(date,1) AS yearWeek1, toYearWeek(date,9) AS yearWeek9;
2019-05-07 11:27:20 +00:00
```
2020-03-20 10:10:48 +00:00
``` text
2019-06-09 15:19:15 +00:00
┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┐
│ 2016-12-27 │ 201652 │ 201652 │ 201701 │
└────────────┴───────────┴───────────┴───────────┘
2019-05-07 11:27:20 +00:00
```
2020-12-01 18:45:00 +00:00
## date\_trunc {#date_trunc}
Truncates date and time data to the specified part of date.
2021-05-28 09:14:28 +00:00
**Syntax**
``` sql
date_trunc(unit, value[, timezone])
```
2021-05-28 09:14:28 +00:00
Alias: `dateTrunc`.
2021-05-28 09:14:28 +00:00
**Arguments**
- `unit` — The type of interval to truncate the result. [String Literal](../syntax.md#syntax-string-literal).
Possible values:
- `second`
- `minute`
- `hour`
- `day`
- `week`
- `month`
- `quarter`
- `year`
- `value` — Date and time. [DateTime](../../sql-reference/data-types/datetime.md) or [DateTime64](../../sql-reference/data-types/datetime64.md).
- `timezone` — [Timezone name](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-timezone) for the returned value (optional). If not specified, the function uses the timezone of the `value` parameter. [String](../../sql-reference/data-types/string.md).
**Returned value**
- Value, truncated to the specified part of date.
Type: [Datetime](../../sql-reference/data-types/datetime.md).
**Example**
Query without timezone:
``` sql
SELECT now(), date_trunc('hour', now());
```
Result:
``` text
┌───────────────now()─┬─date_trunc('hour', now())─┐
│ 2020-09-28 10:40:45 │ 2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘
```
Query with the specified timezone:
```sql
SELECT now(), date_trunc('hour', now(), 'Europe/Moscow');
```
Result:
```text
┌───────────────now()─┬─date_trunc('hour', now(), 'Europe/Moscow')─┐
│ 2020-09-28 10:46:26 │ 2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘
```
2021-05-28 09:14:28 +00:00
**See Also**
- [toStartOfInterval](#tostartofintervaltime-or-data-interval-x-unit-time-zone)
2021-02-05 07:43:03 +00:00
## date\_add {#date_add}
2021-05-28 09:14:28 +00:00
Adds the time interval or date interval to the provided date or date with time.
2021-02-05 07:43:03 +00:00
2021-05-28 09:14:28 +00:00
**Syntax**
2021-02-05 07:43:03 +00:00
``` sql
date_add(unit, value, date)
```
2021-05-28 09:14:28 +00:00
Aliases: `dateAdd`, `DATE_ADD`.
2021-02-05 07:43:03 +00:00
2021-05-28 09:14:28 +00:00
**Arguments**
2021-02-05 07:43:03 +00:00
2021-02-05 21:33:47 +00:00
- `unit` — The type of interval to add. [String](../../sql-reference/data-types/string.md).
2021-05-28 09:14:28 +00:00
Possible values:
2021-02-05 07:43:03 +00:00
2021-05-28 09:14:28 +00:00
- `second`
- `minute`
- `hour`
- `day`
- `week`
- `month`
- `quarter`
- `year`
2021-04-09 15:37:14 +00:00
2021-06-16 18:33:44 +00:00
- `value` — Value of interval to add. [Int](../../sql-reference/data-types/int-uint.md).
2021-05-28 09:14:28 +00:00
- `date` — The date or date with time to which `value` is added. [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
2021-02-05 07:43:03 +00:00
2021-02-05 16:07:02 +00:00
**Returned value**
2021-05-28 09:14:28 +00:00
Date or date with time obtained by adding `value`, expressed in `unit`, to `date`.
Type: [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
2021-02-05 16:07:02 +00:00
2021-02-05 07:43:03 +00:00
**Example**
2021-05-28 09:14:28 +00:00
Query:
2021-02-05 07:43:03 +00:00
```sql
2021-05-28 09:14:28 +00:00
SELECT date_add(YEAR, 3, toDate('2018-01-01'));
2021-02-05 07:43:03 +00:00
```
2021-05-28 09:14:28 +00:00
Result:
2021-02-05 07:43:03 +00:00
```text
┌─plus(toDate('2018-01-01'), toIntervalYear(3))─┐
│ 2021-01-01 │
└───────────────────────────────────────────────┘
```
2021-02-05 16:55:30 +00:00
## date\_diff {#date_diff}
2021-02-05 07:43:03 +00:00
2021-05-28 09:14:28 +00:00
Returns the difference between two dates or dates with time values.
2021-02-05 07:43:03 +00:00
**Syntax**
2021-02-05 07:43:03 +00:00
``` sql
date_diff('unit', startdate, enddate, [timezone])
2021-02-05 07:43:03 +00:00
```
2021-05-28 09:14:28 +00:00
Aliases: `dateDiff`, `DATE_DIFF`.
2021-02-05 16:07:02 +00:00
2021-05-28 09:14:28 +00:00
**Arguments**
2021-02-05 07:43:03 +00:00
2021-05-28 09:14:28 +00:00
- `unit` — The type of interval for result. [String](../../sql-reference/data-types/string.md).
Possible values:
2021-02-05 07:43:03 +00:00
2021-05-28 09:14:28 +00:00
- `second`
- `minute`
- `hour`
- `day`
- `week`
- `month`
- `quarter`
- `year`
- `startdate` — The first time value to subtract (the subtrahend). [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
- `enddate` — The second time value to subtract from (the minuend). [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
2021-05-28 09:14:28 +00:00
- `timezone` — [Timezone name](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-timezone) (optional). If specified, it is applied to both `startdate` and `enddate`. If not specified, timezones of `startdate` and `enddate` are used. If they are not the same, the result is unspecified. [String](../../sql-reference/data-types/string.md).
**Returned value**
Difference between `enddate` and `startdate` expressed in `unit`.
2021-05-28 09:14:28 +00:00
Type: [Int](../../sql-reference/data-types/int-uint.md).
2021-02-05 07:43:03 +00:00
**Example**
Query:
``` sql
SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00'));
2021-02-05 07:43:03 +00:00
```
Result:
``` text
┌─dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00'))─┐
│ 25 │
└────────────────────────────────────────────────────────────────────────────────────────┘
2021-02-05 08:03:45 +00:00
```
2021-02-06 20:59:31 +00:00
## date\_sub {#date_sub}
2021-05-28 09:14:28 +00:00
Subtracts the time interval or date interval from the provided date or date with time.
2021-02-06 20:59:31 +00:00
**Syntax**
``` sql
date_sub(unit, value, date)
```
2021-05-28 09:14:28 +00:00
Aliases: `dateSub`, `DATE_SUB`.
2021-02-06 20:59:31 +00:00
2021-05-28 09:14:28 +00:00
**Arguments**
2021-02-06 20:59:31 +00:00
- `unit` — The type of interval to subtract. [String](../../sql-reference/data-types/string.md).
2021-05-28 09:14:28 +00:00
Possible values:
- `second`
- `minute`
- `hour`
- `day`
- `week`
- `month`
- `quarter`
- `year`
2021-04-09 15:37:14 +00:00
2021-06-16 18:33:44 +00:00
- `value` — Value of interval to subtract. [Int](../../sql-reference/data-types/int-uint.md).
2021-05-28 09:14:28 +00:00
- `date` — The date or date with time from which `value` is subtracted. [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
2021-02-06 20:59:31 +00:00
**Returned value**
2021-05-28 09:14:28 +00:00
Date or date with time obtained by subtracting `value`, expressed in `unit`, from `date`.
Type: [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
2021-02-06 20:59:31 +00:00
**Example**
Query:
``` sql
SELECT date_sub(YEAR, 3, toDate('2018-01-01'));
```
Result:
``` text
┌─minus(toDate('2018-01-01'), toIntervalYear(3))─┐
│ 2015-01-01 │
└────────────────────────────────────────────────┘
```
2021-02-05 08:03:45 +00:00
## timestamp\_add {#timestamp_add}
Adds the specified time value with the provided date or date time value.
2021-05-28 09:14:28 +00:00
**Syntax**
2021-02-05 08:03:45 +00:00
``` sql
timestamp_add(date, INTERVAL value unit)
```
2021-05-28 09:14:28 +00:00
Aliases: `timeStampAdd`, `TIMESTAMP_ADD`.
**Arguments**
2021-04-09 15:37:14 +00:00
2021-05-28 09:14:28 +00:00
- `date` — Date or date with time. [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
- `value` — Value of interval to add. [Int](../../sql-reference/data-types/int-uint.md).
2021-02-05 21:33:47 +00:00
- `unit` — The type of interval to add. [String](../../sql-reference/data-types/string.md).
2021-05-28 09:14:28 +00:00
Possible values:
2021-02-05 08:03:45 +00:00
2021-05-28 09:14:28 +00:00
- `second`
- `minute`
- `hour`
- `day`
- `week`
- `month`
- `quarter`
- `year`
2021-02-05 16:07:02 +00:00
**Returned value**
2021-05-28 09:14:28 +00:00
Date or date with time with the specified `value` expressed in `unit` added to `date`.
Type: [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
2021-02-05 08:03:45 +00:00
**Example**
2021-05-28 09:14:28 +00:00
Query:
2021-02-05 08:03:45 +00:00
```sql
select timestamp_add(toDate('2018-01-01'), INTERVAL 3 MONTH);
```
2021-05-28 09:14:28 +00:00
Result:
2021-02-05 08:03:45 +00:00
```text
┌─plus(toDate('2018-01-01'), toIntervalMonth(3))─┐
│ 2018-04-01 │
└────────────────────────────────────────────────┘
```
## timestamp\_sub {#timestamp_sub}
2021-05-28 09:14:28 +00:00
Subtracts the time interval from the provided date or date with time.
2021-02-05 08:03:45 +00:00
2021-05-28 09:14:28 +00:00
**Syntax**
2021-02-05 08:03:45 +00:00
``` sql
timestamp_sub(unit, value, date)
```
2021-05-28 09:14:28 +00:00
Aliases: `timeStampSub`, `TIMESTAMP_SUB`.
2021-02-05 08:03:45 +00:00
2021-05-28 09:14:28 +00:00
**Arguments**
2021-02-05 08:03:45 +00:00
2021-05-28 09:14:28 +00:00
- `unit` — The type of interval to subtract. [String](../../sql-reference/data-types/string.md).
Possible values:
2021-04-09 15:37:14 +00:00
2021-05-28 09:14:28 +00:00
- `second`
- `minute`
- `hour`
- `day`
- `week`
- `month`
- `quarter`
- `year`
2021-06-16 18:33:44 +00:00
- `value` — Value of interval to subtract. [Int](../../sql-reference/data-types/int-uint.md).
2021-05-28 09:14:28 +00:00
- `date` — Date or date with time. [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
2021-02-05 16:07:02 +00:00
**Returned value**
2021-05-28 09:14:28 +00:00
Date or date with time obtained by subtracting `value`, expressed in `unit`, from `date`.
Type: [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
2021-02-05 08:03:45 +00:00
**Example**
2021-05-28 09:14:28 +00:00
Query:
2021-02-05 08:03:45 +00:00
```sql
select timestamp_sub(MONTH, 5, toDateTime('2018-12-18 01:02:03'));
```
2021-05-28 09:14:28 +00:00
Result:
2021-02-05 08:03:45 +00:00
```text
┌─minus(toDateTime('2018-12-18 01:02:03'), toIntervalMonth(5))─┐
│ 2018-07-18 01:02:03 │
└──────────────────────────────────────────────────────────────┘
2021-02-05 07:43:03 +00:00
```
2021-05-28 09:14:28 +00:00
2020-12-01 18:45:00 +00:00
## now {#now}
2021-05-28 09:14:28 +00:00
Returns the current date and time.
2021-05-28 09:14:28 +00:00
**Syntax**
``` sql
now([timezone])
```
2021-05-28 09:14:28 +00:00
**Arguments**
- `timezone` — [Timezone name](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-timezone) for the returned value (optional). [String](../../sql-reference/data-types/string.md).
**Returned value**
- Current date and time.
Type: [Datetime](../../sql-reference/data-types/datetime.md).
**Example**
Query without timezone:
``` sql
SELECT now();
```
Result:
``` text
┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘
```
Query with the specified timezone:
``` sql
SELECT now('Europe/Moscow');
```
Result:
``` text
┌─now('Europe/Moscow')─┐
│ 2020-10-17 10:42:23 │
└──────────────────────┘
```
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## today {#today}
2017-04-26 19:16:38 +00:00
Accepts zero arguments and returns the current date at one of the moments of request execution.
2020-03-20 10:10:48 +00:00
The same as toDate(now()).
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## yesterday {#yesterday}
2020-03-20 10:10:48 +00:00
Accepts zero arguments and returns yesterdays date at one of the moments of request execution.
The same as today() - 1.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## timeSlot {#timeslot}
2017-04-26 19:16:38 +00:00
Rounds the time to the half hour.
2020-03-20 10:10:48 +00:00
This function is specific to Yandex.Metrica, since half an hour is the minimum amount of time for breaking a session into two sessions if a tracking tag shows a single users consecutive pageviews that differ in time by strictly more than this amount. This means that tuples (the tag ID, user ID, and time slot) can be used to search for pageviews that are included in the corresponding session.
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
## toYYYYMM {#toyyyymm}
2020-03-20 10:10:48 +00:00
Converts a date or date with time to a UInt32 number containing the year and month number (YYYY \* 100 + MM).
2020-03-20 10:10:48 +00:00
## toYYYYMMDD {#toyyyymmdd}
2020-03-20 10:10:48 +00:00
Converts a date or date with time to a UInt32 number containing the year and month number (YYYY \* 10000 + MM \* 100 + DD).
2020-03-20 10:10:48 +00:00
## toYYYYMMDDhhmmss {#toyyyymmddhhmmss}
2020-03-20 10:10:48 +00:00
Converts a date or date with time to a UInt64 number containing the year and month number (YYYY \* 10000000000 + MM \* 100000000 + DD \* 1000000 + hh \* 10000 + mm \* 100 + ss).
2020-03-20 10:10:48 +00:00
## addYears, addMonths, addWeeks, addDays, addHours, addMinutes, addSeconds, addQuarters {#addyears-addmonths-addweeks-adddays-addhours-addminutes-addseconds-addquarters}
Function adds a Date/DateTime interval to a Date/DateTime and then return the Date/DateTime. For example:
2020-03-20 10:10:48 +00:00
``` sql
WITH
toDate('2018-01-01') AS date,
toDateTime('2018-01-01 00:00:00') AS date_time
SELECT
addYears(date, 1) AS add_years_with_date,
addYears(date_time, 1) AS add_years_with_date_time
```
2020-03-20 10:10:48 +00:00
``` text
┌─add_years_with_date─┬─add_years_with_date_time─┐
│ 2019-01-01 │ 2019-01-01 00:00:00 │
└─────────────────────┴──────────────────────────┘
```
2020-03-20 10:10:48 +00:00
## subtractYears, subtractMonths, subtractWeeks, subtractDays, subtractHours, subtractMinutes, subtractSeconds, subtractQuarters {#subtractyears-subtractmonths-subtractweeks-subtractdays-subtracthours-subtractminutes-subtractseconds-subtractquarters}
Function subtract a Date/DateTime interval to a Date/DateTime and then return the Date/DateTime. For example:
2020-03-20 10:10:48 +00:00
``` sql
WITH
toDate('2019-01-01') AS date,
toDateTime('2019-01-01 00:00:00') AS date_time
SELECT
subtractYears(date, 1) AS subtract_years_with_date,
subtractYears(date_time, 1) AS subtract_years_with_date_time
```
2020-03-20 10:10:48 +00:00
``` text
┌─subtract_years_with_date─┬─subtract_years_with_date_time─┐
│ 2018-01-01 │ 2018-01-01 00:00:00 │
└──────────────────────────┴───────────────────────────────┘
```
2020-03-20 10:10:48 +00:00
## timeSlots(StartTime, Duration,\[, Size\]) {#timeslotsstarttime-duration-size}
2020-03-20 10:10:48 +00:00
For a time interval starting at StartTime and continuing for Duration seconds, it returns an array of moments in time, consisting of points from this interval rounded down to the Size in seconds. Size is an optional parameter: a constant UInt32, set to 1800 by default.
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 {#formatdatetime}
2021-05-28 09:14:28 +00:00
Formats a Time according to the given Format string. Format is a constant expression, so you cannot have multiple formats for a single result column.
**Syntax**
``` sql
formatDateTime(Time, Format\[, Timezone\])
```
**Returned value(s)**
2020-03-20 10:10:48 +00:00
2021-06-16 18:33:44 +00:00
Returns time and date values according to the determined format.
**Replacement fields**
Using replacement fields, you can define a pattern for the resulting string. “Example” column shows formatting result for `2018-01-02 22:33:44`.
| Placeholder | Description | Example |
|----------|---------------------------------------------------------|------------|
2020-03-20 10:10:48 +00:00
| %C | year divided by 100 and truncated to integer (00-99) | 20 |
| %d | day of the month, zero-padded (01-31) | 02 |
| %D | Short MM/DD/YY date, equivalent to %m/%d/%y | 01/02/18 |
2021-05-28 09:14:28 +00:00
| %e | day of the month, space-padded ( 1-31) |   2 |
2020-03-20 10:10:48 +00:00
| %F | short YYYY-MM-DD date, equivalent to %Y-%m-%d | 2018-01-02 |
| %G | four-digit year format for ISO week number, calculated from the week-based year [defined by the ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Week_dates) standard, normally useful only with %V | 2018 |
| %g | two-digit year format, aligned to ISO 8601, abbreviated from four-digit notation | 18 |
2020-03-20 10:10:48 +00:00
| %H | hour in 24h format (00-23) | 22 |
| %I | hour in 12h format (01-12) | 10 |
| %j | day of the year (001-366) | 002 |
| %m | month as a decimal number (01-12) | 01 |
| %M | minute (00-59) | 33 |
| %n | new-line character () | |
| %p | AM or PM designation | PM |
| %Q | Quarter (1-4) | 1 |
2020-03-20 10:10:48 +00:00
| %R | 24-hour HH:MM time, equivalent to %H:%M | 22:33 |
| %S | second (00-59) | 44 |
| %t | horizontal-tab character () | |
| %T | ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S | 22:33:44 |
| %u | ISO 8601 weekday as number with Monday as 1 (1-7) | 2 |
| %V | ISO 8601 week number (01-53) | 01 |
| %w | weekday as a decimal number with Sunday as 0 (0-6) | 2 |
| %y | Year, last two digits (00-99) | 18 |
| %Y | Year | 2018 |
| %% | a % sign | % |
**Example**
Query:
``` sql
SELECT formatDateTime(toDate('2010-01-04'), '%g')
```
Result:
```
┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10 │
└────────────────────────────────────────────┘
```
2021-06-16 18:33:44 +00:00
## dateName {#dataname}
Returns specified part of date.
2021-06-16 18:33:44 +00:00
**Syntax**
``` sql
dateName(date_part, date)
```
**Arguments**
- `date_part` — Date part. Possible values: 'year', 'quarter', 'month', 'week', 'dayofyear', 'day', 'weekday', 'hour', 'minute', 'second'. [String](../../sql-reference/data-types/string.md).
2021-06-29 01:55:31 +00:00
- `date` — Date. [Date](../../sql-reference/data-types/date.md), [DateTime](../../sql-reference/data-types/datetime.md) or [DateTime64](../../sql-reference/data-types/datetime64.md).
2021-06-29 00:59:19 +00:00
- `timezone` — Timezone. Optional. [String](../../sql-reference/data-types/string.md).
2021-06-16 18:33:44 +00:00
**Returned value**
- The specified part of date.
2021-06-16 18:33:44 +00:00
Type: [String](../../sql-reference/data-types/string.md#string)
**Example**
Query:
```sql
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT dateName('year', date_value), dateName('month', date_value), dateName('day', date_value);
```
Result:
```text
┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021 │ April │ 14 │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────
```
2021-05-26 12:38:54 +00:00
## FROM\_UNIXTIME {#fromunixfime}
2020-07-14 06:29:01 +00:00
2021-05-28 09:14:28 +00:00
Function converts Unix timestamp to a calendar date and a time of a day. When there is only a single argument of [Integer](../../sql-reference/data-types/int-uint.md) type, it acts in the same way as [toDateTime](../../sql-reference/functions/type-conversion-functions.md#todatetime) and return [DateTime](../../sql-reference/data-types/datetime.md) type.
2020-07-14 06:29:01 +00:00
2021-05-28 09:14:28 +00:00
**Example:**
Query:
2020-07-14 06:29:01 +00:00
```sql
2021-05-28 09:14:28 +00:00
SELECT FROM_UNIXTIME(423543535);
2020-07-14 06:29:01 +00:00
```
2021-05-28 09:14:28 +00:00
Result:
2020-07-14 06:29:01 +00:00
```text
┌─FROM_UNIXTIME(423543535)─┐
│ 1983-06-04 10:58:55 │
└──────────────────────────┘
```
2021-05-28 09:14:28 +00:00
When there are two arguments: first is an [Integer](../../sql-reference/data-types/int-uint.md) or [DateTime](../../sql-reference/data-types/datetime.md), second is a constant format string — it acts in the same way as [formatDateTime](#formatdatetime) and return [String](../../sql-reference/data-types/string.md#string) type.
2020-07-14 06:29:01 +00:00
For example:
```sql
2021-05-28 09:14:28 +00:00
SELECT FROM_UNIXTIME(1234334543, '%Y-%m-%d %R:%S') AS DateTime;
2020-07-14 06:29:01 +00:00
```
```text
┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘
```
2020-12-08 15:32:55 +00:00
## toModifiedJulianDay {#tomodifiedjulianday}
Converts a [Proleptic Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar) date in text form `YYYY-MM-DD` to a [Modified Julian Day](https://en.wikipedia.org/wiki/Julian_day#Variants) number in Int32. This function supports date from `0000-01-01` to `9999-12-31`. It raises an exception if the argument cannot be parsed as a date, or the date is invalid.
**Syntax**
``` sql
2020-12-08 15:32:55 +00:00
toModifiedJulianDay(date)
```
2021-05-28 09:14:28 +00:00
**Arguments**
- `date` — Date in text form. [String](../../sql-reference/data-types/string.md) or [FixedString](../../sql-reference/data-types/fixedstring.md).
**Returned value**
- Modified Julian Day number.
Type: [Int32](../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
2020-12-08 15:32:55 +00:00
SELECT toModifiedJulianDay('2020-01-01');
```
Result:
``` text
2020-12-08 15:32:55 +00:00
┌─toModifiedJulianDay('2020-01-01')─┐
│ 58849 │
└───────────────────────────────────┘
```
2020-12-08 15:32:55 +00:00
## toModifiedJulianDayOrNull {#tomodifiedjuliandayornull}
2020-12-08 15:32:55 +00:00
Similar to [toModifiedJulianDay()](#tomodifiedjulianday), but instead of raising exceptions it returns `NULL`.
**Syntax**
``` sql
2020-12-08 15:32:55 +00:00
toModifiedJulianDayOrNull(date)
```
2021-05-28 09:14:28 +00:00
**Arguments**
- `date` — Date in text form. [String](../../sql-reference/data-types/string.md) or [FixedString](../../sql-reference/data-types/fixedstring.md).
**Returned value**
- Modified Julian Day number.
Type: [Nullable(Int32)](../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
2020-12-08 15:32:55 +00:00
SELECT toModifiedJulianDayOrNull('2020-01-01');
```
Result:
``` text
2020-12-08 15:32:55 +00:00
┌─toModifiedJulianDayOrNull('2020-01-01')─┐
│ 58849 │
└─────────────────────────────────────────┘
```
2020-12-08 15:32:55 +00:00
## fromModifiedJulianDay {#frommodifiedjulianday}
Converts a [Modified Julian Day](https://en.wikipedia.org/wiki/Julian_day#Variants) number to a [Proleptic Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar) date in text form `YYYY-MM-DD`. This function supports day number from `-678941` to `2973119` (which represent 0000-01-01 and 9999-12-31 respectively). It raises an exception if the day number is outside of the supported range.
**Syntax**
``` sql
2020-12-08 15:32:55 +00:00
fromModifiedJulianDay(day)
```
2021-05-28 09:14:28 +00:00
**Arguments**
- `day` — Modified Julian Day number. [Any integral types](../../sql-reference/data-types/int-uint.md).
**Returned value**
- Date in text form.
Type: [String](../../sql-reference/data-types/string.md)
**Example**
Query:
``` sql
2020-12-08 15:32:55 +00:00
SELECT fromModifiedJulianDay(58849);
```
Result:
``` text
2020-12-08 15:32:55 +00:00
┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01 │
└──────────────────────────────┘
```
2020-12-08 15:32:55 +00:00
## fromModifiedJulianDayOrNull {#frommodifiedjuliandayornull}
2020-12-08 15:32:55 +00:00
Similar to [fromModifiedJulianDayOrNull()](#frommodifiedjuliandayornull), but instead of raising exceptions it returns `NULL`.
**Syntax**
``` sql
2020-12-08 15:32:55 +00:00
fromModifiedJulianDayOrNull(day)
```
2021-05-28 09:14:28 +00:00
**Arguments**
- `day` — Modified Julian Day number. [Any integral types](../../sql-reference/data-types/int-uint.md).
**Returned value**
- Date in text form.
Type: [Nullable(String)](../../sql-reference/data-types/string.md)
**Example**
Query:
``` sql
2020-12-08 15:32:55 +00:00
SELECT fromModifiedJulianDayOrNull(58849);
```
Result:
``` text
2020-12-08 15:32:55 +00:00
┌─fromModifiedJulianDayOrNull(58849)─┐
│ 2020-01-01 │
└────────────────────────────────────┘
```