型変換関数

データ変換でよくある問題

ClickHouse は一般的に C++ プログラムと同じ挙動を採用しています。

to<type> 関数と cast は、いくつかのケースで異なる動作をします。たとえば LowCardinality の場合、cast は LowCardinality の特性を削除しますが、to<type> 関数は削除しません。Nullable についても同様です。この挙動は SQL 標準とは互換性がなく、cast_keep_nullable SETTING を使用して変更できます。

注記

あるデータ型の値を、より小さいデータ型（たとえば Int64 から Int32）や互換性のないデータ型（たとえば String から Int）に変換する場合、データが失われる可能性があることに注意してください。結果が期待どおりになっているかを慎重に確認してください。

例:

SELECT
    toTypeName(toLowCardinality('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type

┌─source_type────────────┬─to_type_result_type────┬─cast_result_type─┐
│ LowCardinality(String) │ LowCardinality(String) │ String           │
└────────────────────────┴────────────────────────┴──────────────────┘

SELECT
    toTypeName(toNullable('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type

┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String)    │ String           │
└──────────────────┴─────────────────────┴──────────────────┘

SELECT
    toTypeName(toNullable('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type
SETTINGS cast_keep_nullable = 1

┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String)    │ Nullable(String) │
└──────────────────┴─────────────────────┴──────────────────┘

`toString` 関数に関する注意事項

toString 系の関数は、数値、文字列（ただし FixedString ではない）、日付、および日時の間での変換を行います。これらの関数はすべて 1 つの引数を受け取ります。

文字列への変換または文字列からの変換を行う場合、値は TabSeparated 形式（およびほぼすべての他のテキスト形式）と同じルールに従ってフォーマットまたは解析されます。文字列を解析できない場合は例外がスローされ、クエリはキャンセルされます。
日付を数値に変換する場合、またはその逆の場合、日付は Unix エポックの開始からの日数に対応します。
日時を数値に変換する場合、またはその逆の場合、日時は Unix エポックの開始からの秒数に対応します。
DateTime 引数に対する toString 関数は、タイムゾーン名を含む 2 つ目の String 引数を取ることができます（例: Europe/Amsterdam）。この場合、時刻は指定されたタイムゾーンに従ってフォーマットされます。

`toDate`/`toDateTime` 関数に関する注意事項

toDate/toDateTime 関数で使用される日付および日時の形式は、次のように定義されています。

YYYY-MM-DD
YYYY-MM-DD hh:mm:ss

例外として、UInt32、Int32、UInt64、または Int64 の数値型から Date への変換において、数値が 65536 以上の場合、その数値は日数ではなく Unix タイムスタンプとして解釈され、日付に丸められます。これにより、本来であればエラーとなり、より煩雑な toDate(toDateTime(unix_timestamp)) と書く必要があるところを、よくある toDate(unix_timestamp) の記述もサポートできるようになります。

日付と日時との相互変換は、時刻 0 を付加するか、時刻を切り捨てるという自然な方法で行われます。

数値型同士の変換は、C++ における異なる数値型間の代入と同じルールに従います。

例

クエリ:

SELECT
    now() AS ts,
    time_zone,
    toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

結果：

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

toUnixTimestamp 関数も参照してください。

CAST

導入バージョン: v1.1

値を指定されたデータ型に変換します。 reinterpret 関数とは異なり、CAST は対象の型において同じ値になるように変換を試みます。それが不可能な場合は、例外がスローされます。

構文

CAST(x, T)
or CAST(x AS T)
or x::T

引数

x — 任意の型の値。Any
T — 変換先のデータ型。String

戻り値

変換先のデータ型に変換された値を返します。Any

使用例

基本的な使い方

SELECT CAST(42, 'String')

┌─CAST(42, 'String')─┐
│ 42                 │
└────────────────────┘

AS 構文の利用

SELECT CAST('2025-01-01' AS Date)

┌─CAST('2025-01-01', 'Date')─┐
│                 2025-01-01 │
└────────────────────────────┘

「::」構文の使用

SELECT '123'::UInt32

┌─CAST('123', 'UInt32')─┐
│                   123 │
└───────────────────────┘

DATE

導入バージョン: v21.2

引数を Date データ型に変換します。これは MySQL 互換の toDate のエイリアスであり、toDate と同様に動作します。

構文

DATE(expr)

引数

expr — 変換する値。String、UInt32、Date、DateTime のいずれか。

戻り値

Date 型の値を返します。Date

例

基本的な使い方

SELECT DATE('2023-01-01')

2023-01-01

accurateCast

導入バージョン: v1.1

値を指定したデータ型に変換します。CAST と異なり、accurateCast はより厳密な型チェックを行い、変換によってデータ精度の損失が発生する場合や、変換が不可能な場合には例外をスローします。

この関数は、精度の損失や不正な変換を防ぐため、通常の CAST よりも安全です。

構文

accurateCast(x, T)

引数

x — 変換する値。Any
T — 変換先のデータ型名。String

戻り値

指定されたデータ型に変換された値を返します。Any

例

変換が成功する例

SELECT accurateCast(42, 'UInt16')

┌─accurateCast(42, 'UInt16')─┐
│                        42 │
└───────────────────────────┘

文字列から数値への変換

SELECT accurateCast('123.45', 'Float64')

┌─accurateCast('123.45', 'Float64')─┐
│                            123.45 │
└───────────────────────────────────┘

accurateCastOrDefault

導入バージョン: v21.1

値を指定したデータ型に変換します。 accurateCast と同様ですが、変換を正確に行えない場合に、例外を送出する代わりにデフォルト値を返します。

第 2 引数としてデフォルト値を指定する場合、その値は変換先の型でなければなりません。デフォルト値を指定しない場合は、変換先の型のデフォルト値が使用されます。

構文

accurateCastOrDefault(x, T[, default_value])

引数

x — 変換する値。Any
T — 変換先のデータ型名。const String
default_value — 省略可能。変換に失敗した場合に返すデフォルト値。Any

戻り値

指定されたデータ型に変換された値、または変換が不可能な場合はデフォルト値を返します。Any

使用例

変換が成功する例

SELECT accurateCastOrDefault(42, 'String')

┌─accurateCastOrDefault(42, 'String')─┐
│ 42                                  │
└─────────────────────────────────────┘

明示的なデフォルト値指定時の変換失敗

SELECT accurateCastOrDefault('abc', 'UInt32', 999::UInt32)

┌─accurateCastOrDefault('abc', 'UInt32', 999)─┐
│                                         999 │
└─────────────────────────────────────────────┘

暗黙のデフォルトによる変換失敗

SELECT accurateCastOrDefault('abc', 'UInt32')

┌─accurateCastOrDefault('abc', 'UInt32')─┐
│                                      0 │
└────────────────────────────────────────┘

accurateCastOrNull

導入バージョン: v1.1

値を指定したデータ型に変換します。 accurateCast と似ていますが、変換を正確に行えない場合は、例外をスローする代わりに NULL を返します。

この関数は、accurateCast の安全性と、例外を発生させない穏当なエラー処理を兼ね備えています。

構文

accurateCastOrNull(x, T)

引数

x — 変換する値。Any
T — 変換先のデータ型名。String

戻り値

変換先のデータ型の値を返します。変換できない場合は NULL を返します。Any

例

変換が成功する例

SELECT accurateCastOrNull(42, 'String')

┌─accurateCastOrNull(42, 'String')─┐
│ 42                               │
└──────────────────────────────────┘

失敗した変換は NULL を返す

SELECT accurateCastOrNull('abc', 'UInt32')

┌─accurateCastOrNull('abc', 'UInt32')─┐
│                                ᴺᵁᴸᴸ │
└─────────────────────────────────────┘

formatRow

導入バージョン: v20.7

任意の式を、指定されたフォーマットを使って文字列に変換します。

注記

フォーマットにサフィックスまたはプレフィックスが含まれている場合、それは各行に出力されます。この関数では、行ベースのフォーマットのみがサポートされます。

構文

formatRow(format, x, y, ...)

引数

format — テキスト形式。例: CSV、TSV。String
x, y, ... — 式。Any

返される値

書式化された文字列（テキスト形式の場合は通常、末尾に改行文字が付きます）。String

例

基本的な使用例

SELECT formatRow('CSV', number, 'good')
FROM numbers(3)

┌─formatRow('CSV', number, 'good')─┐
│ 0,"good"
                         │
│ 1,"good"
                         │
│ 2,"good"
                         │
└──────────────────────────────────┘

カスタムフォーマットを使用する場合

SELECT formatRow('CustomSeparated', number, 'good')
FROM numbers(3)
SETTINGS format_custom_result_before_delimiter='<prefix>\n', format_custom_result_after_delimiter='<suffix>'

┌─formatRow('CustomSeparated', number, 'good')─┐
│ <prefix>
0    good
<suffix>                   │
│ <prefix>
1    good
<suffix>                   │
│ <prefix>
2    good
<suffix>                   │
└──────────────────────────────────────────────┘

formatRowNoNewline

導入バージョン: v20.7

formatRow と同様ですが、各行の改行文字を削除します。

任意の式を指定されたフォーマットで文字列に変換しますが、結果から末尾の改行文字をすべて削除します。

構文

formatRowNoNewline(format, x, y, ...)

引数

format — テキストフォーマット。例: CSV、TSV。String
x, y, ... — 式。Any

返される値

改行を削除したフォーマット済み文字列を返します。String

例

基本的な使い方

SELECT formatRowNoNewline('CSV', number, 'good')
FROM numbers(3)

┌─formatRowNoNewline('CSV', number, 'good')─┐
│ 0,"good"                                  │
│ 1,"good"                                  │
│ 2,"good"                                  │
└───────────────────────────────────────────┘

fromUnixTimestamp64Micro

導入バージョン: v20.5

マイクロ秒単位の Unix タイムスタンプを、マイクロ秒精度の DateTime64 値に変換します。

入力値は、マイクロ秒精度の Unix タイムスタンプ（1970-01-01 00:00:00 UTC からの経過マイクロ秒数）として扱われます。

構文

fromUnixTimestamp64Micro(value[, timezone])

引数

value — マイクロ秒単位の Unix タイムスタンプ。Int64
timezone — 省略可能。返される値に適用するタイムゾーン。String

戻り値

マイクロ秒精度を持つ DateTime64 値を返します。DateTime64(6)

例

使用例

SELECT fromUnixTimestamp64Micro(1640995200123456)

┌─fromUnixTimestamp64Micro(1640995200123456)─┐
│                 2022-01-01 00:00:00.123456 │
└────────────────────────────────────────────┘

fromUnixTimestamp64Milli

導入バージョン: v20.5

ミリ秒精度の Unix タイムスタンプを、ミリ秒精度の DateTime64 値に変換します。

入力値は、ミリ秒精度の Unix タイムスタンプ（1970-01-01 00:00:00 UTC からの経過ミリ秒数）として扱われます。

構文

fromUnixTimestamp64Milli(value[, timezone])

引数

value — ミリ秒単位の Unix タイムスタンプ。Int64
timezone — 省略可能。返される値に適用するタイムゾーン。String

戻り値

ミリ秒精度の DateTime64 値。DateTime64(3)

例

使用例

SELECT fromUnixTimestamp64Milli(1640995200123)

┌─fromUnixTimestamp64Milli(1640995200123)─┐
│                 2022-01-01 00:00:00.123 │
└─────────────────────────────────────────┘

fromUnixTimestamp64Nano

導入バージョン: v20.5

ナノ秒単位の Unix タイムスタンプを、ナノ秒精度を持つ DateTime64 値に変換します。

入力値は、1970-01-01 00:00:00 UTC からの経過ナノ秒数としての、ナノ秒精度の Unix タイムスタンプとして扱われます。

注記

入力値は、その値に紐づくタイムゾーンではなく、UTC タイムスタンプとして扱われる点に注意してください。

構文

fromUnixTimestamp64Nano(value[, timezone])

引数

value — ナノ秒単位の Unix タイムスタンプ。Int64
timezone — 省略可能。返される値のタイムゾーンを指定します。String

戻り値

ナノ秒精度の DateTime64 値を返します。DateTime64(9)

例

使用例

SELECT fromUnixTimestamp64Nano(1640995200123456789)

┌─fromUnixTimestamp64Nano(1640995200123456789)─┐
│                2022-01-01 00:00:00.123456789 │
└──────────────────────────────────────────────┘

fromUnixTimestamp64Second

導入バージョン: v24.12

秒単位の Unix タイムスタンプを、秒精度の DateTime64 値に変換します。

入力値は、秒精度（1970-01-01 00:00:00 UTC からの経過秒数）の Unix タイムスタンプとして扱われます。

構文

fromUnixTimestamp64Second(value[, timezone])

引数

value — 秒単位の Unix タイムスタンプ。Int64
timezone — 省略可能。返される値のタイムゾーンです。String

戻り値

秒精度の DateTime64 値を返します。DateTime64(0)

例

使用例

SELECT fromUnixTimestamp64Second(1640995200)

┌─fromUnixTimestamp64Second(1640995200)─┐
│                   2022-01-01 00:00:00 │
└───────────────────────────────────────┘

parseDateTime

導入バージョン: v23.3

MySQL の日付フォーマット文字列に従って、日付と時刻の文字列を解析します。

この関数は formatDateTime の逆の処理を行います。フォーマット文字列に従って String 型の引数を解析し、DateTime 型を返します。

構文

parseDateTime(time_string, format[, timezone])

別名: TO_UNIXTIME

引数

time_string — DateTime に解析される対象の文字列。String
format — time_string をどのように解析するかを指定するフォーマット文字列。String
timezone — 省略可能。タイムゾーン。String

返される値

MySQL スタイルのフォーマット文字列に従って、入力文字列から解析された DateTime を返します。DateTime

例

使用例

SELECT parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                       2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────┘

parseDateTime32BestEffort

導入バージョン: v20.9

日付と時刻の文字列表現を DateTime データ型に変換します。

この関数は、ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 独自の形式およびその他のいくつかの日付・時刻フォーマットを解釈します。

構文

parseDateTime32BestEffort(time_string[, time_zone])

引数

time_string — 変換対象の日時を含む文字列。String
time_zone — 省略可能。time_string の解析に用いるタイムゾーン。String

返り値

time_string を DateTime として返します。DateTime

例

使用例

SELECT parseDateTime32BestEffort('23/10/2025 12:12:57')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2025-10-23 12:12:57 │
└───────────────────────────┘

タイムゾーン付き

SELECT parseDateTime32BestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2025-08-18 10:22:16 │
└───────────────────────────┘

UNIXタイムスタンプ

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2015-07-07 12:04:41 │
└───────────────────────────┘

parseDateTime32BestEffortOrNull

導入バージョン: v20.9

parseDateTime32BestEffort と同様ですが、処理できない日付形式を検出した場合は NULL を返します。

構文

parseDateTime32BestEffortOrNull(time_string[, time_zone])

引数

time_string — 変換する日時を含む文字列。String
time_zone — 省略可能。time_string を解釈する際に使用するタイムゾーン。String

返り値

文字列をパースして得られた DateTime オブジェクトを返し、パースに失敗した場合は NULL を返します。DateTime

例

使用例

SELECT
    parseDateTime32BestEffortOrNull('23/10/2025 12:12:57') AS valid,
    parseDateTime32BestEffortOrNull('invalid date') AS invalid

┌─valid───────────────┬─invalid─┐
│ 2025-10-23 12:12:57 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

parseDateTime32BestEffortOrZero

導入バージョン: v20.9

処理できない日付形式に遭遇した場合にゼロ日付またはゼロ日時を返す点を除き、parseDateTime32BestEffort と同じです。

構文

parseDateTime32BestEffortOrZero(time_string[, time_zone])

引数

time_string — 変換対象の日時が含まれる文字列。String
time_zone — 省略可能。time_string を解釈する際に使用するタイムゾーン。String

返り値

文字列からパースされた DateTime オブジェクト、またはパースに失敗した場合はゼロ日付（1970-01-01 00:00:00）を返します。DateTime

例

使用例

SELECT
    parseDateTime32BestEffortOrZero('23/10/2025 12:12:57') AS valid,
    parseDateTime32BestEffortOrZero('invalid date') AS invalid

┌─valid───────────────┬─invalid─────────────┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

parseDateTime64

導入バージョン: v24.11

MySQL の日付フォーマット文字列に従って、サブ秒精度を持つ日付と時刻の文字列をパースします。

この関数は、DateTime64 に対する formatDateTime の逆関数です。文字列引数を指定されたフォーマット文字列を使ってパースします。1900 年から 2299 年までの日時をサブ秒精度で表現できる DateTime64 型を返します。

構文

parseDateTime64(time_string, format[, timezone])

引数

time_string — DateTime64 に解析される文字列。String
format — time_string の解析方法を指定するフォーマット文字列。String
timezone — 任意。タイムゾーン。String

戻り値

MySQL スタイルのフォーマット文字列に従って、入力文字列から解析された DateTime64 を返します。DateTime64

例

使用例

SELECT parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                       2025-01-04 23:00:00.123       │
└─────────────────────────────────────────────────────────────────────┘

parseDateTime64BestEffort

導入バージョン: v20.1

parseDateTimeBestEffort 関数と同様ですが、ミリ秒およびマイクロ秒も解析し、DateTime64 データ型を返します。

構文

parseDateTime64BestEffort(time_string[, precision[, time_zone]])

引数

time_string — 変換対象の日付、または日付と時刻を含む文字列。String
precision — オプション。必要な精度。ミリ秒の場合は 3、マイクロ秒の場合は 6。デフォルト: 3。UInt8
time_zone — オプション。タイムゾーン。関数はこのタイムゾーンに従って time_string をパースします。String

戻り値

DateTime64 データ型に変換された time_string を返します。DateTime64

例

使用例

SELECT parseDateTime64BestEffort('2025-01-01') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',6) AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',3,'Asia/Istanbul') AS a, toTypeName(a) AS t
FORMAT PrettyCompactMonoBlock

┌──────────────────────────a─┬─t──────────────────────────────┐
│ 2025-01-01 01:01:00.123000 │ DateTime64(3)                  │
│ 2025-01-01 00:00:00.000000 │ DateTime64(3)                  │
│ 2025-01-01 01:01:00.123460 │ DateTime64(6)                  │
│ 2025-12-31 22:01:00.123000 │ DateTime64(3, 'Asia/Istanbul') │
└────────────────────────────┴────────────────────────────────┘

parseDateTime64BestEffortOrNull

導入バージョン: v20.1

parseDateTime64BestEffort と同様ですが、処理できない日付形式を検出した場合は NULL を返します。

構文

parseDateTime64BestEffortOrNull(time_string[, precision[, time_zone]])

引数

time_string — 変換対象の日時、または日付と時刻を含む文字列。String
precision — 省略可能。要求される精度。ミリ秒の場合は 3、マイクロ秒の場合は 6。デフォルト: 3。UInt8
time_zone — 省略可能。タイムゾーン。関数は、このタイムゾーンに従って time_string を解析します。String

返される値

time_string を DateTime64 に変換した値、または入力を解析できない場合は NULL を返します。DateTime64 または NULL

例

使用例

SELECT parseDateTime64BestEffortOrNull('2025-01-01 01:01:00.123') AS valid,
       parseDateTime64BestEffortOrNull('invalid') AS invalid

┌─valid───────────────────┬─invalid─┐
│ 2025-01-01 01:01:00.123 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

parseDateTime64BestEffortOrZero

導入バージョン: v20.1

parseDateTime64BestEffort と同様ですが、解釈できない日付形式に遭遇した場合は、ゼロの日付またはゼロの日時を返します。

構文

parseDateTime64BestEffortOrZero(time_string[, precision[, time_zone]])

引数

time_string — 変換対象の日付または日時を含む文字列。String
precision — 省略可能。要求される精度。ミリ秒は 3、マイクロ秒は 6。デフォルト: 3。UInt8
time_zone — 省略可能。タイムゾーン。この関数は指定されたタイムゾーンに従って time_string を解析します。String

返される値

time_string を DateTime64 に変換した値を返します。入力を解析できない場合は、ゼロ日付/日時（1970-01-01 00:00:00.000）を返します。DateTime64

例

使用例

SELECT parseDateTime64BestEffortOrZero('2025-01-01 01:01:00.123') AS valid,
       parseDateTime64BestEffortOrZero('invalid') AS invalid

┌─valid───────────────────┬─invalid─────────────────┐
│ 2025-01-01 01:01:00.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

parseDateTime64BestEffortUS

導入バージョン: v22.8

この関数は、あいまいさがある場合に US 日付形式（MM/DD/YYYY など）を優先する点を除き、parseDateTime64BestEffort と同じです。

構文

parseDateTime64BestEffortUS(time_string [, precision [, time_zone]])

引数

time_string — 変換対象の日付または日時を表す文字列。String
precision — 省略可。必要な精度。ミリ秒は 3、マイクロ秒は 6。デフォルト: 3。UInt8
time_zone — 省略可。タイムゾーン。この関数は指定されたタイムゾーンに従って time_string をパースします。String

返される値

あいまいなケースでは US の日付フォーマットを優先して解釈し、time_string を DateTime64 に変換して返します。DateTime64

例

使用例

SELECT parseDateTime64BestEffortUS('02/10/2025 12:30:45.123') AS us_format,
       parseDateTime64BestEffortUS('15/08/2025 10:15:30.456') AS fallback_to_standard

┌─us_format───────────────┬─fallback_to_standard────┐
│ 2025-02-10 12:30:45.123 │ 2025-08-15 10:15:30.456 │
└─────────────────────────┴─────────────────────────┘

parseDateTime64BestEffortUSOrNull

導入バージョン: v22.8

parseDateTime64BestEffort と同様ですが、曖昧さがある場合には US 日付形式（MM/DD/YYYY など）を優先し、処理できない日付形式に遭遇した場合は NULL を返します。

構文

parseDateTime64BestEffortUSOrNull(time_string[, precision[, time_zone]])

引数

time_string — 変換対象の日付、または日付と時刻を含む文字列。String
precision — 省略可。指定する精度。ミリ秒は 3、マイクロ秒は 6。デフォルト: 3。UInt8
time_zone — 省略可。タイムゾーン。この関数は指定されたタイムゾーンに従って time_string を解析します。String

返り値

US 形式を優先して DateTime64 に変換した time_string を返します。入力を解析できない場合は NULL を返します。DateTime64 または NULL

例

使用例

SELECT parseDateTime64BestEffortUSOrNull('02/10/2025 12:30:45.123') AS valid_us,
       parseDateTime64BestEffortUSOrNull('invalid') AS invalid

┌─valid_us────────────────┬─invalid─┐
│ 2025-02-10 12:30:45.123 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

parseDateTime64BestEffortUSOrZero

導入バージョン: v22.8

parseDateTime64BestEffort と同様ですが、あいまいな場合には US の日付形式（MM/DD/YYYY など）を優先し、処理できない日付形式に遭遇した場合はゼロ日付またはゼロ日時を返します。

構文

parseDateTime64BestEffortUSOrZero(time_string [, precision [, time_zone]])

引数

time_string — 変換対象の日付、または日付と時刻を含む文字列。String
precision — 任意。要求する精度。ミリ秒は 3、マイクロ秒は 6。デフォルト: 3。UInt8
time_zone — 任意。タイムゾーン。この関数は time_string をこのタイムゾーンとして解釈します。String

返される値

time_string を米国形式を優先して DateTime64 に変換して返します。入力をパースできない場合は、ゼロ日付/日時（1970-01-01 00:00:00.000）を返します。DateTime64

例

使用例

SELECT parseDateTime64BestEffortUSOrZero('02/10/2025 12:30:45.123') AS valid_us,
       parseDateTime64BestEffortUSOrZero('invalid') AS invalid

┌─valid_us────────────────┬─invalid─────────────────┐
│ 2025-02-10 12:30:45.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

parseDateTime64InJodaSyntax

導入バージョン: v24.10

Joda 形式の日付フォーマット文字列に従って、サブ秒精度を持つ日時文字列をパースします。

この関数は、DateTime64 向けの formatDateTimeInJodaSyntax の逆関数です。 Joda 形式のフォーマット文字列を使用して String 型の引数をパースします。サブ秒精度を持ち、1900 年から 2299 年までの日付を表現できる DateTime64 型を返します。

フォーマットパターンについては、Joda Time のドキュメントを参照してください。

構文

parseDateTime64InJodaSyntax(time_string, format[, timezone])

引数

time_string — DateTime64 にパースされる文字列。String
format — time_string をどのようにパースするかを指定する、Joda 構文のフォーマット文字列。String
timezone — 省略可能。タイムゾーン。String

戻り値

入力文字列を Joda 形式のフォーマット文字列に従ってパースした結果の DateTime64 を返します。DateTime64

例

使用例

SELECT parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                          2025-01-04 23:00:00.123   │
└────────────────────────────────────────────────────────────────────────────────────┘

parseDateTime64InJodaSyntaxOrNull

導入: v24.10

parseDateTime64InJodaSyntax と同様ですが、解析できない日付形式に遭遇した場合は NULL を返します。

構文

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

引数

time_string — DateTime64 に解析される文字列。String
format — time_string の解析方法を指定する Joda 構文のフォーマット文字列。String
timezone — 省略可。タイムゾーン。String

戻り値

入力文字列から解析された DateTime64 を返します。解析に失敗した場合は NULL を返します。Nullable(DateTime64)

例

使用例

SELECT parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                             2025-01-04 23:00:00.123      │
└──────────────────────────────────────────────────────────────────────────────────────────┘

parseDateTime64InJodaSyntaxOrZero

導入バージョン: v24.10

parseDateTime64InJodaSyntax と同様ですが、解析できない日付形式に遭遇した場合はゼロの日時を返します。

構文

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

引数

time_string — DateTime64 に解析する対象の文字列。String
format — time_string の解析方法を指定する Joda 構文のフォーマット文字列。String
timezone — オプションのタイムゾーン。String

戻り値

入力文字列から解析された DateTime64、または解析に失敗した場合はゼロ値の DateTime64 を返します。DateTime64

例

使用例

SELECT parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                              2025-01-04 23:00:00.123     │
└──────────────────────────────────────────────────────────────────────────────────────────┘

parseDateTime64OrNull

導入バージョン: v24.11

parseDateTime64 と同様ですが、パースできない日付形式に遭遇した場合は NULL を返します。

構文

parseDateTime64OrNull(time_string, format[, timezone])

引数

time_string — DateTime64 型にパースされる文字列。String
format — time_string のパース方法を指定する書式文字列。String
timezone — 省略可能。タイムゾーン。String

戻り値

入力文字列からパースされた DateTime64 型を返し、パースに失敗した場合は NULL を返す。Nullable(DateTime64)

例

使用例

SELECT parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                            2025-01-04 23:00:00.123        │
└───────────────────────────────────────────────────────────────────────────┘

parseDateTime64OrZero

導入バージョン: v24.11

parseDateTime64 と同様ですが、解析できない日付形式に対してはゼロ日付を返します。

構文

parseDateTime64OrZero(time_string, format[, timezone])

引数

time_string — DateTime64 にパースする対象の文字列。String
format — time_string のパース方法を指定するフォーマット文字列。String
timezone — 省略可能。タイムゾーン。String

返される値

入力文字列からパースされた DateTime64 を返します。パースに失敗した場合は、値が 0 の DateTime64 を返します。DateTime64

例

使用例

SELECT parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                             2025-01-04 23:00:00.123       │
└───────────────────────────────────────────────────────────────────────────┘

parseDateTimeBestEffort

導入バージョン: v1.1

文字列形式で表現された日付と時刻を DateTime データ型に変換します。この関数は ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 独自の形式およびその他のいくつかの日付と時刻の形式を解析します。

サポートされる非標準フォーマットは次のとおりです:

9〜10 桁の UNIX タイムスタンプを含む文字列。
日付と時刻の要素を持つ文字列: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss など。
日付を持ち、時刻要素を持たない文字列: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY など。
日と時刻を持つ文字列: DD, DD hh, DD hh:mm。この場合 MM は 01 に置き換えられます。
日付と時刻に加えてタイムゾーンオフセット情報を含む文字列: YYYY-MM-DD hh:mm:ss ±h:mm など。
syslog のタイムスタンプ: Mmm dd hh:mm:ss。例: Jun 9 14:20:32。

区切り文字を含むすべてのフォーマットでは、月名をフルスペルまたは月名の先頭 3 文字で表記したものを解析します。年が指定されていない場合、現在の年と見なされます。

構文

parseDateTimeBestEffort(time_string[, time_zone])

引数

time_string — 変換対象の日時を表す文字列。String
time_zone — 省略可能。time_string の解析に使用するタイムゾーン。String

返される値

time_string を DateTime 型として返します。DateTime

例

使用例

SELECT parseDateTimeBestEffort('23/10/2025 12:12:57') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-10-23 12:12:57 │
└─────────────────────────┘

タイムゾーン指定あり

SELECT parseDateTimeBestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-08-18 10:22:16 │
└─────────────────────────┘

Unix タイムスタンプ

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-01-01 00:00:00 │
└─────────────────────────┘

parseDateTimeBestEffortOrNull

導入バージョン: v1.1

parseDateTimeBestEffort と同様ですが、処理できない日付形式を検出した場合に NULL を返す点が異なります。この関数は ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse の独自形式およびその他のいくつかの日付・時刻形式をパースします。

サポートされる非標準形式:

9～10 桁の Unix タイムスタンプを含む文字列。
日付と時刻コンポーネントを含む文字列: YYYYMMDDhhmmss、DD/MM/YYYY hh:mm:ss、DD-MM-YY hh:mm、YYYY-MM-DD hh:mm:ss など。
日付を含むが、時刻コンポーネントを含まない文字列: YYYY、YYYYMM、YYYY*MM、DD/MM/YYYY、DD-MM-YY など。
日と時刻を含む文字列: DD、DD hh、DD hh:mm。この場合、MM は 01 に置き換えられます。
日付と時刻に加えてタイムゾーンオフセット情報を含む文字列: YYYY-MM-DD hh:mm:ss ±h:mm など。
syslog のタイムスタンプ: Mmm dd hh:mm:ss。例: Jun 9 14:20:32。

区切り文字を含む形式では、この関数は月名をフルスペル、または月名の先頭 3 文字のいずれかとして表現されたものをパースします。年が指定されていない場合、現在の年とみなされます。

構文

parseDateTimeBestEffortOrNull(time_string[, time_zone])

引数

time_string — 変換対象の日時を含む文字列。String
time_zone — 省略可能。time_string の解析に使用するタイムゾーン。String

返り値

time_string を DateTime として返し、入力を解析できない場合は NULL を返します。DateTime または NULL

例

使用例

SELECT parseDateTimeBestEffortOrNull('23/10/2025 12:12:57') AS valid,
       parseDateTimeBestEffortOrNull('invalid') AS invalid

┌─valid───────────────┬─invalid─┐
│ 2025-10-23 12:12:57 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

parseDateTimeBestEffortOrZero

導入バージョン: v1.1

parseDateTimeBestEffort と同様ですが、処理できない日付形式に遭遇した場合に、ゼロ日付またはゼロ日時を返します。この関数は ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 独自の形式およびその他のいくつかの日付・時刻形式を解析します。

サポートされている非標準形式:

9～10 桁の Unix タイムスタンプを含む文字列。
日付と時刻コンポーネントを含む文字列: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss など。
日付のみで、時刻コンポーネントを含まない文字列: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY など。
日と時刻を含む文字列: DD, DD hh, DD hh:mm。この場合、MM は 01 に置き換えられます。
日付と時刻に加えてタイムゾーンオフセット情報を含む文字列: YYYY-MM-DD hh:mm:ss ±h:mm など。
syslog のタイムスタンプ: Mmm dd hh:mm:ss。例えば Jun 9 14:20:32。

区切り文字を含む形式では、この関数は月名をフルスペルまたは先頭 3 文字で表現したものとして解析します。年が指定されていない場合は、現在の年と見なされます。

構文

parseDateTimeBestEffortOrZero(time_string[, time_zone])

引数

time_string — 変換対象の日時を含む文字列。String
time_zone — 省略可能。time_string を解析する際に使用するタイムゾーン。String

返される値

time_string を DateTime として返します。入力を解析できない場合は、ゼロの日付/日時（1970-01-01 または 1970-01-01 00:00:00）を返します。DateTime

例

使用例

SELECT parseDateTimeBestEffortOrZero('23/10/2025 12:12:57') AS valid,
       parseDateTimeBestEffortOrZero('invalid') AS invalid

┌─valid───────────────┬─invalid─────────────┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

parseDateTimeBestEffortUS

導入バージョン: v1.1

この関数は、YYYY-MM-DD hh:mm:ss のような ISO 日付形式および、YYYYMMDDhhmmss、YYYY-MM、DD hh、YYYY-MM-DD hh:mm:ss ±h:mm など、月と日の成分を一意に抽出できるその他の日付形式に対しては、parseDateTimeBestEffort と同様に動作します。 MM/DD/YYYY、MM-DD-YYYY、MM-DD-YY のように、月と日の成分を一意に抽出できない形式の場合には、DD/MM/YYYY、DD-MM-YYYY、DD-MM-YY ではなく、米国式の日付形式を優先します。ただし前述の規則の例外として、月の値が 12 より大きく 31 以下の場合、この関数は parseDateTimeBestEffort の動作にフォールバックします。たとえば 15/08/2020 は 2020-08-15 として解釈されます。

構文

parseDateTimeBestEffortUS(time_string[, time_zone])

引数

time_string — 変換対象の日時を含む文字列。String
time_zone — オプション。time_string の解析に使用するタイムゾーン。String

返り値

あいまいなケースでは US の日付形式の優先規則を用いて、time_string を DateTime として返します。DateTime

例

使用例

SELECT parseDateTimeBestEffortUS('02/10/2025') AS us_format,
       parseDateTimeBestEffortUS('15/08/2025') AS fallback_to_standard

┌─us_format───────────┬─fallback_to_standard─┐
│ 2025-02-10 00:00:00 │  2025-08-15 00:00:00 │
└─────────────────────┴──────────────────────┘

parseDateTimeBestEffortUSOrNull

導入バージョン: v1.1

解釈できない日付形式に遭遇した場合に NULL を返す点を除き、parseDateTimeBestEffortUS 関数と同じです。

この関数は ISO 日付形式に対しては parseDateTimeBestEffort と同様に動作しますが、あいまいなケースでは US 日付形式を優先し、パースエラー時には NULL を返します。

構文

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

引数

time_string — 変換対象の日時を表す文字列。String
time_zone — 任意。time_string を解釈する際に使用するタイムゾーン。String

戻り値

time_string を US 形式の日時表記を優先して解釈し、DateTime として返します。入力をパースできない場合は NULL を返します。DateTime または NULL

例

使用例

SELECT parseDateTimeBestEffortUSOrNull('02/10/2025') AS valid_us,
       parseDateTimeBestEffortUSOrNull('invalid') AS invalid

┌─valid_us────────────┬─invalid─┐
│ 2025-02-10 00:00:00 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

parseDateTimeBestEffortUSOrZero

導入バージョン: v1.1

parseDateTimeBestEffortUS 関数と同様ですが、処理できない日付形式に遭遇した場合には、ゼロ日付（1970-01-01）または時刻付きゼロ日付（1970-01-01 00:00:00）を返す点が異なります。

この関数は ISO 日付形式に対しては parseDateTimeBestEffort と同様に動作しますが、あいまいな場合には US 日付形式を優先し、パースエラー時にはゼロを返します。

構文

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

引数

time_string — 変換対象の日付と時刻を含む文字列。String
time_zone — 省略可能。time_string の解析に使用するタイムゾーン。String

戻り値

US 形式を優先して time_string を DateTime として返します。入力を解釈できない場合は、ゼロ日付/ゼロ日時（1970-01-01 または 1970-01-01 00:00:00）を返します。DateTime

例

使用例

SELECT parseDateTimeBestEffortUSOrZero('02/10/2025') AS valid_us,
       parseDateTimeBestEffortUSOrZero('invalid') AS invalid

┌─valid_us────────────┬─invalid─────────────┐
│ 2025-02-10 00:00:00 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

parseDateTimeInJodaSyntax

導入バージョン: v23.3

Joda の日付フォーマット文字列に従って、日付と時刻の文字列をパースします。

この関数は formatDateTimeInJodaSyntax の逆の動作を行います。 Joda 形式のフォーマット文字列を使用して String 引数をパースし、DateTime 型を返します。

フォーマットパターンについては、Joda Time のドキュメントを参照してください。

構文

parseDateTimeInJodaSyntax(time_string, format[, timezone])

引数

time_string — DateTime に解析する対象の文字列。String
format — time_string の解析方法を指定する Joda 構文のフォーマット文字列。String
timezone — 省略可。タイムゾーン。String

返される値

Joda 形式のフォーマット文字列に従って入力文字列を解析し、DateTime を返します。DateTime

例

使用例

SELECT parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                      2025-01-04 23:00:00 │
└──────────────────────────────────────────────────────────────────────────┘

parseDateTimeInJodaSyntaxOrNull

導入バージョン: v23.3

parseDateTimeInJodaSyntax と同様ですが、解析できない日付形式に遭遇した場合は NULL を返します。

構文

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

引数

time_string — DateTime に変換する対象の文字列。String
format — time_string の解析方法を指定する、Joda 構文で記述されたフォーマット文字列。String
timezone — 省略可能。タイムゾーン。String

戻り値

入力文字列を解析して得られた DateTime を返します。解析に失敗した場合は NULL を返します。Nullable(DateTime)

例

使用例

SELECT parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                         2025-01-04 23:00:00    │
└────────────────────────────────────────────────────────────────────────────────┘

parseDateTimeInJodaSyntaxOrZero

導入バージョン: v23.3

parseDateTimeInJodaSyntax と同様ですが、解析できない日付形式に遭遇した場合は 0 の日付を返します。

構文

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

引数

time_string — DateTime に変換される文字列。String
format — time_string をどのようにパースするかを指定する Joda 構文のフォーマット文字列。String
timezone — 省略可能。タイムゾーン。String

戻り値

入力文字列からパースされた DateTime を返し、パースに失敗した場合は DateTime のゼロ値を返します。DateTime

例

使用例

SELECT parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                          2025-01-04 23:00:00   │
└────────────────────────────────────────────────────────────────────────────────┘

parseDateTimeOrNull

導入バージョン: v23.3

parseDateTime と同様ですが、パースできない日付形式に遭遇した場合は NULL を返します。

構文

parseDateTimeOrNull(time_string, format[, timezone])

別名: str_to_date

引数

time_string — DateTime に変換する対象の文字列。String
format — time_string の解析方法を指定するフォーマット文字列。String
timezone — 省略可能。タイムゾーン。String

返される値

入力文字列を解析して得られた DateTime を返す。解析に失敗した場合は NULL を返す。Nullable(DateTime)

例

使用例

SELECT parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                            2025-01-04 23:00:00  │
└─────────────────────────────────────────────────────────────────┘

parseDateTimeOrZero

導入バージョン: v23.3

parseDateTime と同様ですが、解析できない日付形式に遭遇した場合はゼロ日付を返します。

構文

parseDateTimeOrZero(time_string, format[, timezone])

引数

time_string — DateTime に解析される文字列。String
format — time_string の解析方法を指定するフォーマット文字列。String
timezone — 省略可能なタイムゾーン。String

返される値

入力文字列から解析された DateTime、または解析に失敗した場合は 0 の DateTime 値を返します。DateTime

例

使用例

SELECT parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                             2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘

reinterpret

導入: v1.1

与えられた値 x のメモリ上の同一のバイト列をそのまま利用し、それを変換先の型として再解釈します。

構文

reinterpret(x, type)

引数

x — 任意のデータ型。Any
type — 変換先の型。配列の場合、配列要素の型は固定長型である必要があります。String

戻り値

変換先の型の値。Any

例

使用例

SELECT reinterpret(toInt8(-1), 'UInt8') AS int_to_uint,
    reinterpret(toInt8(1), 'Float32') AS int_to_float,
    reinterpret('1', 'UInt32') AS string_to_int

┌─int_to_uint─┬─int_to_float─┬─string_to_int─┐
│         255 │        1e-45 │            49 │
└─────────────┴──────────────┴───────────────┘

配列の例

SELECT reinterpret(x'3108b4403108d4403108b4403108d440', 'Array(Float32)') AS string_to_array_of_Float32

┌─string_to_array_of_Float32─┐
│ [5.626,6.626,5.626,6.626]  │
└────────────────────────────┘

reinterpretAsDate

導入バージョン: v1.1

入力値を、リトルエンディアン順であると仮定して、Date 型の値として再解釈します。これは Unix エポックである 1970-01-01 からの経過日数を表します。

構文

reinterpretAsDate(x)

引数

x — UNIX エポックの開始からの日数。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

戻り値

日付。Date

例

使用例

SELECT reinterpretAsDate(65), reinterpretAsDate('A')

┌─reinterpretAsDate(65)─┬─reinterpretAsDate('A')─┐
│            1970-03-07 │             1970-03-07 │
└───────────────────────┴────────────────────────┘

reinterpretAsDateTime

導入バージョン: v1.1

入力値を、Unix エポック（1970-01-01）の開始からの経過日数を表す DateTime 値として（リトルエンディアン順であると仮定して）再解釈します。

構文

reinterpretAsDateTime(x)

引数

x — Unix エポックの開始からの経過秒数。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

返される値

日付と時刻。DateTime

例

使用例

SELECT reinterpretAsDateTime(65), reinterpretAsDateTime('A')

┌─reinterpretAsDateTime(65)─┬─reinterpretAsDateTime('A')─┐
│       1970-01-01 01:01:05 │        1970-01-01 01:01:05 │
└───────────────────────────┴────────────────────────────┘

reinterpretAsFixedString

導入バージョン: v1.1

入力値を固定長文字列として再解釈します（リトルエンディアン順を前提とします）。末尾のヌルバイトは無視されます。例えば、UInt32 値 255 に対しては、1 文字だけから成る文字列を返します。

構文

reinterpretAsFixedString(x)

引数

x — 文字列として再解釈する値。(U)Int* または Float* または Date または DateTime

返される値

x を表すバイト列を格納する固定長文字列型。FixedString

例

使用例

SELECT
    reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05')),
    reinterpretAsFixedString(toDate('1970-03-07'))

┌─reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05'))─┬─reinterpretAsFixedString(toDate('1970-03-07'))─┐
│ A                                                           │ A                                              │
└─────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┘

reinterpretAsFloat32

導入バージョン: v1.1

入力値を Float32 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとしません。対象の型が入力値を表現できない場合、出力は未定義です。

構文

reinterpretAsFloat32(x)

引数

x — Float32 型として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

返される値

再解釈された値 x を返します。Float32

例

使用例

SELECT reinterpretAsUInt32(toFloat32(0.2)) AS x, reinterpretAsFloat32(x)

┌──────────x─┬─reinterpretAsFloat32(x)─┐
│ 1045220557 │                     0.2 │
└────────────┴─────────────────────────┘

reinterpretAsFloat64

導入バージョン: v1.1

入力値を Float64 型として再解釈します。 CAST と異なり、この関数は元の値を保持しようとはしません。対象の型が入力値を表現できない場合、出力は未定義になります。

構文

reinterpretAsFloat64(x)

引数

x — Float64 型として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

戻り値

再解釈した値 x を返します。Float64

例

使用例

SELECT reinterpretAsUInt64(toFloat64(0.2)) AS x, reinterpretAsFloat64(x)

┌───────────────────x─┬─reinterpretAsFloat64(x)─┐
│ 4596373779694328218 │                     0.2 │
└─────────────────────┴─────────────────────────┘

reinterpretAsInt128

導入: v1.1

入力値を Int128 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとは試みません。対象の型が入力の型を表現できない場合、出力は未定義です。

構文

reinterpretAsInt128(x)

引数

x — Int128 として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

返り値

x を再解釈した値を返します。Int128

例

使用例

SELECT
    toInt64(257) AS x,
    toTypeName(x),
    reinterpretAsInt128(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int64         │ 257 │ Int128          │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsInt16

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

入力値を Int16 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとはしません。ターゲット型が入力値を表現できない場合、出力は未定義となります。

構文

reinterpretAsInt16(x)

引数

x — Int16 型として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

返される値

Int16 型として再解釈された値 x を返します。Int16

例

使用例

SELECT
    toInt8(257) AS x,
    toTypeName(x),
    reinterpretAsInt16(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ Int8          │   1 │ Int16           │
└───┴───────────────┴─────┴─────────────────┘

reinterpretAsInt256

導入バージョン: v1.1

入力値を Int256 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとしません。対象の型が入力値を表現できない場合、出力は未定義です。

構文

reinterpretAsInt256(x)

引数

x — Int256 として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

戻り値

Int256 として再解釈した値 x を返します。Int256

例

使用例

SELECT
    toInt128(257) AS x,
    toTypeName(x),
    reinterpretAsInt256(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int128        │ 257 │ Int256          │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsInt32

導入バージョン: v1.1

入力値を Int32 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとはしません。ターゲット型が入力値を表現できない場合、戻り値は未定義です。

構文

reinterpretAsInt32(x)

引数

x — Int32 として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString のいずれか。

返り値

再解釈された x の値を返します。Int32

例

使用例

SELECT
    toInt16(257) AS x,
    toTypeName(x),
    reinterpretAsInt32(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int16         │ 257 │ Int32           │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsInt64

導入バージョン: v1.1

入力値を型 Int64 の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとしません。対象の型で入力値を表現できない場合、出力は未定義です。

構文

reinterpretAsInt64(x)

引数

x — Int64 として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

返される値

x を再解釈した値を返します。Int64

例

使用例

SELECT
    toInt32(257) AS x,
    toTypeName(x),
    reinterpretAsInt64(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int32         │ 257 │ Int64           │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsInt8

導入バージョン: v1.1

入力値を Int8 型の値として再解釈します。 CAST と異なり、この関数は元の値の保持を試みません。ターゲット型が入力値を表現できない場合、出力は未定義となります。

構文

reinterpretAsInt8(x)

引数

x — Int8 として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

返される値

再解釈後の値 x を返します。Int8

例

使用例

SELECT
    toUInt8(257) AS x,
    toTypeName(x),
    reinterpretAsInt8(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8         │   1 │ Int8            │
└───┴───────────────┴─────┴─────────────────┘

reinterpretAsString

導入バージョン: v1.1

入力値を文字列として再解釈します（リトルエンディアン順を前提とします）。末尾のヌルバイトは無視されます。たとえば、この関数は UInt32 の値 255 に対して、1 文字だけからなる文字列を返します。

構文

reinterpretAsString(x)

引数

x — 文字列として再解釈する値。(U)Int* または Float* または Date または DateTime

戻り値

x を表すバイト列を含む文字列。String

例

使用例

SELECT
    reinterpretAsString(toDateTime('1970-01-01 01:01:05')),
    reinterpretAsString(toDate('1970-03-07'))

┌─reinterpretAsString(toDateTime('1970-01-01 01:01:05'))─┬─reinterpretAsString(toDate('1970-03-07'))─┐
│ A                                                      │ A                                         │
└────────────────────────────────────────────────────────┴───────────────────────────────────────────┘

reinterpretAsUInt128

導入バージョン: v1.1

入力値を型 UInt128 の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとしません。対象の型が入力値の型を表現できない場合、結果は未定義となります。

構文

reinterpretAsUInt128(x)

引数

x — UInt128 として再解釈される値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

返される値

再解釈後の値 x を返します。型は UInt128 です。

例

使用例

SELECT
    toUInt64(257) AS x,
    toTypeName(x),
    reinterpretAsUInt128(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt64        │ 257 │ UInt128         │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt16

導入バージョン: v1.1

入力値を UInt16 型の値として再解釈します。 CAST とは異なり、この関数は元の値を保持しようとはしません。対象の型が入力値の型を表現できない場合、出力は未定義です。

構文

reinterpretAsUInt16(x)

引数

x — UInt16 として再解釈する値。(U)Int*、Float*、Date、DateTime、UUID、String、または FixedString のいずれか。

戻り値

再解釈した値 x を返します。UInt16

例

使用例

SELECT
    toUInt8(257) AS x,
    toTypeName(x),
    reinterpretAsUInt16(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8         │   1 │ UInt16          │
└───┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt256

導入バージョン: v1.1

入力値を UInt256 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとはしません。対象の型が入力値を表現できない場合、結果は未定義です。

構文

reinterpretAsUInt256(x)

引数

x — UInt256 として再解釈する値です。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

戻り値

再解釈した値 x を返します。UInt256

例

使用例

SELECT
    toUInt128(257) AS x,
    toTypeName(x),
    reinterpretAsUInt256(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt128       │ 257 │ UInt256         │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt32

導入バージョン: v1.1

入力値を UInt32 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとはしません。対象型が入力の型を表現できない場合、出力は未定義です。

構文

reinterpretAsUInt32(x)

引数

x — UInt32 として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

戻り値

x を UInt32 として再解釈した値を返します。UInt32

例

使用例

SELECT
    toUInt16(257) AS x,
    toTypeName(x),
    reinterpretAsUInt32(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt16        │ 257 │ UInt32          │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt64

導入バージョン: v1.1

入力値を UInt64 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとしません。対象の型が入力値を表現できない場合、出力は未定義です。

構文

reinterpretAsUInt64(x)

引数

x — UInt64 として再解釈される値。Int* または UInt* または Float* または Date または DateTime または UUID または String または FixedString

戻り値

x を再解釈した値を返します。UInt64

例

使用例

SELECT
    toUInt32(257) AS x,
    toTypeName(x),
    reinterpretAsUInt64(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt32        │ 257 │ UInt64          │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt8

導入: v1.1

入力値を UInt8 型の値として再解釈します。 CAST と異なり、この関数は元の値を保持しようとしません。対象の型で入力値を表現できない場合、出力は未定義となります。

構文

reinterpretAsUInt8(x)

引数

x — UInt8 型として再解釈する値。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

戻り値

再解釈後の値 x を返します。型は UInt8 です。

例

使用例

SELECT
    toInt8(-1) AS val,
    toTypeName(val),
    reinterpretAsUInt8(val) AS res,
    toTypeName(res);

┌─val─┬─toTypeName(val)─┬─res─┬─toTypeName(res)─┐
│  -1 │ Int8            │ 255 │ UInt8           │
└─────┴─────────────────┴─────┴─────────────────┘

reinterpretAsUUID

導入バージョン: v1.1

16 バイトの文字列を受け取り、前後それぞれ 8 バイトの部分をリトルエンディアンのバイト順として解釈して UUID を返します。文字列が十分な長さでない場合は、末尾に必要な数のヌルバイトがパディングされたかのように動作します。文字列が 16 バイトより長い場合は、末尾の余分なバイトは無視されます。

構文

reinterpretAsUUID(fixed_string)

引数

fixed_string — ビッグエンディアン形式のバイト列。FixedString

戻り値

UUID 型の値。UUID

例

文字列から UUID への変換

SELECT reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))

┌─reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))─┐
│                                  08090a0b-0c0d-0e0f-0001-020304050607 │
└───────────────────────────────────────────────────────────────────────┘

toBFloat16

導入バージョン: v1.1

入力値を BFloat16 型の値に変換します。エラーが発生した場合は例外をスローします。

関連項目:

toBFloat16OrZero
toBFloat16OrNull

構文

toBFloat16(expr)

引数

expr — 数値、または数値を表す文字列を返す式。 Expression

戻り値

16ビットの brain-float 型の値を返します。 BFloat16

例

使用例

SELECT
toBFloat16(toFloat32(42.7)),
toBFloat16(toFloat32('42.7')),
toBFloat16('42.7')
FORMAT Vertical;

toBFloat16(toFloat32(42.7)): 42.5
toBFloat16(t⋯32('42.7')):    42.5
toBFloat16('42.7'):          42.5

toBFloat16OrNull

導入バージョン: v1.1

String 型の入力値を BFloat16 型の値に変換します。文字列が浮動小数点値を表していない場合、この関数は NULL を返します。

サポートされる引数:

数値を表す文字列。

サポートされない引数（NULL を返す）:

2 進数および 16 進数を表す文字列。
数値型の引数。

注記

この関数では、文字列表現から変換する際に発生する精度の損失を暗黙的に許容します。

関連項目:

toBFloat16。
toBFloat16OrZero。

構文

toBFloat16OrNull(x)

引数

x — 数値の文字列表現。String

戻り値

16 ビットの brain-float 値を返し、それ以外の場合は NULL を返します。BFloat16 または NULL

例

使用例

SELECT toBFloat16OrNull('0x5E'), -- unsupported arguments
       toBFloat16OrNull('12.3'), -- typical use
       toBFloat16OrNull('12.3456789') -- silent loss of precision

\N
12.25
12.3125

toBFloat16OrZero

導入バージョン: v1.1

文字列の入力値を BFloat16 型の値に変換します。文字列が浮動小数点値を表していない場合、この関数はゼロを返します。

サポートされる引数:

数値を表す文字列。

サポートされない引数（0 を返す）:

2 進数および 16 進数値を表す文字列。
数値の値。

注記

この関数は、文字列表現から変換する際の精度のサイレントな損失を許容します。

関連項目:

toBFloat16。
toBFloat16OrNull。

構文

toBFloat16OrZero(x)

引数

x — 数値の文字列表現。String

戻り値

16ビットの bfloat16 値を返し、それ以外の場合は 0 を返します。BFloat16

例

使用例

SELECT toBFloat16OrZero('0x5E'), -- unsupported arguments
       toBFloat16OrZero('12.3'), -- typical use
       toBFloat16OrZero('12.3456789') -- silent loss of precision

0
12.25
12.3125

toBool

導入バージョン: v22.2

入力値を Bool 型の値に変換します。

構文

toBool(expr)

引数

expr — 数値または文字列を返す式。文字列の場合、'true' または 'false'（大文字小文字は区別されません）を受け付けます。(U)Int* または Float* または String または Expression

戻り値

引数を評価した結果に基づき、true または false を返します。Bool

例

使用例

SELECT
    toBool(toUInt8(1)),
    toBool(toInt8(-1)),
    toBool(toFloat32(1.01)),
    toBool('true'),
    toBool('false'),
    toBool('FALSE')
FORMAT Vertical

toBool(toUInt8(1)):      true
toBool(toInt8(-1)):      true
toBool(toFloat32(1.01)): true
toBool('true'):          true
toBool('false'):         false
toBool('FALSE'):         false

toDate

導入バージョン: v1.1

入力値を型 Date に変換します。 String、FixedString、DateTime、または数値型からの変換をサポートします。

構文

toDate(x)

引数

x — 変換対象の入力値。String、FixedString、DateTime、(U)Int*、Float* のいずれか。

返り値

変換後の入力値を返します。Date

例

String から Date への変換

SELECT toDate('2025-04-15')

2025-04-15

DateTime 型から Date 型への変換

SELECT toDate(toDateTime('2025-04-15 10:30:00'))

2025-04-15

整数からDateへの変換

SELECT toDate(20297)

2025-07-28

toDate32

導入バージョン: v21.9

引数を Date32 データ型に変換します。値が範囲外の場合、toDate32 は Date32 でサポートされる境界値を返します。引数が Date 型の場合、その型の有効範囲が考慮されます。

構文

toDate32(expr)

引数

expr — 変換対象の値。String または UInt32 または Date

返される値

カレンダー上の日付を返します。Date32

例

範囲内

SELECT toDate32('2025-01-01') AS value, toTypeName(value)
FORMAT Vertical

Row 1:
──────
value:           2025-01-01
toTypeName(value): Date32

範囲外

SELECT toDate32('1899-01-01') AS value, toTypeName(value)
FORMAT Vertical

Row 1:
──────
value:           1900-01-01
toTypeName(value): Date32

toDate32OrDefault

導入: v21.11

引数を Date32 データ型に変換します。値が範囲外の場合、toDate32OrDefault は Date32 でサポートされている下限値を返します。引数が Date 型の場合は、その型の有効な範囲も考慮されます。無効な引数が指定された場合はデフォルト値を返します。

構文

toDate32OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — 省略可能。解析に失敗した場合に返す既定値。Date32

戻り値

成功した場合は Date32 型の値を返し、失敗した場合は、指定されていればデフォルト値を、指定されていなければ 1900-01-01 を返します。Date32

例

変換が成功する例

SELECT toDate32OrDefault('1930-01-01', toDate32('2020-01-01'))

1930-01-01

変換に失敗

SELECT toDate32OrDefault('xx1930-01-01', toDate32('2020-01-01'))

2020-01-01

toDate32OrNull

導入バージョン: v21.9

入力値を型 Date32 の値に変換しますが、不正な引数が渡された場合は NULL を返します。 toDate32 と同様ですが、不正な引数が渡された場合には NULL を返します。

構文

toDate32OrNull(x)

引数

x — 日付を表す文字列。String

戻り値

成功した場合は Date32 型の値を返し、失敗した場合は NULL を返します。Date32 または NULL

例

使用例

SELECT toDate32OrNull('2025-01-01'), toDate32OrNull('invalid')

┌─toDate32OrNull('2025-01-01')─┬─toDate32OrNull('invalid')─┐
│                   2025-01-01 │                      ᴺᵁᴸᴸ │
└──────────────────────────────┴───────────────────────────┘

toDate32OrZero

導入バージョン: v21.9

入力値を Date32 型の値に変換しますが、無効な引数を受け取った場合は Date32 の下限値を返します。 toDate32 と同様ですが、無効な引数を受け取った場合に Date32 の下限値を返します。

関連項目:

toDate32
toDate32OrNull
toDate32OrDefault

構文

toDate32OrZero(x)

引数

x — 日付を表す文字列。String

戻り値

成功した場合は Date32 型の値を返し、それ以外の場合は Date32 型の下限値（1900-01-01）を返します。Date32

例

使用例

SELECT toDate32OrZero('2025-01-01'), toDate32OrZero('')

┌─toDate32OrZero('2025-01-01')─┬─toDate32OrZero('')─┐
│                   2025-01-01 │         1900-01-01 │
└──────────────────────────────┴────────────────────┘

toDateOrDefault

導入バージョン: v21.11

toDate と同様ですが、変換に失敗した場合はデフォルト値を返します。デフォルト値は、第 2 引数が指定されている場合はその値、指定されていない場合は Date の下限値です。

構文

toDateOrDefault(expr[, default])

引数

expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
default — 省略可能。パースに失敗した場合に返すデフォルト値。Date

戻り値

成功した場合は Date 型の値を返し、失敗した場合は指定されていればデフォルト値、指定されていなければ 1970-01-01 を返します。Date

例

正常に変換できた例

SELECT toDateOrDefault('2022-12-30')

2022-12-30

変換失敗

SELECT toDateOrDefault('', CAST('2023-01-01', 'Date'))

2023-01-01

toDateOrNull

導入バージョン: v1.1

入力値を型 Date の値に変換しますが、無効な引数が指定された場合は NULL を返します。 toDate と同様ですが、無効な引数が指定された場合に NULL を返します。

構文

toDateOrNull(x)

引数

x — 日付の文字列表現。String

戻り値

成功した場合は Date 型の値を返し、そうでない場合は NULL を返します。Date または NULL

例

使用例

SELECT toDateOrNull('2025-12-30'), toDateOrNull('invalid')

┌─toDateOrNull('2025-12-30')─┬─toDateOrNull('invalid')─┐
│                 2025-12-30 │                   ᴺᵁᴸᴸ │
└────────────────────────────┴────────────────────────┘

toDateOrZero

導入バージョン: v1.1

入力値をDate型の値に変換しますが、無効な引数を受け取った場合はDateの下限値を返します。 toDateと同様ですが、無効な引数を受け取った場合にDateの下限値を返します。

関連項目:

toDate
toDateOrNull
toDateOrDefault

構文

toDateOrZero(x)

引数

x — 日付を表す文字列。String

返される値

成功した場合は Date 型の値を返し、失敗した場合は Date 型の下限値（1970-01-01）を返します。Date

例

使用例

SELECT toDateOrZero('2025-12-30'), toDateOrZero('')

┌─toDateOrZero('2025-12-30')─┬─toDateOrZero('')─┐
│                 2025-12-30 │       1970-01-01 │
└────────────────────────────┴──────────────────┘

toDateTime

導入バージョン: v1.1

入力値を型 DateTime に変換します。

注記

expr が数値の場合、Unix エポックの開始時点からの秒数（Unix タイムスタンプ）として解釈されます。 expr が String の場合、Unix タイムスタンプとして、または日付 / 日付と時刻の文字列表現として解釈されることがあります。そのため、短い数値の文字列表現（最大 4 桁）のパースはあいまいさのため明示的に無効化されています。例えば、文字列 '1999' は年（Date / DateTime の不完全な文字列表現）とも Unix タイムスタンプとも解釈できるためです。より長い数値文字列は許可されています。

構文

toDateTime(expr[, time_zone])

引数

expr — 値。String または Int または Date または DateTime
time_zone — タイムゾーン。String

戻り値

日時を返します。DateTime

例

使用例

SELECT toDateTime('2025-01-01 00:00:00'), toDateTime(1735689600, 'UTC')
FORMAT Vertical

Row 1:
──────
toDateTime('2025-01-01 00:00:00'): 2025-01-01 00:00:00
toDateTime(1735689600, 'UTC'):     2025-01-01 00:00:00

toDateTime32

導入バージョン: v20.9

入力値を DateTime 型に変換します。 String、FixedString、Date、Date32、DateTime、または数値型（(U)Int*、Float*、Decimal）からの変換をサポートします。 DateTime32 は DateTime と比較してより広い有効範囲を持ち、1900-01-01 から 2299-12-31 までの日付を扱うことができます。

構文

toDateTime32(x[, timezone])

引数

x — 変換する入力値。String または FixedString または UInt* または Float* または Date または DateTime または DateTime64
timezone — 省略可能。返される DateTime 値のタイムゾーンを表す値。String

返される値

変換された入力値を返します。DateTime

例

値が範囲内にある場合

SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64('20255-01-01 00:00:00.000', 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)                                          │
└─────────────────────────┴────────────────────────────────────────────────────────┘

指定した精度の十進小数として

SELECT toDateTime64(1735689600.000, 3) AS value, toTypeName(value);
-- without the decimal point the value is still treated as Unix Timestamp in seconds
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64(1735689600.000, 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)                            │
└─────────────────────────┴──────────────────────────────────────────┘
┌───────────────────value─┬─toTypeName(toDateTime64(1546300800000, 3))─┐
│ 2282-12-31 00:00:00.000 │ DateTime64(3)                              │
└─────────────────────────┴────────────────────────────────────────────┘

タイムゾーンあり

SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul'))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, 'Asia/Istanbul')                                      │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────┘

toDateTime64

導入バージョン: v20.1

入力値をDateTime64型に変換します。

構文

toDateTime64(expr, scale[, timezone])

引数

expr — 数値、または数値の文字列表現を返す式。Expression
scale — ティックサイズ（精度）：10^(-scale) 秒。UInt8
timezone — 省略可能。指定された DateTime64 オブジェクトのタイムゾーン。String

返される値

サブ秒精度を持つ暦の日付と時刻を返します。DateTime64

例

値が範囲内にある場合

SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00.000', 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)                                          │
└─────────────────────────┴────────────────────────────────────────────────────────┘

精度指定の Decimal 型として

SELECT toDateTime64(1546300800.000, 3) AS value, toTypeName(value);
-- Without the decimal point the value is still treated as Unix Timestamp in seconds
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64(1546300800000, 3))─┐
│ 2282-12-31 00:00:00.000 │ DateTime64(3)                              │
└─────────────────────────┴────────────────────────────────────────────┘

タイムゾーン付き

SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul'))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, 'Asia/Istanbul')                                      │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────┘

toDateTime64OrDefault

導入バージョン: v21.11

toDateTime64 と同様に、この関数は入力値を DateTime64 型の値に変換しますが、無効な引数を受け取った場合は DateTime64 のデフォルト値または指定されたデフォルト値のいずれかを返します。

構文

toDateTime64OrDefault(expr, scale[, timezone, default])

引数

expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
scale — ティックサイズ（精度）。10^-precision 秒。UInt8
timezone — オプション。タイムゾーン。String
default — オプション。解析に失敗した場合に返すデフォルト値。DateTime64

戻り値

成功した場合は DateTime64 型の値を返し、失敗した場合は指定されていればデフォルト値を返し、指定されていなければ 1970-01-01 00:00:00.000 を返す。DateTime64

例

変換が成功する例

SELECT toDateTime64OrDefault('1976-10-18 00:00:00.30', 3)

1976-10-18 00:00:00.300

変換に失敗

SELECT toDateTime64OrDefault('1976-10-18 00:00:00 30', 3, 'UTC', toDateTime64('2001-01-01 00:00:00.00',3))

2000-12-31 23:00:00.000

toDateTime64OrNull

導入バージョン: v20.1

入力値を DateTime64 型に変換しますが、不正な引数が渡された場合は NULL を返します。これは toDateTime64 と同様ですが、不正な引数が渡された場合には NULL を返します。

構文

toDateTime64OrNull(x)

引数

x — 時刻およびサブ秒精度を含む日付の文字列表現。String

戻り値

成功した場合は DateTime64 型の値を返し、失敗した場合は NULL を返します。DateTime64 または NULL

例

使用例

SELECT toDateTime64OrNull('2025-12-30 13:44:17.123'), toDateTime64OrNull('invalid')

┌─toDateTime64OrNull('2025-12-30 13:44:17.123')─┬─toDateTime64OrNull('invalid')─┐
│                         2025-12-30 13:44:17.123 │                          ᴺᵁᴸᴸ │
└─────────────────────────────────────────────────┴───────────────────────────────┘

toDateTime64OrZero

導入バージョン: v20.1

入力値を型 DateTime64 の値に変換しますが、不正な引数を受け取った場合は DateTime64 の下限値を返します。 toDateTime64 と同様で、不正な引数を受け取った場合に DateTime64 の下限値を返します。

関連項目:

toDateTime64。
toDateTime64OrNull。
toDateTime64OrDefault。

構文

toDateTime64OrZero(x)

引数

x — 日付と時刻をサブ秒精度まで含む文字列表現。String

戻り値

成功した場合は DateTime64 値を返し、失敗した場合は DateTime64 の下限値（1970-01-01 00:00:00.000）を返します。DateTime64

例

使用例

SELECT toDateTime64OrZero('2025-12-30 13:44:17.123'), toDateTime64OrZero('invalid')

┌─toDateTime64OrZero('2025-12-30 13:44:17.123')─┬─toDateTime64OrZero('invalid')─┐
│                         2025-12-30 13:44:17.123 │             1970-01-01 00:00:00.000 │
└─────────────────────────────────────────────────┴─────────────────────────────────────┘

toDateTimeOrDefault

導入バージョン: v21.11

toDateTime と同様ですが、変換に失敗した場合はデフォルト値を返します。デフォルト値は、第 3 引数が指定されていればその値であり、指定されていなければ DateTime 型の下限値です。

構文

toDateTimeOrDefault(expr[, timezone, default])

引数

expr — 数値または数値の文字列表現を返す式。String または (U)Int* または Float*
timezone — 省略可能。タイムゾーン。String
default — 省略可能。解析に失敗した場合に返されるデフォルト値。DateTime

戻り値

変換に成功した場合は DateTime 型の値を返し、失敗した場合は指定されていればデフォルト値を、指定されていなければ 1970-01-01 00:00:00 を返します。DateTime

例

変換の成功例

SELECT toDateTimeOrDefault('2022-12-30 13:44:17')

2022-12-30 13:44:17

変換が失敗した場合

SELECT toDateTimeOrDefault('', 'UTC', CAST('2023-01-01', 'DateTime(\'UTC\')'))

2023-01-01 00:00:00

toDateTimeOrNull

導入バージョン: v1.1

入力値を DateTime 型に変換しますが、無効な引数が渡された場合は NULL を返します。 toDateTime と同様ですが、無効な引数が渡された場合には NULL を返します。

構文

toDateTimeOrNull(x)

引数

x — 日時の文字列表現。String

戻り値

変換に成功した場合は DateTime 値を返し、失敗した場合は NULL を返します。DateTime または NULL

例

使用例

SELECT toDateTimeOrNull('2025-12-30 13:44:17'), toDateTimeOrNull('invalid')

┌─toDateTimeOrNull('2025-12-30 13:44:17')─┬─toDateTimeOrNull('invalid')─┐
│                     2025-12-30 13:44:17 │                        ᴺᵁᴸᴸ │
└─────────────────────────────────────────┴─────────────────────────────┘

toDateTimeOrZero

導入バージョン: v1.1

入力値を DateTime 型に変換しますが、無効な引数が指定された場合は DateTime の下限値を返します。 toDateTime と同様の動作をしますが、無効な引数が指定された場合に DateTime の下限値を返します。

構文

toDateTimeOrZero(x)

引数

x — 日時を表す文字列。String

戻り値

成功した場合は DateTime の値を返し、失敗した場合は DateTime の下限値（1970-01-01 00:00:00）を返します。DateTime

例

使用例

SELECT toDateTimeOrZero('2025-12-30 13:44:17'), toDateTimeOrZero('invalid')

┌─toDateTimeOrZero('2025-12-30 13:44:17')─┬─toDateTimeOrZero('invalid')─┐
│                     2025-12-30 13:44:17 │         1970-01-01 00:00:00 │
└─────────────────────────────────────────┴─────────────────────────────┘

toDecimal128

導入バージョン: v18.12

入力値を、スケール S を持つ型 Decimal(38, S) の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされない引数:

Float* 型の NaN および Inf（大文字・小文字は区別しない）、またはその文字列表現。
2 進数および 16 進数値の文字列表現。例: SELECT toDecimal128('0xc0fe', 1);。

注記

expr の値が Decimal128 の範囲 (-1*10^(38 - S), 1*10^(38 - S)) を超えるとオーバーフローが発生する可能性があります。小数部の桁数が多すぎる場合は、余分な桁は切り捨てられます（丸めは行われません）。整数部の桁数が多すぎる場合は、例外が発生します。

注意

変換では余分な桁が切り捨てられ、Float32/Float64 の入力を扱う場合、演算が浮動小数点命令で実行されるため、予期しない動作となる可能性があります。例えば、toDecimal128(1.15, 2) は 1.14 に等しくなります。これは浮動小数点において 1.15 * 100 が 114.99 となるためです。 String を入力として使用すると、演算は基盤となる整数型で行われます: toDecimal128('1.15', 2) = 1.15

構文

toDecimal128(expr, S)

引数

expr — 数値または数値を表す文字列を返す式。Expression
S — 0 から 38 の範囲のスケールパラメータで、数値の小数部が持てる桁数を指定します。UInt8

戻り値

型 Decimal(38, S) の値を返します。Decimal128(S)

例

使用例

SELECT
    toDecimal128(99, 1) AS a, toTypeName(a) AS type_a,
    toDecimal128(99.67, 2) AS b, toTypeName(b) AS type_b,
    toDecimal128('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      99
type_a: Decimal(38, 1)
b:      99.67
type_b: Decimal(38, 2)
c:      99.67
type_c: Decimal(38, 3)

toDecimal128OrDefault

導入バージョン: v21.11

toDecimal128 と同様に、この関数は入力値を Decimal(38, S) 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。

構文

toDecimal128OrDefault(expr, S[, default])

引数

expr — 数値を表す文字列。String
S — 0 から 38 の間のスケールパラメータ。小数部に許容される桁数を指定します。UInt8
default — 省略可。Decimal128(S) 型へのパースに失敗した場合に返すデフォルト値。Decimal128(S)

返り値

成功した場合は型 Decimal(38, S) の値を返し、失敗した場合は指定されていればデフォルト値を、指定されていなければ 0 を返します。Decimal128(S)

例

変換に成功する例

SELECT toDecimal128OrDefault(toString(1/42), 18)

0.023809523809523808

変換に失敗

SELECT toDecimal128OrDefault('Inf', 0, CAST('-1', 'Decimal128(0)'))

-1

toDecimal128OrNull

導入: v20.1

入力値を型 Decimal(38, S) の値に変換しますが、エラーが発生した場合は NULL を返します。変換エラー発生時に例外をスローするのではなく NULL を返す点を除き、toDecimal128 と同様です。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされない引数（NULL を返す）:

Float* 値 NaN および Inf の値、またはその文字列表現（大文字小文字を区別しない）。
2 進数および 16 進数値の文字列表現。
Decimal128 の範囲 (-1*10^(38 - S), 1*10^(38 - S)) を超える値。

関連項目:

toDecimal128。
toDecimal128OrZero。
toDecimal128OrDefault。

構文

toDecimal128OrNull(expr, S)

引数

expr — 数値、または数値を表す文字列を返す式。Expression
S — 0 ～ 38 の間のスケールパラメータで、数値の小数部が持てる桁数を指定します。UInt8

返される値

成功した場合は Decimal(38, S) 型の値を返し、そうでない場合は NULL を返します。Decimal128(S) または NULL

例

使用例

SELECT toDecimal128OrNull('42.7', 2), toDecimal128OrNull('invalid', 2)

┌─toDecimal128OrNull('42.7', 2)─┬─toDecimal128OrNull('invalid', 2)─┐
│                         42.70 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

toDecimal128OrZero

導入バージョン: v20.1

入力値を型 Decimal(38, S) の値に変換しますが、エラー発生時には 0 を返します。 toDecimal128 と同様ですが、変換エラー時に例外をスローする代わりに 0 を返します。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされない引数（0 を返す）:

Float* 型の値 NaN および Inf（大文字小文字は区別しない）、またはそれらの文字列表現。
2 進数および 16 進数の値を表す文字列。

注記

入力値が Decimal128 の範囲 (-1*10^(38 - S), 1*10^(38 - S)) を超える場合、この関数は 0 を返します。

構文

toDecimal128OrZero(expr, S)

引数

expr — 数値、または数値の文字列表現を返す式。Expression
S — 0 から 38 の間のスケールパラメータ。数値の小数部に許容される桁数を指定する。UInt8

戻り値

成功した場合は Decimal(38, S) 型の値を返し、失敗した場合は 0 を返す。Decimal128(S)

例

基本的な使い方

SELECT toDecimal128OrZero('42.7', 2), toDecimal128OrZero('invalid', 2)

┌─toDecimal128OrZero('42.7', 2)─┬─toDecimal128OrZero('invalid', 2)─┐
│                         42.70 │                             0.00 │
└───────────────────────────────┴──────────────────────────────────┘

toDecimal256

導入バージョン: v20.8

入力値をスケール S を持つ Decimal(76, S) 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

型が (U)Int* の値、またはその文字列表現。
型が Float* の値、またはその文字列表現。

サポートされない引数:

Float* 型の NaN および Inf（大文字・小文字は区別されません）の値、またはその文字列表現。
バイナリ値や 16 進値の文字列表現。例: SELECT toDecimal256('0xc0fe', 1);。

注記

expr の値が Decimal256 の範囲 (-1*10^(76 - S), 1*10^(76 - S)) を超えるとオーバーフローが発生する可能性があります。小数部の桁数が多すぎる場合は、余分な桁は切り捨てられます（四捨五入はされません）。整数部の桁数が多すぎる場合は、例外がスローされます。

注意

変換では余分な桁が切り捨てられ、Float32/Float64 入力を扱う場合、浮動小数点命令を使用して演算が行われるため、意図しない動作となる可能性があります。例えば、toDecimal256(1.15, 2) は 1.14 と等しくなります。これは、浮動小数点において 1.15 * 100 が 114.99 になるためです。演算で内部的に整数型が使われるようにするには、String 入力を使用します: toDecimal256('1.15', 2) = 1.15

構文

toDecimal256(expr, S)

引数

expr — 数値または数値を表す文字列を返す式。Expression
S — 0 から 76 までのスケールパラメータ。数値の小数部の桁数の上限を指定します。UInt8

戻り値

型 Decimal(76, S) の値を返します。Decimal256(S)

例

使用例

SELECT
    toDecimal256(99, 1) AS a, toTypeName(a) AS type_a,
    toDecimal256(99.67, 2) AS b, toTypeName(b) AS type_b,
    toDecimal256('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      99
type_a: Decimal(76, 1)
b:      99.67
type_b: Decimal(76, 2)
c:      99.67
type_c: Decimal(76, 3)

toDecimal256OrDefault

導入: v21.11

toDecimal256 と同様に、この関数は入力値を型 Decimal(76, S) の値に変換しますが、エラーが発生した場合はデフォルトの値を返します。

構文

toDecimal256OrDefault(expr, S[, default])

引数

expr — 数値の文字列表現。String
S — 0 から 76 の間の Scale パラメータ。数値の小数部が取りうる桁数を指定します。UInt8
default — 省略可能。型 Decimal256(S) への変換に失敗した場合に返されるデフォルト値。Decimal256(S)

戻り値

変換に成功した場合は型 Decimal(76, S) の値を返し、失敗した場合は、指定されていればデフォルト値を、指定されていなければ 0 を返します。Decimal256(S)

例

変換の成功例

SELECT toDecimal256OrDefault(toString(1/42), 76)

0.023809523809523808

変換に失敗

SELECT toDecimal256OrDefault('Inf', 0, CAST('-1', 'Decimal256(0)'))

-1

toDecimal256OrNull

導入バージョン: v20.8

入力値を Decimal(76, S) 型の値に変換しますが、エラーが発生した場合はNULLを返します。変換エラー時に例外をスローする代わりにNULLを返す点を除き、toDecimal256と同様です。

サポートされている引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされていない引数（NULL を返す）:

Float* 値 NaN および Inf（大文字・小文字は区別しない）、またはその文字列表現。
2 進数および 16 進数値の文字列表現。
Decimal256 の範囲を超える値: (-1 * 10^(76 - S), 1 * 10^(76 - S))。

関連項目:

toDecimal256。
toDecimal256OrZero。
toDecimal256OrDefault。

構文

toDecimal256OrNull(expr, S)

引数

expr — 数値、または数値の文字列表現を返す式。Expression
S — 0 から 76 の間のスケールパラメータ。数値の小数部が取りうる桁数を指定します。UInt8

返される値

成功すると Decimal(76, S) の値を返し、そうでない場合は NULL を返します。Decimal256(S) または NULL

例

使用例

SELECT toDecimal256OrNull('42.7', 2), toDecimal256OrNull('invalid', 2)

┌─toDecimal256OrNull('42.7', 2)─┬─toDecimal256OrNull('invalid', 2)─┐
│                         42.70 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

toDecimal256OrZero

導入されたバージョン: v20.8

入力値を型 Decimal(76, S) の値に変換しますが、エラーが発生した場合は 0 を返します。変換エラー時に例外をスローする代わりに 0 を返す点を除いて、toDecimal256 と同様です。

サポートされている引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされていない引数（0 を返す）:

Float* 型の値 NaN および Inf（大文字小文字は区別しない）、またはそれらの文字列表現。
2進数および16進数の値の文字列表現。

注記

入力値が Decimal256 の範囲 (-1*10^(76 - S), 1*10^(76 - S)) を超えた場合、この関数は 0 を返します。

関連項目:

toDecimal256.
toDecimal256OrNull.
toDecimal256OrDefault.

構文

toDecimal256OrZero(expr, S)

引数

expr — 数値または数値の文字列表現を返す式。Expression
S — 0 から 76 の間のスケールパラメータで、数値の小数部が持てる桁数を指定します。UInt8

戻り値

成功すると Decimal(76, S) の値を返し、失敗時は 0 を返します。Decimal256(S)

例

使用例

SELECT toDecimal256OrZero('42.7', 2), toDecimal256OrZero('invalid', 2)

┌─toDecimal256OrZero('42.7', 2)─┬─toDecimal256OrZero('invalid', 2)─┐
│                         42.70 │                             0.00 │
└───────────────────────────────┴──────────────────────────────────┘

toDecimal32

導入バージョン: v18.12

入力値をスケール S を持つ Decimal(9, S) 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

(U)Int* 型の値またはその文字列表現。
Float* 型の値またはその文字列表現。

サポートされない引数:

Float* 値 NaN および Inf（大文字小文字は区別しない）の値またはその文字列表現。
2進数および16進数の文字列表現。例: SELECT toDecimal32('0xc0fe', 1);。

注記

expr の値が Decimal32 の範囲 (-1*10^(9 - S), 1*10^(9 - S)) を超えるとオーバーフローが発生する可能性があります。小数部の桁数が多すぎる場合、余分な桁は切り捨てられます（丸めは行われません）。整数部の桁数が多すぎる場合は例外がスローされます。

注意

変換では余分な桁が切り捨てられ、Float32/Float64 の入力に対しては浮動小数点命令を用いて演算が行われるため、想定外の動作になる場合があります。例えば、toDecimal32(1.15, 2) は 1.14 と等しくなります。これは浮動小数点において 1.15 * 100 が 114.99 になるためです。演算で内部的に整数型を使用させるには、文字列入力を使用できます: toDecimal32('1.15', 2) = 1.15

構文

toDecimal32(expr, S)

引数

expr — 数値または数値を表す文字列表現を返す式。Expression
S — 0〜9 のスケールパラメータ。数値の小数部の桁数の上限を指定します。UInt8

戻り値

Decimal(9, S) 型の値を返します。Decimal32(S)

例

使用例

SELECT
    toDecimal32(2, 1) AS a, toTypeName(a) AS type_a,
    toDecimal32(4.2, 2) AS b, toTypeName(b) AS type_b,
    toDecimal32('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      2
type_a: Decimal(9, 1)
b:      4.2
type_b: Decimal(9, 2)
c:      4.2
type_c: Decimal(9, 3)

toDecimal32OrDefault

導入バージョン: v21.11

toDecimal32 と同様に、この関数は入力値を型 Decimal(9, S) の値に変換しますが、エラー発生時にはデフォルト値を返します。

構文

toDecimal32OrDefault(expr, S[, default])

引数

expr — 数値の文字列表現。String
S — 0 から 9 の間のスケールパラメーター。数値の小数部が取りうる桁数を指定します。UInt8
default — オプション。Decimal32(S) 型への変換に失敗した場合に返されるデフォルト値。Decimal32(S)

返される値

成功した場合は Decimal(9, S) 型の値。失敗した場合は、指定されていればデフォルト値を、指定されていなければ 0 を返します。Decimal32(S)

例

変換の成功例

SELECT toDecimal32OrDefault(toString(0.0001), 5)

0.0001

変換に失敗した場合

SELECT toDecimal32OrDefault('Inf', 0, CAST('-1', 'Decimal32(0)'))

-1

toDecimal32OrNull

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

入力値を Decimal(9, S) 型の値に変換しますが、エラー時には NULL を返します。変換エラー時に例外をスローする代わりに NULL を返す点を除き、toDecimal32 と同様です。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされない引数（NULL を返す）:

Float* 型のうち、値 NaN および Inf（大文字小文字は区別しない）、またはそれらの文字列表現。
2 進数および 16 進数値の文字列表現。
Decimal32 の範囲を超える値：(-1*10^(9 - S), 1*10^(9 - S))。

関連項目:

toDecimal32。
toDecimal32OrZero。
toDecimal32OrDefault。

構文

toDecimal32OrNull(expr, S)

引数

expr — 数値、または数値を表す文字列を返す式。Expression
S — 0 から 9 の間のスケールパラメータ。数値の小数部分に許容される桁数を指定します。UInt8

戻り値

成功した場合は Decimal(9, S) 型の値を返し、そうでない場合は NULL を返します。Decimal32(S) または NULL

例

使用例

SELECT toDecimal32OrNull('42.7', 2), toDecimal32OrNull('invalid', 2)

┌─toDecimal32OrNull('42.7', 2)─┬─toDecimal32OrNull('invalid', 2)─┐
│                        42.70 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

toDecimal32OrZero

導入バージョン: v20.1

入力値を Decimal(9, S) 型の値に変換し、エラーが発生した場合は 0 を返します。 toDecimal32 と同様ですが、変換エラー時に例外をスローする代わりに 0 を返します。

サポートされる引数:

型が (U)Int* の値またはその文字列表現。
型が Float* の値またはその文字列表現。

サポートされない引数（0 を返す）:

Float* 値 NaN および Inf（大文字小文字を区別しない）の値または文字列表現。
2 進数および 16 進数値の文字列表現。

注記

入力値が Decimal32 の範囲 (-1*10^(9 - S), 1*10^(9 - S)) を超える場合、この関数は 0 を返します。

構文

toDecimal32OrZero(expr, S)

引数

expr — 数値、または数値を表す文字列を返す式。Expression
S — 0〜9 の範囲のスケールパラメータ。数値の小数部に含めることができる桁数を指定します。UInt8

返される値

成功した場合は Decimal(9, S) の値、それ以外の場合は 0 を返します。Decimal32(S)

例

使用例

SELECT toDecimal32OrZero('42.7', 2), toDecimal32OrZero('invalid', 2)

┌─toDecimal32OrZero('42.7', 2)─┬─toDecimal32OrZero('invalid', 2)─┐
│                        42.70 │                            0.00 │
└──────────────────────────────┴─────────────────────────────────┘

toDecimal64

導入バージョン: v18.12

入力値をスケール S を持つ型 Decimal(18, S) の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされない引数:

型 Float* の NaN および Inf（大文字・小文字は区別しない）、またはそれらの文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toDecimal64('0xc0fe', 1);）。

注記

expr の値が Decimal64 の範囲 (-1*10^(18 - S), 1*10^(18 - S)) を超えるとオーバーフローが発生する可能性があります。小数部分の桁数が多すぎる場合は、余分な桁は切り捨てられます（四捨五入はされません）。整数部分の桁数が多すぎる場合は、例外が発生します。

注意

変換では余分な桁が切り捨てられ、Float32/Float64 の入力に対しては、処理が浮動小数点命令で実行されるため、予期しない動作をする可能性があります。たとえば、toDecimal64(1.15, 2) は、浮動小数点演算では 1.15 * 100 が 114.99 となるため、1.14 に等しくなります。内部の整数型を用いて処理させるには、String 型の入力を使用できます: toDecimal64('1.15', 2) = 1.15

構文

toDecimal64(expr, S)

引数

expr — 数値、または数値の文字列表現を返す式。Expression
S — 0 以上 18 以下のスケールパラメータ。数値の小数部が取り得る最大桁数を指定します。UInt8

戻り値

Decimal 値を返します。Decimal(18, S)

例

使用例

SELECT
    toDecimal64(2, 1) AS a, toTypeName(a) AS type_a,
    toDecimal64(4.2, 2) AS b, toTypeName(b) AS type_b,
    toDecimal64('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      2.0
type_a: Decimal(18, 1)
b:      4.20
type_b: Decimal(18, 2)
c:      4.200
type_c: Decimal(18, 3)

toDecimal64OrDefault

導入バージョン: v21.11

toDecimal64 と同様に、この関数は入力値を Decimal(18, S) 型の値に変換しますが、エラーが発生した場合にはデフォルト値を返します。

構文

toDecimal64OrDefault(expr, S[, default])

引数

expr — 数値の文字列表現。String
S — 0 から 18 の間のスケールパラメーター。数値の小数部に許容される桁数を指定します。UInt8
default — オプション。Decimal64(S) 型への変換に失敗した場合に返すデフォルト値。Decimal64(S)

返される値

成功した場合は Decimal(18, S) 型の値を返し、失敗した場合はデフォルト値が指定されていればその値、指定されていなければ 0 を返します。Decimal64(S)

例

変換の成功例

SELECT toDecimal64OrDefault(toString(0.0001), 18)

0.0001

変換に失敗

SELECT toDecimal64OrDefault('Inf', 0, CAST('-1', 'Decimal64(0)'))

-1

toDecimal64OrNull

導入バージョン: v20.1

入力値を Decimal(18, S) 型の値に変換しますが、エラーが発生した場合は NULL を返します。 toDecimal64 と同様ですが、変換エラー時に例外をスローする代わりに NULL を返します。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされない引数（NULL を返す）:

Float* 値 NaN および Inf の文字列表現（大文字小文字を区別しない）。
2 進数および 16 進数値の文字列表現。
Decimal64 の範囲 (-1*10^(18 - S), 1*10^(18 - S)) を超える値。

関連項目:

toDecimal64。
toDecimal64OrZero。
toDecimal64OrDefault。

構文

toDecimal64OrNull(expr, S)

引数

expr — 数値、または数値を表す文字列を返す式。Expression
S — 0 から 18 の間のスケールパラメータで、数値の小数部に許容される桁数を指定します。UInt8

戻り値

成功した場合は Decimal(18, S) 型の値を返し、そうでない場合は NULL を返します。Decimal64(S) または NULL

例

使用例

SELECT toDecimal64OrNull('42.7', 2), toDecimal64OrNull('invalid', 2)

┌─toDecimal64OrNull('42.7', 2)─┬─toDecimal64OrNull('invalid', 2)─┐
│                        42.70 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

toDecimal64OrZero

導入バージョン: v20.1

入力値を型 Decimal(18, S) の値に変換しますが、エラーが発生した場合は 0 を返します。 toDecimal64 と同様ですが、変換エラー時に例外をスローする代わりに 0 を返します。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値、またはその文字列表現。

サポートされない引数（0 を返す）:

Float* 値 NaN および Inf の文字列表現（大文字小文字を区別しない）。
2 進数および 16 進数値の文字列表現。

注記

入力値が Decimal64 の範囲 (-1*10^(18 - S), 1*10^(18 - S)) を超える場合、この関数は 0 を返します。

関連項目:

toDecimal64。
toDecimal64OrNull。
toDecimal64OrDefault。

構文

toDecimal64OrZero(expr, S)

引数

expr — 数値、または数値を表す文字列を返す式。Expression
S — 0 から 18 までのスケールパラメータで、数値の小数部に許容される桁数を指定します。UInt8

戻り値

成功した場合は Decimal(18, S) 型の値を返し、失敗した場合は 0 を返します。Decimal64(S)

例

使用例

SELECT toDecimal64OrZero('42.7', 2), toDecimal64OrZero('invalid', 2)

┌─toDecimal64OrZero('42.7', 2)─┬─toDecimal64OrZero('invalid', 2)─┐
│                        42.70 │                            0.00 │
└──────────────────────────────┴─────────────────────────────────┘

toDecimalString

導入バージョン: v23.3

数値を、指定した小数桁数を持つ String 型の文字列に変換します。

この関数は、入力値を指定された小数点以下の桁数に丸めます。入力値の小数桁数が指定より少ない場合、結果は 0 で埋められ、指定された小数桁数ちょうどになるように調整されます。

構文

toDecimalString(number, scale)

引数

number — 文字列に変換する数値。任意の数値型 (Int, UInt, Float, Decimal) を指定できます。Int8、Int16、Int32、Int64、UInt8、UInt16、UInt32、UInt64、Float32、Float64、Decimal のいずれか。
scale — 小数部に表示する桁数。必要に応じて結果は丸められます。UInt8

戻り値

指定した小数桁数ちょうどで数値を表現した文字列を返します。String

使用例

数値を丸めてフォーマットする

SELECT toDecimalString(2.1456, 2)

┌─toDecimalString(2.1456, 2)─┐
│ 2.15                       │
└────────────────────────────┘

ゼロ埋め

SELECT toDecimalString(5, 3)

┌─toDecimalString(5, 3)─┐
│ 5.000                 │
└───────────────────────┘

異なる数値型間

SELECT toDecimalString(CAST(123.456 AS Decimal(10,3)), 2) AS decimal_val,
       toDecimalString(CAST(42.7 AS Float32), 4) AS float_val

┌─decimal_val─┬─float_val─┐
│ 123.46      │ 42.7000   │
└─────────────┴───────────┘

toFixedString

導入: v1.1

String 引数を FixedString(N) 型（長さ N の固定長文字列）に変換します。

文字列のバイト数が N 未満の場合は、右側がヌルバイトで埋められます。文字列のバイト数が N を超える場合は、例外がスローされます。

構文

toFixedString(s, N)

引数

s — 変換する文字列。String
N — 変換結果の FixedString の長さ。const UInt*

戻り値

長さ N の FixedString を返します。FixedString(N)

例

使用例

SELECT toFixedString('foo', 8) AS s;

┌─s─────────────┐
│ foo\0\0\0\0\0 │
└───────────────┘

toFloat32

導入バージョン: v1.1

入力値を Float32 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされている引数:

(U)Int* 型の値。
(U)Int8/16/32/128/256 の文字列表現。
NaN および Inf を含む Float* 型の値。
大文字小文字を区別せず、NaN および Inf を含む Float* 型の文字列表現。

サポートされていない引数:

SELECT toFloat32('0xc0fe'); のような、バイナリ値および 16 進値の文字列表現。

関連項目:

toFloat32OrZero。
toFloat32OrNull。
toFloat32OrDefault。

構文

toFloat32(expr)

引数

expr — 数値、または数値を表す文字列を返す式。Expression

返される値

32 ビット浮動小数点数を返します。Float32

例

使用例

SELECT
    toFloat32(42.7),
    toFloat32('42.7'),
    toFloat32('NaN')
FORMAT Vertical

Row 1:
──────
toFloat32(42.7):   42.7
toFloat32('42.7'): 42.7
toFloat32('NaN'):  nan

toFloat32OrDefault

導入バージョン: v21.11

toFloat32 と同様に、この関数は入力値を Float32 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が指定されなかった場合、エラー時には 0 が返されます。

構文

toFloat32OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — 省略可能。解析に失敗した場合に返す既定値。Float32

戻り値

成功した場合は Float32 型の値を返し、失敗した場合は、指定されていれば既定値を、指定されていなければ 0 を返します。Float32

例

変換が成功する例

SELECT toFloat32OrDefault('8', CAST('0', 'Float32'))

変換に失敗

SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))

toFloat32OrNull

導入バージョン: v1.1

入力値を型 Float32 の値に変換しますが、エラーが発生した場合は NULL を返します。 toFloat32 と同様ですが、変換エラー時に例外をスローする代わりに NULL を返します。

サポートされる引数:

型 (U)Int* の値。
(U)Int8/16/32/128/256 の文字列表現。
NaN および Inf を含む、型 Float* の値。
NaN および Inf を含む、Float* の文字列表現（大文字小文字を区別しない）。

サポートされない引数（NULL を返す）:

SELECT toFloat32OrNull('0xc0fe'); のような、2 進数および 16 進数値の文字列表現。
無効な文字列形式。

関連項目:

toFloat32。
toFloat32OrZero。
toFloat32OrDefault。

構文

toFloat32OrNull(x)

引数

x — 数値の文字列表現。String

戻り値

成功すると 32 ビットの Float 値を返し、それ以外の場合は NULL を返します。Float32 または NULL

例

使用例

SELECT
    toFloat32OrNull('42.7'),
    toFloat32OrNull('NaN'),
    toFloat32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'):  nan
toFloat32OrNull('abc'):  \N

toFloat32OrZero

導入バージョン: v1.1

入力値を Float32 型の値に変換しますが、エラー時には 0 を返します。 toFloat32 と同様ですが、変換エラー時に例外をスローする代わりに 0 を返します。

関連項目:

toFloat32。
toFloat32OrNull。
toFloat32OrDefault。

構文

toFloat32OrZero(x)

引数

x — 数値を表す文字列。String

返される値

変換に成功した場合は 32 ビットの Float 値を返し、失敗した場合は 0 を返します。Float32

例

使用例

SELECT
    toFloat32OrZero('42.7'),
    toFloat32OrZero('abc')
FORMAT Vertical

Row 1:
──────
toFloat32OrZero('42.7'): 42.7
toFloat32OrZero('abc'):  0

toFloat64

導入バージョン: v1.1

入力値を Float64 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

(U)Int* 型の値。
(U)Int8/16/32/128/256 の文字列表現。
NaN および Inf を含む Float* 型の値。
Float* 型の文字列表現（NaN および Inf を含み、これらは大文字小文字を区別しない）。

サポートされない引数:

たとえば SELECT toFloat64('0xc0fe'); のような、2 進数値および 16 進数値の文字列表現。

関連項目:

toFloat64OrZero。
toFloat64OrNull。
toFloat64OrDefault。

構文

toFloat64(expr)

引数

expr — 数値または数値の文字列表現を返す式。Expression

戻り値

64 ビットの浮動小数点数を返します。Float64

例

使用例

SELECT
    toFloat64(42.7),
    toFloat64('42.7'),
    toFloat64('NaN')
FORMAT Vertical

Row 1:
──────
toFloat64(42.7):   42.7
toFloat64('42.7'): 42.7
toFloat64('NaN'):  nan

toFloat64OrDefault

導入: v21.11

toFloat64 と同様に、この関数は入力値を Float64 型の値に変換しますが、エラーが発生した場合にはデフォルト値を返します。 default 値が指定されていない場合、エラー時には 0 が返されます。

構文

toFloat64OrDefault(expr[, default])

引数

expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
default — 省略可能。変換に失敗した場合に返されるデフォルト値。Float64

返される値

成功した場合は Float64 型の値を返し、失敗した場合は default が指定されていればその値を、指定されていなければ 0 を返します。Float64

例

変換が成功する例

SELECT toFloat64OrDefault('8', CAST('0', 'Float64'))

変換失敗

SELECT toFloat64OrDefault('abc', CAST('0', 'Float64'))

toFloat64OrNull

導入バージョン: v1.1

入力値を Float64 型の値に変換しますが、エラーが発生した場合は NULL を返します。 toFloat64 と同様ですが、変換エラー時に例外をスローする代わりに NULL を返します。

サポートされる引数:

(U)Int* 型の値。
(U)Int8/16/32/128/256 の文字列表現。
NaN および Inf を含む Float* 型の値。
NaN および Inf を含む Float* 型の文字列表現（大文字小文字を区別しない）。

サポートされない引数（NULL を返す）:

SELECT toFloat64OrNull('0xc0fe'); のようなバイナリおよび 16 進数の文字列表現。
不正な文字列形式。

関連項目:

toFloat64。
toFloat64OrZero。
toFloat64OrDefault。

構文

toFloat64OrNull(x)

引数

x — 数値を表す文字列。String

戻り値

成功した場合は 64 ビットの Float 値を返し、失敗した場合は NULL を返します。Float64 または NULL

例

使用例

SELECT
    toFloat64OrNull('42.7'),
    toFloat64OrNull('NaN'),
    toFloat64OrNull('abc')
FORMAT Vertical

Row 1:
──────
toFloat64OrNull('42.7'): 42.7
toFloat64OrNull('NaN'):  nan
toFloat64OrNull('abc'):  \N

toFloat64OrZero

導入バージョン: v1.1

入力値を Float64 型に変換しますが、エラーが発生した場合は 0 を返します。 toFloat64 と同様ですが、変換エラー時に例外をスローする代わりに 0 を返します。

関連項目:

toFloat64。
toFloat64OrNull。
toFloat64OrDefault。

構文

toFloat64OrZero(x)

引数

x — 数値の文字列表現。String

戻り値

成功した場合は 64ビットの Float 値を返し、失敗した場合は 0 を返します。Float64

例

使用例

SELECT
    toFloat64OrZero('42.7'),
    toFloat64OrZero('abc')
FORMAT Vertical

Row 1:
──────
toFloat64OrZero('42.7'): 42.7
toFloat64OrZero('abc'):  0

toInt128

導入バージョン：v1.1

入力値を Int128 型の値に変換します。エラーが発生した場合は例外をスローします。この関数はゼロ方向への丸めを行い、数値の小数部を切り捨てます。

サポートされる引数:

型が (U)Int* の値、またはその文字列表現。
型が Float* の値。

サポートされない引数:

NaN や Inf を含む、型が Float* の値の文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toInt128('0xc0fe');）。

注記

入力値が Int128 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toInt128OrZero。
toInt128OrNull。
toInt128OrDefault。

構文

toInt128(expr)

引数

expr — 数値または数値を表す文字列表現を返す式。Expression

戻り値

128 ビット整数値を返します。Int128

例

使用例

SELECT
    toInt128(-128),
    toInt128(-128.8),
    toInt128('-128')
FORMAT Vertical

Row 1:
──────
toInt128(-128):   -128
toInt128(-128.8): -128
toInt128('-128'): -128

toInt128OrDefault

導入バージョン: v21.11

toInt128 と同様に、この関数は入力値を型 Int128 の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が渡されない場合は、エラー時に 0 が返されます。

構文

toInt128OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — 省略可能。パースに失敗した場合に返されるデフォルト値。Int128

戻り値

成功した場合は Int128 型の値を返し、失敗した場合は default が指定されていればその値を、指定されていなければ 0 を返します。Int128

例

変換が成功する例

SELECT toInt128OrDefault('-128', CAST('-1', 'Int128'))

-128

変換に失敗

SELECT toInt128OrDefault('abc', CAST('-1', 'Int128'))

-1

toInt128OrNull

導入バージョン: v20.8

toInt128 と同様に、この関数は入力値を型 Int128 の値に変換しますが、エラー発生時には NULL を返します。

サポートされる引数:

(U)Int* 型の文字列表現。

サポートされない引数（NULL を返す）:

NaN および Inf を含む、Float* 型の値の文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toInt128OrNull('0xc0fe');）。

注記

入力値が Int128 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローを起こします。これはエラーとはみなされません。

関連項目:

toInt128。
toInt128OrZero。
toInt128OrDefault。

構文

toInt128OrNull(x)

引数

x — 数値の文字列表現。String

戻り値

変換が成功した場合は Int128 型の値を返し、失敗した場合は NULL を返します。Int128 または NULL

例

使用例

SELECT
    toInt128OrNull('-128'),
    toInt128OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt128OrNull('-128'): -128
toInt128OrNull('abc'):  \N

toInt128OrZero

導入バージョン: v20.8

入力値を型 Int128 に変換しますが、エラーが発生した場合は 0 を返します。 toInt128 と同様ですが、例外をスローする代わりに 0 を返します。

関連項目:

toInt128。
toInt128OrNull。
toInt128OrDefault。

構文

toInt128OrZero(x)

引数

x — 変換対象の入力値。String または FixedString または Float* または Decimal または (U)Int* または Date または DateTime

戻り値

変換に成功した場合は変換後の入力値を、変換に失敗した場合は 0 を返します。戻り値の型は Int128 です。

例

使用例

SELECT toInt128OrZero('123')

変換に失敗した場合は 0 を返します

SELECT toInt128OrZero('abc')

toInt16

導入バージョン: v1.1

入力値をInt16 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値。

サポートされない引数:

NaN や Inf を含む、Float* 値の文字列表現。
2進数および16進数値の文字列表現。例: SELECT toInt16('0xc0fe');。

注記

入力値が Int16 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとはみなされません。例: SELECT toInt16(32768) == -32768;。

注記

この関数はゼロ方向への丸めを行い、小数部を切り捨てます。

関連項目:

toInt16OrZero。
toInt16OrNull。
toInt16OrDefault。

構文

toInt16(expr)

引数

expr — 数値または数値を表す文字列を返す式。Expression

戻り値

16 ビットの整数値を返します。Int16

例

使用例

SELECT
    toInt16(-16),
    toInt16(-16.16),
    toInt16('-16')
FORMAT Vertical

Row 1:
──────
toInt16(-16):    -16
toInt16(-16.16): -16
toInt16('-16'):  -16

toInt16OrDefault

導入バージョン: v21.11

toInt16 と同様に、この関数は入力値を Int16 型の値に変換しますが、エラーが発生した場合にはデフォルト値を返します。 default 値が渡されない場合、エラー時には 0 が返されます。

構文

toInt16OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — オプション。パースに失敗した場合に返す既定値。Int16

返り値

成功した場合は型 Int16 の値を返し、失敗した場合は指定されていれば既定値を、指定されていなければ 0 を返します。Int16

使用例

変換の成功例

SELECT toInt16OrDefault('-16', CAST('-1', 'Int16'))

-16

変換に失敗

SELECT toInt16OrDefault('abc', CAST('-1', 'Int16'))

-1

toInt16OrNull

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

toInt16 と同様に、この関数は入力値を Int16 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む Float* 値の文字列表現。
SELECT toInt16OrNull('0xc0fe'); のような、2進数および16進数値の文字列表現。

注記

入力値が Int16 の表現可能範囲外の場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toInt16。
toInt16OrZero。
toInt16OrDefault。

構文

toInt16OrNull(x)

引数

x — 数値を表す文字列。String

戻り値

変換が成功した場合は型 Int16 の値を返し、失敗した場合は NULL を返します。Int16 または NULL

例

使用例

SELECT
    toInt16OrNull('-16'),
    toInt16OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt16OrNull('-16'): -16
toInt16OrNull('abc'): \N

toInt16OrZero

導入バージョン: v1.1

toInt16 と同様に、この関数は入力値を型 Int16 の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

(U)Int* 型の値を表す文字列。

サポートされない引数（0 を返す）:

NaN や Inf を含む Float* 値を表す文字列。
2 進数および 16 進数値を表す文字列（例: SELECT toInt16OrZero('0xc0fe');）。

注記

入力値が Int16 の範囲内で表現できない場合、結果でオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toInt16。
toInt16OrNull。
toInt16OrDefault。

構文

toInt16OrZero(x)

引数

x — 数値を表す文字列。String

戻り値

Int16 型の値を返します。変換に失敗した場合は 0 を返します。Int16

例

使用例

SELECT
    toInt16OrZero('16'),
    toInt16OrZero('abc')
FORMAT Vertical

Row 1:
──────
toInt16OrZero('16'): 16
toInt16OrZero('abc'): 0

toInt256

導入バージョン: v1.1

入力値を型 Int256 の値に変換します。エラーが発生した場合は例外をスローします。この関数は 0 に向かう丸めを行い、数値の小数部分を切り捨てます。

サポートされる引数:

型 (U)Int* の値またはその文字列表現。
型 Float* の値。

サポートされない引数:

NaN や Inf を含む、Float* 値の文字列表現。
例えば SELECT toInt256('0xc0fe'); のような、2 進および 16 進数値の文字列表現。

注記

入力値が Int256 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toInt256OrZero。
toInt256OrNull。
toInt256OrDefault。

構文

toInt256(expr)

引数

expr — 数値、または数値の文字列表現を返す式。 Expression

戻り値

256ビット整数値を返します。 Int256

例

使用例

SELECT
    toInt256(-256),
    toInt256(-256.256),
    toInt256('-256')
FORMAT Vertical

Row 1:
──────
toInt256(-256):     -256
toInt256(-256.256): -256
toInt256('-256'):   -256

toInt256OrDefault

導入: v21.11

toInt256 と同様に、この関数は入力値を Int256 型の値に変換しますが、エラーが発生した場合にはデフォルト値を返します。 default 引数が指定されなかった場合は、エラー時に 0 が返されます。

構文

toInt256OrDefault(expr[, default])

引数

expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
default — 省略可能。パースに失敗した場合に返されるデフォルト値。Int256

返される値

成功した場合は Int256 型の値を返し、失敗した場合は、指定されていればデフォルト値を返し、指定されていなければ 0 を返します。Int256

例

成功する変換の例

SELECT toInt256OrDefault('-256', CAST('-1', 'Int256'))

-256

変換に失敗

SELECT toInt256OrDefault('abc', CAST('-1', 'Int256'))

-1

toInt256OrNull

導入バージョン: v20.8

toInt256 と同様に、この関数は入力値を Int256 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む Float* 値の文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toInt256OrNull('0xc0fe');）。

注記

入力値が Int256 の範囲内で表現できない場合、結果でオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toInt256。
toInt256OrZero。
toInt256OrDefault。

構文

toInt256OrNull(x)

引数

x — 数値を表す文字列。String

戻り値

型 Int256 の値を返します。変換に失敗した場合は NULL を返します。Int256 または NULL

例

使用例

SELECT
    toInt256OrNull('-256'),
    toInt256OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt256OrNull('-256'): -256
toInt256OrNull('abc'):  \N

toInt256OrZero

導入バージョン: v20.8

入力値を Int256 型に変換しますが、エラーが発生した場合は 0 を返します。 toInt256 と同様ですが、例外をスローする代わりに 0 を返します。

関連項目:

toInt256。
toInt256OrNull。
toInt256OrDefault。

構文

toInt256OrZero(x)

引数

x — 変換する入力値。String、FixedString、Float*、Decimal、(U)Int*、Date、DateTime のいずれか。

返り値

変換された入力値を返します。変換に失敗した場合は 0 を返します。戻り値の型は Int256 です。

例

使用例

SELECT toInt256OrZero('123')

変換に失敗した場合は 0 を返す

SELECT toInt256OrZero('abc')

toInt32

導入バージョン: v1.1

入力値を Int32 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

(U)Int* 型の値、またはその文字列表現。
Float* 型の値。

サポートされない引数:

NaN や Inf を含む、Float* 値の文字列表現。
SELECT toInt32('0xc0fe'); のような、バイナリおよび 16 進数値の文字列表現。

注記

入力値が Int32 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。例: SELECT toInt32(2147483648) == -2147483648;

注記

この関数は rounding towards zero（ゼロ方向への丸め）を使用し、数値の小数部分を切り捨てます。

関連項目:

toInt32OrZero
toInt32OrNull
toInt32OrDefault

構文

toInt32(expr)

引数

expr — 数値、または数値を表す文字列を返す式。Expression

戻り値

32ビット符号付き整数値を返します。Int32

例

使用例

SELECT
    toInt32(-32),
    toInt32(-32.32),
    toInt32('-32')
FORMAT Vertical

Row 1:
──────
toInt32(-32):    -32
toInt32(-32.32): -32
toInt32('-32'):  -32

toInt32OrDefault

導入バージョン: v21.11

toInt32 と同様に、この関数は入力値を Int32 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が指定されていない場合は、エラー時に 0 が返されます。

構文

toInt32OrDefault(expr[, default])

引数

expr — 数値または数値を表す文字列を返す式。String または (U)Int* または Float*
default — オプション。パースに失敗した場合に返される既定値。Int32

返される値

成功した場合は Int32 型の値を返し、それ以外の場合は指定されていれば既定値を、指定されていない場合は 0 を返します。Int32

例

成功した変換の例

SELECT toInt32OrDefault('-32', CAST('-1', 'Int32'))

-32

変換に失敗

SELECT toInt32OrDefault('abc', CAST('-1', 'Int32'))

-1

toInt32OrNull

導入バージョン: v1.1

toInt32 と同様に、この関数は入力値を Int32 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む Float* 値の文字列表現。
SELECT toInt32OrNull('0xc0fe'); のような、2 進数および 16 進数の文字列表現。

注記

入力値が Int32 の範囲内で表現できない場合、結果にオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toInt32。
toInt32OrZero。
toInt32OrDefault。

構文

toInt32OrNull(x)

引数

x — 数値を表す文字列。String

戻り値

変換に成功した場合は Int32 型の値を返し、失敗した場合は NULL を返します。Int32 または NULL

例

使用例

SELECT
    toInt32OrNull('-32'),
    toInt32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt32OrNull('-32'): -32
toInt32OrNull('abc'): \N

toInt32OrZero

導入バージョン: v1.1

toInt32 と同様に、この関数は入力値を Int32 型の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされている引数:

(U)Int* の文字列表現。

サポートされていない引数（0 を返す）:

NaN や Inf を含む、Float* 値の文字列表現。
SELECT toInt32OrZero('0xc0fe'); のような、2進数および16進数値の文字列表現。

注記

入力値が Int32 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toInt32。
toInt32OrNull。
toInt32OrDefault。

構文

toInt32OrZero(x)

引数

x — 数値を表す文字列。String

返される値

変換に成功した場合は型 Int32 の値を返し、失敗した場合は 0 を返します。Int32

例

使用例

SELECT
    toInt32OrZero('32'),
    toInt32OrZero('abc')
FORMAT Vertical

Row 1:
──────
toInt32OrZero('32'): 32
toInt32OrZero('abc'): 0

toInt64

導入バージョン: v1.1

入力値を Int64 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

(U)Int* 型の値またはその文字列表現
Float* 型の値

サポートされない引数:

NaN や Inf を含む、Float* 値の文字列表現
SELECT toInt64('0xc0fe'); のような、2 進数および 16 進数値の文字列表現

注記

入力値が Int64 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローした値になります。これはエラーとは見なされません。例えば、SELECT toInt64(9223372036854775808) == -9223372036854775808;

注記

この関数は rounding towards zero による丸めを行います。これは数値の小数部分を切り捨てることを意味します。

関連項目:

toInt64OrZero
toInt64OrNull
toInt64OrDefault

構文

toInt64(expr)

引数

expr — 数値、または数値の文字列表現を返す式。サポート対象: 型 (U)Int* の値またはその文字列表現、型 Float* の値。サポート外: NaN および Inf を含む Float* 値の文字列表現、2 進数および 16 進数値の文字列表現。Expression

戻り値

64 ビット整数値を返します。Int64

例

使用例

SELECT
    toInt64(-64),
    toInt64(-64.64),
    toInt64('-64')
FORMAT Vertical

Row 1:
──────
toInt64(-64):    -64
toInt64(-64.64): -64
toInt64('-64'):  -64

toInt64OrDefault

導入バージョン: v21.11

toInt64 と同様に、この関数は入力値を型 Int64 の値に変換しますが、エラーが発生した場合にはデフォルト値を返します。 default 引数が指定されていない場合は、エラー時に 0 が返されます。

構文

toInt64OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — 省略可能。解析に失敗した場合に返すデフォルト値。Int64

戻り値

変換に成功した場合は Int64 型の値を返し、失敗した場合は指定されていればデフォルト値を、指定されていなければ 0 を返します。Int64

例

変換が成功する例

SELECT toInt64OrDefault('-64', CAST('-1', 'Int64'))

-64

変換失敗

SELECT toInt64OrDefault('abc', CAST('-1', 'Int64'))

-1

toInt64OrNull

導入バージョン: v1.1

toInt64 と同様に、この関数は入力値を Int64 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int* 型の値の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む Float* 型の値の文字列表現。
2進数および16進数値の文字列表現（例: SELECT toInt64OrNull('0xc0fe');）。

注記

入力値が Int64 の範囲で表現できない場合、結果にオーバーフローまたはアンダーフローが発生します。これはエラーとはみなされません。

関連項目:

toInt64。
toInt64OrZero。
toInt64OrDefault。

構文

toInt64OrNull(x)

引数

x — 数値を表す文字列。String

返される値

変換が成功した場合は型 Int64 の値を返し、失敗した場合は NULL を返します。Int64 または NULL

例

使用例

SELECT
    toInt64OrNull('-64'),
    toInt64OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): \N

toInt64OrZero

導入バージョン: v1.1

入力値を型 Int64 に変換しますが、エラーが発生した場合は 0 を返します。 toInt64 と同様ですが、例外をスローする代わりに 0 を返します。

関連項目:

toInt64
toInt64OrNull
toInt64OrDefault

構文

toInt64OrZero(x)

引数

x — 変換対象の入力値。String または FixedString または Float* または Decimal または (U)Int* または Date または DateTime

返される値

変換された入力値を返します。変換に失敗した場合は 0 を返します。戻り値の型は Int64 です。

例

使用例

SELECT toInt64OrZero('123')

失敗した変換は 0 を返す

SELECT toInt64OrZero('abc')

toInt8

導入バージョン: v1.1

入力値を Int8 型の値に変換します。エラーが発生した場合は例外を送出します。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値。

サポートされない引数:

NaN や Inf を含む、Float* 値の文字列表現。
SELECT toInt8('0xc0fe'); のような、2 進数および 16 進数値の文字列表現。

注記

入力値が Int8 の範囲で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは扱われません。例: SELECT toInt8(128) == -128;。

注記

この関数はゼロ方向への丸めを使用します。つまり、小数部分の桁を切り捨てます。

関連項目:

toInt8OrZero。
toInt8OrNull。
toInt8OrDefault。

構文

toInt8(expr)

引数

expr — 数値、または数値を表す文字列を返す式。Expression

戻り値

8 ビット符号付き整数値を返します。Int8

例

使用例

SELECT
    toInt8(-8),
    toInt8(-8.8),
    toInt8('-8')
FORMAT Vertical

Row 1:
──────
toInt8(-8):   -8
toInt8(-8.8): -8
toInt8('-8'): -8

toInt8OrDefault

導入バージョン: v21.11

toInt8 と同様に、この関数は入力値を Int8 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が指定されない場合、エラー時には 0 が返されます。

構文

toInt8OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — 省略可。解析に失敗した場合に返すデフォルト値。Int8

戻り値

成功した場合は型 Int8 の値を返し、失敗した場合は指定されていればデフォルト値を、指定されていなければ 0 を返します。Int8

例

変換が成功する例

SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))

-8

変換に失敗した場合

SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))

-1

toInt8OrNull

導入バージョン: v1.1

toInt8 と同様に、この関数は入力値を型 Int8 の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（NULL を返す）:

NaN および Inf を含む Float* 値の文字列表現。
2進数および16進数値の文字列表現（例: SELECT toInt8OrNull('0xc0fe');）。

注記

入力値が Int8 の範囲内で表現できない場合、結果にオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toInt8。
toInt8OrZero。
toInt8OrDefault。

構文

toInt8OrNull(x)

引数

x — 数値の文字列表現。String

戻り値

変換に成功した場合は Int8 型の値、失敗した場合は NULL を返します。Int8 または NULL

例

使用例

SELECT
    toInt8OrNull('-8'),
    toInt8OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt8OrNull('-8'):  -8
toInt8OrNull('abc'): \N

toInt8OrZero

導入バージョン: v1.1

toInt8 と同様に、この関数は入力値を Int8 型の値に変換しますが、エラーが発生した場合には 0 を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（0 を返す）:

NaN や Inf を含む Float* 値の文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toInt8OrZero('0xc0fe');）。

注記

入力値が Int8 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toInt8。
toInt8OrNull。
toInt8OrDefault。

構文

toInt8OrZero(x)

引数

x — 数値を表す文字列。String

戻り値

Int8 型の値を返します。変換に失敗した場合は 0 を返します。Int8

例

使用例

SELECT
    toInt8OrZero('8'),
    toInt8OrZero('abc')
FORMAT Vertical

Row 1:
──────
toInt8OrZero('8'): 8
toInt8OrZero('abc'): 0

toInterval

導入バージョン: v25.4

数値と単位文字列から Interval 値を作成します。

この関数は、単位を文字列引数として指定することで、1つの関数で異なる種類（秒、分、時間、日、週、月、四半期、年）の Interval 値を作成するための統一的な方法を提供します。単位文字列の大文字・小文字は区別されません。

これは toIntervalSecond、toIntervalMinute、toIntervalDay などの型固有の関数を呼び出すのと同等ですが、単位を文字列パラメータとして動的に指定できます。

構文

toInterval(value, unit)

引数

value — 単位数を表す数値。任意の数値型を指定できます。Int8 または Int16 または Int32 または Int64 または UInt8 または UInt16 または UInt32 または UInt64 または Float32 または Float64
unit — 時間の単位。定数文字列である必要があります。有効な値: 'nanosecond', 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'month', 'quarter', 'year'. String

戻り値

指定された型の Interval 値を返します。結果の型は unit の値に応じて、IntervalNanosecond, IntervalMicrosecond, IntervalMillisecond, IntervalSecond, IntervalMinute, IntervalHour, IntervalDay, IntervalWeek, IntervalMonth, IntervalQuarter, IntervalYear のいずれかになります。Interval

使用例

異なる単位の Interval を作成する

SELECT
    toInterval(5, 'second') AS seconds,
    toInterval(3, 'day') AS days,
    toInterval(2, 'month') AS months

┌─seconds─┬─days─┬─months─┐
│ 5       │ 3    │ 2      │
└─────────┴──────┴────────┘

日付演算には interval を使用する

SELECT
    now() AS current_time,
    now() + toInterval(1, 'hour') AS one_hour_later,
    now() - toInterval(7, 'day') AS week_ago

┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00  │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘

インターバルの動的生成

SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)

┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘

toIntervalDay

導入バージョン: v1.1

データ型 IntervalDay の、n 日間を表す間隔を返します。

構文

toIntervalDay(n)

引数

n — 日数。整数値またはその文字列表現、ならびに浮動小数点数。型は (U)Int* または Float* または String

戻り値

n 日間の間隔を返します。Interval

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result

┌─────result─┐
│ 2025-06-20 │
└────────────┘

toIntervalHour

導入バージョン: v1.1

IntervalHour データ型の、n 時間を表す間隔値を返します。

構文

toIntervalHour(n)

引数

n — 時間数。整数値、その文字列表現、または浮動小数点数を受け付けます。Int* または UInt* または Float* または String

戻り値

n 時間の Interval を返します。Interval

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result

┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘

toIntervalMicrosecond

導入バージョン: v22.6

データ型 IntervalMicrosecond の n マイクロ秒の時間間隔を返します。

構文

toIntervalMicrosecond(n)

引数

n — マイクロ秒の数。(U)Int* または Float* または String

戻り値

n マイクロ秒の Interval を返します。

例

使用例

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMicrosecond(30) AS interval_to_microseconds
SELECT date + interval_to_microseconds AS result

┌─────────────────────result─┐
│ 2025-06-15 00:00:00.000030 │
└────────────────────────────┘

toIntervalMillisecond

導入バージョン: v22.6

データ型 IntervalMillisecond の、n ミリ秒を表す間隔を返します。

構文

toIntervalMillisecond(n)

引数

n — ミリ秒数。(U)Int* または Float* または String

返される値

n ミリ秒の Interval を返します。Interval

例

使用例

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMillisecond(30) AS interval_to_milliseconds
SELECT date + interval_to_milliseconds AS result

┌──────────────────result─┐
│ 2025-06-15 00:00:00.030 │
└─────────────────────────┘

toIntervalMinute

導入: v1.1

データ型 IntervalMinute の、n 分を表す時間間隔を返します。

構文

toIntervalMinute(n)

引数

n — 分を表す値。整数値またはその文字列表現、もしくは浮動小数点数。(U)Int* または Float* または String

返される値

n 分の Interval を返します。Interval

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalMinute(12) AS interval_to_minutes
SELECT date + interval_to_minutes AS result

┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘

toIntervalMonth

導入バージョン: v1.1

データ型 IntervalMonth の n か月の間隔を表す値を返します。

構文

toIntervalMonth(n)

引数

n — 月数。(U)Int* または Float* または String

返される値

n か月を表す interval を返します。Interval

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result

┌─────result─┐
│ 2025-07-15 │
└────────────┘

toIntervalNanosecond

導入バージョン: v22.6

データ型 IntervalNanosecond の、n ナノ秒の時間間隔を返します。

構文

toIntervalNanosecond(n)

引数

n — ナノ秒の数。(U)Int* または Float* または String

戻り値

n ナノ秒の Interval 型の値を返します。

例

使用例

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result

┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘

toIntervalQuarter

導入バージョン: v1.1

データ型 IntervalQuarter の n 四半期分の間隔を返します。

構文

toIntervalQuarter(n)

引数

n — 四半期の数。(U)Int* または Float* または String

戻り値

n 四半期を表す Interval 型の値を返します。

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result

┌─────result─┐
│ 2025-09-15 │
└────────────┘

toIntervalSecond

導入バージョン: v1.1

データ型 IntervalSecond で表される n 秒の時間間隔を返します。

構文

toIntervalSecond(n)

引数

n — 秒数。整数値またはその文字列表現、および浮動小数点数。(U)Int* または Float* または String

返り値

n 秒の Interval 型の値を返します。

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result

┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘

toIntervalWeek

導入バージョン: v1.1

データ型 IntervalWeek の n 週間を表す間隔値を返します。

構文

toIntervalWeek(n)

引数

n — 週数。(U)Int* または Float* または String

戻り値

n 週間の間隔を表す値を返します。Interval

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result

┌─────result─┐
│ 2025-06-22 │
└────────────┘

toIntervalYear

導入バージョン: v1.1

データ型 IntervalYear の n 年を表す間隔を返します。

構文

toIntervalYear(n)

引数

n — 年数。(U)Int* または Float* または String

返される値

n 年の Interval を返します。Interval

例

使用例

WITH
    toDate('2024-06-15') AS date,
    toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result

┌─────result─┐
│ 2025-06-15 │
└────────────┘

toLowCardinality

導入バージョン: v18.12

入力引数を同じデータ型の LowCardinality 型に変換します。

ヒント

LowCardinality データ型から通常のデータ型に変換するには、CAST 関数を使用します。例: CAST(x AS String)。

構文

toLowCardinality(expr)

引数

expr — サポートされているデータ型のいずれかの値を結果とする式。String または FixedString または Date または DateTime または (U)Int* または Float*

戻り値

入力値を LowCardinality データ型に変換したものを返します。LowCardinality

例

使用例

SELECT toLowCardinality('1')

┌─toLowCardinality('1')─┐
│ 1                     │
└───────────────────────┘

toString

導入バージョン: v1.1

値を文字列表現に変換します。 DateTime 引数に対しては、タイムゾーン名を指定する 2 番目の String 型引数を受け取ることができます。

構文

toString(value[, timezone])

引数

value — 文字列に変換する値。Any
timezone — 省略可能。DateTime 変換用のタイムゾーン名。String

戻り値

入力値の文字列表現を返します。String

例

使用例

SELECT
    now() AS ts,
    time_zone,
    toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam  │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra    │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan  │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens     │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast    │ 2023-09-08 20:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘

toStringCutToZero

導入バージョン: v1.1

String または FixedString を引数として受け取り、最初のヌルバイトで切り詰められた元の文字列のコピーを含む String を返します。

ヌルバイト (\0) は文字列終端として扱われます。この関数は、ヌルバイトが意味のある内容の終端を示す C 形式の文字列やバイナリデータを処理する際に有用です。

構文

toStringCutToZero(s)

引数

s — 処理対象の String または FixedString。String または FixedString

戻り値

最初に現れるヌルバイトより前の文字列を含む String を返します。String

例

使用例

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

toTime

導入バージョン: v1.1

入力値を Time 型に変換します。 String、FixedString、DateTime、または午前0時からの経過秒数を表す数値型からの変換をサポートします。

構文

toTime(x)

引数

x — 変換対象の入力値。String、FixedString、DateTime、(U)Int*、または Float*

戻り値

変換後の値を返します。Time

使用例

String から Time への変換

SELECT toTime('14:30:25')

14:30:25

DateTime から Time への型変換

SELECT toTime(toDateTime('2025-04-15 14:30:25'))

14:30:25

整数から Time 型への変換

SELECT toTime(52225)

14:30:25

toTime64

導入バージョン: v25.6

入力値を Time64 型に変換します。 String、FixedString、DateTime64、または午前0時からの経過マイクロ秒数を表す数値型からの変換をサポートします。時刻値に対してマイクロ秒精度を提供します。

構文

toTime64(x)

引数

x — 変換する入力値。String、FixedString、DateTime64、(U)Int*、または Float* のいずれか。

返り値

入力値をマイクロ秒精度で変換した値を返します。Time64(6)

使用例

String から Time64 への変換

SELECT toTime64('14:30:25.123456')

14:30:25.123456

DateTime64 から Time64 への変換

SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))

14:30:25.123456

整数から Time64 への型変換

SELECT toTime64(52225123456)

14:30:25.123456

toTime64OrNull

導入バージョン: v25.6

入力値を Time64 型の値に変換しますが、エラーが発生した場合には NULL を返します。 toTime64 と同様ですが、変換エラー時に例外をスローする代わりに NULL を返します。

関連項目:

toTime64
toTime64OrZero

構文

toTime64OrNull(x)

引数

x — サブ秒精度の時刻の文字列表現。String

戻り値

成功した場合は Time64 型の値を返し、そうでない場合は NULL を返します。Time64 または NULL

例

使用例

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

toTime64OrZero

導入バージョン: v25.6

入力値を Time64 型の値に変換し、エラーが発生した場合は 00:00:00.000 を返します。 toTime64 と同様ですが、変換エラーが発生した場合でも例外をスローせず、代わりに 00:00:00.000 を返します。

構文

toTime64OrZero(x)

引数

x — サブ秒精度の時刻文字列表現。String

戻り値

成功した場合は Time64 型の値、それ以外の場合は 00:00:00.000 を返します。Time64

例

使用例

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │             00:00:00.000 │
└────────────────────────────────┴──────────────────────────┘

toTimeOrNull

導入バージョン: v1.1

入力値を Time 型に変換しますが、エラーが発生した場合は NULL を返します。 toTime と同様の動作をしますが、変換エラー時に例外をスローする代わりに NULL を返します。

関連項目:

toTime
toTimeOrZero

構文

toTimeOrNull(x)

引数

x — 時刻を表す文字列。String

戻り値

変換に成功した場合は Time 型の値を返し、そうでない場合は NULL を返します。Time または NULL

例

使用例

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

toTimeOrZero

導入バージョン: v1.1

入力値を Time 型の値に変換しますが、エラーが発生した場合は 00:00:00 を返します。 toTime と同様に動作しますが、変換エラー時に例外をスローする代わりに 00:00:00 を返します。

構文

toTimeOrZero(x)

引数

x — 時刻を表す文字列。String

戻り値

成功した場合は Time の値を返し、失敗した場合は 00:00:00 を返します。Time

例

使用例

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

toUInt128

導入バージョン: v1.1

入力値を UInt128 型の値に変換します。エラーが発生した場合は例外をスローします。この関数はゼロ方向への丸めを行い、数値の小数部を切り捨てます。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値。

サポートされない引数:

NaN や Inf を含む、型 Float* の値の文字列表現。
SELECT toUInt128('0xc0fe'); のような、2 進数および 16 進数値の文字列表現。

注記

入力値が UInt128 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toUInt128OrZero。
toUInt128OrNull。
toUInt128OrDefault。

構文

toUInt128(expr)

引数

expr — 数値または数値を表す文字列を返す式。Expression

戻り値

128 ビットの符号なし整数値を返します。UInt128

例

使用例

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

toUInt128OrDefault

導入バージョン: v21.11

toUInt128 と同様に、この関数は入力値を UInt128 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 引数が指定されていない場合は、エラー時に 0 が返されます。

構文

toUInt128OrDefault(expr[, default])

引数

expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
default — 省略可能。解析に失敗した場合に返される既定値。UInt128

戻り値

成功した場合は UInt128 型の値を返し、失敗した場合は、指定されている場合は既定値を返し、指定されていない場合は 0 を返します。UInt128

例

変換が成功する例

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

変換失敗

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

toUInt128OrNull

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

toUInt128 と同様に、この関数は入力値を UInt128 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む Float* 値の文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toUInt128OrNull('0xc0fe');）。

注記

入力値が UInt128 の範囲内で表現できない場合、結果にオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toUInt128。
toUInt128OrZero。
toUInt128OrDefault。

構文

toUInt128OrNull(x)

引数

x — 数値を表す文字列。String

戻り値

変換に成功した場合は UInt128 型の値を返し、失敗した場合は NULL を返します。UInt128 または NULL

例

使用例

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N

toUInt128OrZero

導入バージョン: v1.1

toUInt128 と同様に、この関数は入力値を UInt128 型の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（0 を返す）:

NaN や Inf を含む Float* 値の文字列表現。
SELECT toUInt128OrZero('0xc0fe'); のような、2 進数および 16 進数値の文字列表現。

注記

入力値が UInt128 の表現可能な範囲外の場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toUInt128。
toUInt128OrNull。
toUInt128OrDefault。

構文

toUInt128OrZero(x)

引数

x — 数値の文字列表現。String

返される値

変換に成功した場合は UInt128 型の値を返し、失敗した場合は 0 を返します。UInt128

例

使用例

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

toUInt16

導入バージョン: v1.1

入力値をUInt16型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

型が (U)Int* の値、またはその文字列表現。
型が Float* の値。

サポートされない引数:

NaN や Inf を含む、Float* 値の文字列表現。
2 進数および 16 進数値の文字列表現。例: SELECT toUInt16('0xc0fe');。

注記

入力値がUInt16の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとはみなされません。例: SELECT toUInt16(65536) == 0;。

注記

この関数はゼロ方向への丸めを使用します。これは数値の小数部分を切り捨てることを意味します。

関連項目:

toUInt16OrZero。
toUInt16OrNull。
toUInt16OrDefault。

構文

toUInt16(expr)

引数

expr — 数値、または数値を表す文字列を返す式。Expression

返される値

16 ビット符号なし整数値を返します。UInt16

例

使用例

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Row 1:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

toUInt16OrDefault

導入バージョン: v21.11

toUInt16 と同様に、この関数は入力値を UInt16 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が渡されていない場合、エラーが発生した場合には 0 が返されます。

構文

toUInt16OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — 省略可能。パースに失敗した場合に返されるデフォルト値。UInt16

返される値

成功した場合は型 UInt16 の値を返し、失敗した場合は指定されていればデフォルト値を、指定されていなければ 0 を返します。UInt16

例

変換が成功する例

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

変換失敗時

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

toUInt16OrNull

導入バージョン: v1.1

toUInt16 と同様に、この関数は入力値を UInt16 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む Float* 値の文字列表現。
2 進数および 16 進数値の文字列表現。例: SELECT toUInt16OrNull('0xc0fe');。

注記

入力値が UInt16 の範囲内で表現できない場合、結果がオーバーフローまたはアンダーフローします。これはエラーとはみなされません。

関連項目:

toUInt16。
toUInt16OrZero。
toUInt16OrDefault。

構文

toUInt16OrNull(x)

引数

x — 数値を表す文字列。String

返り値

変換が成功した場合は型 UInt16 の値を返し、失敗した場合は NULL を返します。UInt16 または NULL

例

使用例

SELECT
    toUInt16OrNull('16'),
    toUInt16OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): \N

toUInt16OrZero

導入バージョン: v1.1

toUInt16 と同様に、この関数は入力値を UInt16 型の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

(U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（0 を返す）:

NaN や Inf を含む Float* 値の文字列表現。
バイナリ値や 16 進数値の文字列表現（例: SELECT toUInt16OrZero('0xc0fe');）。

注記

入力値が UInt16 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとはみなされません。

関連項目:

toUInt16。
toUInt16OrNull。
toUInt16OrDefault。

構文

toUInt16OrZero(x)

引数

x — 数値を表す文字列。String

戻り値

UInt16 型の値を返します。変換に失敗した場合は 0 を返します。UInt16

例

使用例

SELECT
    toUInt16OrZero('16'),
    toUInt16OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt16OrZero('16'):  16
toUInt16OrZero('abc'): 0

toUInt256

導入バージョン: v1.1

入力値を UInt256 型の値に変換します。エラーが発生した場合は例外をスローします。この関数は 0 に向かって丸めを行い、小数部を切り捨てます。

サポートされる引数:

型 (U)Int* の値またはその文字列表現。
型 Float* の値。

サポートされない引数:

NaN や Inf を含む、型 Float* の値の文字列表現。
2 進数および 16 進数の値の文字列表現（例: SELECT toUInt256('0xc0fe');）。

注記

入力値が UInt256 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toUInt256OrZero
toUInt256OrNull
toUInt256OrDefault

構文

toUInt256(expr)

引数

expr — 数値、または数値を表す文字列を返す式。 Expression

戻り値

256ビットの符号なし整数値を返します。 UInt256

例

使用例

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Row 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

toUInt256OrDefault

導入バージョン: v21.11

toUInt256 と同様に、この関数は入力値を UInt256 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が指定されていない場合は、エラー時に 0 が返されます。

構文

toUInt256OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — 省略可能。パースに失敗した場合に返されるデフォルト値。UInt256

戻り値

成功した場合は UInt256 型の値を返します。失敗した場合は、指定されていればデフォルト値を、指定されていなければ 0 を返します。UInt256

例

成功した変換

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

変換に失敗

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

toUInt256OrNull

導入バージョン: v20.8

toUInt256 と同様に、この関数は入力値を UInt256 型の値に変換しますが、エラー発生時には NULL を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む Float* 値の文字列表現。
SELECT toUInt256OrNull('0xc0fe'); のような、2 進数および 16 進数の値の文字列表現。

注記

入力値が UInt256 の範囲内で表現できない場合、結果にオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toUInt256。
toUInt256OrZero。
toUInt256OrDefault。

構文

toUInt256OrNull(x)

引数

x — 数値を表す文字列。String

返される値

変換に成功した場合は UInt256 型の値を返し、失敗した場合は NULL を返します。UInt256 または NULL

例

使用例

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): \N

toUInt256OrZero

導入バージョン: v20.8

toUInt256 と同様に、この関数は入力値を UInt256 型の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

(U)Int* の文字列表現。

サポートされない引数（0 を返す）:

NaN や Inf を含む Float* 値の文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toUInt256OrZero('0xc0fe');）。

注記

入力値が UInt256 の範囲で表現できない場合、結果にはオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toUInt256。
toUInt256OrNull。
toUInt256OrDefault。

構文

toUInt256OrZero(x)

引数

x — 数値を表す文字列。String

戻り値

UInt256 型の値を返します。変換に失敗した場合は 0 を返します。UInt256

例

使用例

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

toUInt32

導入: v1.1

入力値を UInt32 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値。

サポートされない引数:

NaN や Inf を含む、Float* 値の文字列表現。
SELECT toUInt32('0xc0fe'); のような、2進数および16進数値の文字列表現。

注記

入力値が UInt32 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。例: SELECT toUInt32(4294967296) == 0;

注記

この関数はゼロ方向への丸めを行います。つまり、小数部の桁を切り捨てます。

参照:

toUInt32OrZero。
toUInt32OrNull。
toUInt32OrDefault。

構文

toUInt32(expr)

引数

expr — 数値、または数値を表す文字列を返す式です。Expression

返される値

32 ビット符号なし整数値を返します。UInt32

例

使用例

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

toUInt32OrDefault

導入バージョン: v21.11

toUInt32 と同様に、この関数は入力値を UInt32 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が指定されていない場合、エラー時には 0 が返されます。

構文

toUInt32OrDefault(expr[, default])

引数

expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
default — 省略可能。解析に失敗した場合に返す既定値。UInt32

戻り値

成功した場合は型 UInt32 の値を返します。失敗した場合は、指定されていれば既定値を返し、指定されていなければ 0 を返します。UInt32

例

変換が成功する例

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

変換失敗

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

toUInt32OrNull

導入バージョン: v1.1

toUInt32 と同様に、この関数は入力値を UInt32 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（NULL を返します）:

NaN や Inf を含む Float* 型値の文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toUInt32OrNull('0xc0fe');）。

注記

入力値が UInt32 の範囲内で表現できない場合、結果としてオーバーフローまたはアンダーフローが発生しますが、これはエラーとはみなされません。

関連項目:

toUInt32。
toUInt32OrZero。
toUInt32OrDefault。

構文

toUInt32OrNull(x)

引数

x — 数値を表す文字列。String

戻り値

型 UInt32 の値を返します。変換に失敗した場合は NULL を返します。UInt32 または NULL

例

使用例

SELECT
    toUInt32OrNull('32'),
    toUInt32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): \N

toUInt32OrZero

導入バージョン: v1.1

toUInt32 と同様に、この関数は入力値を UInt32 型の値に変換しますが、エラーの場合は 0 を返します。

サポートされる引数:

(U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（0 を返す）:

NaN や Inf を含む Float* 型の値の文字列表現。
SELECT toUInt32OrZero('0xc0fe'); のような、2進数および16進数値の文字列表現。

注記

入力値が UInt32 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toUInt32。
toUInt32OrNull。
toUInt32OrDefault。

構文

toUInt32OrZero(x)

引数

x — 数値を表す文字列。String

戻り値

変換に成功した場合は UInt32 型の値を返し、失敗した場合は 0 を返します。UInt32

例

使用例

SELECT
    toUInt32OrZero('32'),
    toUInt32OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt32OrZero('32'):  32
toUInt32OrZero('abc'): 0

toUInt64

導入バージョン: v1.1

入力値を UInt64 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

型 (U)Int* の値、またはその文字列表現。
型 Float* の値。

サポートされない型:

NaN や Inf を含む、型 Float* の値の文字列表現。
2 進数値および 16 進数値の文字列表現 (例: SELECT toUInt64('0xc0fe');)。

注記

入力値が UInt64 の表現可能範囲外となる場合、結果はオーバーフローまたはアンダーフローします。これはエラーとはみなされません。例: SELECT toUInt64(18446744073709551616) == 0;

注記

この関数は0 への丸めを行います。つまり、小数部分の桁を切り捨てます。

関連項目:

toUInt64OrZero
toUInt64OrNull
toUInt64OrDefault

構文

toUInt64(expr)

引数

expr — 数値、または数値を表す文字列を返す式。Expression

戻り値

64 ビットの符号なし整数値を返します。UInt64

例

使用例

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

toUInt64OrDefault

導入バージョン: v21.11

toUInt64 と同様に、この関数は入力値を UInt64 型の値に変換しますが、エラーが発生した場合にはデフォルト値を返します。 default 値が渡されない場合、エラー時には 0 が返されます。

構文

toUInt64OrDefault(expr[, default])

引数

expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
default — 省略可能。変換に失敗した場合に返されるデフォルト値。UInt64

戻り値

成功した場合は UInt64 型の値を返し、失敗した場合は default が指定されていればその値を、指定されていなければ 0 を返します。UInt64

例

変換が成功する例

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

変換に失敗

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

toUInt64OrNull

導入バージョン: v1.1

toUInt64 と同様に、この関数は入力値を UInt64 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

(U)Int* 型の値の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む Float* 型の値の文字列表現。
SELECT toUInt64OrNull('0xc0fe'); のような、2 進数および 16 進数値の文字列表現。

注記

入力値が UInt64 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとはみなされません。

関連項目:

toUInt64。
toUInt64OrZero。
toUInt64OrDefault。

構文

toUInt64OrNull(x)

引数

x — 数値の文字列表現。String

戻り値

変換に成功した場合は型 UInt64 の値を返し、失敗した場合は NULL を返します。UInt64 または NULL

例

使用例

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): \N

toUInt64OrZero

導入バージョン: v1.1

toUInt64 と同様に、この関数は入力値を UInt64 型の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

(U)Int* 型の値の文字列表現。

サポートされない引数（0 を返す）:

NaN や Inf を含む Float* 型の値の文字列表現。
2進数および16進数値の文字列表現（例: SELECT toUInt64OrZero('0xc0fe');）。

注記

入力値が UInt64 の範囲で表現できない場合、結果はオーバーフローまたはアンダーフローした値になります。これはエラーとは見なされません。

関連項目:

toUInt64。
toUInt64OrNull。
toUInt64OrDefault。

構文

toUInt64OrZero(x)

引数

x — 数値を表す文字列。String

戻り値

変換に成功した場合は UInt64 型の値を返し、失敗した場合は 0 を返します。UInt64

例

使用例

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

toUInt8

導入バージョン: v1.1

入力値を UInt8 型の値に変換します。エラーが発生した場合は例外をスローします。

サポートされる引数:

(U)Int* 型の値またはその文字列表現。
Float* 型の値。

サポートされない引数:

NaN や Inf を含む、Float* 値の文字列表現。
2 進数および 16 進数値の文字列表現。例: SELECT toUInt8('0xc0fe');。

注記

入力値が UInt8 の範囲内で表現できない場合、結果がオーバーフローまたはアンダーフローします。これはエラーとはみなされません。例: SELECT toUInt8(256) == 0;。

注記

この関数はゼロ方向への丸めを使用します。つまり、小数部の桁を切り捨てます。

関連項目:

toUInt8OrZero
toUInt8OrNull
toUInt8OrDefault

構文

toUInt8(expr)

引数

expr — 数値、または数値の文字列表現を返す式。Expression

返される値

8 ビット符号なし整数値を返します。UInt8

例

使用例

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

toUInt8OrDefault

導入バージョン: v21.11

toUInt8 と同様に、この関数は入力値を UInt8 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 引数が指定されない場合は、エラー時には 0 が返されます。

構文

toUInt8OrDefault(expr[, default])

引数

expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
default — 省略可能。パースに失敗した場合に返されるデフォルト値。UInt8

戻り値

成功した場合は UInt8 型の値を返し、そうでない場合は、指定されていればデフォルト値を、指定されていなければ 0 を返します。UInt8

例

変換が成功する例

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

変換失敗

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

toUInt8OrNull

導入バージョン: v1.1

toUInt8 と同様に、この関数は入力値を UInt8 型の値に変換しますが、エラー時には NULL を返します。

サポートされる引数:

(U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（NULL を返す）:

NaN や Inf を含む、通常の Float* 値の文字列表現。
2 進数および 16 進数値の文字列表現（例: SELECT toUInt8OrNull('0xc0fe');）。

注記

入力値が UInt8 の範囲で表現できない場合、結果でオーバーフローまたはアンダーフローが発生します。これはエラーとは見なされません。

関連項目:

toUInt8。
toUInt8OrZero。
toUInt8OrDefault。

構文

toUInt8OrNull(x)

引数

x — 数値を表す文字列。String

返される値

変換に成功した場合は UInt8 型の値を返し、変換に失敗した場合は NULL を返します。UInt8 または NULL

例

使用例

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): \N

toUInt8OrZero

導入バージョン: v1.1

toUInt8 と同様に、この関数は入力値を UInt8 型の値に変換しますが、エラーが発生した場合には 0 を返します。

サポートされる引数:

(U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（0 を返す）:

一般的な Float* 型値の文字列表現（NaN および Inf を含む）。
2 進値および 16 進値の文字列表現（例: SELECT toUInt8OrZero('0xc0fe');）。

注記

入力値が UInt8 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。これはエラーとは見なされません。

関連項目:

toUInt8。
toUInt8OrNull。
toUInt8OrDefault。

構文

toUInt8OrZero(x)

引数

x — 数値を表す文字列。String

戻り値

UInt8 型の値を返します。変換に失敗した場合は 0 を返します。UInt8

例

使用例

SELECT
    toUInt8OrZero('-8'),
    toUInt8OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

toUUID

導入バージョン: v1.1

String 型の値を UUID 型の値に変換します。

構文

toUUID(string)

引数

string — UUID を表す文字列。String または FixedString

戻り値

UUID の文字列表現から UUID 型の値を返します。UUID

例

使用例

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

toUUIDOrZero

導入バージョン: v20.12

入力値を UUID 型の値に変換しますが、エラー時にはゼロ UUID を返します。 toUUID と同様ですが、変換エラー時に例外をスローする代わりにゼロ UUID（00000000-0000-0000-0000-000000000000）を返します。

サポートされる引数:

標準形式での UUID の文字列表現（8-4-4-4-12 個の 16 進数）。
ハイフンなしの UUID の文字列表現（32 個の 16 進数）。

サポートされない引数（ゼロ UUID を返す）:

無効な文字列形式。
文字列型以外の型。

構文

toUUIDOrZero(x)

引数

x — UUID の文字列表現。String

返される値

成功した場合は UUID の値を返し、失敗した場合はゼロ UUID (00000000-0000-0000-0000-000000000000) を返します。UUID

例

使用例

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

toUnixTimestamp64Micro

導入バージョン: v20.5

DateTime64 を固定のマイクロ秒精度を持つ Int64 値に変換します。入力値は、その精度に応じて適切に拡大または縮小されます。

注記

出力値は入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Micro(value)

引数

value — 任意の精度を持つ DateTime64 値。DateTime64

返される値

マイクロ秒単位の Unix タイムスタンプを返します。Int64

例

使用例

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

┌─toUnixTimestamp64Micro(dt64)─┐
│               1739489491011123 │
└────────────────────────────────┘

toUnixTimestamp64Milli

導入バージョン: v20.5

DateTime64 を、ミリ秒単位の固定精度を持つ Int64 値に変換します。入力値は、その精度に応じて適切に拡大または縮小されます。

注記

出力値は入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Milli(value)

引数

value — 任意の精度を持つ DateTime64 値。DateTime64

戻り値

Unix タイムスタンプ（ミリ秒単位）を返します。Int64

例

使用例

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

toUnixTimestamp64Nano

導入バージョン: v20.5

DateTime64 を、ナノ秒単位の固定精度を持つ Int64 値に変換します。入力値は、その精度に応じて適切にスケーリング（拡大または縮小）されます。

注記

出力値は、入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Nano(value)

引数

value — 任意精度の DateTime64 値。DateTime64

戻り値

ナノ秒単位の Unix タイムスタンプを返します。Int64

例

使用例

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

┌─toUnixTimestamp64Nano(dt64)────┐
│            1739489491011123456 │
└────────────────────────────────┘

toUnixTimestamp64Second

導入バージョン: v24.12

DateTime64 を、秒単位の固定精度を持つ Int64 値に変換します。入力値の精度に応じて、値は適切にスケーリングされます。

注記

出力値は入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Second(value)

引数

value — 任意の精度を持つ DateTime64 値。DateTime64

戻り値

秒単位の Unix タイムスタンプを返します。Int64

例

使用例

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘

データ変換でよくある問題​

toString 関数に関する注意事項​

toDate/toDateTime 関数に関する注意事項​

CAST​

DATE​

accurateCast​

accurateCastOrDefault​

accurateCastOrNull​

formatRow​

formatRowNoNewline​

fromUnixTimestamp64Micro​

fromUnixTimestamp64Milli​

fromUnixTimestamp64Nano​

fromUnixTimestamp64Second​

parseDateTime​

parseDateTime32BestEffort​

parseDateTime32BestEffortOrNull​

parseDateTime32BestEffortOrZero​

parseDateTime64​

parseDateTime64BestEffort​

parseDateTime64BestEffortOrNull​

parseDateTime64BestEffortOrZero​

parseDateTime64BestEffortUS​

parseDateTime64BestEffortUSOrNull​

parseDateTime64BestEffortUSOrZero​

parseDateTime64InJodaSyntax​

parseDateTime64InJodaSyntaxOrNull​

parseDateTime64InJodaSyntaxOrZero​

parseDateTime64OrNull​

parseDateTime64OrZero​

parseDateTimeBestEffort​

parseDateTimeBestEffortOrNull​

parseDateTimeBestEffortOrZero​

parseDateTimeBestEffortUS​

parseDateTimeBestEffortUSOrNull​

parseDateTimeBestEffortUSOrZero​

parseDateTimeInJodaSyntax​

parseDateTimeInJodaSyntaxOrNull​

parseDateTimeInJodaSyntaxOrZero​

parseDateTimeOrNull​

parseDateTimeOrZero​

reinterpret​

reinterpretAsDate​

reinterpretAsDateTime​

reinterpretAsFixedString​

reinterpretAsFloat32​

reinterpretAsFloat64​

reinterpretAsInt128​

reinterpretAsInt16​

reinterpretAsInt256​

reinterpretAsInt32​

reinterpretAsInt64​

reinterpretAsInt8​

reinterpretAsString​

reinterpretAsUInt128​

reinterpretAsUInt16​

reinterpretAsUInt256​

reinterpretAsUInt32​

reinterpretAsUInt64​

reinterpretAsUInt8​

reinterpretAsUUID​

toBFloat16​

toBFloat16OrNull​

toBFloat16OrZero​

toBool​

toDate​

toDate32​

toDate32OrDefault​

toDate32OrNull​

toDate32OrZero​

toDateOrDefault​

toDateOrNull​

toDateOrZero​

toDateTime​

toDateTime32​

toDateTime64​

toDateTime64OrDefault​

toDateTime64OrNull​

toDateTime64OrZero​

toDateTimeOrDefault​

データ変換でよくある問題

`toString` 関数に関する注意事項

`toDate`/`toDateTime` 関数に関する注意事項

CAST

DATE

accurateCast

accurateCastOrDefault

accurateCastOrNull

formatRow

formatRowNoNewline

fromUnixTimestamp64Micro

fromUnixTimestamp64Milli

fromUnixTimestamp64Nano

fromUnixTimestamp64Second

parseDateTime

parseDateTime32BestEffort

parseDateTime32BestEffortOrNull

parseDateTime32BestEffortOrZero

parseDateTime64

parseDateTime64BestEffort

parseDateTime64BestEffortOrNull

parseDateTime64BestEffortOrZero

parseDateTime64BestEffortUS

parseDateTime64BestEffortUSOrNull

parseDateTime64BestEffortUSOrZero

parseDateTime64InJodaSyntax

parseDateTime64InJodaSyntaxOrNull

parseDateTime64InJodaSyntaxOrZero

parseDateTime64OrNull

parseDateTime64OrZero

parseDateTimeBestEffort

parseDateTimeBestEffortOrNull

parseDateTimeBestEffortOrZero

parseDateTimeBestEffortUS

parseDateTimeBestEffortUSOrNull

parseDateTimeBestEffortUSOrZero

parseDateTimeInJodaSyntax

parseDateTimeInJodaSyntaxOrNull

parseDateTimeInJodaSyntaxOrZero

parseDateTimeOrNull

parseDateTimeOrZero

reinterpret

reinterpretAsDate

reinterpretAsDateTime

reinterpretAsFixedString

reinterpretAsFloat32

reinterpretAsFloat64

reinterpretAsInt128

reinterpretAsInt16

reinterpretAsInt256

reinterpretAsInt32

reinterpretAsInt64

reinterpretAsInt8

reinterpretAsString

reinterpretAsUInt128

reinterpretAsUInt16

reinterpretAsUInt256

reinterpretAsUInt32

reinterpretAsUInt64

reinterpretAsUInt8

reinterpretAsUUID

toBFloat16

toBFloat16OrNull

toBFloat16OrZero

toBool

toDate

toDate32

toDate32OrDefault

toDate32OrNull

toDate32OrZero

toDateOrDefault

toDateOrNull

toDateOrZero

toDateTime

toDateTime32

toDateTime64

toDateTime64OrDefault

toDateTime64OrNull

toDateTime64OrZero

toDateTimeOrDefault