日付と時刻を扱う関数

このセクションのほとんどの関数は、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

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

構文

addDate(datetime, interval)

引数

datetime — interval を加算する対象となる日付または日時。Date、Date32、DateTime、DateTime64、または String
interval — 加算する時間間隔。Interval

戻り値

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

例

日付に interval を加算する

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

あるインターバル、またはインターバルのタプルに別のインターバルを加算します。

注記

同じ種類のインターバルは単一のインターバルにまとめられます。たとえば 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

日付、日時、または文字列形式の日付・日時に、指定した秒数を加算します。

構文

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

指定した週数を、日付、日時、または文字列でエンコードされた日付または日時に加算します。

構文

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

Date または DateTime の分の値を変更します。

構文

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 の差分は、unit が day の場合は 3 日（toRelativeDayNum を参照）、unit が month の場合は 1 か月（toRelativeMonthNum を参照）、unit が year の場合は 1 年（toRelativeYearNum を参照）となります。

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

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

構文

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

エイリアス: timestampDiff, TIMESTAMP_DIFF, DATE_DIFF, date_diff, timestamp_diff

引数

unit — 結果の単位となる間隔の種類。

Unit	Possible values
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	互換性
`nanosecond`	DateTime64 とのみ互換性があります
`microsecond`	DateTime64 とのみ互換性があります
`millisecond`	DateTime64 とのみ互換性があります
`second`
`minute`
`hour`
`day`
`week`
`month`
`quarter`
`year`
`String`

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

戻り値

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

Unit 引数	`datetime` 引数	戻り値の型
Year, Quarter, Month, Week	`Date32` または `DateTime64` または `Date` または `DateTime`	`Date32` または `Date`
Day, Hour, Minute, Second	`Date32`, `DateTime64`, `Date`, または `DateTime`	`DateTime64` または `DateTime`
Millisecond, Microsecond,	任意	`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 をフォーマットした結果を示しています。

置換フィールド:

プレースホルダー	説明	例
%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	月曜日を 1 とする ISO 8601 の曜日番号 (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 より前のバージョンでは、%f はフォーマット対象が Date、Date32、DateTime (いずれも秒未満を持たない) または精度 0 の DateTime64 の場合、単一のゼロ (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 です。

置換フィールドを使用して、出力される文字列のパターンを定義できます。

置換フィールド:

プレースホルダ	説明	表現形式	例
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	1 日の時 (0~23)	数値	0
k	1 日の時計時刻 (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

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

構文

fromDaysSinceYearZero32(days)

引数

days — 年 0 からの経過日数。UInt32

返される値

指定された年 0 からの経過日数に対応する日付を返します。Date32

使用例

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

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 通りの呼び出し方ができます。

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

2 つまたは 3 つの引数を渡した場合で、1 番目の引数が Integer、Date、Date32、DateTime、または DateTime64 型の値、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 値を返します。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 型の値を返します。

例

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 または Tuple(Interval)
interval_2 — 符号を反転する 2 つ目のインターバル。Interval

戻り値

インターバルのタプル Tuple(T) を返します。

使用例

インターバルを減算する

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

導入バージョン: 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 では 1970 年から 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 — 日を取得する対象の日時。Date または Date32 または DateTime または DateTime64

返される値

指定した日時の「日」を返します。型は UInt8 です。

例

使用例

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

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

toDayOfWeek

導入バージョン: v1.1

Date または DateTime の値に対して、その週における曜日番号を返します。

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

モード	週の開始曜日	範囲
0	月曜日	1〜7: 月曜日 = 1, 火曜日 = 2, ..., 日曜日 = 7
1	月曜日	0〜6: 月曜日 = 0, 火曜日 = 1, ..., 日曜日 = 6
2	日曜日	0〜6: 日曜日 = 0, 月曜日 = 1, ..., 土曜日 = 6
3	日曜日	1〜7: 日曜日 = 1, 月曜日 = 2, ..., 土曜日 = 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 で定義されるプロレプティック・グレゴリオ暦における西暦 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

Row 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 型の修正ユリウス日に変換します。この関数は 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

返り値

日付または日時を、その日の開始時刻まで切り捨てて返します。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

Row 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

Row 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

返される値

時刻を切り下げて、その時刻が属する時間の先頭に揃えた日時を返します。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	year 0
QUARTER	1900 Q1
MONTH	1900 January
WEEK	1970, 1st week (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
(*) 時間単位の間隔は特別であり、計算は常に当日 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]])

別名: date_bin, time_bucket

引数

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

行 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

日付または日時を、その月の月初日に切り下げます。

注記

戻り値の型は、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

Row 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

Row 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

日付または日時を、その年の最初の日（1月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

あるタイムゾーンの date または日時の値を、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 を、1970-01-01 00:00:00 UTC からの経過秒を表す Unix タイムスタンプ（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;

Row 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

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

toISOWeek() は互換性のための関数であり、toWeek(date,3) と等価です。

次の表は、mode 引数の動作を示します。

Mode	First day of week	Range	Week 1 is the first week ...
0	Sunday	0-53	この年に日曜日を含む週
1	Monday	0-53	この年に 4 日以上含まれる週
2	Sunday	1-53	この年に日曜日を含む週
3	Monday	1-53	この年に 4 日以上含まれる週
4	Sunday	0-53	この年に 4 日以上含まれる週
5	Monday	0-53	この年に月曜日を含む週
6	Sunday	1-53	この年に 4 日以上含まれる週
7	Monday	1-53	この年に月曜日を含む週
8	Sunday	1-53	1 月 1 日を含む週
9	Monday	1-53	1 月 1 日を含む週

意味が「この年に 4 日以上含まれる週」となる mode 値では、週番号は ISO 8601:1988 に従って付与されます:

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

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

最初の引数は、parseDateTime64BestEffort() がサポートする形式の String で指定することもできます。文字列引数のサポートは、特定のサードパーティーツールが期待する MySQL との互換性のためにのみ存在します。将来的には、文字列引数のサポートが新しい MySQL 互換性設定に依存するよう変更される可能性があること、また一般的に文字列のパースは遅い処理であることから、この機能の使用は推奨されません。

構文

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

日付、または日付と時刻を、年と月を表す UInt32 型の数値（YYYY * 100 + MM）に変換します。 2 番目の省略可能な引数としてタイムゾーンを受け取ります。指定する場合、タイムゾーンは文字列リテラルでなければなりません。

この関数は、関数 YYYYMMDDToDate() の逆の動作を行います。

構文

toYYYYMM(datetime[, timezone])

引数

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

戻り値

年と月の値を含む UInt32 型の数値を返します (YYYY * 100 + MM)。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

返り値

年、月、日、時、分、秒 (YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss) を表す UInt64 型の数値を返します。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 互換性設定に依存するようになる可能性があり、また一般に文字列のパースは低速であるため、使用しないことを推奨します。

構文

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

別名: yearweek

引数

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

返される値

年と週番号を結合した整数値を返します。UInt32

例

さまざまなモードで年-週の組み合わせを取得する

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