型変換関数

型変換関数に関するドキュメント

​

データ変換に関する一般的な問題

ClickHouse は通常、C++ プログラムと同じ動作をします。

to<type> 関数と cast は、場合によっては異なる動作をします。たとえば LowCardinality の場合、cast は LowCardinality 特性を取り除きますが、to<type> 関数は取り除きません。Nullable についても同様です。この動作は SQL 標準とは互換性がなく、cast_keep_nullable 設定で変更できます。

データ型の値をより小さいデータ型 (たとえば 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 関数ファミリーでは、数値、文字列 (固定長文字列を除く) 、日付、日時の間で変換できます。 これらの関数はすべて 1 つの引数を受け取ります。

• 文字列との相互変換では、値のフォーマットや解析に TabSeparated フォーマット (および、ほぼすべての他のテキストフォーマット) と同じ規則が使われます。文字列を解析できない場合は例外が発生し、リクエストはキャンセルされます。
• 日付を数値に変換する場合、およびその逆の場合、日付は Unix epoch の開始からの日数に対応します。
• 日時を数値に変換する場合、およびその逆の場合、日時は Unix epoch の開始からの秒数に対応します。
• DateTime 型の引数に対する toString 関数では、タイムゾーン名 (たとえば Europe/Amsterdam) を含む 2 番目の String 型引数を指定できます。この場合、時刻は指定したタイムゾーンに従ってフォーマットされます。

​

toDate/toDateTime 関数に関する注意

toDate/toDateTime 関数の日付および日時のフォーマットは、次のように定義されています。

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

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

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

数値型同士の変換には、C++ における異なる数値型間の代入と同じ規則が適用されます。

例

Query

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

Response

┌──────────────────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.0

値を指定したデータ型に変換します。 reinterpret 関数とは異なり、CAST は変換先の型でも同じ値になるように変換を試みます。 それが不可能な場合は、例外が送出されます。

構文

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

引数

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

戻り値

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

例

基本的な使い方

Query

SELECT CAST(42, 'String')

Response

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

AS構文を使う

Query

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

Response

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

「::」構文の使用

Query

SELECT '123'::UInt32

Response

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

​

DATE

導入バージョン: v21.2.0

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

構文

DATE(expr)

引数

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

戻り値

Date 型の値を返します。

例

基本的な使い方

Query

SELECT DATE('2023-01-01')

Response

2023-01-01

​

accurateCast

導入バージョン: v1.1.0

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

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

構文

accurateCast(x, T)

引数

• x — 変換する値。Any
• T — 変換先の型名。String

戻り値

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

例

変換に成功した場合

Query

SELECT accurateCast(42, 'UInt16')

Response

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

文字列から数値

Query

SELECT accurateCast('123.45', 'Float64')

Response

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

​

accurateCastOrDefault

導入バージョン: v21.1.0

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

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

構文

accurateCastOrDefault(x, T[, default_value])

引数

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

戻り値

変換後の値を返します。変換できない場合はデフォルト値を返します。Any

例

変換に成功した場合

Query

SELECT accurateCastOrDefault(42, 'String')

Response

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

明示的なデフォルト値を使った変換の失敗

Query

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

Response

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

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

Query

SELECT accurateCastOrDefault('abc', 'UInt32')

Response

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

​

accurateCastOrNull

導入バージョン: v1.1.0

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

この関数は、accurateCast の安全性と、適切なエラーハンドリングを兼ね備えています。

構文

accurateCastOrNull(x, T)

引数

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

戻り値

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

例

変換が成功する場合

Query

SELECT accurateCastOrNull(42, 'String')

Response

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

変換に失敗すると NULL を返します

Query

SELECT accurateCastOrNull('abc', 'UInt32')

Response

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

​

formatRow

導入バージョン: v20.7.0

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

フォーマットに接尾辞/プレフィックスが含まれている場合、それらは各行に書き込まれます。 この関数では、行ベースのフォーマットのみをサポートします。

構文

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

引数

• format — テキストフォーマット。たとえば、CSV、TSV。String
• x, y, ... — 式。Any

戻り値

書式化された文字列。 (テキストフォーマットでは通常、末尾に改行文字が付きます) 。String

例

基本的な使い方

Query

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

Response

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

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

Query

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

Response

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

​

formatRowNoNewline

導入バージョン: v20.7.0

formatRow と同じですが、各行の改行文字を取り除きます。

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

構文

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

引数

• format — テキストのフォーマット。たとえば、CSV、TSV。 String
• x, y, ... — 式。 Any

戻り値

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

例

基本的な使い方

Query

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

Response

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

​

fromUnixTimestamp64Micro

導入バージョン: v20.5.0

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

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

構文

fromUnixTimestamp64Micro(value[, timezone])

引数

• value — マイクロ秒単位の Unix timestamp。Int64
• timezone — 省略可。戻り値のタイムゾーン。String

戻り値

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

例

使用例

Query

SELECT fromUnixTimestamp64Micro(1640995200123456)

Response

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

​

fromUnixTimestamp64Milli

導入バージョン: v20.5.0

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

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

構文

fromUnixTimestamp64Milli(value[, timezone])

引数

• value — ミリ秒単位の Unixタイムスタンプ。Int64
• timezone — 省略可能。戻り値のタイムゾーン。String

戻り値

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

例

使用例

Query

SELECT fromUnixTimestamp64Milli(1640995200123)

Response

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

​

fromUnixTimestamp64Nano

導入バージョン: v20.5.0

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

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

入力値は UTC のタイムスタンプとして扱われ、入力値のタイムゾーンは考慮されないことに注意してください。

構文

fromUnixTimestamp64Nano(value[, timezone])

引数

• value — ナノ秒単位の Unixタイムスタンプ。Int64
• timezone — 省略可。戻り値のタイムゾーン。String

戻り値

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

例

使用例

Query

SELECT fromUnixTimestamp64Nano(1640995200123456789)

Response

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

​

fromUnixTimestamp64Second

導入バージョン: v24.12.0

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

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

構文

fromUnixTimestamp64Second(value[, timezone])

引数

• value — 秒単位のUnixタイムスタンプ。 Int64
• timezone — 省略可能。戻り値のタイムゾーン。 String

戻り値

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

例

使用例

Query

SELECT fromUnixTimestamp64Second(1640995200)

Response

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

​

parseDateTime

導入バージョン: v23.3.0

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

この関数は formatDateTime の逆関数です。 フォーマット文字列を使用して String 型の引数を解析します。戻り値は DateTime 型です。

構文

parseDateTime(time_string, format[, timezone])

別名: TO_UNIXTIME

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTime32BestEffort

導入バージョン: v20.9.0

日付と時刻の文字列表現を、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

例

使用例

Query

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

Response

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

タイムゾーンあり

Query

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

Response

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

Unixタイムスタンプ

Query

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

Response

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

​

parseDateTime32BestEffortOrNull

導入バージョン: v20.9.0

parseDateTime32BestEffort と同様ですが、処理できない日付フォーマットが指定された場合は NULL を返します。

構文

parseDateTime32BestEffortOrNull(time_string[, time_zone])

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTime32BestEffortOrZero

導入バージョン: v20.9.0

parseDateTime32BestEffort と同様ですが、処理できない日付フォーマットに遭遇した場合は、ゼロ日付またはゼロ日時を返します。

構文

parseDateTime32BestEffortOrZero(time_string[, time_zone])

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTime64

導入バージョン: v24.11.0

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

この関数は、DateTime64 に対する formatDateTime の逆関数です。 フォーマット String を使って String 型の argument を解析します。1900 年から 2299 年までの日付をサブ秒精度で表現できる DateTime64 型を返します。

構文

parseDateTime64(time_string, format[, timezone])

引数

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

戻り値

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

例

使用例

Query

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

Response

┌─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.0

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

構文

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

引数

• time_string — 変換する日付または日時を含む String。String
• precision — 任意。必要な精度。ミリ秒は 3、マイクロ秒は 6。デフォルト: 3。UInt8
• time_zone — 任意。タイムゾーン。関数は time_zone に従って time_string を解析します。String

戻り値

time_string を DateTime64 型に変換して返します。DateTime64

例

使用例

Query

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

Response

┌──────────────────────────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.0

parseDateTime64BestEffort と同様ですが、処理できない日付フォーマットに遭遇した場合は NULL を返します。

構文

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

引数

• time_string — 変換する日付または日時を含む String。String
• precision — 任意。必要な精度です。ミリ秒は 3、マイクロ秒は 6 です。デフォルト: 3。UInt8
• time_zone — 任意。タイムゾーン。関数は time_zone に従って time_string を解析します。String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTime64BestEffortOrZero

導入バージョン: v20.1.0

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

例

使用例

Query

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

Response

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

​

parseDateTime64BestEffortUS

導入バージョン: v22.8.0

曖昧な場合に 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

例

使用例

Query

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

Response

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

​

parseDateTime64BestEffortUSOrNull

導入バージョン: v22.8.0

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

Syntax

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

引数

• time_string — 変換する日付または日時を含む String。 String
• precision — 任意。必要な精度。3 はミリ秒、6 はマイクロ秒です。デフォルト: 3。 UInt8
• time_zone — 任意。タイムゾーン。関数はこのタイムゾーンに従って time_string を解析します。 String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTime64BestEffortUSOrZero

導入バージョン: v22.8.0

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

構文

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

引数

• time_string — 変換する日付または日時を含む String。String
• precision — 任意。必要な精度です。ミリ秒は 3、マイクロ秒は 6。デフォルト値: 3。UInt8
• time_zone — 任意。タイムゾーン。関数は time_string をこのタイムゾーンに従って解析します。String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTime64InJodaSyntax

導入バージョン: v24.10.0

Joda の日付フォーマット文字列に従って、秒未満の精度を持つ日付と時刻の文字列を解析します。

この関数は、DateTime64 に対する formatDateTimeInJodaSyntax の逆関数です。 Joda 形式のフォーマット String を使用して String 型の引数を解析します。戻り値は、1900 年から 2299 年までの日付を秒未満の精度で表現できる DateTime64 型です。

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

構文

parseDateTime64InJodaSyntax(time_string, format[, timezone])

引数

• time_string — DateTime64 として解析する文字列。String
• format — time_string をどのように解析するかを指定する Joda 構文のフォーマット文字列。String
• timezone — 任意。タイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

┌─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.0

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

構文

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

引数

• time_string — DateTime64 にパースする対象の文字列。String
• format — time_string をどのようにパースするかを指定する Joda 構文のフォーマット文字列。String
• timezone — 任意。タイムゾーン。String

戻り値

入力文字列をパースして得られた DateTime64 を返します。パースに失敗した場合は NULL を返します。Nullable(DateTime64)

例

使用例

Query

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

Response

┌─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.0

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

構文

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

引数

• time_string — DateTime64 にパースする文字列。String
• format — time_string をどのようにパースするかを指定する Joda 構文のフォーマット文字列。String
• timezone — 任意。タイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

┌─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.0

parseDateTime64 と同様ですが、解析できない日付形式が指定された場合は NULL を返します。

構文

parseDateTime64OrNull(time_string, format[, timezone])

引数

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

戻り値

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

例

使用例

Query

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

Response

┌─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.0

parseDateTime64 と同様ですが、解釈できない日付フォーマットが指定された場合はゼロ日付を返します。

構文

parseDateTime64OrZero(time_string, format[, timezone])

引数

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

戻り値

入力文字列をパースして得られた DateTime64 を返します。パースに失敗した場合は、ゼロの DateTime64 を返します。DateTime64

例

使用例

Query

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

Response

┌─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.0

String 形式で表された日付と時刻を DateTime データ型に変換します。 この関数は、ISO 8601、RFC 1123 - 5.2.14 RFC-822 の日付と時刻の仕様、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。String
• time_zone — 任意。time_string を解析する際に使用するタイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

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

タイムゾーン指定あり

Query

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

Response

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

Unixタイムスタンプ

Query

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

Response

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

​

parseDateTimeBestEffortOrNull

導入バージョン: v1.1.0

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。String
• time_zone — 任意。time_string の解析に使用するタイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTimeBestEffortOrZero

導入バージョン: v1.1.0

処理できない日付フォーマットを検出した場合に、ゼロ日付またはゼロ日時を返す点を除き、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 に置き換えられます。
• 日付と時刻に加えて time zone オフセット情報を含む文字列: YYYY-MM-DD hh:mm:ss ±h:mm など。
• syslog の timestamp: 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

例

使用例

Query

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

Response

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

​

parseDateTimeBestEffortUS

導入バージョン: v1.1.0

この関数は、ISO 日付フォーマット (例: YYYY-MM-DD hh:mm:ss) や、月と日の部分を曖昧さなく判別できるその他の日付フォーマット (例: 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 ではなく、US 日付形式を優先します。 ただし、前述の説明の例外として、月が 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

例

使用例

Query

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

Response

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

​

parseDateTimeBestEffortUSOrNull

導入バージョン: v1.1.0

処理できない日付フォーマットに遭遇した場合に 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

例

使用例

Query

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

Response

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

​

parseDateTimeBestEffortUSOrZero

導入バージョン: v1.1.0

parseDateTimeBestEffortUS 関数と同様ですが、処理できない日付フォーマットに遭遇した場合は、ゼロ日付 (1970-01-01) または日時のゼロ日付 (1970-01-01 00:00:00) を返します。

この関数は ISO 日付フォーマットに対しては parseDateTimeBestEffort と同様に動作しますが、曖昧なケースでは US 日付形式を優先し、パースエラー時にはゼロを返します。

構文

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

引数

• time_string — 変換する日付と時刻を含む String。String
• time_zone — 任意。time_string を解析する際に使用するタイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTimeInJodaSyntax

導入バージョン: v23.3.0

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

この関数は formatDateTimeInJodaSyntax の逆関数です。 Joda スタイルのフォーマット String を使用して String 型の argument を解析します。戻り値は DateTime 型です。

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

構文

parseDateTimeInJodaSyntax(time_string, format[, timezone])

引数

• time_string — DateTime に解析される文字列。 String
• format — time_string をどのように解析するかを指定する Joda 構文のフォーマット文字列。 String
• timezone — 任意。タイムゾーン。 String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTimeInJodaSyntaxOrNull

導入バージョン: v23.3.0

parseDateTimeInJodaSyntax と同じですが、解析不能な日付フォーマットに遭遇した場合は NULL を返します。

構文

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

引数

• time_string — DateTime にパースされる文字列。String
• format — time_string のパース方法を指定する、Joda 構文のフォーマット文字列。String
• timezone — 任意。タイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTimeInJodaSyntaxOrZero

導入バージョン: v23.3.0

parseDateTimeInJodaSyntax と同じですが、解析できない日付形式が指定された場合はゼロ日付を返します。

構文

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

引数

• time_string — DateTime にパースする文字列。String
• format — time_string のパース方法を指定する、Joda 構文 の format string。String
• timezone — 省略可能。タイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTimeOrNull

導入バージョン: v23.3.0

parseDateTime と同様ですが、解釈できない日付形式の場合は NULL を返します。

構文

parseDateTimeOrNull(time_string, format[, timezone])

別名: str_to_date

引数

• time_string — DateTime にパースする対象の文字列。String
• format — time_string をどのようにパースするかを指定するフォーマット文字列。String
• timezone — 任意。タイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

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

​

parseDateTimeOrZero

導入バージョン: v23.3.0

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

構文

parseDateTimeOrZero(time_string, format[, timezone])

引数

• time_string — DateTime にパースする文字列。String
• format — time_string をどのようにパースするかを指定するフォーマット文字列。String
• timezone — 任意。タイムゾーン。String

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpret

導入バージョン: v1.1.0

指定された値 x のメモリ上のバイト列をそのまま使用し、宛先の型として再解釈します。

構文

reinterpret(x, type)

引数

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

戻り値

変換先の型の値。Any

例

使用例

Query

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

Response

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

Array の例

Query

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

Response

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

​

reinterpretAsDate

導入バージョン: v1.1.0

入力値を Date 型の値として再解釈します (リトルエンディアン順を前提) 。これは、Unix エポック 1970-01-01 の開始からの日数を表します

構文

reinterpretAsDate(x)

引数

• x — Unixエポックの開始以降の日数。(U)Int* または Float* または Date または DateTime または UUID または String または FixedString

戻り値

Date。Date

例

使用例

Query

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

Response

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

​

reinterpretAsDateTime

導入バージョン: v1.1.0

入力値を DateTime 値として再解釈します (リトルエンディアン順を前提) 。この値は Unix エポック 1970-01-01 の開始からの日数を表します。

構文

reinterpretAsDateTime(x)

引数

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

戻り値

日付と時刻。DateTime

例

使用例

Query

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

Response

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

​

reinterpretAsFixedString

導入バージョン: v1.1.0

入力値を固定長文字列として再解釈します (リトルエンディアン順であると仮定します) 。 末尾のヌルバイトは無視されます。たとえば、UInt32 の値 255 に対して、この関数は 1 文字の文字列を返します。

構文

reinterpretAsFixedString(x)

引数

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

戻り値

x を表すバイトを含む固定長文字列。FixedString

例

使用例

Query

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

Response

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

​

reinterpretAsFloat32

導入バージョン: v1.1.0

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

構文

reinterpretAsFloat32(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsFloat64

導入バージョン: v1.1.0

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

構文

reinterpretAsFloat64(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsInt128

導入バージョン: v1.1.0

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

構文

reinterpretAsInt128(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsInt16

導入バージョン: v1.1.0

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

構文

reinterpretAsInt16(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsInt256

導入バージョン: v1.1.0

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

構文

reinterpretAsInt256(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsInt32

導入バージョン: v1.1.0

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

構文

reinterpretAsInt32(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsInt64

導入バージョン: v1.1.0

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

構文

reinterpretAsInt64(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsInt8

導入バージョン: v1.1.0

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

構文

reinterpretAsInt8(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsString

導入バージョン: v1.1.0

入力値を文字列として再解釈します (リトルエンディアン順を前提とします) 。 末尾のヌルバイトは無視されます。たとえば、UInt32 型の値 255 に対しては、1 文字の文字列を返します。

構文

reinterpretAsString(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsUInt128

導入バージョン: v1.1.0

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

構文

reinterpretAsUInt128(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsUInt16

導入バージョン: v1.1.0

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

構文

reinterpretAsUInt16(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsUInt256

導入バージョン: v1.1.0

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

構文

reinterpretAsUInt256(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsUInt32

導入バージョン: v1.1.0

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

構文

reinterpretAsUInt32(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsUInt64

導入バージョン: v1.1.0

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

構文

reinterpretAsUInt64(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsUInt8

導入バージョン: v1.1.0

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

構文

reinterpretAsUInt8(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

reinterpretAsUUID

導入バージョン: v1.1.0

16バイトの文字列を受け取り、各8バイトの半分をリトルエンディアンのバイト順として解釈し、UUID を返します。文字列の長さが足りない場合、この関数は末尾に必要な数の null byte が追加されたものとして動作します。文字列が16バイトを超える場合、末尾の余分なバイトは無視されます。

構文

reinterpretAsUUID(fixed_string)

引数

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

戻り値

UUID 型の値。UUID

例

文字列から UUID

Query

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

Response

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

​

toBFloat16

導入バージョン: v1.1.0

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

関連項目:

• toBFloat16OrZero。
• toBFloat16OrNull。

構文

toBFloat16(expr)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toBFloat16OrNull

導入バージョン: v1.1.0

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

サポートされる引数:

• 数値を表す文字列。

サポートされない引数 (NULL を返します):

• バイナリ値および16進値を表す文字列。
• 数値。

この関数では、文字列表現から変換する際に精度が失われることがありますが、その際にエラーは返されません。

関連項目:

• toBFloat16.
• toBFloat16OrZero.

構文

toBFloat16OrNull(x)

引数

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

戻り値

16 ビットの brain-float 値を返します。変換できない場合は NULL を返します。BFloat16 または NULL

例

使用例

Query

SELECT toBFloat16OrNull('0x5E'), -- サポート対象外の引数
       toBFloat16OrNull('12.3'), -- 一般的な使用例
       toBFloat16OrNull('12.3456789') -- 精度が失われても通知されない

Response

\N
12.25
12.3125

​

toBFloat16OrZero

導入バージョン: v1.1.0

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

サポートされる引数:

• 数値を表す文字列。

サポートされない引数 (0 を返します):

• バイナリ値および 16 進数値を表す文字列。
• 数値。

この関数では、文字列表現から変換する際に、精度が失われてもエラーになりません。

関連項目:

• toBFloat16.
• toBFloat16OrNull.

構文

toBFloat16OrZero(x)

引数

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

戻り値

16 ビットの brain-float 値を返します。そうでない場合は 0 を返します。 BFloat16

例

使用例

Query

SELECT toBFloat16OrZero('0x5E'), -- サポート対象外の引数
       toBFloat16OrZero('12.3'), -- 一般的な使用例
       toBFloat16OrZero('12.3456789') -- 精度が暗黙的に失われる

Response

0
12.25
12.3125

​

toBool

導入バージョン: v22.2.0

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

構文

toBool(expr)

引数

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

戻り値

引数の評価結果に応じて true または false を返します。 Bool

例

使用例

Query

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

Response

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.0

入力値を Date 型に変換します。 String、FixedString、DateTime、または数値型から変換できます。

構文

toDate(x)

引数

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

戻り値

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

例

String から Date への変換

Query

SELECT toDate('2025-04-15')

Response

2025-04-15

DateTimeをDateに変換

Query

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

Response

2025-04-15

整数をDateに変換

Query

SELECT toDate(20297)

Response

2025-07-28

​

toDate32

導入バージョン: v21.9.0

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

構文

toDate32(expr)

引数

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

戻り値

日付を返します。Date32

例

範囲内

Query

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

Response

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

範囲外

Query

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

Response

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

​

toDate32OrDefault

導入バージョン: v21.11.0

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

構文

toDate32OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

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

Response

1930-01-01

変換に失敗した場合

Query

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

Response

2020-01-01

​

toDate32OrNull

導入バージョン: v21.9.0

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

構文

toDate32OrNull(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toDate32OrZero

導入バージョン: v21.9.0

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

関連項目:

• toDate32
• toDate32OrNull
• toDate32OrDefault

構文

toDate32OrZero(x)

引数

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

戻り値

成功した場合は Date32 値を返し、失敗した場合は Date32 の下限値 (1900-01-01) を返します。Date32

例

使用例

Query

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

Response

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

​

toDateOrDefault

導入バージョン: v21.11.0

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

構文

toDateOrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

SELECT toDateOrDefault('2022-12-30')

Response

2022-12-30

変換に失敗

Query

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

Response

2023-01-01

​

toDateOrNull

導入バージョン: v1.1.0

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

構文

toDateOrNull(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toDateOrZero

導入バージョン: v1.1.0

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

関連項目:

• toDate
• toDateOrNull
• toDateOrDefault

構文

toDateOrZero(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toDateTime

導入バージョン: v1.1.0

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

expr が数値の場合、Unix epoch の開始からの経過秒数 (Unix timestamp) として解釈されます。 expr が String の場合、Unix timestamp、または date / 日時の文字列表現として解釈されることがあります。 そのため、短い数値文字列 (4 桁以下) のパースは、曖昧さを避けるため明示的に無効化されています。たとえば、文字列 '1999' は年 (Date / DateTime の不完全な文字列表現) を表す場合も、unix timestamp を表す場合もあります。より長い数値文字列は使用できます。

構文

toDateTime(expr[, time_zone])

引数

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

戻り値

日時を返します。DateTime

例

使用例

Query

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

Response

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.0

入力値を 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

例

値が範囲内にある場合

Query

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

Response

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

精度付きの Decimal として

Query

SELECT toDateTime64(1735689600.000, 3) AS value, toTypeName(value);
-- 小数点がない場合でも、この値は引き続き秒単位の Unix timestamp として扱われます
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

Response

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

タイムゾーンを指定した場合

Query

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

Response

┌───────────────────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.0

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

構文

toDateTime64(expr, scale[, timezone])

引数

• expr — 数値、または数値の文字列表現を返す式。式
• scale — ティックサイズ (精度) : 10^(-scale) Seconds。UInt8
• timezone — 任意。指定した DateTime64 オブジェクトのタイムゾーン。String

戻り値

秒未満の精度を持つ日付と時刻を返します。DateTime64

例

値が範囲内にある

Query

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

Response

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

精度を指定した Decimal として

Query

SELECT toDateTime64(1546300800.000, 3) AS value, toTypeName(value);
-- 小数点がなくても、この値は引き続き秒単位の Unix timestamp として扱われます
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

Response

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

タイムゾーンあり

Query

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

Response

┌───────────────────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.0

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

構文

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

引数

• expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
• scale — ティックサイズ (精度) : 10^-precision Seconds。UInt8
• timezone — 任意。タイムゾーン。String
• default — 任意。パースに失敗した場合に返すデフォルト値。DateTime64

戻り値

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

例

変換に成功した場合

Query

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

Response

1976-10-18 00:00:00.300

変換失敗

Query

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

Response

2000-12-31 23:00:00.000

​

toDateTime64OrNull

導入バージョン: v20.1.0

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

構文

toDateTime64OrNull(x)

引数

• x — 日時 (秒未満の精度を含む) の文字列表現。String

戻り値

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

例

使用例

Query

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

Response

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

​

toDateTime64OrZero

導入バージョン: v20.1.0

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

関連項目:

• toDateTime64.
• toDateTime64OrNull.
• toDateTime64OrDefault.

構文

toDateTime64OrZero(x)

引数

• x — 日時を秒未満の精度まで含む文字列表現。String

戻り値

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

例

使用例

Query

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

Response

┌─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.0

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

構文

toDateTimeOrDefault(expr[, timezone, default])

引数

• expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
• timezone — 任意。タイムゾーン。String
• default — 任意。パースに失敗した場合に返すデフォルト値。DateTime

戻り値

成功した場合は DateTime 型の値を返します。失敗した場合は、default が渡されていればその値を返し、渡されていなければ 1970-01-01 00:00:00 を返します。DateTime

例

変換に成功した場合

Query

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

Response

2022-12-30 13:44:17

変換失敗

Query

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

Response

2023-01-01 00:00:00

​

toDateTimeOrNull

導入バージョン: v1.1.0

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

構文

toDateTimeOrNull(x)

引数

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

戻り値

成功した場合は DateTime 型の値を返し、それ以外の場合は NULL を返します。DateTime または NULL

例

使用例

Query

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

Response

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

​

toDateTimeOrZero

導入バージョン: v1.1.0

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

構文

toDateTimeOrZero(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toDecimal128

導入バージョン: v18.12.0

入力値を、スケール S の Decimal(38, S) 型の値に変換します。 エラー時には例外をスローします。

サポートされる引数:

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

サポートされない引数:

• Float* 型の値 NaN および Inf の文字列表現 (大文字と小文字を区別しません) 。
• 二進数値および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 になるためです。 文字列入力を使うと、演算には基になる整数型が使用されます: toDecimal128('1.15', 2) = 1.15

構文

toDecimal128(expr, S)

引数

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

戻り値

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

例

使用例

Query

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

Response

行 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.0

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)

例

変換に成功した場合

Query

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

Response

0.023809523809523808

変換失敗

Query

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

Response

-1

​

toDecimal128OrNull

導入バージョン: v20.1.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します) :

• Float* 型の値 NaN および Inf、またはその文字列表現 (大文字と小文字を区別しません) 。
• バイナリ値および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

例

使用例

Query

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

Response

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

​

toDecimal128OrZero

導入バージョン: v20.1.0

入力値を 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)

例

基本的な使い方

Query

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

Response

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

​

toDecimal256

導入バージョン: v20.8.0

入力値を、スケール 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 になるためです。 文字列入力を使用すると、演算には基になる整数型が使われます: toDecimal256('1.15', 2) = 1.15

構文

toDecimal256(expr, S)

引数

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

戻り値

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

例

使用例

Query

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

Response

行 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.0

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

構文

toDecimal256OrDefault(expr, S[, default])

引数

• expr — 数値の文字列表現です。String
• S — 0〜76 のスケールパラメータで、数値の小数部に指定できる桁数を表します。UInt8
• default — 任意。Decimal256(S) 型へのパースに失敗した場合に返すデフォルト値です。Decimal256(S)

戻り値

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

例

変換成功

Query

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

Response

0.023809523809523808

変換に失敗

Query

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

Response

-1

​

toDecimal256OrNull

導入バージョン: v20.8.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します) :

• Float* 型の値 NaN および Inf、またはその文字列表現 (大文字と小文字を区別しません) 。
• バイナリ値および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

例

使用例

Query

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

Response

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

​

toDecimal256OrZero

導入バージョン: v20.8.0

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

サポートされる引数:

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

サポートされない引数 (0 を返します):

• Float* 型の値 NaN および Inf の値、またはその文字列表現 (大文字と小文字を区別しません) 。
• バイナリ値および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)

例

使用例

Query

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

Response

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

​

toDecimal32

導入バージョン: v18.12.0

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

サポートされる引数:

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

サポートされない引数:

• Float* 型の値 NaN および Inf、またはそれらの文字列表現 (大文字と小文字を区別しません) 。
• バイナリ値および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 になるためです。 代わりに String 入力を使うと、演算に基になる整数型が使用されます: toDecimal32('1.15', 2) = 1.15

構文

toDecimal32(expr, S)

引数

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

戻り値

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

例

使用例

Query

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

Response

行 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.0

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)

例

変換成功

Query

SELECT toDecimal32OrDefault(toString(0.0001), 5)

Response

0.0001

変換に失敗

Query

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

Response

-1

​

toDecimal32OrNull

導入バージョン: v20.1.0

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

サポートされる引数:

• 型 (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

例

使用例

Query

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

Response

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

​

toDecimal32OrZero

導入バージョン: v20.1.0

入力値を 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)

例

使用例

Query

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

Response

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

​

toDecimal64

導入バージョン: v18.12.0

入力値を、スケール 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.14 になります。これは、浮動小数点では 1.15 * 100 が 114.99 になるためです。 文字列入力を使用すると、演算には内部の整数型が使われます: toDecimal64('1.15', 2) = 1.15

構文

toDecimal64(expr, S)

引数

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

戻り値

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

例

使用例

Query

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

Response

行 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.0

この関数は 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)

例

変換に成功した場合

Query

SELECT toDecimal64OrDefault(toString(0.0001), 18)

Response

0.0001

変換の失敗

Query

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

Response

-1

​

toDecimal64OrNull

導入バージョン: v20.1.0

入力値を 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

例

使用例

Query

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

Response

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

​

toDecimal64OrZero

導入バージョン: v20.1.0

入力値を 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)

例

使用例

Query

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

Response

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

​

toDecimalString

導入バージョン: v23.3.0

数値を、指定した小数点以下の桁数を持つ String に変換します。

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

構文

toDecimalString(number, scale)

引数

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

戻り値

指定した小数点以下の桁数で、数値を文字列として返します。String

例

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

Query

SELECT toDecimalString(2.1456, 2)

Response

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

0で埋める

Query

SELECT toDecimalString(5, 3)

Response

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

さまざまな数値型

Query

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

Response

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

​

toFixedString

導入バージョン: v1.1.0

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

文字列のバイト数が N 未満の場合は、右側が null バイトで埋められます。 文字列のバイト数が N を超える場合は、例外が発生します。

構文

toFixedString(s, N)

引数

• s — 変換する文字列。String
• N — 生成される FixedString の長さ。const UInt*

戻り値

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

例

使用例

Query

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

Response

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

​

toFloat32

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数:

• 2進数および16進数の文字列表現。たとえば SELECT toFloat32('0xc0fe');。

関連項目:

• toFloat32OrZero。
• toFloat32OrNull。
• toFloat32OrDefault。

構文

toFloat32(expr)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toFloat32OrDefault

導入バージョン: v21.11.0

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

構文

toFloat32OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

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

Response

8

変換に失敗した場合

Query

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

Response

0

​

toFloat32OrNull

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します):

• 2進数および16進数の文字列表現。例: SELECT toFloat32OrNull('0xc0fe');。
• 無効な文字列フォーマット。

関連項目:

• toFloat32。
• toFloat32OrZero。
• toFloat32OrDefault。

構文

toFloat32OrNull(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toFloat32OrZero

導入バージョン: v1.1.0

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

関連項目:

• toFloat32。
• toFloat32OrNull。
• toFloat32OrDefault。

構文

toFloat32OrZero(x)

引数

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

戻り値

成功した場合は 32 ビットの浮動小数点値を返し、それ以外の場合は 0 を返します。 Float32

例

使用例

Query

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

Response

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

​

toFloat64

導入バージョン: v1.1.0

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

サポートされる引数:

• (U)Int* 型の値。
• (U)Int8/16/32/128/256 の文字列表現。
• NaN と Inf を含む Float* 型の値。
• NaN と Inf を含む Float* 型の文字列表現 (大文字と小文字は区別されません) 。

サポートされない引数:

• 2 進数および 16 進数の値の文字列表現。例: SELECT toFloat64('0xc0fe');。

関連項目:

• toFloat64OrZero。
• toFloat64OrNull。
• toFloat64OrDefault。

構文

toFloat64(expr)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toFloat64OrDefault

導入バージョン: v21.11.0

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

構文

toFloat64OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した例

Query

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

Response

8

変換に失敗した場合

Query

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

Response

0

​

toFloat64OrNull

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します) :

• 2進数値および16進数値の文字列表現。例: SELECT toFloat64OrNull('0xc0fe');。
• 無効な文字列形式。

関連項目:

• toFloat64。
• toFloat64OrZero。
• toFloat64OrDefault。

構文

toFloat64OrNull(x)

引数

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

戻り値

成功した場合は 64 ビットの浮動小数点値を返し、失敗した場合は NULL を返します。Float64 または NULL

例

使用例

Query

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

Response

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

​

toFloat64OrZero

導入バージョン: v1.1.0

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

関連項目:

• toFloat64。
• toFloat64OrNull。
• toFloat64OrDefault。

構文

toFloat64OrZero(x)

引数

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

戻り値

成功した場合は 64 ビットの浮動小数点値を返し、失敗した場合は 0 を返します。Float64

例

使用例

Query

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

Response

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

​

toInt128

導入バージョン: v1.1.0

入力値を Int128 型の値に変換します。 エラーが発生した場合は例外をスローします。 この関数ではゼロ方向への丸めが使用されるため、数値の小数点以下の桁数は切り捨てられます。

サポートされる引数:

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

サポートされない引数:

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

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

関連項目:

• toInt128OrZero。
• toInt128OrNull。
• toInt128OrDefault。

構文

toInt128(expr)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toInt128OrDefault

導入バージョン: v21.11.0

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

構文

toInt128OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

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

Response

-128

変換に失敗した場合

Query

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

Response

-1

​

toInt128OrNull

導入バージョン: v20.8.0

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

例

使用例

Query

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

Response

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

​

toInt128OrZero

導入バージョン: v20.8.0

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

関連項目:

• toInt128.
• toInt128OrNull.
• toInt128OrDefault.

構文

toInt128OrZero(x)

引数

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

戻り値

変換後の入力値を返します。変換に失敗した場合は 0 を返します。Int128

例

使用例

Query

SELECT toInt128OrZero('123')

Response

123

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

Query

SELECT toInt128OrZero('abc')

Response

0

​

toInt16

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数:

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

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

この関数は ゼロ方向への丸め を使用します。つまり、数値の小数点以下の桁数を切り捨てます。

関連項目:

• toInt16OrZero。
• toInt16OrNull。
• toInt16OrDefault。

構文

toInt16(expr)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toInt16OrDefault

導入バージョン: v21.11.0

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

構文

toInt16OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

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

Response

-16

変換に失敗しました

Query

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

Response

-1

​

toInt16OrNull

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します) :

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

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

関連項目:

• toInt16。
• toInt16OrZero。
• toInt16OrDefault。

構文

toInt16OrNull(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toInt16OrZero

導入バージョン: v1.1.0

この関数は 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

例

使用例

Query

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

Response

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

​

toInt256

導入バージョン: v1.1.0

入力値を Int256 型の値に変換します。 エラーが発生した場合は例外をスローします。 この関数ではゼロ方向への丸めが使用されるため、数値の小数点以下の桁数は切り捨てられます。

サポートされる引数:

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

サポートされない引数:

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

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

関連項目:

• toInt256OrZero。
• toInt256OrNull。
• toInt256OrDefault。

構文

toInt256(expr)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toInt256OrDefault

導入バージョン: v21.11.0

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

構文

toInt256OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

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

Response

-256

変換に失敗

Query

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

Response

-1

​

toInt256OrNull

導入バージョン: v20.8.0

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

例

使用例

Query

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

Response

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

​

toInt256OrZero

導入バージョン: v20.8.0

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

関連項目:

• toInt256。
• toInt256OrNull。
• toInt256OrDefault。

構文

toInt256OrZero(x)

引数

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

戻り値

変換後の入力値を返します。変換に失敗した場合は 0 を返します。Int256

例

使用例

Query

SELECT toInt256OrZero('123')

Response

123

変換に失敗するとゼロを返します

Query

SELECT toInt256OrZero('abc')

Response

0

​

toInt32

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数:

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

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

この関数は ゼロ方向への丸め を使用します。つまり、数値の小数点以下の桁を切り捨てます。

関連項目:

• toInt32OrZero。
• toInt32OrNull。
• toInt32OrDefault。

構文

toInt32(expr)

引数

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

戻り値

32 ビットの整数値を返します。Int32

例

使用例

Query

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

Response

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

​

toInt32OrDefault

導入バージョン: v21.11.0

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

構文

toInt32OrDefault(expr[, default])

Arguments

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

戻り値

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

Examples

変換に成功した場合

Query

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

Response

-32

変換の失敗

Query

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

Response

-1

​

toInt32OrNull

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します) :

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

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

関連項目:

• toInt32。
• toInt32OrZero。
• toInt32OrDefault。

構文

toInt32OrNull(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toInt32OrZero

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数 (0 を返します) :

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

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

関連項目:

• toInt32。
• toInt32OrNull。
• toInt32OrDefault。

構文

toInt32OrZero(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toInt64

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数:

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

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

この関数は ゼロ方向への丸め を使用します。つまり、数値の小数部分を切り落とします。

関連項目:

• toInt64OrZero。
• toInt64OrNull。
• toInt64OrDefault。

構文

toInt64(expr)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toInt64OrDefault

導入バージョン: v21.11.0

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

構文

toInt64OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

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

Response

-64

変換に失敗した場合

Query

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

Response

-1

​

toInt64OrNull

導入バージョン: v1.1.0

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

例

使用例

Query

SELECT
    toInt64OrNull('-64'),
    toInt64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): \N

​

toInt64OrZero

導入バージョン: v1.1.0

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

関連項目:

• toInt64。
• toInt64OrNull。
• toInt64OrDefault。

構文

toInt64OrZero(x)

引数

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

戻り値

変換後の入力値を返します。変換に失敗した場合は 0 を返します。Int64

例

使用例

Query

SELECT toInt64OrZero('123')

Response

123

変換に失敗した場合、ゼロを返します

Query

SELECT toInt64OrZero('abc')

Response

0

​

toInt8

導入バージョン: v1.1.0

入力値を Int8 型の値に変換します。 エラー時には例外をスローします。

サポートされる引数:

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

サポートされない引数:

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

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

この関数は ゼロ方向への丸め を使用します。つまり、数値の小数点以下の桁数を切り捨てます。

関連項目:

• toInt8OrZero。
• toInt8OrNull。
• toInt8OrDefault。

構文

toInt8(expr)

引数

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

戻り値

8ビット整数値を返します。Int8

例

使用例

Query

SELECT
    toInt8(-8),
    toInt8(-8.8),
    toInt8('-8')
FORMAT Vertical

Response

Row 1:
──────
toInt8(-8):   -8
toInt8(-8.8): -8
toInt8('-8'): -8

​

toInt8OrDefault

導入バージョン: v21.11.0

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

構文

toInt8OrDefault(expr[, default])

引数

• expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
• default — 任意。パースに失敗した場合に返すデフォルト値。Int8

戻り値

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

例

変換に成功した場合

Query

SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))

Response

-8

変換に失敗した場合

Query

SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))

Response

-1

​

toInt8OrNull

導入バージョン: v1.1.0

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

例

使用例

Query

SELECT
    toInt8OrNull('-8'),
    toInt8OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt8OrNull('-8'):  -8
toInt8OrNull('abc'): \N

​

toInt8OrZero

導入バージョン: v1.1.0

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

例

使用例

Query

SELECT
    toInt8OrZero('8'),
    toInt8OrZero('abc')
FORMAT Vertical

Response

行 1:
──────
toInt8OrZero('8'): 8
toInt8OrZero('abc'): 0

​

toInterval

導入バージョン: v25.4.0

数値と単位を表す文字列から Interval 値を作成します。

この関数では、単位を文字列の引数として指定することで、1 つの関数から異なる型のインターバル (秒、分、時間、日、週、月、四半期、年) を統一的に作成できます。単位文字列では大文字と小文字は区別されません。

これは toIntervalSecond、toIntervalMinute、toIntervalDay などの型ごとの関数を呼び出すのと同等ですが、 単位を文字列パラメーターとして動的に指定できます。

構文

toInterval(value, unit)

引数

• value — 単位数を表す数値です。任意の数値型を指定できます。 Int8 or Int16 or Int32 or Int64 or UInt8 or UInt16 or UInt32 or UInt64 or Float32 or Float64
• unit — 時間の単位です。定数文字列である必要があります。有効な値は次のとおりです: ‘nanosecond’, ‘microsecond’, ‘millisecond’, ‘second’, ‘minute’, ‘hour’, ‘day’, ‘week’, ‘month’, ‘quarter’, ‘year’。 String

戻り値

指定した型のInterval値を返します。結果の型は単位に応じて、IntervalNanosecond、IntervalMicrosecond、IntervalMillisecond、IntervalSecond、IntervalMinute、IntervalHour、IntervalDay、IntervalWeek、IntervalMonth、IntervalQuarter、またはIntervalYearになります。 Interval

例

異なる単位のインターバルを作成する

Query

SELECT
    toInterval(5, 'second') AS seconds,
    toInterval(3, 'day') AS days,
    toInterval(2, 'month') AS months

Response

┌─seconds─┬─days─┬─months─┐
│ 5       │ 3    │ 2      │
└─────────┴──────┴────────┘

日付演算でインターバルを使用する

Query

SELECT
    now() AS current_time,
    now() + toInterval(1, 'hour') AS one_hour_later,
    now() - toInterval(7, 'day') AS week_ago

Response

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

動的な interval の生成

Query

SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)

Response

┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘

​

toIntervalDay

導入バージョン: v1.1.0

データ型 IntervalDay の n 日間の インターバル を返します。

構文

toIntervalDay(n)

引数

• n — 日数。整数またはその文字列表現、ならびに浮動小数点数。(U)Int* または Float* または String

戻り値

n 日の Interval を返します。Interval

例

使用例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result

Response

┌─────result─┐
│ 2025-06-20 │
└────────────┘

​

toIntervalHour

導入バージョン: v1.1.0

データ型 IntervalHour の、n 時間を表す インターバル を返します。

構文

toIntervalHour(n)

引数

• n — 時間数。整数またはその文字列表現、および浮動小数点数。Int* または UInt* または Float* または String

戻り値

n 時間の インターバル を返します。Interval

例

使用例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result

Response

┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘

​

toIntervalMicrosecond

導入バージョン: v22.6.0

データ型 IntervalMicrosecond の、n マイクロ秒を表す インターバル を返します。

構文

toIntervalMicrosecond(n)

引数

• n — マイクロ秒数。(U)Int* または Float* または String

戻り値

n マイクロ秒を表す インターバル を返します。Interval

例

使用例

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMicrosecond(30) AS interval_to_microseconds
SELECT date + interval_to_microseconds AS result

Response

┌─────────────────────result─┐
│ 2025-06-15 00:00:00.000030 │
└────────────────────────────┘

​

toIntervalMillisecond

導入バージョン: v22.6.0

データ型 IntervalMillisecond の n ミリ秒のインターバルを返します。

構文

toIntervalMillisecond(n)

引数

• n — ミリ秒数。(U)Int* または Float* または String

戻り値

n ミリ秒の Interval を返します。Interval

例

使用例

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMillisecond(30) AS interval_to_milliseconds
SELECT date + interval_to_milliseconds AS result

Response

┌──────────────────result─┐
│ 2025-06-15 00:00:00.030 │
└─────────────────────────┘

​

toIntervalMinute

導入バージョン: v1.1.0

n 分を表す、データ型 IntervalMinute の interval を返します。

構文

toIntervalMinute(n)

引数

• n — 分単位の数値。整数またはその文字列表現、および浮動小数点数。(U)Int* または Float* または String

戻り値

n 分の interval を返します。インターバル

例

使用例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalMinute(12) AS interval_to_minutes
SELECT date + interval_to_minutes AS result

Response

┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘

​

toIntervalMonth

導入バージョン: v1.1.0

データ型 IntervalMonth の n か月のインターバルを返します。

構文

toIntervalMonth(n)

引数

• n — 月数。(U)Int* または Float* または String

戻り値

n か月の Interval を返します。

例

使用例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result

Response

┌─────result─┐
│ 2025-07-15 │
└────────────┘

​

toIntervalNanosecond

導入バージョン: v22.6.0

データ型 IntervalNanosecond の、n ナノ秒を表す interval を返します。

構文

toIntervalNanosecond(n)

引数

• n — ナノ秒数。(U)Int* または Float* または String

戻り値

n ナノ秒の インターバル を返します。

例

使用例

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result

Response

┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘

​

toIntervalQuarter

導入バージョン: v1.1.0

データ型 IntervalQuarter の n 四半期の interval 値を返します。

構文

toIntervalQuarter(n)

引数

• n — 四半期の数。(U)Int* または Float* または String

戻り値

n 四半期を表す interval を返します。インターバル

例

使用例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result

Response

┌─────result─┐
│ 2025-09-15 │
└────────────┘

​

toIntervalSecond

導入バージョン: v1.1.0

データ型IntervalSecondのn秒のインターバルを返します。

構文

toIntervalSecond(n)

引数

• n — 秒数。整数、整数の文字列表現、または浮動小数点数。 (U)Int* または Float* または String

戻り値

n 秒の Interval を返します。

例

使用例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result

Response

┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘

​

toIntervalWeek

導入バージョン: v1.1.0

データ型 IntervalWeek の n 週間のインターバルを返します。

構文

toIntervalWeek(n)

引数

• n — 週数。(U)Int*、Float*、または String

戻り値

n 週間の インターバル を返します。Interval

例

使用例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result

Response

┌─────result─┐
│ 2025-06-22 │
└────────────┘

​

toIntervalYear

導入バージョン: v1.1.0

データ型IntervalYearの、n 年を表す interval 値を返します。

構文

toIntervalYear(n)

引数

• n — 年数。(U)Int* または Float* または String

戻り値

n 年の期間を表す インターバル を返します。

例

使用例

Query

WITH
    toDate('2024-06-15') AS date,
    toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result

Response

┌─────result─┐
│ 2025-06-15 │
└────────────┘

​

toLowCardinality

導入バージョン: v18.12.0

入力引数を、同じデータ型のLowCardinality版に変換します。

LowCardinality データ型から通常のデータ型に変換するには、CAST 関数を使用します。 例: CAST(x AS String)。

構文

toLowCardinality(expr)

引数

• expr — サポートされているデータ型のいずれかを返す式。String または FixedString または Date または DateTime または (U)Int* または Float*

戻り値

入力値を LowCardinality データ型に変換した結果を返します。LowCardinality

例

使用例

Query

SELECT toLowCardinality('1')

Response

┌─toLowCardinality('1')─┐
│ 1                     │
└───────────────────────┘

​

toString

導入バージョン: v1.1.0

値を文字列表現に変換します。 DateTime 引数の場合、この関数はタイムゾーン名を指定した 2 つ目の String 引数を取ることができます。

構文

toString(value[, timezone])

引数

• value — 文字列に変換する値。Any
• timezone — 省略可能。DateTime の変換に使用するタイムゾーン名。String

戻り値

入力値の文字列表現を返します。String

例

使用例

Query

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

Response

┌──────────────────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.0

String または FixedString 型の引数を受け取り、元の文字列を最初の null byte で切り詰めた String を返します。

null byte (\0) は文字列終端文字として扱われます。 この関数は、null byte が意味のある内容の終端を示す C 形式の文字列やバイナリデータの処理に役立ちます。

構文

toStringCutToZero(s)

引数

• s — 処理対象の String または FixedString。String または FixedString

戻り値

最初のヌルバイトより前の文字を含む String を返します。String

例

使用例

Query

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

Response

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

​

toTime

導入バージョン: v1.1.0

入力値を Time 型に変換します。 String、FixedString、DateTime、または深夜0時からの経過秒数を表す数値型からの変換をサポートします。

構文

toTime(x)

引数

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

戻り値

変換後の値を返します。Time

例

StringからTimeへの変換

Query

SELECT toTime('14:30:25')

Response

14:30:25

DateTimeからTimeへの変換

Query

SELECT toTime(toDateTime('2025-04-15 14:30:25'))

Response

14:30:25

整数からTimeへの変換

Query

SELECT toTime(52225)

Response

14:30:25

​

toTime64

導入バージョン: v25.6.0

入力値を Time64 型に変換します。 String、FixedString、DateTime64、または午前0時からの経過時間をマイクロ秒で表した数値型からの変換をサポートします。 時刻値をマイクロ秒精度で表現できます。

構文

toTime64(x)

引数

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

戻り値

入力値をマイクロ秒精度で変換した値を返します。Time64(6)

例

String から Time64 への変換

Query

SELECT toTime64('14:30:25.123456')

Response

14:30:25.123456

DateTime64 から Time64 への変換

Query

SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))

Response

14:30:25.123456

整数型から Time64 への変換

Query

SELECT toTime64(52225123456)

Response

14:30:25.123456

​

toTime64OrNull

導入バージョン: v25.6.0

入力値を Time64 型の値に変換します。エラーが発生した場合は NULL を返します。 toTime64 と同様ですが、変換エラー時には例外をスローせず、NULL を返します。

関連項目:

• toTime64
• toTime64OrZero

構文

toTime64OrNull(x)

引数

• x — 秒未満の精度を含む時刻の文字列表現。String

戻り値

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

例

使用例

Query

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

Response

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

​

toTime64OrZero

導入バージョン: v25.6.0

入力値を Time64 型の値に変換しますが、エラーが発生した場合は 00:00:00.000 を返します。 toTime64 と同様ですが、変換エラー時には例外をスローせず、代わりに 00:00:00.000 を返します。

構文

toTime64OrZero(x)

引数

• x — 秒未満の精度を含む時刻の文字列表現。String

戻り値

成功した場合は Time64 値を返し、失敗した場合は 00:00:00.000 を返します。Time64

例

使用例

Query

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

Response

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │             00:00:00.000 │
└────────────────────────────────┴──────────────────────────┘

​

toTimeOrNull

導入バージョン: v1.1.0

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

関連項目:

• toTime
• toTimeOrZero

構文

toTimeOrNull(x)

引数

• x — 時刻を表す文字列。String

戻り値

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

例

使用例

Query

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

Response

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

​

toTimeOrZero

導入バージョン: v1.1.0

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

構文

toTimeOrZero(x)

引数

• x — 時刻を表す文字列。String

戻り値

成功した場合は Time 型の値を返し、それ以外の場合は 00:00:00 を返します。Time

例

使用例

Query

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

Response

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

​

toUInt128

導入バージョン: v1.1.0

入力値を UInt128 型の値に変換します。 エラーが発生した場合は例外をスローします。 この関数ではゼロ方向への丸めが使用されるため、数値の小数点以下の桁は切り捨てられます。

サポートされる引数:

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

サポートされない引数:

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

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

関連項目:

• toUInt128OrZero。
• toUInt128OrNull。
• toUInt128OrDefault。

構文

toUInt128(expr)

引数

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

戻り値

128ビットの符号なし整数値を返します。UInt128

例

使用例

Query

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Response

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

​

toUInt128OrDefault

導入バージョン: v21.11.0

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

構文

toUInt128OrDefault(expr[, default])

Arguments

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

戻り値

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

Examples

変換に成功した場合

Query

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

Response

128

変換に失敗した場合

Query

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

Response

0

​

toUInt128OrNull

導入バージョン: v21.6.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します) :

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

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

関連項目:

• toUInt128。
• toUInt128OrZero。
• toUInt128OrDefault。

構文

toUInt128OrNull(x)

引数

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

戻り値

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

例

使用例

Query

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N

​

toUInt128OrZero

導入バージョン: v1.1.0

toUInt128 と同様に、この関数は入力値を UInt128 型の値に変換しますが、エラー時には 0 を返します。

サポートされる引数:

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

サポートされない引数 (0 を返します) :

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

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

関連項目:

• toUInt128。
• toUInt128OrNull。
• toUInt128OrDefault。

構文

toUInt128OrZero(x)

引数

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

戻り値

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

例

使用例

Query

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

​

toUInt16

導入バージョン: v1.1.0

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

対応する引数:

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

対応していない引数:

• NaN や Inf を含む、Float* 型の値の文字列表現。
• バイナリ値や16進値の文字列表現。例: SELECT toUInt16('0xc0fe');。

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

この関数はゼロ方向への丸めを使用します。つまり、数値の小数点以下の桁を切り捨てます。

関連項目:

• toUInt16OrZero。
• toUInt16OrNull。
• toUInt16OrDefault。

構文

toUInt16(expr)

引数

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

戻り値

16 ビットの符号なし整数値を返します。UInt16

例

使用例

Query

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Response

Row 1:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

​

toUInt16OrDefault

導入バージョン: v21.11.0

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

構文

toUInt16OrDefault(expr[, default])

引数

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

戻り値

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

例

変換が成功した場合

Query

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

Response

16

変換に失敗した場合

Query

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

Response

0

​

toUInt16OrNull

導入バージョン: v1.1.0

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

例

使用例

Query

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

Response

Row 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): \N

​

toUInt16OrZero

導入バージョン: v1.1.0

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

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数 (0 を返します):

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

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

関連項目:

• toUInt16。
• toUInt16OrNull。
• toUInt16OrDefault。

構文

toUInt16OrZero(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

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

​

toUInt256

導入バージョン: v1.1.0

入力値を UInt256 型の値に変換します。 エラー時には例外をスローします。 この関数ではゼロ方向への丸めを使用するため、数値の小数点以下の桁数は切り捨てられます。

サポートされる引数:

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

サポートされない引数:

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

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

関連項目:

• toUInt256OrZero.
• toUInt256OrNull.
• toUInt256OrDefault.

構文

toUInt256(expr)

引数

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

戻り値

256 ビットの符号なし整数値を返します。UInt256

例

使用例

Query

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Response

Row 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

​

toUInt256OrDefault

導入バージョン: v21.11.0

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

構文

toUInt256OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

Response

0

変換に失敗した場合

Query

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

Response

0

​

toUInt256OrNull

導入バージョン: v20.8.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します) :

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

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

関連項目:

• toUInt256.
• toUInt256OrZero.
• toUInt256OrDefault.

構文

toUInt256OrNull(x)

引数

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

戻り値

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

例

使用例

Query

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): \N

​

toUInt256OrZero

導入バージョン: v20.8.0

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

例

使用例

Query

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

​

toUInt32

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数:

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

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

この関数は ゼロ方向への丸め を使用します。つまり、数値の小数点以下を切り捨てます。

関連項目:

• toUInt32OrZero.
• toUInt32OrNull.
• toUInt32OrDefault.

構文

toUInt32(expr)

引数

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

戻り値

32 ビットの符号なし整数値を返します。UInt32

例

使用例

Query

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Response

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

​

toUInt32OrDefault

導入バージョン: v21.11.0

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

構文

toUInt32OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

Response

32

変換失敗

Query

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

Response

0

​

toUInt32OrNull

導入バージョン: v1.1.0

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 です。String

戻り値

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

例

使用例

Query

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

Response

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): \N

​

toUInt32OrZero

導入バージョン: v1.1.0

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

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数 (0 を返します):

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

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

関連項目:

• toUInt32.
• toUInt32OrNull.
• toUInt32OrDefault.

構文

toUInt32OrZero(x)

引数

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

戻り値

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

例

使用例

Query

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

Response

行 1:
──────
toUInt32OrZero('32'):  32
toUInt32OrZero('abc'): 0

​

toUInt64

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない型:

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

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

この関数は ゼロ方向への丸め を使用します。つまり、数値の小数点以下の桁を切り捨てます。

関連項目:

• toUInt64OrZero。
• toUInt64OrNull。
• toUInt64OrDefault。

構文

toUInt64(expr)

引数

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

戻り値

64 ビットの符号なし整数値を返します。UInt64

例

使用例

Query

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Response

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

​

toUInt64OrDefault

導入バージョン: v21.11.0

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

構文

toUInt64OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

Response

64

変換に失敗

Query

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

Response

0

​

toUInt64OrNull

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数 (NULL を返します) :

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

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

関連項目:

• toUInt64。
• toUInt64OrZero。
• toUInt64OrDefault。

構文

toUInt64OrNull(x)

引数

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

戻り値

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

例

使用例

Query

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): \N

​

toUInt64OrZero

導入バージョン: v1.1.0

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

例

使用例

Query

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

​

toUInt8

導入バージョン: v1.1.0

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

サポートされる引数:

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

サポートされない引数:

• NaN および Inf を含む、Float* 型の値の文字列表現。
• バイナリ値および16進数値の文字列表現。例: SELECT toUInt8('0xc0fe');。

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

この関数は rounding towards zero を使用します。つまり、数値の小数点以下の桁を切り捨てます。

関連項目:

• toUInt8OrZero。
• toUInt8OrNull。
• toUInt8OrDefault。

構文

toUInt8(expr)

引数

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

戻り値

8 ビットの符号なし整数値を返します。UInt8

例

使用例

Query

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Response

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

​

toUInt8OrDefault

導入バージョン: v21.11.0

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

構文

toUInt8OrDefault(expr[, default])

引数

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

戻り値

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

例

変換に成功した場合

Query

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

Response

8

変換に失敗した場合

Query

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

Response

0

​

toUInt8OrNull

導入バージョン: v1.1.0

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

例

使用例

Query

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): \N

​

toUInt8OrZero

導入バージョン: v1.1.0

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

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数 (0 を返します):

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

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

関連項目:

• toUInt8。
• toUInt8OrNull。
• toUInt8OrDefault。

構文

toUInt8OrZero(x)

引数

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

戻り値

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

例

使用例

Query

SELECT
    toUInt8OrZero('-8'),
    toUInt8OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

​

toUUID

導入バージョン: v1.1.0

String 型の値を UUID 値に変換します。

構文

toUUID(string)

引数

• string — UUID の文字列表現。String または FixedString

戻り値

UUID の文字列表現から UUID を返します。UUID

例

使用例

Query

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

Response

┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

​

toUUIDOrZero

導入バージョン: v20.12.0

入力値を UUID 型の値に変換しますが、エラーが発生した場合はゼロ UUID を返します。 toUUID と似ていますが、変換エラー時に例外をスローする代わりに、ゼロ UUID (00000000-0000-0000-0000-000000000000) を返します。

サポートされる引数:

• 標準形式 (8-4-4-4-12 桁の16進数) の UUID の文字列表現。
• ハイフンなし (32 桁の16進数) の UUID の文字列表現。

サポートされない引数 (ゼロ UUID を返します) :

• 無効な文字列形式。
• 文字列以外の型。

構文

toUUIDOrZero(x)

引数

• x — UUID の文字列表現。String

戻り値

成功した場合は UUID 値を返し、失敗した場合はゼロ UUID (00000000-0000-0000-0000-000000000000) を返します。UUID

例

使用例

Query

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

Response

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

​

toUnixTimestamp64Micro

導入バージョン: v20.5.0

DateTime64 を、固定のマイクロ秒精度を持つ Int64 値に変換します。 入力値は、その精度に応じて適切にスケールアップまたはスケールダウンされます。

出力値は入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Micro(value)

引数

• value — 任意の精度を持つ DateTime64 の値。DateTime64

戻り値

マイクロ秒単位の Unixタイムスタンプを返します。Int64

例

使用例

Query

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

Response

┌─toUnixTimestamp64Micro(dt64)─┐
│               1739489491011123 │
└────────────────────────────────┘

​

toUnixTimestamp64Milli

導入バージョン: v20.5.0

DateTime64 を、固定のミリ秒精度を持つ Int64 値に変換します。 入力値は、その精度に応じて適切にスケールアップまたはスケールダウンされます。

出力値は入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Milli(value)

引数

• value — 任意の精度を持つ DateTime64 値。DateTime64

戻り値

ミリ秒単位の Unix タイムスタンプを返します。Int64

例

使用例

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

Response

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

​

toUnixTimestamp64Nano

導入バージョン: v20.5.0

DateTime64 を、固定のナノ秒精度を持つ Int64 値に変換します。 入力値は、その精度に応じて適切に拡大または縮小されます。

出力値は、入力値のタイムゾーンではなく、UTC を基準にしています。

構文

toUnixTimestamp64Nano(value)

引数

• value — 任意の精度の DateTime64 値。DateTime64

戻り値

ナノ秒単位の Unix タイムスタンプを返します。Int64

例

使用例

Query

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

Response

┌─toUnixTimestamp64Nano(dt64)────┐
│            1739489491011123456 │
└────────────────────────────────┘

​

toUnixTimestamp64Second

導入バージョン: v24.12.0

DateTime64 を、秒単位の固定精度を持つ Int64 値に変換します。 入力値は、その精度に応じて適切にスケールアップまたはスケールダウンされます。

出力値は、入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Second(value)

引数

• value — 任意の精度を持つ DateTime64 型の値。DateTime64

戻り値

秒単位の Unixタイムスタンプを返します。Int64

例

使用例

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

Response

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘