日付と時刻を扱う関数

このセクションのほとんどの関数は、Europe/Amsterdam のようなオプションのタイムゾーン引数を指定できます。この場合、タイムゾーンにはローカル（デフォルト）のタイムゾーンではなく、指定したタイムゾーンが使用されます。

例

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

┌────────────────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 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘

UTCTimestamp

導入バージョン: v22.11

クエリ解析時点の現在の日時を返します。この関数は定数式です。

この関数は now('UTC') と同じ結果を返します。MySQL との互換性のためだけに追加されました。代わりに now を使用することが推奨されます。

構文

UTCTimestamp()

別名: UTC_timestamp

引数

なし。

戻り値

クエリ解析時点の現在の日時を返します。DateTime

例

現在の UTC タイムスタンプを取得

SELECT UTCTimestamp()

┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘

YYYYMMDDToDate

導入バージョン: v23.9

年・月・日を表す数値を Date に変換します。この関数は、toYYYYMMDD() 関数とは逆の動作を行います。入力が有効な Date 値を表していない場合、出力は未定義です。

構文

YYYYMMDDToDate(YYYYMMDD)

引数

YYYYMMDD — 年・月・日を表す数値。(U)Int* または Float* または Decimal

戻り値

指定された引数から Date 型の値を返します。Date

使用例

例

SELECT YYYYMMDDToDate(20230911);

┌─toYYYYMMDD(20230911)─┐
│           2023-09-11 │
└──────────────────────┘

YYYYMMDDToDate32

導入バージョン: v23.9

年・月・日を表す数値を Date32 に変換します。この関数は、toYYYYMMDD() 関数の逆です。入力値が有効な Date32 値を表していない場合、出力は未定義です。

構文

YYYYMMDDToDate32(YYYYMMDD)

引数

YYYYMMDD — 年・月・日を含む数値。(U)Int* または Float* または Decimal

戻り値

指定された引数から Date32 値を返します。Date32

使用例

例

SELECT YYYYMMDDToDate32(20000507);

┌─YYYYMMDDToDate32(20000507)─┐
│                 2000-05-07 │
└────────────────────────────┘

YYYYMMDDhhmmssToDateTime

導入: v23.9

年・月・日・時・分・秒を含む数値を DateTime に変換します。この関数は、関数 toYYYYMMDDhhmmss() の逆です。入力が有効な DateTime 値を表していない場合、出力結果は未定義です。

構文

YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])

引数

YYYYMMDDhhmmss — 年、月、日、時、分、秒を表す数値。(U)Int* または Float* または Decimal
timezone — タイムゾーン名を示す文字列。String

返される値

指定された引数から DateTime 型の値を返します。DateTime

使用例

例

SELECT YYYYMMDDToDateTime(20230911131415);

┌──────YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│                           2023-09-11 13:14:15 │
└───────────────────────────────────────────────┘

YYYYMMDDhhmmssToDateTime64

導入バージョン: v23.9

年、月、日、時、分、秒を含む数値を DateTime64 に変換します。この関数は、関数 toYYYYMMDDhhmmss() の逆です。入力が有効な DateTime64 値をエンコードしていない場合、出力は未定義です。

構文

YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])

引数

YYYYMMDDhhmmss — 年・月・日・時・分・秒を含む数値。(U)Int* または Float* または Decimal
precision — 小数部の精度（0〜9）。UInt8
timezone — タイムゾーン名。String

戻り値

指定された引数から DateTime64 型の値を生成して返します。DateTime64

例

SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');

┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│  2023-09-11 13:14:15.000 │
└──────────────────────────┘

addDate

導入バージョン: v23.9

指定された日付、日時、または日付／日時を表す文字列に、時間間隔を加算します。加算の結果がデータ型の範囲外になる場合、結果は未定義です。

構文

addDate(datetime, interval)

引数

datetime — interval を加算する対象となる日付または日時。Date または Date32 または DateTime または DateTime64 または String
interval — 加算するインターバル。Interval

戻り値

datetime に interval を加算して得られる日付または日時を返します。Date または Date32 または DateTime または DateTime64

使用例

日付へのインターバルの加算

SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)

┌─addDate(toDa⋯valYear(3))─┐
│               2021-01-01 │
└──────────────────────────┘

addDays

導入バージョン: v1.1

指定した日数を、日付、日時、または文字列表現の日付／日時に加算します。

構文

addDays(datetime, num)

引数

datetime — 指定した日数を加算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 加算する日数。(U)Int* または Float*

戻り値

datetime に num 日を加算した値を返します。Date または Date32 または DateTime または DateTime64

例

さまざまな日付型に日数を加算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addDays(date, 5) AS add_days_with_date,
    addDays(date_time, 5) AS add_days_with_date_time,
    addDays(date_time_string, 5) AS add_days_with_date_time_string

┌─add_days_with_date─┬─add_days_with_date_time─┬─add_days_with_date_time_string─┐
│         2024-01-06 │     2024-01-06 00:00:00 │        2024-01-06 00:00:00.000 │
└────────────────────┴─────────────────────────┴────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)

┌─plus(CAST('1⋯valDay(10))─┐
│               1998-06-26 │
└──────────────────────────┘

addHours

導入バージョン: v1.1

指定した時間数を、日付型、日時型、または文字列としてエンコードされた日付・日時に加算します。

構文

addHours(datetime, num)

引数

datetime — 指定した時間数を加算する対象となる日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 加算する時間数。(U)Int* または Float*

戻り値

datetime に num 時間を加算した値を返します。型は DateTime または DateTime64(3) です。

例

異なる日付型に時間を加算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addHours(date, 12) AS add_hours_with_date,
    addHours(date_time, 12) AS add_hours_with_date_time,
    addHours(date_time_string, 12) AS add_hours_with_date_time_string

┌─add_hours_with_date─┬─add_hours_with_date_time─┬─add_hours_with_date_time_string─┐
│ 2024-01-01 12:00:00 │      2024-01-01 12:00:00 │         2024-01-01 12:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)

┌─plus(CAST('1⋯alHour(10))─┐
│      1998-06-16 10:00:00 │
└──────────────────────────┘

addInterval

導入バージョン: v22.11

ある interval または interval のタプルに、別の interval を加算します。

注記

同じ型の interval は 1 つの interval に集約されます。たとえば toIntervalDay(1) と toIntervalDay(2) を渡した場合、結果は (1,1) ではなく (3) になります。

構文

addInterval(interval_1, interval_2)

引数

interval_1 — 最初の Interval または Interval のタプル。Interval または Tuple(Interval)
interval_2 — 加算する 2 つ目の Interval。Interval

戻り値

Interval のタプル Tuple(Interval) を返します

例

Interval を加算する

SELECT addInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT addInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT addInterval(INTERVAL 2 DAY, INTERVAL 1 DAY)

┌─addInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,1)                                             │
└───────────────────────────────────────────────────┘
┌─addInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,1)                                                                │
└────────────────────────────────────────────────────────────────────────┘
┌─addInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (3)                                             │
└─────────────────────────────────────────────────┘

addMicroseconds

導入バージョン: v22.6

時刻付き日付、または文字列表現の時刻付き日付に、指定したマイクロ秒数を加算します。

構文

addMicroseconds(datetime, num)

引数

datetime — 指定したマイクロ秒数を加算する日付と時刻。DateTime または DateTime64 または String
num — 加算するマイクロ秒数。(U)Int* または Float*

返される値

date_time に num マイクロ秒を加算した値を返します。型は DateTime64 です。

例

異なる日付時刻型にマイクロ秒を加算する

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMicroseconds(date_time, 1000000) AS add_microseconds_with_date_time,
    addMicroseconds(date_time_string, 1000000) AS add_microseconds_with_date_time_string

┌─add_microseconds_with_date_time─┬─add_microseconds_with_date_time_string─┐
│      2024-01-01 00:00:01.000000 │             2024-01-01 00:00:01.000000 │
└─────────────────────────────────┴────────────────────────────────────────┘

別の INTERVAL 構文を使用する

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)

┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘

addMilliseconds

導入バージョン: v22.6

指定したミリ秒数を、日時型または日時を表す文字列に加算します。

構文

addMilliseconds(datetime, num)

引数

datetime — 指定したミリ秒数を加算する対象の日時。DateTime または DateTime64 または String
num — 加算するミリ秒数。(U)Int* または Float*

戻り値

datetime に num ミリ秒を加算した値を返します。型は DateTime64 です。

使用例

異なる日時型にミリ秒を加算する

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMilliseconds(date_time, 1000) AS add_milliseconds_with_date_time,
    addMilliseconds(date_time_string, 1000) AS add_milliseconds_with_date_time_string

┌─add_milliseconds_with_date_time─┬─add_milliseconds_with_date_time_string─┐
│         2024-01-01 00:00:01.000 │                2024-01-01 00:00:01.000 │
└─────────────────────────────────┴────────────────────────────────────────┘

INTERVAL の別構文を使用する

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)

┌─plus(CAST('1⋯second(10))─┐
│  1998-06-16 00:00:00.010 │
└──────────────────────────┘

addMinutes

導入バージョン: v1.1

日付、日時、または文字列表現の日付／日時に、指定した分数を加算します。

構文

addMinutes(datetime, num)

引数

datetime — 指定した分の値を加算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 加算する分の値。(U)Int* または Float*

戻り値

datetime に num 分を加算した値を返す。型は DateTime または DateTime64(3)

使用例

異なる日付型に分を加算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMinutes(date, 20) AS add_minutes_with_date,
    addMinutes(date_time, 20) AS add_minutes_with_date_time,
    addMinutes(date_time_string, 20) AS add_minutes_with_date_time_string

┌─add_minutes_with_date─┬─add_minutes_with_date_time─┬─add_minutes_with_date_time_string─┐
│   2024-01-01 00:20:00 │        2024-01-01 00:20:00 │           2024-01-01 00:20:00.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)

┌─plus(CAST('1⋯Minute(10))─┐
│      1998-06-16 00:10:00 │
└──────────────────────────┘

addMonths

導入: v1.1

日付、日時、または文字列表現の日付・日時に対して、指定した月数を加算します。

構文

addMonths(datetime, num)

引数

datetime — 指定した月数を加算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 加算する月数。(U)Int* または Float*

戻り値

datetime に num か月を加算した結果を返します。型は Date または Date32 または DateTime または DateTime64

使用例

さまざまな日付型に対して月を加算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMonths(date, 6) AS add_months_with_date,
    addMonths(date_time, 6) AS add_months_with_date_time,
    addMonths(date_time_string, 6) AS add_months_with_date_time_string

┌─add_months_with_date─┬─add_months_with_date_time─┬─add_months_with_date_time_string─┐
│           2024-07-01 │       2024-07-01 00:00:00 │          2024-07-01 00:00:00.000 │
└──────────────────────┴───────────────────────────┴──────────────────────────────────┘

別の INTERVAL 構文の利用

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)

┌─plus(CAST('1⋯lMonth(10))─┐
│               1999-04-16 │
└──────────────────────────┘

addNanoseconds

導入バージョン: v22.6

日時または文字列表現の日時に、指定したナノ秒を加算します。

構文

addNanoseconds(datetime, num)

引数

datetime — 指定したナノ秒を加算する日時。DateTime または DateTime64 または String
num — 加算するナノ秒数。(U)Int* または Float*

戻り値

datetime に num ナノ秒を加算した値を返します。型は DateTime64 です。

例

異なる日時型にナノ秒を加算する

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addNanoseconds(date_time, 1000) AS add_nanoseconds_with_date_time,
    addNanoseconds(date_time_string, 1000) AS add_nanoseconds_with_date_time_string

┌─add_nanoseconds_with_date_time─┬─add_nanoseconds_with_date_time_string─┐
│  2024-01-01 00:00:00.000001000 │         2024-01-01 00:00:00.000001000 │
└────────────────────────────────┴───────────────────────────────────────┘

別の INTERVAL 構文の使用

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)

┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘

addQuarters

導入バージョン: v20.1

日付、日付と時刻、または文字列表現の日付／日付と時刻に対して、指定した数の四半期を加算します。

構文

addQuarters(datetime, num)

引数

datetime — 指定した四半期数を加算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 加算する四半期の数。(U)Int* または Float*

戻り値

datetime に num 四半期を加算した値を返します。型は Date または Date32 または DateTime または DateTime64 です。

例

異なる日付型に四半期を加算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addQuarters(date, 1) AS add_quarters_with_date,
    addQuarters(date_time, 1) AS add_quarters_with_date_time,
    addQuarters(date_time_string, 1) AS add_quarters_with_date_time_string

┌─add_quarters_with_date─┬─add_quarters_with_date_time─┬─add_quarters_with_date_time_string─┐
│             2024-04-01 │         2024-04-01 00:00:00 │            2024-04-01 00:00:00.000 │
└────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

INTERVAL の別構文を使用する

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)

┌─plus(CAST('1⋯uarter(10))─┐
│               2000-12-16 │
└──────────────────────────┘

addSeconds

導入バージョン: v1.1

指定した秒数を、Date 型、日時型、またはそれらを文字列としてエンコードした値に加算します。

構文

addSeconds(datetime, num)

引数

datetime — 指定した秒数を加算する対象となる日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 加算する秒数。(U)Int* または Float*

返り値

datetime に num 秒を加算した値を返します。型は DateTime または DateTime64(3) です。

使用例

異なる日付型に秒数を加算

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addSeconds(date, 30) AS add_seconds_with_date,
    addSeconds(date_time, 30) AS add_seconds_with_date_time,
    addSeconds(date_time_string, 30) AS add_seconds_with_date_time_string

┌─add_seconds_with_date─┬─add_seconds_with_date_time─┬─add_seconds_with_date_time_string─┐
│   2024-01-01 00:00:30 │        2024-01-01 00:00:30 │           2024-01-01 00:00:30.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)

┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│                             1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘

addTupleOfIntervals

導入バージョン: v22.11

日付または日時に対して、間隔タプルを順に加算します。

構文

addTupleOfIntervals(datetime, intervals)

引数

datetime — 加算対象となる日付または日時。Date または Date32 または DateTime または DateTime64
intervals — datetime に加算するインターバルのタプル。Tuple(Interval)

返り値

intervals を加算した date を返します。型は Date または Date32 または DateTime または DateTime64

例

日付にインターバルのタプルを加算する

WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))

┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│                                                                           2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘

addWeeks

v1.1 で導入

指定した数の週を、date、日時付きの date、またはそれらを文字列としてエンコードした値に加算します。

構文

addWeeks(datetime, num)

引数

datetime — 指定した週数を加算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 加算する週数。(U)Int* または Float*

戻り値

datetime に num 週を加算した値を返します。型は Date または Date32 または DateTime または DateTime64 です。

例

異なる日付型に週を加算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addWeeks(date, 5) AS add_weeks_with_date,
    addWeeks(date_time, 5) AS add_weeks_with_date_time,
    addWeeks(date_time_string, 5) AS add_weeks_with_date_time_string

┌─add_weeks_with_date─┬─add_weeks_with_date_time─┬─add_weeks_with_date_time_string─┐
│          2024-02-05 │      2024-02-05 00:00:00 │         2024-02-05 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

別の INTERVAL 構文の利用

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)

┌─plus(CAST('1⋯alWeek(10))─┐
│               1998-08-25 │
└──────────────────────────┘

addYears

導入バージョン: v1.1

指定した年数を、日付、日時、または文字列表現の日付もしくは日時に加算します。

構文

addYears(datetime, num)

引数

datetime — 指定した年数を加算する対象の日付または日時。Date、Date32、DateTime、DateTime64、String のいずれか。
num — 加算する年数。(U)Int* または Float*

戻り値

datetime に num 年を加算した値を返します。型は Date、Date32、DateTime、DateTime64 のいずれか。

例

異なる日付型に年数を加算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addYears(date, 1) AS add_years_with_date,
    addYears(date_time, 1) AS add_years_with_date_time,
    addYears(date_time_string, 1) AS add_years_with_date_time_string

┌─add_years_with_date─┬─add_years_with_date_time─┬─add_years_with_date_time_string─┐
│          2025-01-01 │      2025-01-01 00:00:00 │         2025-01-01 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)

┌─plus(CAST('1⋯alYear(10))─┐
│               2008-06-16 │
└──────────────────────────┘

age

導入バージョン: v23.1

startdate と enddate の差分のうち、指定した単位の値を返します。差分は 1 ナノ秒の精度で計算されます。

たとえば、2021-12-29 と 2022-01-01 の差分は、日単位では 3 日、月単位では 0 か月、年単位では 0 年です。

age の代替としては、dateDiff 関数を参照してください。

構文

age('unit', startdate, enddate[, timezone])

引数

unit — 結果を表す時間間隔の単位。

Unit	取りうる値
nanosecond	`nanosecond`, `nanoseconds`, `ns`
microsecond	`microsecond`, `microseconds`, `us`, `u`
millisecond	`millisecond`, `milliseconds`, `ms`
second	`second`, `seconds`, `ss`, `s`
minute	`minute`, `minutes`, `mi`, `n`
hour	`hour`, `hours`, `hh`, `h`
day	`day`, `days`, `dd`, `d`
week	`week`, `weeks`, `wk`, `ww`
month	`month`, `months`, `mm`, `m`
quarter	`quarter`, `quarters`, `qq`, `q`
year	`year`, `years`, `yyyy`, `yy`

startdate — 減算される側の最初の時刻値（減数）。Date または Date32 または DateTime または DateTime64
enddate — 減算する側の 2 番目の時刻値（被減数）。Date または Date32 または DateTime または DateTime64
timezone — 省略可能。タイムゾーン名。指定された場合、startdate と enddate の両方に適用されます。指定されていない場合、startdate と enddate にそれぞれ設定されているタイムゾーンが使用されます。両者が同じでない場合、結果は未定義となります。String

戻り値

enddate から startdate を引いた差を、unit で表した値を返します。Int32

使用例

時間単位で年齢を計算する

SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))

┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│                                                                                24 │
└───────────────────────────────────────────────────────────────────────────────────┘

異なる単位で年齢を計算する

SELECT
    toDate('2022-01-01') AS e,
    toDate('2021-12-29') AS s,
    age('day', s, e) AS day_age,
    age('month', s, e) AS month_age,
    age('year', s, e) AS year_age

┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │       3 │         0 │        0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘

changeDay

導入バージョン: v24.7

日付または日時の「日」要素を変更します。

構文

changeDay(date_or_datetime, value)

引数

date_or_datetime — 変更対象の値。Date または Date32 または DateTime または DateTime64
value — 新しい値。(U)Int*

返り値

date_or_datetime と同じ型で、日を変更した値を返します。Date または Date32 または DateTime または DateTime64

例

使用例

SELECT changeDay('2024-01-31'::DateTime, 15)

2024-01-15 00:00:00

changeHour

導入バージョン: v24.7

日付または日時の「時」部分を変更します。

構文

changeHour(date_or_datetime, value)

引数

date_or_datetime — 変更する値。Date または Date32 または DateTime または DateTime64
value — 新しい値。(U)Int*

返り値

date_or_datetime と同じ型で、時の部分が変更された値を返します。DateTime または DateTime64

例

使用例

SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)

2024-01-01 05:00:00

changeMinute

導入バージョン: v24.7

日付または日時の「分」要素を変更します。

構文

changeMinute(date_or_datetime, value)

引数

date_or_datetime — 変更する値。Date または Date32 または DateTime または DateTime64
value — 新しい値。(U)Int*

戻り値

date_or_datetime と同じ型で、分の値を変更したものを返します。DateTime または DateTime64

例

使用例

SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)

2024-01-01 12:45:00

changeMonth

導入バージョン: v24.7

日付または日時の月の部分を変更します。

構文

changeMonth(date_or_datetime, value)

引数

date_or_datetime — 変更対象の値。Date または Date32 または DateTime または DateTime64
value — 新しい値。(U)Int*

戻り値

date_or_datetime と同じ型で、月の部分が変更された値を返します。Date または Date32 または DateTime または DateTime64

例

使用例

SELECT changeMonth('2024-01-01'::DateTime, 12)

2024-12-01 00:00:00

changeSecond

導入バージョン: v24.7

日付または日時の秒の部分を変更します。

構文

changeSecond(date_or_datetime, value)

引数

date_or_datetime — 変更する値。Date または Date32 または DateTime または DateTime64
value — 設定する新しい値。(U)Int*

返される値

date_or_datetime と同じ型で、秒の部分が変更された値を返します。DateTime または DateTime64

例

使用例

SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)

2024-01-01 12:30:15

changeYear

導入バージョン: v24.7

日付または日時の年の部分を変更します。

構文

changeYear(date_or_datetime, value)

引数

date_or_datetime — 変更対象の値。Date または Date32 または DateTime または DateTime64
value — 設定する新しい値。(U)Int*

戻り値

date_or_datetime と同じ型で、年の値が変更された値を返します。Date または Date32 または DateTime または DateTime64

例

使用例

SELECT changeYear('2024-01-01'::DateTime, 2023)

2023-01-01 00:00:00

dateDiff

導入バージョン: v23.4

指定した unit について、startdate と enddate の間で跨いだ境界の数を返します。差分は相対単位を使って計算されます。例えば、2021-12-29 と 2022-01-01 の差分は、day 単位では 3 日（toRelativeDayNum を参照）、month 単位では 1 か月（toRelativeMonthNum を参照）、year 単位では 1 年（toRelativeYearNum を参照）です。

week 単位が指定された場合、dateDiff は週の開始日を月曜日として扱います。この動作は、デフォルトで週の開始日を日曜日とする関数 toWeek() とは異なることに注意してください。

dateDiff の代替としては、関数 age を参照してください。

構文

dateDiff(unit, startdate, enddate[, timezone])

別名: timestampDiff, date_diff, TIMESTAMP_DIFF, DATE_DIFF, timestamp_diff

引数

unit — 結果の間隔を表す単位。

Unit	取りうる値
nanosecond	`nanosecond`, `nanoseconds`, `ns`
microsecond	`microsecond`, `microseconds`, `us`, `u`
millisecond	`millisecond`, `milliseconds`, `ms`
second	`second`, `seconds`, `ss`, `s`
minute	`minute`, `minutes`, `mi`, `n`
hour	`hour`, `hours`, `hh`, `h`
day	`day`, `days`, `dd`, `d`
week	`week`, `weeks`, `wk`, `ww`
month	`month`, `months`, `mm`, `m`
quarter	`quarter`, `quarters`, `qq`, `q`
year	`year`, `years`, `yyyy`, `yy`

startdate — 減算される最初の時刻値（減数）。Date または Date32 または DateTime または DateTime64
enddate — 減算の基準となる 2 番目の時刻値（被減数）。Date または Date32 または DateTime または DateTime64
timezone — オプション。タイムゾーン名。指定された場合は startdate と enddate の両方に適用されます。指定しない場合は、それぞれの startdate と enddate に設定されているタイムゾーンが使用されます。それらが同一でない場合、結果は未定義です。String

戻り値

enddate から startdate を引いた差を、unit で表した値を返します。Int64

例

日付の差を時間単位で計算する

SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res

┌─res─┐
│  25 │
└─────┘

日付の差をさまざまな単位で計算する

SELECT
    toDate('2022-01-01') AS e,
    toDate('2021-12-29') AS s,
    dateDiff('day', s, e) AS day_diff,
    dateDiff('month', s, e) AS month_diff,
    dateDiff('year', s, e) AS year_diff

┌──────────e─┬──────────s─┬─day_diff─┬─month_diff─┬─year_diff─┐
│ 2022-01-01 │ 2021-12-29 │        3 │          1 │         1 │
└────────────┴────────────┴──────────┴────────────┴───────────┘

dateName

導入: v21.7

日付の指定された部分を返します。

指定可能な値:

'year'
'quarter'
'month'
'week'
'dayofyear'
'day'
'weekday'
'hour'
'minute'
'second'

構文

dateName(date_part, date[, timezone])

引数

date_part — 抽出したい日付要素。String
datetime — 日付、または日付と時刻の値。Date または Date32 または DateTime または DateTime64
timezone — 省略可能。タイムゾーン。String

戻り値

指定した日付要素を返します。String

例

さまざまな日付要素の抽出

WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT
    dateName('year', date_value),
    dateName('month', date_value),
    dateName('day', date_value)

┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021                         │ April                         │ 14                          │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘

dateTrunc

導入バージョン: v20.8

日付時刻の値を、指定した日付部分まで切り捨てます。

構文

dateTrunc(unit, datetime[, timezone])

別名: DATE_TRUNC

引数

unit — 結果をどの時間単位で切り捨てるかを指定します。unit 引数は大文字と小文字を区別しません。
Unit Compatibility
nanosecond DateTime64 にのみ対応
microsecond DateTime64 にのみ対応
millisecond DateTime64 にのみ対応
second
minute
hour
day
week
month
quarter
year
String
datetime — 日付と時刻。Date または Date32 または DateTime または DateTime64
timezone — 省略可能。返される datetime のタイムゾーン名を指定します。指定されていない場合、関数は datetime パラメータのタイムゾーンを使用します。String

Unit	Compatibility
`nanosecond`	DateTime64 にのみ対応
`microsecond`	DateTime64 にのみ対応
`millisecond`	DateTime64 にのみ対応
`second`
`minute`
`hour`
`day`
`week`
`month`
`quarter`
`year`
`String`

返される値

切り捨て後の日付と時刻の値を返します。

Unit Argument	`datetime` Argument	Return Type
Year, Quarter, Month, Week	`Date32` or `DateTime64` or `Date` or `DateTime`	`Date32` or `Date`
Day, Hour, Minute, Second	`Date32`, `DateTime64`, `Date`, or `DateTime`	`DateTime64` or `DateTime`
Millisecond, Microsecond,	Any	`DateTime64`
Nanosecond		スケール 3、6、または 9

例

タイムゾーンを指定せずに切り捨て

SELECT now(), dateTrunc('hour', now());

┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │       2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘

指定タイムゾーンでの切り捨て

SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');

┌───────────────now()─┬─dateTrunc('hour', now(), 'Asia/Istanbul')──┐
│ 2020-09-28 10:46:26 │                        2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘

formatDateTime

導入バージョン: v1.1

指定されたフォーマット文字列に従って、日付または日時をフォーマットします。format は定数式であるため、1つの結果カラムに対して複数のフォーマットを指定することはできません。

formatDateTime は MySQL の datetime フォーマットスタイルを使用します。mysql docs を参照してください。

この関数の逆操作は parseDateTime です。

置換フィールドを使用して、結果文字列のパターンを定義できます。以下の表の「例」カラムは、2018-01-02 22:33:44 をフォーマットした結果を示します。

置換フィールド:

Placeholder	説明	例
%a	曜日の省略名 (Mon-Sun)	Mon
%b	月の省略名 (Jan-Dec)	Jan
%c	月を整数 (01-12) で表現	01
%C	西暦年を 100 で割り、整数に切り捨てた値 (00-99)	20
%d	日 (ゼロ詰め) (01-31)	02
%D	短い MM/DD/YY 日付形式。%m/%d/%y と同等	01/02/18
%e	日 (スペース詰め) (1-31)	2
%f	小数部の秒	123456
%F	短い YYYY-MM-DD 日付形式。%Y-%m-%d と同等	2018-01-02
%g	ISO 8601 に合わせた 2 桁の年	18
%G	ISO 週番号に対応する 4 桁の年	2018
%h	12 時間制の時 (01-12)	09
%H	24 時間制の時 (00-23)	22
%i	分 (00-59)	33
%I	12 時間制の時 (01-12)	10
%j	年内通算日 (001-366)	002
%k	24 時間制の時 (00-23)	14
%l	12 時間制の時 (01-12)	09
%m	月を整数 (01-12) で表現	01
%M	月名 (January-December)	January
%n	改行文字
%p	AM か PM の区別	PM
%Q	四半期 (1-4)	1
%r	12 時間制 HH:MM AM/PM 形式。%h:%i %p と同等	10:30 PM
%R	24 時間制 HH:MM 形式。%H:%i と同等	22:33
%s	秒 (00-59)	44
%S	秒 (00-59)	44
%t	水平タブ文字
%T	ISO 8601 時刻形式 (HH:MM:SS)。%H:%i:%S と同等	22:33:44
%u	ISO 8601 の曜日番号 (月曜を 1 とする 1-7)	2
%V	ISO 8601 の週番号 (01-53)	01
%w	曜日を整数で表現 (日曜を 0 とする 0-6)	2
%W	曜日の完全名 (Monday-Sunday)	Monday
%y	西暦年の下 2 桁 (00-99)	18
%Y	西暦年	2018
%z	UTC からの時差 (+HHMM または -HHMM)	-0500
%%	% 記号	%

ClickHouse v23.4 より前のバージョンでは、フォーマット対象が Date、Date32、DateTime (いずれも秒の小数部を持たない) または精度 0 の DateTime64 の場合、%f は単一のゼロ (0) を出力します。
ClickHouse v25.1 より前のバージョンでは、%f は固定の 6 桁ではなく、DateTime64 のスケールで指定された桁数を出力します。
ClickHouse v23.4 より前のバージョンでは、%M は月名 (January-December) ではなく分 (00-59) を出力します。

構文

formatDateTime(datetime, format[, timezone])

別名: DATE_FORMAT

引数

datetime — 書式設定する日付または日時。Date または Date32 または DateTime または DateTime64
format — 置換フィールドを含む書式文字列。String
timezone — 省略可能。書式化された時刻に使用するタイムゾーン名。String

戻り値

指定された書式に従った日時の値を返します。String

例

年のプレースホルダーを使って日付をフォーマットする

SELECT formatDateTime(toDate('2010-01-04'), '%g')

┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10                                         │
└────────────────────────────────────────────┘

小数秒を含めて DateTime64 をフォーマットする

SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')

┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560                                                             │
└─────────────────────────────────────────────────────────────────────┘

タイムゾーン付きでのフォーマット

SELECT
    now() AS ts,
    time_zone,
    formatDateTime(ts, '%T', time_zone) AS str_tz_time
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

┌──────────────────ts─┬─time_zone─────────┬─str_tz_time─┐
│ 2023-09-08 19:13:40 │ Europe/Amsterdam  │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Andorra    │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Astrakhan  │ 23:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Athens     │ 22:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Belfast    │ 20:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Belgrade   │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Berlin     │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Bratislava │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Brussels   │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Bucharest  │ 22:13:40    │
└─────────────────────┴───────────────────┴─────────────┘

formatDateTimeInJodaSyntax

導入バージョン: v20.1

formatDateTime と似ていますが、MySQL スタイルではなく Joda スタイルで日時をフォーマットします。Joda Time ドキュメントを参照してください。

この関数の逆の操作は parseDateTimeInJodaSyntax です。

置換フィールドを使用して、結果の文字列のパターンを定義できます。

置換フィールド:

Placeholder	説明	表示形式	例
G	紀元	テキスト	AD
C	紀元の世紀 (>=0)	数値	20
Y	紀元の年 (>=0)	年	1996
x	weekyear (未サポート)	年	1996
w	weekyear 内の週 (未サポート)	数値	27
e	曜日	数値	2
E	曜日	テキスト	Tuesday; Tue
y	年	年	1996
D	年内通算日	数値	189
M	月	月	July; Jul; 07
d	日 (月内通算日)	数値	10
a	午前/午後	テキスト	PM
K	午前/午後内の時 (0〜11)	数値	0
h	午前/午後の時刻 (1〜12)	数値	12
H	一日の時 (0〜23)	数値	0
k	一日の時刻 (1〜24)	数値	24
m	分	数値	30
s	秒	数値	55
S	秒の小数部	数値	978
z	タイムゾーン	テキスト	Eastern Standard Time; EST
Z	タイムゾーンオフセット	ゾーン	-0800; -0812
'	テキストのエスケープ	デリミタ
''	シングルクォート	リテラル	'

構文

formatDateTimeInJodaSyntax(datetime, format[, timezone])

引数

datetime — フォーマットする日付または日時。DateTime または Date または Date32 または DateTime64
format — Joda スタイルの置換フィールドを含むフォーマット文字列。String
timezone — 省略可。フォーマット時に使用するタイムゾーン名。String

返される値

指定されたフォーマットに従って日付と時刻の値を返します。String

例

Joda 構文を使用して datetime をフォーマットする

SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')

┌─formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')─┐
│ 2010-01-04 12:34:56                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────────┘

fromDaysSinceYearZero

導入バージョン: v23.11

西暦 0000 年 1 月 1 日からの経過日数を指定すると、ISO 8601 で定義されるプロレプティック・グレゴリオ暦に対応する日付を返します。

計算方法は MySQL の FROM_DAYS() 関数と同じです。結果が Date 型の範囲内で表現できない場合、結果は未定義です。

構文

fromDaysSinceYearZero(days)

エイリアス: FROM_DAYS

引数

days — 西暦0年から経過した日数。UInt32

戻り値

西暦0年からの経過日数に対応する日付を返します。Date

例

西暦0年からの経過日数を日付に変換する

SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2

┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

fromDaysSinceYearZero32

導入バージョン: v23.11

0000年1月1日からの経過日数を指定すると、ISO 8601 で定義されるプロレプティック・グレゴリオ暦における対応する日付を返します。計算方法は MySQL の FROM_DAYS() 関数と同じです。結果が Date32 型の範囲内で表現できない場合、結果は未定義です。

構文

fromDaysSinceYearZero32(days)

引数

days — 紀元年（year zero）から経過した日数。UInt32

返される値

紀元年（year zero）からの経過日数に対応する日付を返します。Date32

例

紀元年（year zero）からの経過日数を日付に変換する

SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2

┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

fromModifiedJulianDay

導入バージョン: v21.1

修正ユリウス日の数値を、テキスト形式 YYYY-MM-DD のプロレプティック・グレゴリオ暦の日付に変換します。この関数は、-678941 から 2973483 までの日番号をサポートします（それぞれ 0000-01-01 および 9999-12-31 を表します）。サポート範囲外の値が指定された場合は例外をスローします。

構文

fromModifiedJulianDay(day)

引数

day — 修正ユリウス日番号。(U)Int*

戻り値

テキスト形式の日付を返します。String

例

修正ユリウス日を日付に変換する

SELECT fromModifiedJulianDay(58849)

┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01                   │
└──────────────────────────────┘

fromModifiedJulianDayOrNull

導入バージョン: v21.1

fromModifiedJulianDay() と同様ですが、例外をスローする代わりに NULL を返します。

構文

fromModifiedJulianDayOrNull(day)

引数

day — 修正ユリウス日番号。(U)Int*

戻り値

有効な day 引数に対しては文字列形式の日付を返し、引数が無効な場合は null を返します。Nullable(String)

使用例

修正ユリウス日を null 処理を考慮して日付に変換する

SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- 無効な引数、NULLを返す

┌─fromModified⋯Null(58849)─┐
│ 2020-01-01               │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ                     │
└──────────────────────────┘

fromUTCTimestamp

導入バージョン: v22.1

日付または日時の値を、UTC タイムゾーンから指定したタイムゾーンの日付または日時の値に変換します。この関数は主に、Apache Spark や類似のフレームワークとの互換性を保つために提供されています。

構文

fromUTCTimestamp(datetime, time_zone)

別名: from_utc_timestamp

引数

datetime — 日付、または時刻付き日付の定数値、もしくは式。DateTime または DateTime64
time_zone — タイムゾーンを表す String 型の定数値、もしくは式。String

返される値

指定されたタイムゾーンの DateTime/DateTime64 値を返します。DateTime または DateTime64

例

UTC タイムゾーンを指定したタイムゾーンに変換する

SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')

┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00',3), 'Asia/Shanghai')─┐
│                                                 2023-03-16 18:00:00.000 │
└─────────────────────────────────────────────────────────────────────────┘

fromUnixTimestamp

導入バージョン: v20.8

この関数は Unix タイムスタンプを日付および一日の時刻に変換します。

2 通りの呼び出し方があります。

単一の引数として型 Integer を取る場合、型 DateTime の値を返します。つまり、toDateTime と同様に動作します。
2 つまたは 3 つの引数を取り、1 番目の引数が型 Integer、Date、Date32、DateTime または DateTime64 の値であり、2 番目の引数が定数のフォーマット文字列、3 番目の引数が省略可能な定数のタイムゾーン文字列である場合、この関数は型 String の値を返します。つまり、formatDateTime と同様に動作します。この場合、MySQL の datetime フォーマット形式が使用されます。

構文

fromUnixTimestamp(timestamp)
fromUnixTimestamp(timestamp[, format[, timezone]])

別名: FROM_UNIXTIME

引数

timestamp — Unix タイムスタンプ、または日付／日時を表す値。(U)Int* または Date または Date32 または DateTime または DateTime64
format — 省略可能。出力用の定数フォーマット文字列。String
timezone — 省略可能。タイムゾーンを表す定数文字列。String

戻り値

引数が 1 つの場合は、そのタイムスタンプに対応する DateTime を返し、引数が 2 つまたは 3 つの場合は String を返します。DateTime または String

例

Unix タイムスタンプを DateTime に変換する

SELECT fromUnixTimestamp(423543535)

┌─fromUnixTimestamp(423543535)─┐
│          1983-06-04 10:58:55 │
└──────────────────────────────┘

Unix タイムスタンプを指定フォーマットに変換

SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime

┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘

fromUnixTimestampInJodaSyntax

導入バージョン: v23.1

この関数は Unix タイムスタンプをカレンダー日付および時刻に変換します。

呼び出し方法は 2 通りあります。

単一の引数として Integer 型を渡した場合、DateTime 型の値を返します。つまり、toDateTime と同様に動作します。

1 番目の引数が Integer、Date、Date32、DateTime あるいは DateTime64 型の値であり、2 番目の引数に定数のフォーマット文字列、3 番目の引数に省略可能な定数のタイムゾーン文字列を指定した 2 つまたは 3 つの引数で呼び出した場合、関数は String 型の値を返します。つまり、formatDateTimeInJodaSyntax と同様に動作します。この場合、Joda の日時フォーマットスタイルが使用されます。

構文

fromUnixTimestampInJodaSyntax(timestamp)
fromUnixTimestampInJodaSyntax(timestamp, format[, timezone])

引数

timestamp — Unix タイムスタンプまたは日付/時刻の値。(U)Int* または Date または Date32 または DateTime または DateTime64
format — 省略可能。出力の書式指定に Joda 構文を使用する定数のフォーマット文字列。String
timezone — 省略可能。タイムゾーンを表す定数文字列。String

戻り値

1 つの引数で呼び出された場合は日時を、2 または 3 つの引数で呼び出された場合は文字列を返します。DateTime または String

例

Unix タイムスタンプを Joda フォーマットで変換する

SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime

┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘

makeDate

導入バージョン: v22.6

次のいずれかから Date を生成します：

年・月・日
年・年内通算日

構文

makeDate(year, month, day)
makeDate(year, day_of_year)

引数

year — 年を表す数値。(U)Int* または Float* または Decimal
month — 月を表す数値 (1-12)。(U)Int* または Float* または Decimal
day — 日を表す数値 (1-31)。(U)Int* または Float* または Decimal
day_of_year — 年初からの通算日 (1-365)。(U)Int* または Float* または Decimal

戻り値

指定した引数から構築された Date 型の値を返します。Date

使用例

年・月・日から Date 値を作成する

SELECT makeDate(2023, 2, 28) AS date;

┌───────date─┐
│ 2023-02-28 │
└────────────┘

年と年内通算日から日付を生成

SELECT makeDate(2023, 42) AS date;

┌───────date─┐
│ 2023-02-11 │
└────────────┘

makeDate32

導入バージョン: v22.6

次のいずれかから Date32 を生成します:

年・月・日
年と年内通算日（通し日）

構文

makeDate32(year, month, day)
makeDate32(year, day_of_year)

引数

year — 年を表す数値。(U)Int* または Float* または Decimal
month — 月を表す数値 (1-12)。(U)Int* または Float* または Decimal
day — 月の日 (1-31)。(U)Int* または Float* または Decimal
day_of_year — 年内通算日 (1-365)。(U)Int* または Float* または Decimal

戻り値

指定した引数から構築された Date32 型の値を返します。

例

year, month, day から Date32 を生成

SELECT makeDate(2023, 2, 28) AS date;

┌───────date─┐
│ 2023-02-28 │
└────────────┘

年と年内通算日からの Date32

SELECT makeDate(2023, 42) AS date;

┌───────date─┐
│ 2023-02-11 │
└────────────┘

makeDateTime

導入バージョン: v22.6

年、月、日、時、分、秒から DateTime を生成し、タイムゾーンを任意指定できます。

構文

makeDateTime(year, month, day, hour, minute, second[, timezone])

引数

year — 年を表す数値。(U)Int* または Float* または Decimal
month — 月を表す数値 (1-12)。(U)Int* または Float* または Decimal
day — 月内の日付 (1-31)。(U)Int* または Float* または Decimal
hour — 時 (0-23)。(U)Int* または Float* または Decimal
minute — 分 (0-59)。(U)Int* または Float* または Decimal
second — 秒 (0-59)。(U)Int* または Float* または Decimal
timezone — タイムゾーン名。String

戻り値

指定した引数から構築される DateTime 値を返します。DateTime

例

year, month, day, hour, minute, second から DateTime を構築

SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;

┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘

makeDateTime64

導入バージョン: v22.6

年、月、日、時、分、秒に、オプションの小数部、精度、タイムゾーンを指定して、DateTime64 を生成します。

構文

makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])

引数

year — 年を表す数値。(U)Int* または Float* または Decimal
month — 月の番号 (1-12)。(U)Int* または Float* または Decimal
day — 月の日付 (1-31)。(U)Int* または Float* または Decimal
hour — 時 (0-23)。(U)Int* または Float* または Decimal
minute — 分 (0-59)。(U)Int* または Float* または Decimal
second — 秒 (0-59)。(U)Int* または Float* または Decimal
fraction — 秒の小数部分。(U)Int* または Float* または Decimal
precision — 小数部分の精度 (0-9)。UInt8
timezone — タイムゾーン名。String

戻り値

指定された引数から構築された DateTime64 型の値を返します。DateTime64

例

year, month, day, hour, minute, second から DateTime64 を生成

SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);

┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│                       2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘

monthName

導入バージョン: v22.1

日付または日時の値から、月名を文字列として返します。

構文

monthName(datetime)

引数

datetime — 日付または日時。Date、Date32、DateTime、DateTime64 のいずれか。

戻り値

月の名前を返します。String

使用例

日付から月名を取得する

WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)

┌─monthName(date_value)─┐
│ April                 │
└───────────────────────┘

now

導入バージョン: v1.1

クエリ解析時の現在の日時を返します。この関数は定数式です。

構文

now([timezone])

別名: current_timestamp

引数

timezone — 省略可能。返される値のタイムゾーン名。String

戻り値

現在の日付と時刻を返します。DateTime

例

タイムゾーンを指定しないクエリ

SELECT now()

┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘

タイムゾーンを指定したクエリ

SELECT now('Asia/Istanbul')

┌─now('Asia/Istanbul')─┐
│  2020-10-17 10:42:23 │
└──────────────────────┘

now64

導入バージョン: v20.1

クエリ解析時の現在の日時をサブ秒精度で返します。この関数は定数式です。

構文

now64([scale[, timezone]])

引数

scale — 任意。ティックサイズ（精度）：10^-scale 秒。許容範囲: [0 : 9]。一般的には 3（デフォルト）（ミリ秒）、6（マイクロ秒）、9（ナノ秒）が使用されます。UInt8
timezone — 任意。返される値のタイムゾーン名。String

返される値

サブ秒精度で現在の日時を返します。DateTime64

例

デフォルト精度およびカスタム精度でのクエリ

SELECT now64(), now64(9, 'Asia/Istanbul')

┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘

nowInBlock

導入バージョン: v22.8

各データブロックの処理時点における現在の日時を返します。関数 now と異なり、これは定数式ではなく、長時間実行されるクエリではブロックごとに異なる値が返されます。

長時間実行される INSERT SELECT クエリで現在時刻を生成する用途に適しています。

構文

nowInBlock([timezone])

引数

timezone — 省略可能。返される値のタイムゾーン名です。String

戻り値

各データブロックを処理している時点の現在の日付と時刻を返します。DateTime

例

now() 関数との違い

SELECT
    now(),
    nowInBlock(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock

┌───────────────now()─┬────────nowInBlock()─┬─sleep(1)─┐
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:19 │        0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:20 │        0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:21 │        0 │
└─────────────────────┴─────────────────────┴──────────┘

nowInBlock64

導入バージョン: v25.8

各データブロックを処理する時点の現在の日時をミリ秒単位で返します。関数 now64 と異なり、これは定数式ではなく、長時間実行されるクエリではブロックごとに異なる値が返されます。

長時間実行される INSERT SELECT クエリで現在時刻を生成する場合に、この関数を使用するのが有効です。

構文

nowInBlock([scale[, timezone]])

引数

scale — 省略可。ティックサイズ（精度）。単位は 10^-precision 秒。有効範囲: [0 : 9]。一般的な値は 3（デフォルト、ミリ秒）、6（マイクロ秒）、9（ナノ秒）です。UInt8
timezone — 省略可。戻り値のタイムゾーン名。String

戻り値

各データブロックを処理する時点の現在日時を、サブ秒精度で返します。DateTime64

例

now64() 関数との違い

SELECT
    now64(),
    nowInBlock64(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock

┌─────────────────now64()─┬──────────nowInBlock64()─┬─sleep(1)─┐
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:29.534 │        0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:30.535 │        0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:31.535 │        0 │
└─────────────────────────┴─────────────────────────┴──────────┘

serverTimezone

導入バージョン: v23.6

サーバーのタイムゾーン、つまり timezone 設定の値を返します。関数が分散テーブルのコンテキストで実行される場合は、各分片に対応する値を持つ通常のカラムを返します。そうでない場合は定数値を返します。

構文

serverTimeZone()

別名: serverTimeZone

引数

なし。

戻り値

サーバーのタイムゾーンを String 型として返します。

例

使用例

SELECT serverTimeZone()

┌─serverTimeZone()─┐
│ UTC              │
└──────────────────┘

subDate

導入バージョン: v23.9

指定された日付、日時、または文字列エンコードされた日付または日時から時間間隔を減算します。減算の結果がデータ型の範囲外となる場合、結果は未定義です。

構文

subDate(datetime, interval)

引数

datetime — interval を差し引く元となる日付または日付時刻。Date または Date32 または DateTime または DateTime64
interval — 減算する間隔値。Interval

戻り値

datetime から interval を減算して得られた日付または日付時刻を返します。Date または Date32 または DateTime または DateTime64

例

日付から interval を減算する

SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)

┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│                                       2015-01-01 │
└──────────────────────────────────────────────────┘

subtractDays

導入バージョン: v1.1

日付、日時、または文字列で表現された日付/日時から、指定した日数を減算します。

構文

subtractDays(datetime, num)

引数

datetime — 指定した日数を減算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 減算する日数。(U)Int* または Float*

戻り値

datetime から num 日を減算した値を返します。型は Date または Date32 または DateTime または DateTime64 のいずれかです。

例

異なる日付型から日数を減算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractDays(date, 31) AS subtract_days_with_date,
    subtractDays(date_time, 31) AS subtract_days_with_date_time,
    subtractDays(date_time_string, 31) AS subtract_days_with_date_time_string

┌─subtract_days_with_date─┬─subtract_days_with_date_time─┬─subtract_days_with_date_time_string─┐
│              2023-12-01 │          2023-12-01 00:00:00 │             2023-12-01 00:00:00.000 │
└─────────────────────────┴──────────────────────────────┴─────────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)

┌─minus(CAST('⋯valDay(10))─┐
│               1998-06-06 │
└──────────────────────────┘

subtractHours

導入バージョン: v1.1

日付、日時、または文字列でエンコードされた日付もしくは日時から、指定した時間数だけ差し引きます。

構文

subtractHours(datetime, num)

引数

datetime — 指定した時間を減算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 減算する時間数。(U)Int* または Float*

戻り値

datetime から num 時間を引いた結果を返す。型は DateTime または DateTime64(3)

使用例

異なる日付型から時間を減算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractHours(date, 12) AS subtract_hours_with_date,
    subtractHours(date_time, 12) AS subtract_hours_with_date_time,
    subtractHours(date_time_string, 12) AS subtract_hours_with_date_time_string

┌─subtract_hours_with_date─┬─subtract_hours_with_date_time─┬─subtract_hours_with_date_time_string─┐
│      2023-12-31 12:00:00 │           2023-12-31 12:00:00 │              2023-12-31 12:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

別の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)

┌─minus(CAST('⋯alHour(10))─┐
│      1998-06-15 14:00:00 │
└──────────────────────────┘

subtractInterval

導入バージョン: v22.11

符号を反転させたインターバルを、別のインターバルまたはインターバルのタプルに加算します。

注意: 同じ型のインターバルは 1 つのインターバルに結合されます。例えば toIntervalDay(2) と toIntervalDay(1) が渡された場合、結果は (2,1) ではなく (1) になります。

構文

subtractInterval(interval_1, interval_2)

引数

interval_1 — 1 つ目の interval、または interval のタプル。Interval または Tuple(Interval)
interval_2 — 符号反転される 2 つ目の interval。Interval

戻り値

interval のタプル Tuple(T) を返します。

例

interval の減算

SELECT subtractInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT subtractInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT subtractInterval(INTERVAL 2 DAY, INTERVAL 1 DAY);

┌─subtractInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,-1)                                                 │
└────────────────────────────────────────────────────────┘
┌─subtractInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,-1)                                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─subtractInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (1)                                                  │
└──────────────────────────────────────────────────────┘

subtractMicroseconds

導入バージョン: v22.6

指定されたマイクロ秒数を、日時または文字列表現の日時から減算します。

構文

subtractMicroseconds(datetime, num)

引数

datetime — 指定されたマイクロ秒数を減算する対象の日時。DateTime または DateTime64 または String
num — 減算するマイクロ秒数。(U)Int* または Float*

返り値

datetime から num マイクロ秒を引いた値を返します。型は DateTime64 です。

例

異なる日時データ型からマイクロ秒を減算する

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMicroseconds(date_time, 1000000) AS subtract_microseconds_with_date_time,
    subtractMicroseconds(date_time_string, 1000000) AS subtract_microseconds_with_date_time_string

┌─subtract_microseconds_with_date_time─┬─subtract_microseconds_with_date_time_string─┐
│           2023-12-31 23:59:59.000000 │                  2023-12-31 23:59:59.000000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘

別の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)

┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘

subtractMilliseconds

導入バージョン: v22.6

日時、または文字列表現の日時から、指定したミリ秒数を減算します。

構文

subtractMilliseconds(datetime, num)

引数

datetime — 指定したミリ秒数を減算する対象の日時。DateTime または DateTime64 または String
num — 減算するミリ秒数。(U)Int* または Float*

戻り値

datetime から num ミリ秒を引いた値を返します。型は DateTime64 です。

使用例

異なる日時型に対してミリ秒を減算する

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMilliseconds(date_time, 1000) AS subtract_milliseconds_with_date_time,
    subtractMilliseconds(date_time_string, 1000) AS subtract_milliseconds_with_date_time_string

┌─subtract_milliseconds_with_date_time─┬─subtract_milliseconds_with_date_time_string─┐
│              2023-12-31 23:59:59.000 │                     2023-12-31 23:59:59.000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)

┌─minus(CAST('⋯second(10))─┐
│  1998-06-15 23:59:59.990 │
└──────────────────────────┘

subtractMinutes

導入バージョン: v1.1

指定した分数を、日付、日時、または文字列表現の日付／日時から減算します。

構文

subtractMinutes(datetime, num)

引数

datetime — 指定した分数（分の数）を減算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 減算する分数（分の数）。(U)Int* または Float*

戻り値

datetime から num 分を減算した値を返します。型は DateTime または DateTime64(3) です。

使用例

異なる日付型から分を減算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMinutes(date, 30) AS subtract_minutes_with_date,
    subtractMinutes(date_time, 30) AS subtract_minutes_with_date_time,
    subtractMinutes(date_time_string, 30) AS subtract_minutes_with_date_time_string

┌─subtract_minutes_with_date─┬─subtract_minutes_with_date_time─┬─subtract_minutes_with_date_time_string─┐
│        2023-12-31 23:30:00 │             2023-12-31 23:30:00 │                2023-12-31 23:30:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)

┌─minus(CAST('⋯Minute(10))─┐
│      1998-06-15 23:50:00 │
└──────────────────────────┘

subtractMonths

導入バージョン: v1.1

指定した月数を、日付、日時、またはそれらを文字列として表現した値から減算します。

構文

subtractMonths(datetime, num)

引数

datetime — 指定した月数を減算する基準となる日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 減算する月数。(U)Int* または Float*

戻り値

datetime から num か月分を減算した値を返します。型は Date または Date32 または DateTime または DateTime64

使用例

異なる日付型から月を減算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMonths(date, 1) AS subtract_months_with_date,
    subtractMonths(date_time, 1) AS subtract_months_with_date_time,
    subtractMonths(date_time_string, 1) AS subtract_months_with_date_time_string

┌─subtract_months_with_date─┬─subtract_months_with_date_time─┬─subtract_months_with_date_time_string─┐
│                2023-12-01 │            2023-12-01 00:00:00 │               2023-12-01 00:00:00.000 │
└───────────────────────────┴────────────────────────────────┴───────────────────────────────────────┘

別の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)

┌─minus(CAST('⋯lMonth(10))─┐
│               1997-08-16 │
└──────────────────────────┘

subtractNanoseconds

導入バージョン: v20.1

日時型の値、または文字列表現の日時から、指定したナノ秒数を減算します。

構文

subtractNanoseconds(datetime, num)

引数

datetime — 指定したナノ秒数を減算する対象の日時。DateTime または DateTime64 または String
num — 減算するナノ秒数。(U)Int* または Float*

戻り値

datetime から num ナノ秒を引いた値を返します。戻り値の型は DateTime64 です。

使用例

異なる日時型からナノ秒を減算する

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractNanoseconds(date_time, 1000) AS subtract_nanoseconds_with_date_time,
    subtractNanoseconds(date_time_string, 1000) AS subtract_nanoseconds_with_date_time_string

┌─subtract_nanoseconds_with_date_time─┬─subtract_nanoseconds_with_date_time_string─┐
│       2023-12-31 23:59:59.999999000 │              2023-12-31 23:59:59.999999000 │
└─────────────────────────────────────┴────────────────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)

┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘

subtractQuarters

導入バージョン: v20.1

日付、日時、または文字列形式の日付・日時から、指定した数の四半期を減算します。

構文

subtractQuarters(datetime, num)

引数

datetime — 指定した四半期数を減算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 減算する四半期数。(U)Int* または Float*

戻り値

datetime から num 四半期を減算した値を返す。型は Date または Date32 または DateTime または DateTime64 のいずれか。

使用例

異なる日付型に対して四半期を減算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractQuarters(date, 1) AS subtract_quarters_with_date,
    subtractQuarters(date_time, 1) AS subtract_quarters_with_date_time,
    subtractQuarters(date_time_string, 1) AS subtract_quarters_with_date_time_string

┌─subtract_quarters_with_date─┬─subtract_quarters_with_date_time─┬─subtract_quarters_with_date_time_string─┐
│                  2023-10-01 │              2023-10-01 00:00:00 │                 2023-10-01 00:00:00.000 │
└─────────────────────────────┴──────────────────────────────────┴─────────────────────────────────────────┘

INTERVAL の別構文を使用する

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)

┌─minus(CAST('1⋯Quarter(10))─┐
│                1996-09-16 │
└───────────────────────────┘

subtractSeconds

導入バージョン: v1.1

指定した秒数を、日付、日時、または文字列表現の日時/日付から減算します。

構文

subtractSeconds(datetime, num)

引数

datetime — 指定した秒数を減算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 減算する秒数。(U)Int* または Float*

戻り値

datetime から num 秒を減算した値を返す。型は DateTime または DateTime64(3)

使用例

異なる日付型に対して秒数を減算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractSeconds(date, 60) AS subtract_seconds_with_date,
    subtractSeconds(date_time, 60) AS subtract_seconds_with_date_time,
    subtractSeconds(date_time_string, 60) AS subtract_seconds_with_date_time_string

┌─subtract_seconds_with_date─┬─subtract_seconds_with_date_time─┬─subtract_seconds_with_date_time_string─┐
│        2023-12-31 23:59:00 │             2023-12-31 23:59:00 │                2023-12-31 23:59:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘

代替の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)

┌─minus(CAST('⋯Second(10))─┐
│      1998-06-15 23:59:50 │
└──────────────────────────┘

subtractTupleOfIntervals

Introduced in: v22.11

日付または日時から、タプルで指定された複数の時間間隔を連続して差し引きます。

構文

subtractTupleOfIntervals(datetime, intervals)

引数

datetime — インターバルを減算する対象となる日付または日時。Date または Date32 または DateTime または DateTime64
intervals — datetime から減算するインターバルのタプル。Tuple(Interval)

返り値

intervals を減算した date を返します。型は Date または Date32 または DateTime または DateTime64

例

日付からインターバルのタプルを減算する

WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))

┌─subtractTupl⋯alYear(1)))─┐
│               2016-12-31 │
└──────────────────────────┘

subtractWeeks

導入バージョン: v1.1

指定した週数を、日付、日時、またはそれらを表す文字列から減算します。

構文

subtractWeeks(datetime, num)

引数

datetime — 指定した週数を減算する基準となる日付または日時。 Date または Date32 または DateTime または DateTime64 または String
num — 減算する週数。 (U)Int* または Float*

戻り値

datetime から num 週を引いた値を返します。 Date または Date32 または DateTime または DateTime64

例

異なる日付型から週を減算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractWeeks(date, 1) AS subtract_weeks_with_date,
    subtractWeeks(date_time, 1) AS subtract_weeks_with_date_time,
    subtractWeeks(date_time_string, 1) AS subtract_weeks_with_date_time_string

┌─subtract_weeks_with_date─┬─subtract_weeks_with_date_time─┬─subtract_weeks_with_date_time_string─┐
│               2023-12-25 │           2023-12-25 00:00:00 │              2023-12-25 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

別の INTERVAL 構文を使用する

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)

┌─minus(CAST('⋯alWeek(10))─┐
│               1998-04-07 │
└──────────────────────────┘

subtractYears

導入バージョン: v1.1

日付、日時、または文字列形式の日付／日時から、指定した年数を減算します。

構文

subtractYears(datetime, num)

引数

datetime — 指定した年数を減算する対象の日付または日時。Date または Date32 または DateTime または DateTime64 または String
num — 減算する年数。(U)Int* または Float*

戻り値

datetime から num 年を減算した結果を返します。型は Date または Date32 または DateTime または DateTime64 です。

使用例

さまざまな日付型から年数を減算する

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractYears(date, 1) AS subtract_years_with_date,
    subtractYears(date_time, 1) AS subtract_years_with_date_time,
    subtractYears(date_time_string, 1) AS subtract_years_with_date_time_string

┌─subtract_years_with_date─┬─subtract_years_with_date_time─┬─subtract_years_with_date_time_string─┐
│               2023-01-01 │           2023-01-01 00:00:00 │              2023-01-01 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

INTERVAL の代替構文を使用する

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)

┌─minus(CAST('⋯alYear(10))─┐
│               1988-06-16 │
└──────────────────────────┘

timeDiff

導入バージョン: v23.4

2 つの日付、または時刻情報を含む日付（日時）の差を秒単位で返します。差分は enddate - startdate として計算されます。

この関数は dateDiff('second', startdate, enddate) と同等です。

他の単位（時間、日、月など）で時間差を計算する場合は、代わりに dateDiff 関数を使用してください。

構文

timeDiff(startdate, enddate)

引数

startdate — 減算の対象となる最初の時刻値（減数）。Date または Date32 または DateTime または DateTime64
enddate — そこから減算する 2 番目の時刻値（被減数）。Date または Date32 または DateTime または DateTime64

返り値

enddate と startdate の差分を秒単位で返します。Int64

例

時間差を秒単位で計算する

SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res

┌───res─┐
│ 90000 │
└───────┘

時間差を計算して時間数に変換する

SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours

┌─hours─┐
│    25 │
└───────┘

秒を単位とする dateDiff と同等

SELECT
    timeDiff(toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS time_diff_result,
    dateDiff('second', toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS date_diff_result

┌─time_diff_result─┬─date_diff_result─┐
│           259200 │           259200 │
└──────────────────┴──────────────────┘

timeSlot

導入: v1.1

時刻を30分間隔の開始時刻に丸めます。

注記

この関数は拡張型の Date32 および DateTime64 の値を引数として受け取ることができますが、通常の範囲（Date では 1970 年から 2149 年まで / DateTime では 2106 年まで）を超える時刻を渡すと誤った結果を返します。

構文

timeSlot(time[, time_zone])

引数

time — 30 分単位の区間の開始時刻に丸める対象の時刻。DateTime または Date32 または DateTime64
time_zone — 省略可能。タイムゾーンを表す String 型の定数値または式。String

戻り値

30 分単位の区間の開始時刻に丸められた時刻を返します。DateTime

使用例

時刻を 30 分単位に丸める

SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))

┌─timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))─┐
│                                2000-01-02 03:00:00 │
└────────────────────────────────────────────────────┘

timeSlots

導入バージョン: v1.1

StartTime から始まり Duration 秒間続く時間間隔について、その区間内の時刻を配列で返します。配列に含まれる各時刻は、この区間内の時刻を秒数で Size 単位に切り捨てたものです。Size はオプションのパラメータで、デフォルトは 1800（30 分）です。

これは、例えば対応するセッション内でページビューを検索する場合などに必要となります。

DateTime64 の場合、戻り値のスケールは StartTime のスケールと異なることがあります。指定されたすべての引数の中で、最も高いスケールが採用されます。

構文

timeSlots(StartTime, Duration[, Size])

引数

StartTime — インターバルの開始時刻。DateTime または DateTime64
Duration — インターバルの継続時間（秒）。UInt32 または DateTime64
Size — 省略可能。タイムスロットのサイズ（秒）。デフォルトは 1800（30 分）。UInt32 または DateTime64

戻り値

DateTime/DateTime64 の配列を返します（戻り値の型は StartTime の型と一致します）。DateTime64 の場合、戻り値のスケールは StartTime のスケールと異なる場合があります。渡されたすべての引数のうち、最大のスケールが使用されます。Array(DateTime) または Array(DateTime64)

例

インターバルのタイムスロットを生成する

SELECT timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600));
SELECT timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299);
SELECT timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))

┌─timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600))─┐
│ ['2012-01-01 12:00:00','2012-01-01 12:30:00']               │
└─────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299)─┐
│ ['1980-12-12 20:56:13','1980-12-12 21:01:12','1980-12-12 21:06:11']     │
└─────────────────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))─┐
│ ['1980-12-12 20:56:13.0000','1980-12-12 21:01:12.0000','1980-12-12 21:06:11.0000']                        │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘

timestamp

導入バージョン: v23.9

最初の引数 expr を型 DateTime64(6) に変換します。 2番目の引数 expr_time が指定されている場合、指定された時間を変換後の値に加算します。

構文

timestamp(expr[, expr_time])

引数

expr — 日付または日時。String
expr_time — 省略可。変換後の値に加算する時刻。String

戻り値

expr を変換した値、または時刻を加算した expr を返します。型は DateTime64(6) です。

使用例

日付文字列を DateTime64(6) に変換する

SELECT timestamp('2023-12-31') AS ts;

┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘

日付文字列に時刻を追加

SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;

┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘

timezone

導入バージョン: v21.4

現在のセッションのタイムゾーン名を返すか、タイムゾーンのオフセットまたは名前を正準的なタイムゾーン名に変換します。

構文

timezone()

別名: timeZone

引数

なし。

戻り値

正規のタイムゾーン名を String として返します。

例

使用例

SELECT timezone()

┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘

timezoneOf

導入バージョン: v21.4

DateTime または DateTime64 の値のタイムゾーン名を返します。

構文

timeZoneOf(datetime)

別名: timeZoneOf

引数

datetime — 型 DateTime または DateTime64 の値。
timezone — 省略可能。datetime 値のタイムゾーンを変換する先のタイムゾーン名。型は String。

返される値

datetime のタイムゾーン名を返します。型は String。

例

使用例

SELECT timezoneOf(now());

┌─timezoneOf(now())─┐
│ Europe/Amsterdam  │
└───────────────────┘

timezoneOffset

導入バージョン: v21.6

UTC からのタイムゾーンオフセットを秒単位で返します。この関数は、指定された日時における夏時間および歴史的なタイムゾーンの変更を考慮します。

構文

timeZoneOffset(datetime)

別名: timeZoneOffset

引数

datetime — タイムゾーンオフセットを取得する対象の DateTime 値。DateTime または DateTime64

返り値

UTC からのオフセットを秒単位で返す。型は Int32

例

使用例

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;

┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │            -14400 │              -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘

toDayOfMonth

導入されたバージョン: v1.1

Date または DateTime の月の日付 (1〜31) を返します。

構文

toDayOfMonth(datetime)

エイリアス: DAY, DAYOFMONTH

引数

datetime — 日（day of month）を取得する対象となる日付または日時。Date または Date32 または DateTime または DateTime64

返される値

指定された日付/時刻の月内の日（day of month）を UInt8 型で返します。

例

使用例

SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                              21 │
└─────────────────────────────────────────────────┘

toDayOfWeek

導入バージョン: v1.1

Date または DateTime 値について、その週の曜日を表す番号を返します。

toDayOfWeek() の 2 つの引数を取る形式では、週の開始曜日を Monday または Sunday から指定でき、さらに戻り値の範囲を 0〜6 にするか 1〜7 にするかを指定できます。

Mode	First day of week	Range
0	Monday	1-7: Monday = 1, Tuesday = 2, ..., Sunday = 7
1	Monday	0-6: Monday = 0, Tuesday = 1, ..., Sunday = 6
2	Sunday	0-6: Sunday = 0, Monday = 1, ..., Saturday = 6
3	Sunday	1-7: Sunday = 1, Monday = 2, ..., Saturday = 7

構文

toDayOfWeek(datetime[, mode[, timezone]])

エイリアス: DAYOFWEEK

引数

datetime — 曜日を取得する対象の日付または日時。Date または Date32 または DateTime または DateTime64
mode — 省略可能。週モードを指定する整数 (0-3)。省略時のデフォルトは 0。UInt8
timezone — 省略可能。変換に使用するタイムゾーン。String

戻り値

指定された Date または DateTime の曜日を表す値を返す。戻り値の型は UInt8。

例

使用例

-- 以下の日付は2023年4月21日で、金曜日です:
SELECT
    toDayOfWeek(toDateTime('2023-04-21')),
    toDayOfWeek(toDateTime('2023-04-21'), 1)

┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│                                     5 │                                        4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘

toDayOfYear

導入バージョン: v18.4

Date または DateTime 値について、その年の通算日 (1〜366) を返します。

構文

toDayOfYear(datetime)

別名: DAYOFYEAR

引数

datetime — 年内通算日を取得する対象の日付または日時。Date または Date32 または DateTime または DateTime64

戻り値

指定された Date または DateTime の年内通算日を、型 UInt16 で返します。

例

使用例

SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))

┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                            111 │
└────────────────────────────────────────────────┘

toDaysSinceYearZero

導入バージョン: v23.9

指定された日付について、ISO 8601 で定義されているプロレプティック・グレゴリオ暦 (proleptic Gregorian calendar) における紀元 0000 年 1 月 1 日から経過した日数を返します。

計算方法は MySQL の TO_DAYS 関数と同じです。

構文

toDaysSinceYearZero(date[, time_zone])

別名: TO_DAYS

引数

date — 基準日（年 0 年）からの経過日数を計算する対象の日付または日時。Date または Date32 または DateTime または DateTime64
time_zone — タイムゾーン。String

戻り値

日付 0000-01-01 から経過した日数を返します。UInt32

使用例

年 0 年からの経過日数を計算

SELECT toDaysSinceYearZero(toDate('2023-09-08'))

┌─toDaysSinceYearZero(toDate('2023-09-08')))─┐
│                                     713569 │
└────────────────────────────────────────────┘

toHour

導入バージョン: v1.1

DateTime または DateTime64 型の値から、時（0〜23）の部分を返します。

構文

toHour(datetime)

エイリアス: HOUR

引数

datetime — 時間を取得する対象の日時。DateTime または DateTime64

返り値

datetime の時間 (0-23) を返します。UInt8

例

使用例

SELECT toHour(toDateTime('2023-04-21 10:20:30'))

┌─toHour(toDateTime('2023-04-21 10:20:30'))─┐
│                                        10 │
└───────────────────────────────────────────┘

toISOYear

導入バージョン: v18.4

日付または日時を ISO 年の番号に変換します。

構文

toISOYear(datetime)

引数

datetime — 日付、または日時を表す値。Date または Date32 または DateTime または DateTime64

返り値

入力値を ISO 年の番号に変換して返します。UInt16

使用例

日付値から ISO 年を取得する

SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2

┌─week1─┬─week2─┐
│    40 │    40 │
└───────┴───────┘

toLastDayOfMonth

導入バージョン: v1.1

日付または日時を、その月の最終日に切り上げます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toLastDayOfMonth(value)

別名: LAST_DAY

引数

value — 月の最終日に切り上げる対象となる日付または日時。Date または Date32 または DateTime または DateTime64

戻り値

指定された日付または日時について、その月の最終日の日付を返します。Date

使用例

月の最終日への切り上げ

SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-30 │
└─────────────────────────────────────────────────────┘

toLastDayOfWeek

導入バージョン: v23.5

日付または日時を、直近の土曜日または日曜日に丸めます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toLastDayOfWeek(datetime[, mode[, timezone]])

引数

datetime — 変換対象の日付または日時。Date または DateTime または Date32 または DateTime64
mode — toWeek() 関数で説明されているように、週の開始曜日を指定します。デフォルトは 0。UInt8
timezone — 省略可能。変換に使用するタイムゾーン。指定しない場合はサーバーのタイムゾーンが使用されます。String

返り値

指定された日付（当日を含む）以降で、mode の値に応じて最も近い土曜日または日曜日の日付を返します。Date または Date32 または DateTime または DateTime64

例

最も近い土曜日または日曜日への切り上げ

SELECT
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')), /* 金曜日 */
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* 金曜日 */
    toLastDayOfWeek(toDate('2023-04-23')), /* 日曜日 */
    toLastDayOfWeek(toDate('2023-04-23'), 1) /* 日曜日 */
FORMAT Vertical

行 1:
──────
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')):      2023-04-23
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1):   2023-04-22
toLastDayOfWeek(toDate('2023-04-23')):                   2023-04-23
toLastDayOfWeek(toDate('2023-04-23'), 1):                2023-04-23

toMillisecond

導入バージョン: v24.2

DateTime または DateTime64 の値から、ミリ秒部分（0〜999）を返します。

構文

toMillisecond(datetime)

別名: MILLISECOND

引数

datetime — ミリ秒を取得する対象とする日時。DateTime または DateTime64

戻り値

datetime の分内におけるミリ秒 (0 - 59) を返します。UInt16

例

使用例

SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));

┌──toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│                                                        456 │
└────────────────────────────────────────────────────────────┘

toMinute

導入: v1.1

Date または DateTime 型の値から分（0〜59）を返します。

構文

toMinute(datetime)

別名: MINUTE

引数

datetime — 分を取得する対象の日時。DateTime または DateTime64

戻り値

datetime の時の分 (0 - 59) を返します。UInt8

例

使用例

SELECT toMinute(toDateTime('2023-04-21 10:20:30'))

┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│                                          20 │
└─────────────────────────────────────────────┘

toModifiedJulianDay

導入バージョン: v21.1

プロレプティック・グレゴリオ暦の日付文字列 YYYY-MM-DD を、Int32 型の修正ユリウス日 (Modified Julian Day)番号に変換します。この関数は 0000-01-01 から 9999-12-31 までの日付をサポートします。引数が日付としてパースできない場合、または日付が不正な場合は例外を送出します。

構文

toModifiedJulianDay(date)

引数

date — 文字列表現の日付。String または FixedString

戻り値

修正ユリウス日番号を返します。Int32

例

日付を修正ユリウス日番号に変換する

SELECT toModifiedJulianDay('2020-01-01')

┌─toModifiedJulianDay('2020-01-01')─┐
│                             58849 │
└───────────────────────────────────┘

toModifiedJulianDayOrNull

導入バージョン: v21.1

toModifiedJulianDay() と同様ですが、例外をスローする代わりに NULL を返します。

構文

toModifiedJulianDayOrNull(date)

引数

date — 文字列表現の日付。String または FixedString

戻り値

有効な date の場合は修正ユリウス日番号を、それ以外の場合は null を返します。Nullable(Int32)

使用例

null を考慮した日付から修正ユリウス日への変換

SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- 無効な日付、NULLを返します

┌─toModifiedJu⋯020-01-01')─┐
│                    58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│                     ᴺᵁᴸᴸ │
└──────────────────────────┘

toMonday

導入バージョン: v1.1

日付または日時を同じ週の月曜日に切り下げます。日付を返します。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toMonday(value)

引数

value — 週の月曜日に切り下げる対象の日付または日時。Date または Date32 または DateTime または DateTime64

戻り値

指定された日付または日時について、同じ週の月曜日の日付を返します。Date

例

週の月曜日への切り下げ

SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- 金曜日
toMonday(toDate('2023-04-24'));              -- 既に月曜日

┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│                                  2023-04-17 │                     2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘

toMonth

導入バージョン: v1.1

Date または DateTime 値の月の値（1〜12）を返します。

構文

toMonth(datetime)

別名: MONTH

引数

datetime — 月を取得する対象の日付または日時。Date または Date32 または DateTime または DateTime64

返り値

指定された日付/時刻の月を返します。型は UInt8 です。

例

使用例

SELECT toMonth(toDateTime('2023-04-21 10:20:30'))

┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          4 │
└────────────────────────────────────────────┘

toMonthNumSinceEpoch

導入バージョン: v25.3

1970年から現在までに経過した月数を返します。

構文

toMonthNumSinceEpoch(date)

引数

date — 日付、または日時。Date、DateTime、DateTime64 のいずれか。

戻り値

正の整数値

例

SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))

toQuarter

導入バージョン: v1.1

指定した Date または DateTime の値について、その年の四半期 (1〜4) を返します。

構文

toQuarter(datetime)

別名: QUARTER

引数

datetime — 年の四半期を取得する対象の日付または日時。Date または Date32 または DateTime または DateTime64

返り値

指定された日付・時刻の年内の四半期を UInt8 型で返します。

例

使用例

SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))

┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                            2 │
└──────────────────────────────────────────────┘

toRelativeDayNum

導入バージョン: v1.1

日付または日時を、過去のある固定された時点からの経過日数に変換します。その正確な時点は実装上の詳細であり、そのためこの関数をそれ自体で利用することは想定されていません。この関数の主な目的は、2 つの日付または日時間の日数差を計算することであり、例えば toRelativeDayNum(dt1) - toRelativeDayNum(dt2) のように使用します。

構文

toRelativeDayNum(date)

引数

date — 日付、または日時。Date または DateTime または DateTime64

戻り値

過去の固定基準点からの経過日数を返します。UInt32

使用例

相対日番号を取得する

SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))

┌─minus(toRela⋯3-01-01')))─┐
│                       90 │
└──────────────────────────┘

toRelativeHourNum

導入: v1.1

日付または日時を、過去のある固定時点からの経過時間（時間数）に変換します。その固定時点がいつかは実装の詳細であり、この関数を単体で使用することは想定されていません。この関数の主な用途は、2つの日付または日時の差を時間数で計算することです。例: toRelativeHourNum(dt1) - toRelativeHourNum(dt2)。

構文

toRelativeHourNum(date)

引数

date — 日付または日時。Date または DateTime または DateTime64

戻り値

過去の固定された基準時刻からの経過時間を、時間数として返します。UInt32

例

相対的な時刻（時間番号）を取得する

SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference

┌─hours_difference─┐
│               12 │
└──────────────────┘

toRelativeMinuteNum

導入バージョン: v1.1

日付または日時を、過去のある固定時点からの経過分数に変換します。その正確な時点は実装の詳細であり、そのためこの関数を単独で使用することは想定されていません。この関数の主な目的は、2つの日付または日時の間の分単位の差分を計算することであり、例えば toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2) のように使用します。

構文

toRelativeMinuteNum(date)

引数

date — 日付または日時。Date または DateTime または DateTime64

返り値

固定された過去の基準時点からの経過分数を返します。UInt32

使用例

相対的な分の値を取得する

SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference

┌─minutes_difference─┐
│                 30 │
└────────────────────┘

toRelativeMonthNum

導入バージョン: v1.1

日付または日時を、過去のある固定時点からの経過月数に変換します。その固定時点は実装上の詳細に過ぎないため、この関数を単体で使用することは想定されていません。この関数の主な用途は、2 つの日付または日時の間の月数差を計算することです（例: toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2)）。

構文

toRelativeMonthNum(date)

引数

date — 日付または日時。Date または DateTime または DateTime64

戻り値

過去の固定基準点からの経過月数を返します。UInt32

使用例

相対月番号を取得する

SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference

┌─months_difference─┐
│                 3 │
└───────────────────┘

toRelativeQuarterNum

導入バージョン: v1.1

日付または日時を、過去のある固定時点から経過した四半期数に変換します。その正確な時点は実装上の詳細であり、そのためこの関数を単体で使用することは想定されていません。この関数の主な目的は、2つの日付または日時の間の四半期数の差を計算することであり、たとえば toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2) のように使用します。

構文

toRelativeQuarterNum(date)

引数

date — 日付または日時。Date、DateTime、DateTime64 のいずれか。

戻り値

過去の固定された基準時点からの四半期数を返します。UInt32

例

相対的な四半期番号を取得する

SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference

┌─quarters_difference─┐
│                   1 │
└─────────────────────┘

toRelativeSecondNum

導入バージョン: v1.1

日付または日時を、過去のある固定時点から経過した秒数に変換します。その基準となる正確な時刻は実装依存であり、この関数を単体で使用することは想定されていません。この関数の主な目的は、2つの日付または日時の差を秒単位で計算することであり、例えば toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2) のように使用します。

構文

toRelativeSecondNum(date)

引数

date — 日付または日時。Date または DateTime または DateTime64

戻り値

過去の固定基準時刻からの秒数を返します。UInt32

例

相対秒数を取得する

SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference

┌─seconds_difference─┐
│                 60 │
└────────────────────┘

toRelativeWeekNum

導入バージョン: v1.1

日付または日時を、過去のある固定された基準時点から経過した週数に変換します。その正確な時点は実装上の詳細であり、そのためこの関数は単体で使用することを意図していません。この関数の主な目的は、2つの日付または日時の週単位での差分を計算することであり、例えば toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2) のように使用します。

構文

toRelativeWeekNum(date)

引数

date — 日付または日時。Date または DateTime または DateTime64

戻り値

過去の固定参照点からの経過週数を返します。UInt32

例

相対週番号を取得する

SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference

┌─weeks_difference─┐
│                1 │
└──────────────────┘

toRelativeYearNum

導入バージョン: v1.1

日付または日付時刻を、過去のある固定時点からの経過年数に変換します。その正確な時点は実装上の詳細であり、したがってこの関数は単体での使用を意図していません。この関数の主な用途は、2 つの日付または日付時刻の間の年数差を計算することであり、例えば toRelativeYearNum(dt1) - toRelativeYearNum(dt2) のように使用します。

構文

toRelativeYearNum(date)

引数

date — 日付または日時。Date、DateTime、または DateTime64

戻り値

過去の固定された基準点からの年数を返します。UInt16

使用例

相対的な年数を取得する

SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)

┌─minus(toRela⋯ateTime')))─┐
│                       10 │
└──────────────────────────┘

toSecond

導入バージョン: v1.1

DateTime または DateTime64 値の秒の部分 (0-59) を返します。

構文

toSecond(datetime)

別名: SECOND

引数

datetime — 秒を取得する対象の日時。DateTime または DateTime64

戻り値

datetime の分内の秒 (0 - 59) を返します。UInt8

例

使用例

SELECT toSecond(toDateTime('2023-04-21 10:20:30'))

┌─toSecond(toDateTime('2023-04-21 10:20:30'))─┐
│                                          30 │
└─────────────────────────────────────────────┘

toStartOfDay

導入バージョン: v1.1

日付時刻を、その日の開始時刻に切り捨てます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfDay(datetime)

引数

datetime — 丸める対象の日付または日時。Date または DateTime

返される値

日付と時刻を、その日の開始時刻（00:00）まで切り捨てた値を返します。Date または DateTime または Date32 または DateTime64

例

その日の開始時刻への切り捨て

SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfDay(toDateTime('2023-04-21 10:20:30'))─┐
│                             2023-04-21 00:00:00 │
└─────────────────────────────────────────────────┘

toStartOfFifteenMinutes

導入バージョン: v1.1

日時を直前の 15 分間隔の開始時刻に切り捨てます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで制御できます。

構文

toStartOfFifteenMinutes(datetime)

引数

datetime — 丸めの対象となる日付または日時。DateTime または DateTime64

返される値

最も近い 15 分間隔の開始時刻に丸められた日時を返します。型は DateTime または DateTime64 です。

使用例

例

SELECT
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

行 1:
──────
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:15:00

toStartOfFiveMinutes

導入されたバージョン: v22.6

日時を直前の5分間隔の開始時刻に切り下げます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfFiveMinutes(datetime)

別名: toStartOfFiveMinute

引数

datetime — 丸め対象の日付と時刻。DateTime または DateTime64

返される値

最も近い5分間隔の開始時刻に丸めた日付と時刻を返します。DateTime または DateTime64

使用例

例

SELECT
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

行 1:
──────
toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00

toStartOfHour

導入バージョン: v1.1

日時を、その時刻が属する時間の先頭（ちょうどの時刻）に切り下げます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfHour(datetime)

引数

datetime — 丸め対象の日時。DateTime または DateTime64

返される値

時刻を切り捨てて、その時間の先頭（00 分 00 秒）に丸めた日時を返します。DateTime または DateTime64

使用例

時間の先頭への切り捨て

SELECT
    toStartOfHour(toDateTime('2023-04-21 10:20:30'));

┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime        │
└─────────────────────┴─────────────────┘

toStartOfISOYear

導入バージョン: v1.1

日付または日時を ISO 年の最初の日まで切り捨てます。ISO 年は通常の暦年と異なる場合があります。ISO week date を参照してください。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfISOYear(value)

引数

value — ISO 年の最初の日付へ切り捨てる対象となる日付または日時。Date または Date32 または DateTime または DateTime64

返り値

指定した日付または日時に対応する ISO 年の最初の日付を返します。Date

使用例

ISO 年の最初の日付への切り捨て

SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-01-02 │
└─────────────────────────────────────────────────────┘

toStartOfInterval

導入バージョン: v20.1

この関数は、toStartOfInterval(date_or_date_with_time, INTERVAL x unit [, time_zone]) 構文で、他の toStartOf*() 関数を一般化したものです。

例えば、

toStartOfInterval(t, INTERVAL 1 YEAR) は toStartOfYear(t) と同じ値を返します。
toStartOfInterval(t, INTERVAL 1 MONTH) は toStartOfMonth(t) と同じ値を返します。
toStartOfInterval(t, INTERVAL 1 DAY) は toStartOfDay(t) と同じ値を返します。
toStartOfInterval(t, INTERVAL 15 MINUTE) は toStartOfFifteenMinutes(t) と同じ値を返します。

計算は特定の基準時点に対して行われます:

Interval	Start
YEAR	年 0
QUARTER	1900 Q1
MONTH	1900年1月
WEEK	1970年第1週 (01-05)
DAY	1970-01-01
HOUR	(*)
MINUTE	1970-01-01 00:00:00
SECOND	1970-01-01 00:00:00
MILLISECOND	1970-01-01 00:00:00
MICROSECOND	1970-01-01 00:00:00
NANOSECOND	1970-01-01 00:00:00
(*) 時間間隔 (HOUR) は特別で、計算は常に当日の 00:00:00（真夜中）を基準として行われます。
その結果、1 から 23 までの時間の値のみが有用です。

単位として WEEK が指定された場合、toStartOfInterval は週の開始を月曜日とみなします。この挙動は、デフォルトでは週の開始が日曜日である toStartOfWeek 関数とは異なる点に注意してください。

2 つ目のオーバーロードは、TimescaleDB の time_bucket() 関数および PostgreSQL の date_bin() 関数をエミュレートします。

構文

toStartOfInterval(value, INTERVAL x unit[, time_zone])
toStartOfInterval(value, INTERVAL x unit[, origin[, time_zone]])

別名: time_bucket, date_bin

引数

value — 切り捨て対象の日付または日時の値。Date または DateTime または DateTime64
x — 区間の長さを表す数値。 - unit — 区間の単位: YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND。 - time_zone — 省略可。タイムゾーン名を表す文字列。 - origin — 省略可。計算の基準点（第 2 のオーバーロードのみ）。

返される値

入力値を含む区間の開始時刻を返します。DateTime

例

基本的な区間への丸め

SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)

┌─toStartOfInt⋯alMonth(1))─┐
│               2023-01-01 │
└──────────────────────────┘

起点を使用する

SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))

┌─toStartOfInt⋯14:35:30'))─┐
│      2023-01-01 14:44:30 │
└──────────────────────────┘

toStartOfMicrosecond

導入バージョン: v22.6

日時をマイクロ秒の開始まで切り捨てます。

構文

toStartOfMicrosecond(datetime[, timezone])

引数

datetime — 日時。DateTime64
timezone — 省略可。返される値のタイムゾーン。指定しない場合は value パラメータのタイムゾーンが使用されます。String

返される値

サブマイクロ秒精度を持つ入力値 DateTime64

例

タイムゾーンなしのクエリ

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);

┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘

タイムゾーンを指定したクエリ

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');

┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘

toStartOfMillisecond

導入バージョン: v22.6

日時をミリ秒単位で切り捨てます。

構文

toStartOfMillisecond(datetime[, timezone])

引数

datetime — 日付と時刻。DateTime64
timezone — 省略可能。返される値のタイムゾーンを指定します。指定しない場合、この関数は value パラメータのタイムゾーンを使用します。String

返り値

サブミリ秒精度を持つ入力値。DateTime64

例

タイムゾーンを指定しないクエリ

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);

┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘

タイムゾーン付きクエリ

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');

┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘

toStartOfMinute

導入バージョン: v1.1

日付と時刻を、その分の開始時刻に切り捨てます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfMinute(datetime)

引数

datetime — 丸め対象の日時。DateTime または DateTime64

戻り値

分の開始時刻に切り捨てた日時を返します。DateTime または DateTime64

例

分の開始時刻への切り捨て

SELECT
    toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
    toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical

Row 1:
──────
toStartOfMinute(toDateTime('2023-04-21 10:20:30')):           2023-04-21 10:20:00
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8)): 2023-04-21 10:20:00

toStartOfMonth

導入バージョン: v1.1

日付または日時を、その月の1日（月初日）に切り捨てます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfMonth(value)

引数

value — 切り捨ててその月の初日に丸める対象となる日付または日時。Date または Date32 または DateTime または DateTime64

戻り値

指定された日付または日時について、その月の初日を返します。Date

例

月の初日への丸め（切り捨て）

SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                        2023-04-01 │
└───────────────────────────────────────────────────┘

toStartOfNanosecond

導入バージョン: v22.6

日付と時刻をナノ秒の開始時点に切り捨てます。

構文

toStartOfNanosecond(datetime[, timezone])

引数

datetime — 日付と時刻。DateTime64
timezone — 省略可能。戻り値のタイムゾーン。指定されていない場合、関数は value パラメータのタイムゾーンを使用します。String

戻り値

ナノ秒精度を持つ入力値。DateTime64

例

タイムゾーンを指定しないクエリ

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);

┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘

タイムゾーンを指定したクエリ

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');

┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│              2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘

toStartOfQuarter

導入: v1.1

日付または日時を、その四半期の最初の日に切り捨てます。四半期の最初の日は、1月1日、4月1日、7月1日、または10月1日のいずれかです。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfQuarter(value)

引数

value — 四半期の初日に切り下げる対象となる日付または日時。Date または Date32 または DateTime または DateTime64

戻り値

指定された日付または日時が属する四半期の初日を返します。Date

例

四半期の初日への切り下げ

SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-01 │
└─────────────────────────────────────────────────────┘

toStartOfSecond

導入バージョン: v20.5

日時を秒の開始時点に切り捨てます。

構文

toStartOfSecond(datetime[, timezone])

引数

datetime — サブ秒部分を切り捨てる対象の日時。DateTime64
timezone — 省略可能。返される値のタイムゾーン。指定しない場合、この関数は value パラメータのタイムゾーンを使用します。String

戻り値

サブ秒部分を除いた入力値を返します。DateTime64

使用例

タイムゾーン指定なしのクエリ

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);

┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘

タイムゾーンを指定したクエリ

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');

┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│                2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘

toStartOfTenMinutes

導入バージョン: v20.1

日時を直前の10分単位の区切り時刻に切り捨てます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfTenMinutes(datetime)

引数

datetime — 日時。DateTime または DateTime64

返される値

最も近い 10 分間隔の開始時刻に丸めた日時を返します。返り値の型は DateTime または DateTime64 です。

例

SELECT
    toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

行 1:
──────
toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:10:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00

toStartOfWeek

導入バージョン: v20.1

日付または日時を、最も近い日曜日または月曜日まで切り捨てます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions を設定することで変更できます。

構文

toStartOfWeek(datetime[, mode[, timezone]])

引数

datetime — 変換する日付または日時。Date または DateTime または Date32 または DateTime64
mode — toWeek() 関数で説明されているように、週の始まりとなる曜日を決定します。デフォルトは 0。UInt8
timezone — 変換に使用するタイムゾーン。指定されていない場合は、サーバーのタイムゾーンが使用されます。String

返される値

mode に応じて、指定した日付と同日またはそれ以前で、最も近い日曜日または月曜日の日付を返します。Date または Date32 または DateTime または DateTime64

例

最も近い日曜日または月曜日への切り下げ

SELECT
        toStartOfWeek(toDateTime('2023-04-21 10:20:30')), /* 金曜日 */
        toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* 金曜日 */
        toStartOfWeek(toDate('2023-04-24')), /* 月曜日 */
        toStartOfWeek(toDate('2023-04-24'), 1) /* 月曜日 */
    FORMAT Vertical

行 1:
    ──────
    toStartOfWeek(toDateTime('2023-04-21 10:20:30')):      2023-04-17
    toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1):   2023-04-17
    toStartOfWeek(toDate('2023-04-24')):                   2023-04-24
    toStartOfWeek(toDate('2023-04-24'), 1):                2023-04-24

toStartOfYear

導入バージョン: v1.1

日付または日時を、その年の初日に切り捨てます。結果は Date オブジェクトとして返されます。

注記

戻り値の型は、enable_extended_results_for_datetime_functions の設定によって変更できます。

構文

toStartOfYear(value)

引数

value — 丸め対象となる日付または日時。Date または Date32 または DateTime または DateTime64

戻り値

指定された日付または日時が属する年の最初の日を返します。戻り値の型は Date です。

例

年の初日に切り捨てる

SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                       2023-01-01 │
└──────────────────────────────────────────────────┘

toTimeWithFixedDate

導入バージョン: v1.1

日付または日時から時刻コンポーネントを抽出します。返される結果は、現在は 1970-01-02 に固定された時点からのオフセット値ですが、その正確な時点は実装の詳細であり、将来変更される可能性があります。

したがって、toTime を単独で使用することは想定されていません。この関数の主な目的は、2 つの日付または日時の間の時刻差を計算することです（例: toTime(dt1) - toTime(dt2)）。

構文

toTime(date[, timezone])

引数

date — 時刻に変換する日付。Date または DateTime または DateTime64
timezone — 省略可。返される値のタイムゾーン。String

返される値

日付または日時から、その時刻成分を、固定された時点（現在は 1970-01-02）からのオフセットとして返します。DateTime

使用例

2 つの日付間の時刻差を計算する

SELECT toTime('2025-06-15 12:00:00'::DateTime) - toTime('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)

┌─result─┬─toTypeName(result)─┐
│   3600 │ Int32              │
└────────┴────────────────────┘

toTimezone

導入バージョン: v1.1

DateTime または DateTime64 を指定したタイムゾーンに変換します。データの内部値（UNIX 時間の秒数）は変更されません。変更されるのは、値のタイムゾーン属性と値の文字列表現のみです。

構文

toTimeZone(datetime, timezone)

エイリアス: toTimeZone

引数

date — 変換する値。DateTime または DateTime64
timezone — 変換先のタイムゾーン名。String

戻り値

入力と同じタイムスタンプで、指定されたタイムゾーンを持つ DateTime または DateTime64 を返します。

例

使用例

SELECT toDateTime('2019-01-01 00:00:00', 'UTC') AS time_utc,
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;

行 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

toUTCTimestamp

導入: v23.8

日付または日時の値を、あるタイムゾーンから UTC タイムゾーンのタイムスタンプに変換します。この関数は主に Apache Spark や同様のフレームワークとの互換性のために用意されています。

構文

toUTCTimestamp(datetime, time_zone)

別名: to_utc_timestamp

引数

datetime — 日付、または日時型の定数値または式。DateTime または DateTime64
time_zone — タイムゾーンを表す String 型の定数値または式。String

戻り値

UTC タイムゾーンでの日付または日時を返します。DateTime または DateTime64

使用例

タイムゾーンを UTC に変換する

SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')

┌─toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')─┐
│                                     2023-03-15 16:00:00 │
└─────────────────────────────────────────────────────────┘

toUnixTimestamp

導入バージョン: v1.1

String、Date、または DateTime を、Unix タイムスタンプ（1970-01-01 00:00:00 UTC からの経過秒数）を表す UInt32 に変換します。

構文

toUnixTimestamp(date[, timezone])

引数

date — 変換する値。Date、Date32、DateTime、DateTime64、String のいずれか。
timezone — 省略可能。変換に使用するタイムゾーン。指定しない場合はサーバーのタイムゾーンが使用されます。String

返り値

Unix タイムスタンプを返します。UInt32

例

使用例

SELECT
'2017-11-05 08:07:47' AS dt_str,
toUnixTimestamp(dt_str) AS from_str,
toUnixTimestamp(dt_str, 'Asia/Tokyo') AS from_str_tokyo,
toUnixTimestamp(toDateTime(dt_str)) AS from_datetime,
toUnixTimestamp(toDateTime64(dt_str, 0)) AS from_datetime64,
toUnixTimestamp(toDate(dt_str)) AS from_date,
toUnixTimestamp(toDate32(dt_str)) AS from_date32
FORMAT Vertical;

行 1:
──────
dt_str:          2017-11-05 08:07:47
from_str:        1509869267
from_str_tokyo:  1509836867
from_datetime:   1509869267
from_datetime64: 1509869267
from_date:       1509840000
from_date32:     1509840000

toWeek

導入バージョン: v20.1

この関数は、日付または日時に対して週番号を返します。toWeek() の 2 引数形式では、週の開始曜日を日曜日または月曜日から選択できるほか、戻り値の範囲を 0〜53 にするか 1〜53 にするかを指定できます。

toISOWeek() は、toWeek(date,3) と等価な互換性用の関数です。

次の表は、mode 引数の動作を説明したものです。

Mode	週の最初の曜日	範囲	第 1 週は、次を満たす最初の週 ...
0	Sunday	0-53	この年に属する Sunday を含む
1	Monday	0-53	この年に属する日が 4 日以上ある
2	Sunday	1-53	この年に属する Sunday を含む
3	Monday	1-53	この年に属する日が 4 日以上ある
4	Sunday	0-53	この年に属する日が 4 日以上ある
5	Monday	0-53	この年に属する Monday を含む
6	Sunday	1-53	この年に属する日が 4 日以上ある
7	Monday	1-53	この年に属する Monday を含む
8	Sunday	1-53	1 月 1 日を含む
9	Monday	1-53	1 月 1 日を含む

意味が「with 4 or more days this year」の mode 値の場合、週番号は ISO 8601:1988 に従って付けられます。

1 月 1 日を含む週に、その年に属する日が 4 日以上含まれている場合、その週は第 1 週になります。
それ以外の場合、その週は前年の最終週となり、その次の週が第 1 週になります。

意味が「contains January 1」の mode 値の場合、1 月 1 日を含む週が第 1 週になります。その週が新しい年に属する日を何日含むかは関係なく、1 日しか含まない場合でも同様です。すなわち、12 月の最終週に翌年の 1 月 1 日が含まれる場合、その週は翌年の第 1 週となります。

第 1 引数は、parseDateTime64BestEffort() でサポートされる形式の String として指定することもできます。文字列引数のサポートは、一部のサードパーティツールが想定している MySQL との互換性のためにのみ存在します。将来的には、文字列引数のサポートが新しい MySQL 互換性用 SETTING に依存するよう変更される可能性があること、および一般に文字列のパースは低速であることから、文字列引数の使用は推奨されません。

構文

toWeek(datetime[, mode[, time_zone]])

エイリアス: week

引数

datetime — 週番号を取得する対象の日付、または日時。Date または DateTime
mode — 省略可能。0 から 9 のモード値で、週の開始日と週番号の範囲を決定します。デフォルトは 0。
time_zone — 省略可能。タイムゾーン。String

返される値

指定したモードに応じた週番号を返します。UInt32

例

異なるモードで週番号を取得する

SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9

┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │    52 │    52 │     1 │
└────────────┴───────┴───────┴───────┘

toYYYYMM

導入バージョン: v1.1

日付または日時を、年と月の数値 (YYYY * 100 + MM) を含む UInt32 型の数値に変換します。第 2 引数としてオプションのタイムゾーン引数を受け取ります。指定する場合、その値は文字列定数でなければなりません。

この関数は、関数 YYYYMMDDToDate() の逆に相当します。

構文

toYYYYMM(datetime[, timezone])

引数

datetime — 変換対象の日付または日時。Date または Date32 または DateTime または DateTime64
timezone — オプション。変換に使用するタイムゾーン。指定する場合、タイムゾーンは文字列定数である必要があります。String

返される値

年と月の番号 (YYYY * 100 + MM) を表す UInt32 の数値を返します。UInt32

例

現在の日付を YYYYMM 形式に変換する

SELECT toYYYYMM(now(), 'US/Eastern')

┌─toYYYYMM(now(), 'US/Eastern')─┐
│                        202303 │
└───────────────────────────────┘

toYYYYMMDD

導入バージョン: v1.1

日付または日時を、年・月・日を含む UInt32 型の数値 (YYYY * 10000 + MM * 100 + DD) に変換します。2 番目の省略可能なタイムゾーン引数を受け取ります。指定する場合、タイムゾーンは文字列定数でなければなりません。

構文

toYYYYMMDD(datetime[, timezone])

引数

datetime — 変換対象の日付または日時。Date または Date32 または DateTime または DateTime64
timezone — 省略可能。変換に使用するタイムゾーン。指定する場合は、タイムゾーンは文字列リテラルである必要があります。String

戻り値

年・月・日を表す UInt32 型の数値を返します (YYYY * 10000 + MM * 100 + DD)。UInt32

例

現在の日付を YYYYMMDD 形式に変換

SELECT toYYYYMMDD(now(), 'US/Eastern')

┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│                        20230302 │
└─────────────────────────────────┘

toYYYYMMDDhhmmss

導入: v1.1

日付または日時を、年・月・日・時・分・秒を含む UInt64 型の数値に変換します。数値の形式は (YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss) です。 2 つ目の省略可能なタイムゾーン引数を受け取ります。指定する場合、タイムゾーンは文字列定数である必要があります。

構文

toYYYYMMDDhhmmss(datetime[, timezone])

引数

datetime — 変換対象の日付または日時。Date または Date32 または DateTime または DateTime64
timezone — 省略可。変換に使用するタイムゾーン。指定する場合、タイムゾーンは文字列定数でなければなりません。String

戻り値

年・月・日・時・分・秒を含む UInt64 型の数値を返します (YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss)。UInt64

例

現在の日付と時刻を YYYYMMDDhhmmss 形式に変換

SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')

┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│                        20230302112209 │
└───────────────────────────────────────┘

toYear

導入バージョン: v1.1

Date または DateTime の値から西暦の年の部分を返します。

構文

toYear(datetime)

エイリアス: YEAR

引数

datetime — 年を取得する対象とする日付または日時。Date、Date32、DateTime、DateTime64 のいずれか。

返り値

指定された Date または DateTime の年を返します。型は UInt16 です。

例

使用例

SELECT toYear(toDateTime('2023-04-21 10:20:30'))

┌─toYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                     2023  │
└───────────────────────────────────────────┘

toYearNumSinceEpoch

導入バージョン: v25.3

1970年からの経過年数を返します。

構文

toYearNumSinceEpoch(date)

引数

date — 変換対象の日付または日時。Date または DateTime または DateTime64。

戻り値

正の整数値。

使用例

例

SELECT toYearNumSinceEpoch(toDate('2024-10-01'))

toYearWeek

導入バージョン: v20.1

日付に対して、その年と週番号を返します。結果に含まれる年は、年の最初および最後の週については、引数で指定した日付の年と異なる場合があります。

mode 引数は、toWeek() の mode 引数と同様に動作します。

警告: toYearWeek() が返す週番号は、toWeek() が返すものと異なる場合があります。toWeek() は常に与えられた年のコンテキストで週番号を返し、toWeek() が 0 を返す場合、toYearWeek() は前年の最終週に対応する値を返します。下記の例にある prev_yearWeek を参照してください。

最初の引数は、parseDateTime64BestEffort() がサポートする形式の String として指定することもできます。文字列引数のサポートは、一部のサードパーティーツールが期待する MySQL との互換性のためにのみ存在します。将来的には、文字列引数のサポートが新しい MySQL 互換性 SETTING に依存するようになる可能性があり、また一般に文字列のパースは低速であるため、使用しないことを推奨します。

構文

toYearWeek(datetime[, mode[, timezone]])

別名: yearweek

引数

datetime — 年と週番号を取得する対象の日付または日時。Date または DateTime
mode — 省略可。0 から 9 のモードにより、週の最初の曜日と週番号の範囲を決定します。デフォルトは 0。
timezone — 省略可。タイムゾーン。String

戻り値

年と週番号を結合した単一の整数値を返します。UInt32

例

異なるモードで year-week の組み合わせを取得する

SELECT toDate('2016-12-27') AS date, toYearWeek(date) AS yearWeek0, toYearWeek(date,1) AS yearWeek1, toYearWeek(date,9) AS yearWeek9, toYearWeek(toDate('2022-01-01')) AS prev_yearWeek

┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │    201652 │    201652 │    201701 │        202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘

today

導入バージョン: v1.1

クエリ解析時の現在の日付を返します。toDate(now()) と同じです。

構文

today()

別名: curdate, current_date

引数

なし。

戻り値

現在の日付 Date を返します。

例

使用例

SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty

┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃      today ┃    curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │   2025-03-03 │
└────────────┴────────────┴──────────────┘

yesterday

導入: v1.1

引数を受け取らず、クエリの解析時点のいずれかにおける「昨日」の日付を返します。

構文

yesterday()

引数

なし。

戻り値

昨日の日付を返します。Date

例

昨日の日付を取得する

SELECT yesterday();
SELECT today() - 1;

┌─yesterday()─┐
│  2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│        2025-06-09 │
└───────────────────┘

UTCTimestamp​

YYYYMMDDToDate​

YYYYMMDDToDate32​

YYYYMMDDhhmmssToDateTime​

YYYYMMDDhhmmssToDateTime64​

addDate​

addDays​

addHours​

addInterval​

addMicroseconds​

addMilliseconds​

addMinutes​

addMonths​

addNanoseconds​

addQuarters​

addSeconds​

addTupleOfIntervals​

addWeeks​

addYears​

age​

changeDay​

changeHour​

changeMinute​

changeMonth​

changeSecond​

changeYear​

dateDiff​

dateName​

dateTrunc​

formatDateTime​

formatDateTimeInJodaSyntax​

fromDaysSinceYearZero​

fromDaysSinceYearZero32​

fromModifiedJulianDay​

fromModifiedJulianDayOrNull​

fromUTCTimestamp​

fromUnixTimestamp​

fromUnixTimestampInJodaSyntax​

makeDate​

makeDate32​

makeDateTime​

makeDateTime64​

monthName​

now​

now64​

nowInBlock​

nowInBlock64​

serverTimezone​

subDate​

subtractDays​

subtractHours​

subtractInterval​

subtractMicroseconds​

subtractMilliseconds​

subtractMinutes​

subtractMonths​

subtractNanoseconds​

subtractQuarters​

subtractSeconds​

subtractTupleOfIntervals​

subtractWeeks​

subtractYears​

timeDiff​

timeSlot​

timeSlots​

timestamp​

timezone​

timezoneOf​

timezoneOffset​

toDayOfMonth​

toDayOfWeek​

toDayOfYear​

toDaysSinceYearZero​

toHour​

toISOYear​

toLastDayOfMonth​

toLastDayOfWeek​

toMillisecond​

toMinute​

toModifiedJulianDay​

UTCTimestamp

YYYYMMDDToDate

YYYYMMDDToDate32

YYYYMMDDhhmmssToDateTime

YYYYMMDDhhmmssToDateTime64

addDate

addDays

addHours

addInterval

addMicroseconds

addMilliseconds

addMinutes

addMonths

addNanoseconds

addQuarters

addSeconds

addTupleOfIntervals

addWeeks

addYears

age

changeDay

changeHour

changeMinute

changeMonth

changeSecond

changeYear

dateDiff

dateName

dateTrunc

formatDateTime

formatDateTimeInJodaSyntax

fromDaysSinceYearZero

fromDaysSinceYearZero32

fromModifiedJulianDay

fromModifiedJulianDayOrNull

fromUTCTimestamp

fromUnixTimestamp

fromUnixTimestampInJodaSyntax

makeDate

makeDate32

makeDateTime

makeDateTime64

monthName

now

now64

nowInBlock

nowInBlock64

serverTimezone

subDate

subtractDays

subtractHours

subtractInterval

subtractMicroseconds

subtractMilliseconds

subtractMinutes

subtractMonths

subtractNanoseconds

subtractQuarters

subtractSeconds

subtractTupleOfIntervals

subtractWeeks

subtractYears

timeDiff

timeSlot

timeSlots

timestamp

timezone

timezoneOf

timezoneOffset

toDayOfMonth

toDayOfWeek

toDayOfYear

toDaysSinceYearZero

toHour

toISOYear

toLastDayOfMonth

toLastDayOfWeek

toMillisecond

toMinute

toModifiedJulianDay