型変換関数

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

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

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

注記

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

例:

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

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

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

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

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

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

toString 関数に関する注意事項

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

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

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

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

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

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

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

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

例

クエリ:

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

結果：

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

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

CAST

導入バージョン: v1.1

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

構文

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

引数

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

戻り値

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

例

基本的な使用方法

SELECT CAST(42, 'String')

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

AS 句の使用

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

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

「::」構文の使用

SELECT '123'::UInt32

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

accurateCast

導入バージョン: v1.1

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

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

構文

accurateCast(x, T)

引数

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

返り値

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

例

成功した変換

SELECT accurateCast(42, 'UInt16')

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

文字列から数値への変換

SELECT accurateCast('123.45', 'Float64')

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

accurateCastOrDefault

導入バージョン: v21.1

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

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

構文

accurateCastOrDefault(x, T[, default_value])

引数

• x — 変換する値。Any
• T — 変換先のデータ型名。const String
• default_value — オプション。変換に失敗した場合に返されるデフォルト値。Any

戻り値

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

使用例

正常に変換できる場合

SELECT accurateCastOrDefault(42, 'String')

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

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

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

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

暗黙のデフォルト値を伴う変換失敗

SELECT accurateCastOrDefault('abc', 'UInt32')

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

accurateCastOrNull

導入バージョン: v1.1

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

この関数は、accurateCast の安全性と、より扱いやすいエラー処理を兼ね備えています。

構文

accurateCastOrNull(x, T)

引数

• x — 変換対象の値。Any
• T — 変換先データ型の名前。String

返される値

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

例

変換が成功する例

SELECT accurateCastOrNull(42, 'String')

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

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

SELECT accurateCastOrNull('abc', 'UInt32')

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

formatRow

導入: v20.7

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

注記

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

構文

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

引数

• format — テキスト形式。例えば CSV、TSV など。String
• x, y, ... — 式。Any

返り値

フォーマット済みの文字列（テキスト形式の場合は通常、改行文字で終端されます）。String

例

基本的な使用方法

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

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

カスタムフォーマットを使用

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

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

formatRowNoNewline

導入バージョン: v20.7

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

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

構文

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

引数

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

返される値

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

例

基本的な使い方

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

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

fromUnixTimestamp64Micro

導入バージョン: v20.5

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

入力値は、1970-01-01 00:00:00 UTC からの経過時間をマイクロ秒で表した Unix タイムスタンプとして扱われます。

構文

fromUnixTimestamp64Micro(value[, timezone])

引数

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

返される値

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

例

使用例

SELECT fromUnixTimestamp64Micro(1640995200123456)

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

fromUnixTimestamp64Milli

導入バージョン: v20.5

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

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

構文

fromUnixTimestamp64Milli(value[, timezone])

引数

• value — ミリ秒単位の Unix タイムスタンプ値。Int64
• timezone — 省略可。返される値のタイムゾーンを指定する文字列。String

戻り値

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

例

使用例

SELECT fromUnixTimestamp64Milli(1640995200123)

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

fromUnixTimestamp64Nano

導入バージョン: v20.5

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

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

注記

入力値はタイムゾーンを考慮せず、UTC タイムスタンプとして扱われる点に注意してください。

構文

fromUnixTimestamp64Nano(value[, timezone])

引数

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

返り値

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

例

使用例

SELECT fromUnixTimestamp64Nano(1640995200123456789)

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

fromUnixTimestamp64Second

導入バージョン: v24.12

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

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

構文

fromUnixTimestamp64Second(value[, timezone])

引数

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

戻り値

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

例

使用例

SELECT fromUnixTimestamp64Second(1640995200)

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

parseDateTime

導入バージョン: v23.3

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

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

構文

parseDateTime(time_string, format[, timezone])

別名: TO_UNIXTIME

引数

• time_string — DateTime として解釈される文字列。String
• format — time_string の解釈方法を指定するフォーマット文字列。String
• timezone — 省略可。タイムゾーン。String

戻り値

MySQL 形式のフォーマット文字列に従って、入力文字列から解釈された DateTime を返します。DateTime

例

使用例

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

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

parseDateTime32BestEffort

導入バージョン: v20.9

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

この関数は、ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 独自の形式およびそのほかのいくつかの日付と時刻の形式を解析します。

構文

parseDateTime32BestEffort(time_string[, time_zone])

引数

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

返り値

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

例

使用例

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

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

タイムゾーンあり

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

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

Unixタイムスタンプ

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

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

parseDateTime32BestEffortOrNull

導入バージョン: v20.9

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

構文

parseDateTime32BestEffortOrNull(time_string[, time_zone])

引数

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

返り値

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

例

使用例

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

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

parseDateTime32BestEffortOrZero

導入バージョン: v20.9

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

構文

parseDateTime32BestEffortOrZero(time_string[, time_zone])

引数

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

返される値

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

例

使用例

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

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

parseDateTime64

導入バージョン: v24.11

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

この関数は、DateTime64 に対する formatDateTime の逆関数です。 フォーマット文字列を用いて String 型の引数をパースし、1900 年から 2299 年までの日付をサブ秒精度で表現できる DateTime64 型を返します。

構文

parseDateTime64(time_string, format[, timezone])

引数

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

返される値

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

例

使用例

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

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

parseDateTime64BestEffort

導入バージョン: v20.1

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

構文

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

引数

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

戻り値

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

例

使用例

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

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

parseDateTime64BestEffortOrNull

導入バージョン: v20.1

parseDateTime64BestEffort と同様の動作をしますが、処理できない日付形式に遭遇した場合は NULL を返します。

構文

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

引数

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

戻り値

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

例

使用例

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

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

parseDateTime64BestEffortOrZero

導入バージョン: v20.1

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

構文

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

引数

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

返される値

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

例

使用例

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

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

parseDateTime64BestEffortUS

導入バージョン: v22.8

parseDateTime64BestEffort と同様ですが、あいまいな場合には米国式の日付形式（MM/DD/YYYY など）を優先して解釈します。

構文

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

引数

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

戻り値

あいまいな日付表現については米国式の日付形式を優先して解釈し、time_string を DateTime64 に変換した値を返します。DateTime64

例

使用例

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

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

parseDateTime64BestEffortUSOrNull

導入バージョン: v22.8

この関数は、あいまいな場合に US の日付形式（MM/DD/YYYY など）を優先し、処理できない日付形式に遭遇したときに NULL を返す点を除き、parseDateTime64BestEffort と同じです。

構文

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

引数

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

返り値

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

例

使用例

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

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

parseDateTime64BestEffortUSOrZero

導入バージョン: v22.8

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

構文

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

引数

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

戻り値

US 形式を優先してパースした結果として、time_string を DateTime64 に変換して返します。入力をパースできない場合は、ゼロ日付/日時 (1970-01-01 00:00:00.000) を返します。DateTime64

例

使用例

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

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

parseDateTime64InJodaSyntax

導入バージョン: v24.10

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

この関数は DateTime64 に対する formatDateTimeInJodaSyntax の逆関数です。 Joda 形式のフォーマット文字列を使って String 引数をパースします。結果として、1900 年から 2299 年までの日時をサブ秒精度で表現できる DateTime64 型を返します。

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

構文

parseDateTime64InJodaSyntax(time_string, format[, timezone])

引数

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

返される値

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

例

使用例

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

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

parseDateTime64InJodaSyntaxOrNull

導入バージョン: v24.10

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

構文

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

引数

• time_string — DateTime64 に変換する対象の文字列。String
• format — time_string の解析方法を指定する Joda 形式のフォーマット文字列。String
• timezone — 任意。タイムゾーン。String

返される値

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

例

使用例

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

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

parseDateTime64InJodaSyntaxOrZero

導入: v24.10

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

構文

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

引数

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

戻り値

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

例

使用例

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

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

parseDateTime64OrNull

導入バージョン: v24.11

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

構文

parseDateTime64OrNull(time_string, format[, timezone])

引数

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

戻り値

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

例

使用例

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

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

parseDateTime64OrZero

導入バージョン: v24.11

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

構文

parseDateTime64OrZero(time_string, format[, timezone])

引数

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

戻り値

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

例

使用例

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

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

parseDateTimeBestEffort

導入バージョン: v1.1

String 形式で表現された日付と時刻を DateTime データ型に変換します。 この関数は ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 独自のものやその他のいくつかの日付・時刻フォーマットを解析します。

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

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

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

構文

parseDateTimeBestEffort(time_string[, time_zone])

引数

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

返される値

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

例

使用例

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

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

タイムゾーンあり

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

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

UNIX タイムスタンプ

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

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

parseDateTimeBestEffortOrNull

導入バージョン: v1.1

parseDateTimeBestEffort と同様ですが、処理できない日付フォーマットに遭遇した場合には NULL を返します。 この関数は ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 独自のものやその他のいくつかの日付・時刻フォーマットをパースします。

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

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

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

構文

parseDateTimeBestEffortOrNull(time_string[, time_zone])

引数

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

返される値

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

例

使用例

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

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

parseDateTimeBestEffortOrZero

導入バージョン: v1.1

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

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

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

区切り文字を含むすべての形式については、月名をフルスペルまたは最初の 3 文字で指定したものもパースします。 年が指定されていない場合、現在の年と見なされます。

構文

parseDateTimeBestEffortOrZero(time_string[, time_zone])

引数

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

返される値

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

例

使用例

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

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

parseDateTimeBestEffortUS

導入バージョン: v1.1

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

構文

parseDateTimeBestEffortUS(time_string[, time_zone])

引数

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

戻り値

あいまいな場合には US の日付形式を優先して解釈し、time_string を DateTime として返します。DateTime

例

使用例

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

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

parseDateTimeBestEffortUSOrNull

導入バージョン: v1.1

parseDateTimeBestEffortUS 関数と同様ですが、処理できない日付形式に出会った場合は NULL を返します。

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

構文

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

引数

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

返される値

US 形式を優先して time_string を DateTime 型として返すか、入力を解析できない場合は NULL を返します。DateTime または NULL

例

使用例

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

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

parseDateTimeBestEffortUSOrZero

導入バージョン: v1.1

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

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

構文

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

引数

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

戻り値

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

例

使用例

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

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

parseDateTimeInJodaSyntax

導入バージョン: v23.3

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

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

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

構文

parseDateTimeInJodaSyntax(time_string, format[, timezone])

引数

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

戻り値

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

例

使用例

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

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

parseDateTimeInJodaSyntaxOrNull

導入バージョン: v23.3

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

構文

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

引数

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

戻り値

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

例

使用例

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

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

parseDateTimeInJodaSyntaxOrZero

導入バージョン: v23.3

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

構文

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

引数

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

返される値

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

例

使用例

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

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

parseDateTimeOrNull

導入: v23.3

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

構文

parseDateTimeOrNull(time_string, format[, timezone])

別名: str_to_date

引数

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

返り値

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

例

使用例

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

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

parseDateTimeOrZero

導入バージョン: v23.3

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

構文

parseDateTimeOrZero(time_string, format[, timezone])

引数

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

戻り値

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

例

使用例

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

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

reinterpret

導入バージョン: v1.1

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

構文

reinterpret(x, type)

引数

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

戻り値

変換先の型の値。Any

例

使用例

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

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

配列の例

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

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

reinterpretAsDate

導入バージョン: v1.1

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

構文

reinterpretAsDate(x)

引数

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

戻り値

日付。Date

例

使用例

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

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

reinterpretAsDateTime

導入バージョン: v1.1

入力値を DateTime 値として再解釈します（リトルエンディアンでの格納を想定）。Unix エポックである 1970-01-01 の開始時点からの経過日数として扱われます。

構文

reinterpretAsDateTime(x)

引数

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

戻り値

日付と時刻。DateTime

例

使用例

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

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

reinterpretAsFixedString

導入バージョン: v1.1

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

構文

reinterpretAsFixedString(x)

引数

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

返される値

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

例

使用例

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

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

reinterpretAsFloat32

導入バージョン: v1.1

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

構文

reinterpretAsFloat32(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsFloat64

導入: v1.1

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

構文

reinterpretAsFloat64(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsInt128

導入バージョン: v1.1

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

構文

reinterpretAsInt128(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsInt16

導入バージョン: v1.1

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

構文

reinterpretAsInt16(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsInt256

導入バージョン: v1.1

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

構文

reinterpretAsInt256(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsInt32

導入バージョン: v1.1

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

構文

reinterpretAsInt32(x)

引数

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

返される値

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

例

使用例

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

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

reinterpretAsInt64

導入バージョン: v1.1

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

構文

reinterpretAsInt64(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsInt8

導入バージョン: v1.1

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

構文

reinterpretAsInt8(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsString

導入バージョン: v1.1

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

構文

reinterpretAsString(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsUInt128

導入: v1.1

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

構文

reinterpretAsUInt128(x)

引数

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

返り値

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

例

使用例

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

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

reinterpretAsUInt16

導入バージョン: v1.1

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

構文

reinterpretAsUInt16(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsUInt256

導入バージョン: v1.1

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

構文

reinterpretAsUInt256(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsUInt32

導入バージョン: v1.1

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

構文

reinterpretAsUInt32(x)

引数

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

返り値

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

例

使用例

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

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

reinterpretAsUInt64

導入バージョン: v1.1

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

構文

reinterpretAsUInt64(x)

引数

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

戻り値

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

例

使用例

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

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

reinterpretAsUInt8

導入バージョン: v1.1

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

構文

reinterpretAsUInt8(x)

引数

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

返り値

再解釈された値 x を返します。型は UInt8 です。

例

使用例

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

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

reinterpretAsUUID

導入: v1.1

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

構文

reinterpretAsUUID(fixed_string)

引数

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

戻り値

UUID 型の値。UUID

例

String から UUID への変換

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

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

toBFloat16

導入バージョン: v1.1

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

関連項目:

• toBFloat16OrZero
• toBFloat16OrNull

構文

toBFloat16(expr)

引数

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

返される値

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

例

使用例

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

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

toBFloat16OrNull

導入バージョン: v1.1

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

サポートされる引数:

• 数値を表す文字列。

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

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

注記

この関数は、文字列表現からの変換時に精度が暗黙的に失われることを許容します。

関連項目:

• toBFloat16.
• toBFloat16OrZero.

構文

toBFloat16OrNull(x)

引数

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

返される値

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

例

使用例

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

\N
12.25
12.3125

toBFloat16OrZero

導入バージョン: v1.1

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

サポートされる引数:

• 数値を表す文字列表現。

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

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

注記

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

関連項目:

• toBFloat16。
• toBFloat16OrNull。

構文

toBFloat16OrZero(x)

引数

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

戻り値

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

例

使用例

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

0
12.25
12.3125

toBool

導入: v22.2

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

構文

toBool(expr)

引数

• expr — 数値または文字列を返す式。文字列の場合は、'true' または 'false'（大文字小文字は区別しない）を受け取ります。(U)Int* または Float* または String または Expression

戻り値

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

例

使用例

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

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

toDate

導入バージョン: v1.1

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

構文

toDate(x)

引数

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

戻り値

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

例

String から Date への変換

SELECT toDate('2025-04-15')

2025-04-15

DateTime を Date に変換

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

2025-04-15

整数を日付に変換

SELECT toDate(20297)

2025-07-28

toDate32

導入バージョン: v21.9

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

構文

toDate32(expr)

引数

• expr — 変換する値。String または UInt32 または Date

戻り値

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

例

範囲内の例

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

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

範囲外

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

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

toDate32OrDefault

導入バージョン: v21.11

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

構文

toDate32OrDefault(expr[, default])

引数

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

戻り値

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

例

変換が成功する例

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

1930-01-01

変換失敗

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

2020-01-01

toDate32OrNull

導入バージョン: v21.9

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

構文

toDate32OrNull(x)

引数

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

戻り値

処理が成功した場合は Date32 の値を返し、そうでない場合は NULL を返します。Date32 または NULL

例

使用例

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

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

toDate32OrZero

導入: v21.9

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

関連項目:

• toDate32
• toDate32OrNull
• toDate32OrDefault

構文

toDate32OrZero(x)

引数

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

戻り値

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

例

使用例

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

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

toDateOrDefault

導入バージョン: v21.11

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

構文

toDateOrDefault(expr[, default])

引数

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

戻り値

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

例

変換が成功する例

SELECT toDateOrDefault('2022-12-30')

2022-12-30

変換に失敗

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

2023-01-01

toDateOrNull

導入バージョン: v1.1

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

構文

toDateOrNull(x)

引数

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

戻り値

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

例

使用例

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

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

toDateOrZero

導入バージョン: v1.1

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

関連項目:

• toDate
• toDateOrNull
• toDateOrDefault

構文

toDateOrZero(x)

引数

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

戻り値

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

例

使用例

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

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

toDateTime

導入: v1.1

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

注記

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

構文

toDateTime(expr[, time_zone])

引数

• expr — 値。String、Int、Date、DateTime のいずれか。
• time_zone — タイムゾーン。String

戻り値

日時を返します。DateTime

例

使用例

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

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

toDateTime32

導入バージョン: v20.9

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

構文

toDateTime32(x[, timezone])

引数

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

返される値

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

例

値が範囲内にある場合

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

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

指定した精度の10進数として

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

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

タイムゾーン付き

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

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

toDateTime64

導入バージョン: v20.1

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

構文

toDateTime64(expr, scale[, timezone])

引数

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

戻り値

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

使用例

値が範囲内の場合

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

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

精度指定付きの Decimal として

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

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

タイムゾーン付き

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

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

toDateTime64OrDefault

導入バージョン: v21.11

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

構文

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

引数

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

戻り値

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

使用例

成功した変換の例

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

1976-10-18 00:00:00.300

変換に失敗した例

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

2000-12-31 23:00:00.000

toDateTime64OrNull

導入バージョン: v20.1

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

構文

toDateTime64OrNull(x)

引数

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

戻り値

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

例

使用例

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

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

toDateTime64OrZero

導入: v20.1

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

参照:

• toDateTime64。
• toDateTime64OrNull。
• toDateTime64OrDefault。

構文

toDateTime64OrZero(x)

引数

• x — サブ秒精度付きの日時を表す文字列。String

戻り値

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

例

使用例

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

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

toDateTimeOrDefault

導入バージョン: v21.11

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

構文

toDateTimeOrDefault(expr[, timezone, default])

引数

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

戻り値

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

例

変換成功の例

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

2022-12-30 13:44:17

変換に失敗

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

2023-01-01 00:00:00

toDateTimeOrNull

導入バージョン: v1.1

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

構文

toDateTimeOrNull(x)

引数

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

戻り値

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

例

使用例

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

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

toDateTimeOrZero

導入バージョン: v1.1

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

構文

toDateTimeOrZero(x)

引数

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

戻り値

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

例

使用例

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

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

toDecimal128

導入: v18.12

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

注記

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

構文

toDecimal128(expr, S)

引数

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

返される値

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

例

使用例

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

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

toDecimal128OrDefault

導入: v21.11

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

構文

toDecimal128OrDefault(expr, S[, default])

引数

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

戻り値

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

使用例

変換が成功する例

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

0.023809523809523808

変換失敗

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

-1

toDecimal128OrNull

導入バージョン: v20.1

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

サポートされる引数:

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

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

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

関連項目:

• toDecimal128.
• toDecimal128OrZero.
• toDecimal128OrDefault.

構文

toDecimal128OrNull(expr, S)

引数

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

返される値

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

例

使用例

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

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

toDecimal128OrZero

導入バージョン: v20.1

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

サポートされる引数:

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

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

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

注記

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

構文

toDecimal128OrZero(expr, S)

引数

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

戻り値

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

例

基本的な使用方法

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

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

toDecimal256

導入バージョン: v20.8

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

注記

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

構文

toDecimal256(expr, S)

引数

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

戻り値

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

例

使用例

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

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

toDecimal256OrDefault

導入バージョン: v21.11

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

構文

toDecimal256OrDefault(expr, S[, default])

引数

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

戻り値

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

使用例

正常に変換できる場合

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

0.023809523809523808

変換失敗

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

-1

toDecimal256OrNull

導入バージョン: v20.8

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

サポートされる引数:

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

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

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

関連項目:

• toDecimal256。
• toDecimal256OrZero。
• toDecimal256OrDefault。

構文

toDecimal256OrNull(expr, S)

引数

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

戻り値

変換に成功した場合は Decimal(76, S) の値を返し、それ以外の場合は NULL を返します。Decimal256(S) または NULL

例

使用例

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

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

toDecimal256OrZero

導入バージョン: v20.8

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

サポートされる引数:

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

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

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

注記

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

参照:

• toDecimal256。
• toDecimal256OrNull。
• toDecimal256OrDefault。

構文

toDecimal256OrZero(expr, S)

引数

• expr — 評価結果として数値、または数値の文字列表現を返す式。Expression
• S — 0〜76 の範囲のスケールパラメータで、数値の小数部が取り得る桁数を指定します。UInt8

返される値

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

例

使用例

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

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

toDecimal32

導入バージョン: v18.12

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

注記

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

構文

toDecimal32(expr, S)

引数

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

戻り値

戻り値の型は Decimal(9, S)（Decimal32(S)）です。

例

使用例

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

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

toDecimal32OrDefault

導入バージョン: v21.11

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

構文

toDecimal32OrDefault(expr, S[, default])

引数

• expr — 数値を表す文字列。String
• S — 0 から 9 の間のスケールパラメータ。数値の小数部が取り得る桁数の上限を指定します。UInt8
• default — 省略可能。型 Decimal32(S) への変換に失敗した場合に返すデフォルト値。Decimal32(S)

戻り値

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

例

変換が成功する例

SELECT toDecimal32OrDefault(toString(0.0001), 5)

0.0001

変換が失敗した場合

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

-1

toDecimal32OrNull

導入バージョン: v20.1

入力値を Decimal(9, S) 型の値に変換しますが、エラー時には NULL を返します。 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

例

使用例

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

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

toDecimal32OrZero

導入バージョン: v20.1

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

サポートされる引数:

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

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

• 型 Float* の NaN および Inf の値（大文字小文字は問わない）、またはその文字列表現。
• バイナリ値および 16 進数値の文字列表現。

注記

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

構文

toDecimal32OrZero(expr, S)

引数

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

返される値

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

例

使用例

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

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

toDecimal64

導入: v18.12

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

注記

変換では余分な桁が切り捨てられ、演算が浮動小数点命令で実行されるため、Float32/Float64 の入力を扱う際に予期しない動作になる可能性があります。 たとえば、toDecimal64(1.15, 2) は 1.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)

例

使用例

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

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

toDecimal64OrDefault

導入バージョン: v21.11

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

構文

toDecimal64OrDefault(expr, S[, default])

引数

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

返される値

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

例

変換が成功する例

SELECT toDecimal64OrDefault(toString(0.0001), 18)

0.0001

変換に失敗

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

-1

toDecimal64OrNull

導入バージョン: v20.1

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

サポートされる引数:

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

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

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

参照:

• toDecimal64。
• toDecimal64OrZero。
• toDecimal64OrDefault。

構文

toDecimal64OrNull(expr, S)

引数

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

戻り値

成功した場合は Decimal(18, S) 型の値を返し、それ以外の場合は NULL を返します。Decimal64(S) または NULL

例

使用例

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

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

toDecimal64OrZero

導入バージョン: v20.1

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

サポートされる引数:

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

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

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

注記

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

関連項目:

• toDecimal64。
• toDecimal64OrNull。
• toDecimal64OrDefault。

構文

toDecimal64OrZero(expr, S)

引数

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

返される値

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

例

使用例

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

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

toDecimalString

導入バージョン: v23.3

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

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

構文

toDecimalString(number, scale)

引数

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

戻り値

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

例

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

SELECT toDecimalString(2.1456, 2)

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

ゼロ埋め

SELECT toDecimalString(5, 3)

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

数値型の違い

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

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

toFixedString

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

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

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

構文

toFixedString(s, N)

引数

• s — 変換対象の文字列。String
• N — 返される FixedString の長さ。const UInt*

戻り値

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

例

使用例

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

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

toFloat32

導入バージョン: v1.1

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

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

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

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

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

関連項目:

• toFloat32OrZero。
• toFloat32OrNull。
• toFloat32OrDefault。

構文

toFloat32(expr)

引数

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

戻り値

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

例

使用例

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

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

toFloat32OrDefault

導入バージョン: v21.11

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

構文

toFloat32OrDefault(expr[, default])

引数

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

返り値

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

例

変換が成功する例

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

8

変換に失敗

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

0

toFloat32OrNull

導入: v1.1

入力値を 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 ビットの浮動小数点数を返し、失敗した場合は NULL を返します。Float32 または NULL

例

使用例

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

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

toFloat32OrZero

導入: v1.1

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

関連項目:

• toFloat32。
• toFloat32OrNull。
• toFloat32OrDefault。

構文

toFloat32OrZero(x)

引数

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

戻り値

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

例

使用例

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

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

toFloat64

導入バージョン: v1.1

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

サポートされる引数:

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

サポートされない引数:

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

関連項目:

• toFloat64OrZero。
• toFloat64OrNull。
• toFloat64OrDefault。

構文

toFloat64(expr)

引数

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

戻り値

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

例

使用例

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

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

toFloat64OrDefault

導入: v21.11

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

構文

toFloat64OrDefault(expr[, default])

引数

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

戻り値

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

例

変換が成功する例

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

8

変換に失敗

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

0

toFloat64OrNull

導入バージョン: v1.1

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

サポートされる引数:

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

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

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

関連項目:

• toFloat64。
• toFloat64OrZero。
• toFloat64OrDefault。

構文

toFloat64OrNull(x)

引数

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

戻り値

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

例

使用例

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

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

toFloat64OrZero

導入バージョン: v1.1

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

関連項目:

• toFloat64。
• toFloat64OrNull。
• toFloat64OrDefault。

構文

toFloat64OrZero(x)

引数

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

戻り値

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

例

使用例

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

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

toInt128

導入バージョン: v1.1

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

関連項目:

• toInt128OrZero
• toInt128OrNull
• toInt128OrDefault

構文

toInt128(expr)

引数

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

返される値

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

例

使用例

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

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

toInt128OrDefault

導入バージョン: v21.11

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

構文

toInt128OrDefault(expr[, default])

引数

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

戻り値

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

例

変換が成功する例

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

-128

変換に失敗

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

-1

toInt128OrNull

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

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

サポートされる引数:

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

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

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

注記

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

関連項目:

• toInt128。
• toInt128OrZero。
• toInt128OrDefault。

構文

toInt128OrNull(x)

引数

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

戻り値

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

例

使用例

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

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

toInt128OrZero

導入バージョン: v20.8

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

関連項目:

• toInt128。
• toInt128OrNull。
• toInt128OrDefault。

構文

toInt128OrZero(x)

引数

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

返り値

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

例

使用例

SELECT toInt128OrZero('123')

123

変換に失敗すると 0 を返す

SELECT toInt128OrZero('abc')

0

toInt16

導入バージョン: v1.1

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

注記

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

関連項目:

• toInt16OrZero。
• toInt16OrNull。
• toInt16OrDefault。

構文

toInt16(expr)

引数

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

返り値

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

例

使用例

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

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

toInt16OrDefault

導入バージョン: v21.11

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

構文

toInt16OrDefault(expr[, default])

引数

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

戻り値

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

例

変換が成功する場合

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

-16

変換失敗

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

-1

toInt16OrNull

導入バージョン: v1.1

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

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

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

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

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

注記

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

関連項目:

• toInt16.
• toInt16OrZero.
• toInt16OrDefault.

構文

toInt16OrNull(x)

引数

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

戻り値

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

例

使用例

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

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

toInt16OrZero

導入バージョン: v1.1

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

サポートされる引数:

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

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

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

注記

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

関連項目:

• toInt16。
• toInt16OrNull。
• toInt16OrDefault。

構文

toInt16OrZero(x)

引数

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

返される値

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

例

使用例

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

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

toInt256

導入バージョン: v1.1

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

関連項目:

• toInt256OrZero
• toInt256OrNull
• toInt256OrDefault

構文

toInt256(expr)

引数

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

返される値

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

例

使用例

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

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

toInt256OrDefault

導入バージョン: v21.11

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

構文

toInt256OrDefault(expr[, default])

引数

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

返される値

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

例

変換が成功する例

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

-256

変換に失敗

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

-1

toInt256OrNull

導入バージョン: v20.8

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

サポートされる引数:

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

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

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

注記

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

関連項目:

• toInt256。
• toInt256OrZero。
• toInt256OrDefault。

構文

toInt256OrNull(x)

引数

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

返り値

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

例

使用例

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

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

toInt256OrZero

導入バージョン: v20.8

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

関連項目:

• toInt256。
• toInt256OrNull。
• toInt256OrDefault。

構文

toInt256OrZero(x)

引数

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

戻り値

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

例

使用例

SELECT toInt256OrZero('123')

123

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

SELECT toInt256OrZero('abc')

0

toInt32

導入バージョン: v1.1

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

注記

この関数は rounding towards zero を使用します。これは、小数部を切り捨てることを意味します。

関連項目:

• toInt32OrZero
• toInt32OrNull
• toInt32OrDefault

構文

toInt32(expr)

引数

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

戻り値

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

例

使用例

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

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

toInt32OrDefault

導入バージョン: v21.11

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

構文

toInt32OrDefault(expr[, default])

引数

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

返される値

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

使用例

変換に成功する例

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

-32

変換に失敗

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

-1

toInt32OrNull

導入バージョン: v1.1

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

サポートされる引数:

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

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

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

注記

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

関連項目:

• toInt32。
• toInt32OrZero。
• toInt32OrDefault。

構文

toInt32OrNull(x)

引数

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

返される値

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

例

使用例

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

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

toInt32OrZero

導入バージョン: v1.1

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

サポートされる引数:

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

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

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

注記

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

関連項目:

• toInt32。
• toInt32OrNull。
• toInt32OrDefault。

構文

toInt32OrZero(x)

引数

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

返される値

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

例

使用例

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

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

toInt64

導入バージョン: v1.1

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

注記

この関数は rounding towards zero（ゼロ方向への丸め）を行います。つまり、小数部分の桁を切り捨てます。

関連項目:

• toInt64OrZero。
• toInt64OrNull。
• toInt64OrDefault。

構文

toInt64(expr)

引数

• expr — 数値、または数値の文字列表現を返す式。サポートされるもの: 型 (U)Int* の値およびその文字列表現、型 Float* の値。サポートされないもの: NaN や Inf を含む Float* 値の文字列表現、バイナリ値および 16 進値の文字列表現。Expression

戻り値

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

例

使用例

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

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

toInt64OrDefault

導入バージョン: v21.11

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

構文

toInt64OrDefault(expr[, default])

引数

• expr — 数値、または数値の文字列表現を返す式。String または (U)Int* または Float*
• default — オプション。解析に失敗した場合に返すデフォルト値。Int64

戻り値

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

例

変換が成功する例

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

-64

変換に失敗した場合

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

-1

toInt64OrNull

導入バージョン: v1.1

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

サポートされる引数:

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

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

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

注記

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

関連項目:

• toInt64。
• toInt64OrZero。
• toInt64OrDefault。

構文

toInt64OrNull(x)

引数

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

戻り値

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

例

使用例

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

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

toInt64OrZero

導入バージョン: v1.1

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

参照:

• toInt64
• toInt64OrNull
• toInt64OrDefault

構文

toInt64OrZero(x)

引数

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

戻り値

変換された入力値を返します。変換に失敗した場合は 0 を返します。返される型は Int64 です。

例

使用例

SELECT toInt64OrZero('123')

123

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

SELECT toInt64OrZero('abc')

0

toInt8

導入バージョン: v1.1

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

サポートされる引数:

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

サポートされない引数:

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

注記

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

注記

この関数はゼロ方向への丸めを使用し、小数部分の桁を切り捨てます。

関連項目:

• toInt8OrZero。
• toInt8OrNull。
• toInt8OrDefault。

構文

toInt8(expr)

引数

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

返される値

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

例

使用例

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

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

toInt8OrDefault

導入バージョン: v21.11

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

構文

toInt8OrDefault(expr[, default])

引数

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

返される値

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

例

変換が成功する例

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

-8

変換失敗

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

-1

toInt8OrNull

導入: v1.1

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

サポートされる引数:

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

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

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

注記

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

関連項目:

• toInt8。
• toInt8OrZero。
• toInt8OrDefault。

構文

toInt8OrNull(x)

引数

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

戻り値

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

例

使用例

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

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

toInt8OrZero

導入バージョン: v1.1

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

サポートされる引数:

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

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

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

注記

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

参照:

• toInt8。
• toInt8OrNull。
• toInt8OrDefault。

構文

toInt8OrZero(x)

引数

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

戻り値

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

例

使用例

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

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

toInterval

導入バージョン: v25.4

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

この関数は、単位を文字列引数として指定することで、単一の関数で さまざまな種類の間隔（秒、分、時間、日、週、月、四半期、年）を一貫した方法で作成できるようにします。単位文字列は大文字小文字を区別しません。

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

構文

toInterval(value, unit)

引数

• value — 単位の数を表す数値。いずれかの数値型を指定できます。Int8 または Int16 または Int32 または Int64 または UInt8 または UInt16 または UInt32 または UInt64 または Float32 または Float64
• unit — 時間の単位。定数文字列である必要があります。有効な値: 'nanosecond', 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'month', 'quarter', 'year'. String

返される値

指定された型の Interval 値を返します。結果の型は単位に依存し、IntervalNanosecond、IntervalMicrosecond、IntervalMillisecond、IntervalSecond、IntervalMinute、IntervalHour、IntervalDay、IntervalWeek、IntervalMonth、IntervalQuarter、または IntervalYear のいずれかになります。Interval

例

異なる単位の Interval を作成する

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

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

日付の計算に interval を使用する

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

┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00  │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘

動的な INTERVAL の生成

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

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

toIntervalDay

導入バージョン: v1.1

データ型 IntervalDay の n 日の時間間隔を返します。

構文

toIntervalDay(n)

引数

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

戻り値

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

例

使用例

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

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

toIntervalHour

導入バージョン: v1.1

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

構文

toIntervalHour(n)

引数

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

戻り値

n 時間の Interval を返します。Interval

例

使用例

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

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

toIntervalMicrosecond

導入バージョン: v22.6

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

構文

toIntervalMicrosecond(n)

引数

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

戻り値

n マイクロ秒の Interval 型の値を返します。

例

使用例

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

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

toIntervalMillisecond

導入バージョン: v22.6

n ミリ秒を表すデータ型 IntervalMillisecond の時間間隔を返します。

構文

toIntervalMillisecond(n)

引数

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

戻り値

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

例

使用例

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

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

toIntervalMinute

導入バージョン: v1.1

データ型 IntervalMinute の n 分を表す時間間隔を返します。

構文

toIntervalMinute(n)

引数

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

戻り値

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

例

使用例

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

┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘

toIntervalMonth

導入バージョン: v1.1

データ型 IntervalMonth の、n ヶ月の間隔を表す値を返します。

構文

toIntervalMonth(n)

引数

• n — 月数。(U)Int* または Float* または String

返り値

n か月のインターバルを返します。Interval

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result

┌─────result─┐
│ 2025-07-15 │
└────────────┘

toIntervalNanosecond

導入バージョン: v22.6

データ型 IntervalNanosecond の、n ナノ秒を表す時間間隔を返します。

構文

toIntervalNanosecond(n)

引数

• n — ナノ秒の数。(U)Int* または Float* または String

戻り値

n ナノ秒の Interval を返します。

例

使用例

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result

┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘

toIntervalQuarter

導入バージョン: v1.1

データ型 IntervalQuarter の n 四半期のインターバルを返します。

構文

toIntervalQuarter(n)

引数

• n — 四半期数。(U)Int* または Float* または String

返される値

n 四半期分の期間を表す Interval を返します。

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result

┌─────result─┐
│ 2025-09-15 │
└────────────┘

toIntervalSecond

導入バージョン: v1.1

データ型 IntervalSecond の、長さ n 秒の時間間隔を返します。

構文

toIntervalSecond(n)

引数

• n — 秒数。整数値、その文字列表現、または浮動小数点数。(U)Int* または Float* または String

返される値

n 秒の時間間隔を返します。Interval

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result

┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘

toIntervalWeek

導入バージョン: v1.1

データ型 IntervalWeek の n 週間の間隔を表す値を返します。

構文

toIntervalWeek(n)

引数

• n — 週数。(U)Int* または Float* または String

返される値

n 週間の間隔（Interval）を返します。

例

使用例

WITH
    toDate('2025-06-15') AS date,
    toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result

┌─────result─┐
│ 2025-06-22 │
└────────────┘

toIntervalYear

導入: v1.1

データ型 IntervalYear の n 年の期間を返します。

構文

toIntervalYear(n)

引数

• n — 年数。(U)Int*、Float*、または String

戻り値

n 年の Interval を返します。Interval

例

使用例

WITH
    toDate('2024-06-15') AS date,
    toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result

┌─────result─┐
│ 2025-06-15 │
└────────────┘

toLowCardinality

導入バージョン: v18.12

入力引数を、同一データ型に対応する LowCardinality 型に変換します。

ヒント

LowCardinality データ型から通常のデータ型に変換するには、CAST 関数を使用します。 例: CAST(x AS String)。

構文

toLowCardinality(expr)

引数

• expr — サポートされているいずれかのデータ型の値となる式。String または FixedString または Date または DateTime または (U)Int* または Float*

返される値

入力値を LowCardinality データ型に変換した値を返します。LowCardinality

例

使用例

SELECT toLowCardinality('1')

┌─toLowCardinality('1')─┐
│ 1                     │
└───────────────────────┘

toString

導入バージョン: v1.1

値を文字列表現に変換します。 DateTime 型の引数に対しては、タイムゾーン名を表す 2 番目の String 型引数を指定できます。

構文

toString(value[, timezone])

引数

• value — 文字列に変換する値。Any
• timezone — オプション。DateTime への変換に用いるタイムゾーン名。String

戻り値

入力値の文字列表現を返します。String

例

使用例

SELECT
    now() AS ts,
    time_zone,
    toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam  │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra    │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan  │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens     │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast    │ 2023-09-08 20:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘

toStringCutToZero

導入バージョン: v1.1

String または FixedString 型の引数を受け取り、最初のヌルバイトの位置で切り詰めた元の文字列のコピーを含む String を返します。

ヌルバイト (\0) は文字列終端として扱われます。 この関数は、ヌルバイトが有効な内容の終端を示す C 形式の文字列やバイナリデータを処理する際に有用です。

構文

toStringCutToZero(s)

引数

• s — 処理対象となる String または FixedString。String または FixedString

戻り値

最初のヌルバイトより前の文字からなる String を返します。String

例

使用例

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

toTime

導入: v1.1

入力値を型 Time に変換します。 String、FixedString、DateTime、または午前0時からの経過秒数を表す数値型からの変換をサポートします。

構文

toTime(x)

引数

• x — 変換する入力値。String、FixedString、DateTime、(U)Int*、または Float* のいずれか。

返り値

変換後の値を返します。Time

使用例

String 型から Time 型への変換

SELECT toTime('14:30:25')

14:30:25

DateTime から Time への型変換

SELECT toTime(toDateTime('2025-04-15 14:30:25'))

14:30:25

整数を Time 型に変換

SELECT toTime(52225)

14:30:25

toTime64

導入バージョン: v25.6

入力値を型 Time64 に変換します。 String、FixedString、DateTime64、または真夜中（0時）からの経過マイクロ秒数を表す数値型からの変換をサポートします。 時刻値に対してマイクロ秒単位の精度を提供します。

構文

toTime64(x)

引数

• x — 変換する入力値。String、FixedString、DateTime64、(U)Int*、または Float*

返される値

マイクロ秒単位の精度で変換された入力値を返します。Time64(6)

例

String 型から Time64 型への変換

SELECT toTime64('14:30:25.123456')

14:30:25.123456

DateTime64 から Time64 への変換

SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))

14:30:25.123456

整数から Time64 への型変換

SELECT toTime64(52225123456)

14:30:25.123456

toTime64OrNull

導入バージョン: v25.6

入力値を Time64 型に変換しますが、エラーが発生した場合は NULL を返します。 toTime64 と同様ですが、変換エラー時に例外をスローする代わりに NULL を返します。

関連項目:

• toTime64
• toTime64OrZero

構文

toTime64OrNull(x)

引数

• x — サブ秒精度付きの時刻の文字列表現。String

戻り値

成功した場合は Time64 型の値を返し、それ以外の場合は NULL を返します。Time64 または NULL

例

使用例

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

toTime64OrZero

導入されたバージョン: v25.6

入力値を Time64 型の値に変換しますが、エラーが発生した場合は 00:00:00.000 を返します。 toTime64 と同様ですが、変換エラー時に例外をスローする代わりに 00:00:00.000 を返します。

構文

toTime64OrZero(x)

引数

• x — サブ秒精度を持つ時刻を表す文字列。String

戻り値

成功した場合は Time64 値を返し、失敗した場合は 00:00:00.000 を返します。Time64

例

使用例

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │             00:00:00.000 │
└────────────────────────────────┴──────────────────────────┘

toTimeOrNull

導入バージョン: v1.1

入力値を Time 型の値に変換しますが、エラーが発生した場合は NULL を返します。 変換エラー時に例外をスローする代わりに NULL を返す点を除き、toTime と同様です。

関連項目:

• toTime
• toTimeOrZero

構文

toTimeOrNull(x)

引数

• x — 時刻を表す文字列。String

返される値

成功した場合は Time 型の値を返し、そうでない場合は NULL を返します。Time または NULL

例

使用例

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

toTimeOrZero

導入バージョン: v1.1

入力値を Time 型に変換しますが、エラーが発生した場合は 00:00:00 を返します。 toTime と同様に動作しますが、変換エラー時に例外をスローする代わりに 00:00:00 を返します。

構文

toTimeOrZero(x)

引数

• x — 時刻を表す文字列。String

戻り値

変換に成功した場合は Time 型の値を返し、失敗した場合は 00:00:00 を返します。Time

例

使用例

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

toUInt128

導入バージョン: v1.1

入力値を UInt128 型の値に変換します。 エラーが発生した場合には例外をスローします。 関数はゼロ方向への丸めを使用し、数値の小数桁を切り捨てます。

サポートされる引数:

• 型 (U)Int* の値またはその文字列表現。
• 型 Float* の値。

サポートされない引数:

• NaN や Inf を含む、型 Float* の値の文字列表現。
• SELECT toUInt128('0xc0fe'); のような、2進数および16進数値の文字列表現。

注記

入力値が UInt128 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。 これはエラーとは見なされません。

関連項目:

• toUInt128OrZero。
• toUInt128OrNull。
• toUInt128OrDefault。

構文

toUInt128(expr)

引数

• expr — 数値または数値を表す文字列を返す式。Expression

返される値

128 ビットの符号なし整数値を返します。UInt128

例

使用例

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

toUInt128OrDefault

導入バージョン: v21.11

toUInt128 と同様に、この関数は入力値を UInt128 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が指定されていない場合、エラーが発生したときは 0 が返されます。

構文

toUInt128OrDefault(expr[, default])

引数

• expr — 数値、または数値を表す文字列表現を返す式。String または (U)Int* または Float*
• default — 省略可。パースに失敗した場合に返すデフォルト値。UInt128

戻り値

変換に成功した場合は UInt128 型の値を返し、失敗した場合は指定されていればデフォルト値を、指定されていなければ 0 を返します。UInt128

例

変換が成功する例

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

128

変換に失敗

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

0

toUInt128OrNull

導入バージョン: v21.6

toUInt128 と同様に、この関数は入力値を UInt128 型の値に変換しますが、エラーが発生した場合には NULL を返します。

サポートされる引数:

• (U)Int* の文字列表現。

サポートされない引数（NULL を返す）:

• NaN や Inf を含む Float* 型の値の文字列表現。
• 2 進数および 16 進数値の文字列表現。例: SELECT toUInt128OrNull('0xc0fe');。

注記

入力値が UInt128 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローを起こします。 これはエラーとは見なされません。

関連項目:

• toUInt128。
• toUInt128OrZero。
• toUInt128OrDefault。

構文

toUInt128OrNull(x)

引数

• x — 数値を表す文字列。String

返される値

UInt128 型の値を返します。変換に失敗した場合は NULL を返します。UInt128 または NULL

例

使用例

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N

toUInt128OrZero

導入バージョン: v1.1

toUInt128 と同様に、この関数は入力値を UInt128 型の値に変換しますが、エラーが発生した場合には 0 を返します。

サポートされる引数:

• (U)Int* の文字列表現。

サポートされない引数（0 を返す）:

• NaN や Inf を含む Float* 値の文字列表現。
• 2 進数および 16 進数値の文字列表現（例: SELECT toUInt128OrZero('0xc0fe');）。

注記

入力値が UInt128 の範囲内で表現できない場合、結果のオーバーフローまたはアンダーフローが発生しますが、これはエラーとは見なされません。

関連項目:

• toUInt128。
• toUInt128OrNull。
• toUInt128OrDefault。

構文

toUInt128OrZero(x)

引数

• x — 数値を表す文字列。String

戻り値

変換に成功した場合は UInt128 型の値を返し、失敗した場合は 0 を返します。UInt128

例

使用例

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

toUInt16

導入バージョン: v1.1

入力値を UInt16 型の値に変換します。 エラーが発生した場合は例外をスローします。

サポートされる引数:

• (U)Int* 型の値またはその文字列表現。
• Float* 型の値。

サポートされない引数:

• NaN や Inf を含む、Float* 値の文字列表現。
• SELECT toUInt16('0xc0fe'); のような、2 進数値および 16 進数値の文字列表現。

注記

入力値が UInt16 の表現可能範囲外の場合、結果はオーバーフローまたはアンダーフローします。 これはエラーとは見なされません。 例: SELECT toUInt16(65536) == 0;。

注記

この関数はゼロ方向への丸めを行い、小数部分の桁を切り捨てます。

関連項目:

• toUInt16OrZero。
• toUInt16OrNull。
• toUInt16OrDefault。

構文

toUInt16(expr)

引数

• expr — 数値、または数値を表す文字列のいずれかを返す式。Expression

戻り値

16 ビット符号なし整数値を返します。UInt16

例

使用例

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Row 1:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

toUInt16OrDefault

導入バージョン: v21.11

toUInt16 と同様に、この関数は入力値を UInt16 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が渡されていない場合、エラー時には 0 が返されます。

構文

toUInt16OrDefault(expr[, default])

引数

• expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
• default — 省略可能。解析に失敗した場合に返されるデフォルト値。UInt16

戻り値

変換に成功した場合は UInt16 型の値を返します。失敗した場合は、デフォルト値が指定されていればその値を、指定されていなければ 0 を返します。UInt16

例

変換が成功する例

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

16

変換失敗

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

0

toUInt16OrNull

導入バージョン: v1.1

toUInt16 と同様に、この関数は入力値を UInt16 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（NULL を返す）:

• NaN や Inf を含む Float* 型の値の文字列表現。
• SELECT toUInt16OrNull('0xc0fe'); のような、2 進数および 16 進数値の文字列表現。

注記

入力値が UInt16 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローが発生します。 これはエラーとはみなされません。

関連項目:

• toUInt16。
• toUInt16OrZero。
• toUInt16OrDefault。

構文

toUInt16OrNull(x)

引数

• x — 数値を表す文字列。String

戻り値

変換が成功した場合は型 UInt16 の値を返し、失敗した場合は NULL を返します。UInt16 または NULL

例

使用例

SELECT
    toUInt16OrNull('16'),
    toUInt16OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): \N

toUInt16OrZero

導入バージョン: v1.1

toUInt16 と同様に、この関数は入力値を UInt16 型の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（0 を返す）:

• NaN や Inf を含む Float* 値の文字列表現。
• SELECT toUInt16OrZero('0xc0fe'); のような、バイナリ値および 16 進値の文字列表現。

注記

入力値が UInt16 の範囲内で表現できない場合、結果のオーバーフローまたはアンダーフローが発生します。 これはエラーとは見なされません。

関連項目:

• toUInt16。
• toUInt16OrNull。
• toUInt16OrDefault。

構文

toUInt16OrZero(x)

引数

• x — 数値の文字列表現。String

返される値

変換が成功した場合は UInt16 型の値を返し、変換に失敗した場合は 0 を返します。UInt16

例

使用例

SELECT
    toUInt16OrZero('16'),
    toUInt16OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt16OrZero('16'):  16
toUInt16OrZero('abc'): 0

toUInt256

導入バージョン: v1.1

入力値を UInt256 型の値に変換します。 エラーが発生した場合は例外をスローします。 この関数はゼロ方向への丸めを行い、数値の小数桁を切り捨てます。

サポートされる引数:

• 型 (U)Int* の値またはその文字列表現。
• 型 Float* の値。

サポートされない引数:

• NaN や Inf を含む、型 Float* の値の文字列表現。
• SELECT toUInt256('0xc0fe'); のような、2 進数および 16 進数の値の文字列表現。

注記

入力値が UInt256 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。 これはエラーとは見なされません。

関連項目:

• toUInt256OrZero。
• toUInt256OrNull。
• toUInt256OrDefault。

構文

toUInt256(expr)

引数

• expr — 数値または数値を表す文字列を返す式。Expression

戻り値

256 ビットの符号なし整数値を返します。UInt256

例

使用例

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Row 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

toUInt256OrDefault

導入: v21.11

toUInt256 と同様に、この関数は入力値を UInt256 型の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が渡されない場合、エラー時には 0 が返されます。

構文

toUInt256OrDefault(expr[, default])

引数

• expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
• default — 省略可能。解析（パース）に失敗した場合に返されるデフォルト値。UInt256

戻り値

成功した場合は UInt256 型の値を返し、失敗した場合は、指定されていればデフォルト値を、指定されていなければ 0 を返します。UInt256

例

変換が成功する例

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

0

変換に失敗した場合

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

0

toUInt256OrNull

導入バージョン: v20.8

toUInt256 と同様に、この関数は入力値を UInt256 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

• (U)Int* の文字列表現。

サポートされない引数（NULL を返す）:

• NaN および Inf を含む Float* 値の文字列表現。
• SELECT toUInt256OrNull('0xc0fe'); のような、2 進数および 16 進数の値を表す文字列表現。

注記

入力値が UInt256 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。 これはエラーとはみなされません。

参照:

• toUInt256。
• toUInt256OrZero。
• toUInt256OrDefault。

構文

toUInt256OrNull(x)

引数

• x — 数値を表す文字列。String

戻り値

変換が成功した場合は型 UInt256 の値を返し、失敗した場合は NULL を返します。UInt256 または NULL

例

使用例

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): \N

toUInt256OrZero

導入バージョン: v20.8

toUInt256 と同様に、この関数は入力値を UInt256 型の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

• (U)Int* 型の値の文字列表現。

サポートされない引数（0 を返す）:

• NaN や Inf を含む Float* 型の値の文字列表現。
• SELECT toUInt256OrZero('0xc0fe'); のような、2進数および16進数の値の文字列表現。

注記

入力値が UInt256 の範囲で表現できない場合、結果のオーバーフローまたはアンダーフローが発生します。 これはエラーとは見なされません。

関連項目:

• toUInt256。
• toUInt256OrNull。
• toUInt256OrDefault。

構文

toUInt256OrZero(x)

引数

• x — 数値を表す文字列。String

返される値

型 UInt256 の値。変換に失敗した場合は 0 を返します。UInt256

例

使用例

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

toUInt32

導入バージョン: v1.1

入力値を UInt32 型の値に変換します。 エラーが発生した場合は例外をスローします。

サポートされる引数:

• 型が (U)Int* の値、またはその文字列表現。
• 型が Float* の値。

サポートされない引数:

• NaN や Inf を含む、Float* 値の文字列表現。
• SELECT toUInt32('0xc0fe'); のような、2 進数および 16 進数値の文字列表現。

注記

入力値が UInt32 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。 これはエラーとはみなされません。 例: SELECT toUInt32(4294967296) == 0;

注記

この関数は ゼロ方向への丸め を使用し、小数部の桁を切り捨てます。

関連項目:

• toUInt32OrZero
• toUInt32OrNull
• toUInt32OrDefault

構文

toUInt32(expr)

引数

• expr — 数値または数値を表す文字列を返す式。Expression

戻り値

32 ビットの符号なし整数値を返します。UInt32

例

使用例

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

toUInt32OrDefault

導入バージョン: v21.11

toUInt32 と同様に、この関数は入力値を型 UInt32 の値に変換しますが、エラーが発生した場合はデフォルト値を返します。 default 値が渡されない場合は、エラー時に 0 が返されます。

構文

toUInt32OrDefault(expr[, default])

引数

• expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
• default — 省略可能。パースに失敗した場合に返す既定値。UInt32

戻り値

成功した場合は UInt32 型の値を返します。失敗した場合は、既定値が指定されていればその値を、指定されていなければ 0 を返します。UInt32

例

変換が成功する例

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

32

変換失敗

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

0

toUInt32OrNull

導入バージョン: v1.1

toUInt32 と同様に、この関数は入力値を UInt32 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（NULL を返す）:

• NaN や Inf を含む Float* 型の値の文字列表現。
• 2 進数および 16 進数値の文字列表現（例: SELECT toUInt32OrNull('0xc0fe');）。

注記

入力値が UInt32 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。 これはエラーとはみなされません。

参照:

• toUInt32。
• toUInt32OrZero。
• toUInt32OrDefault。

構文

toUInt32OrNull(x)

引数

• x — 数値を表す文字列。String

戻り値

変換に成功した場合は型 UInt32 の値を返し、失敗した場合は NULL を返します。UInt32 または NULL

例

使用例

SELECT
    toUInt32OrNull('32'),
    toUInt32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): \N

toUInt32OrZero

導入バージョン: v1.1

toUInt32 と同様に、この関数は入力値を UInt32 型の値に変換しますが、エラーが発生した場合には 0 を返します。

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（0 を返す）:

• NaN や Inf を含む Float* 値の文字列表現。
• SELECT toUInt32OrZero('0xc0fe'); のような、2 進数値や 16 進数値の文字列表現。

注記

入力値が UInt32 の範囲内で表現できない場合、結果がオーバーフローまたはアンダーフローします。 これはエラーとは見なされません。

関連項目:

• toUInt32。
• toUInt32OrNull。
• toUInt32OrDefault。

構文

toUInt32OrZero(x)

引数

• x — 数値を表す文字列。String

戻り値

変換に成功した場合は型 UInt32 の値を返し、失敗した場合は 0 を返します。UInt32

例

使用例

SELECT
    toUInt32OrZero('32'),
    toUInt32OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt32OrZero('32'):  32
toUInt32OrZero('abc'): 0

toUInt64

導入バージョン: v1.1

入力値をUInt64型の値に変換します。 エラーが発生した場合は例外をスローします。

サポートされる引数:

• 型 (U)Int* の値またはその文字列表現。
• 型 Float* の値。

サポートされない型:

• NaN や Inf を含む、Float* 値の文字列表現。
• バイナリ値および 16 進値の文字列表現（例: SELECT toUInt64('0xc0fe');）。

注記

入力値がUInt64の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。 これはエラーとは見なされません。 例: SELECT toUInt64(18446744073709551616) == 0;

注記

この関数はゼロ方向への丸めを行います。つまり、小数部の桁を切り捨てます。

関連項目:

• toUInt64OrZero。
• toUInt64OrNull。
• toUInt64OrDefault。

構文

toUInt64(expr)

引数

• expr — 数値または数値を表す文字列を返す式。Expression

戻り値

64 ビット符号なし整数値を返します。UInt64

例

使用例

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

toUInt64OrDefault

導入バージョン: v21.11

toUInt64 と同様に、この関数は入力値を UInt64 型の値に変換しますが、エラーが発生した場合にはデフォルト値を返します。 default 引数が渡されていない場合は、エラー時に 0 が返されます。

構文

toUInt64OrDefault(expr[, default])

引数

• expr — 数値、または数値を表す文字列を返す式です。String または (U)Int* または Float*
• default — 省略可能。パースに失敗した場合に返されるデフォルト値。UInt64

返される値

成功した場合は UInt64 型の値を返し、そうでない場合は、指定されていればデフォルト値を返し、指定されていなければ 0 を返します。UInt64

例

変換が成功する例

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

64

変換に失敗

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

0

toUInt64OrNull

導入バージョン: v1.1

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

例

使用例

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): \N

toUInt64OrZero

導入バージョン: v1.1

toUInt64 と同様に、この関数は入力値を型 UInt64 の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

• (U)Int* の文字列表現。

サポートされない引数（0 を返す）:

• NaN や Inf を含む Float* 値の文字列表現。
• SELECT toUInt64OrZero('0xc0fe'); のようなバイナリ値および 16 進値の文字列表現。

注記

入力値が UInt64 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローが発生します。 これはエラーとは見なされません。

関連項目:

• toUInt64。
• toUInt64OrNull。
• toUInt64OrDefault。

構文

toUInt64OrZero(x)

引数

• x — 数値を表す文字列。String

戻り値

変換に成功した場合は UInt64 型の値を返し、失敗した場合は 0 を返します。UInt64

例

使用例

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

toUInt8

導入バージョン: v1.1

入力値を UInt8 型に変換します。 エラーが発生した場合は例外をスローします。

サポートされる引数:

• 型 (U)Int* の値またはその文字列表現。
• 型 Float* の値。

サポートされない引数:

• NaN や Inf を含む、Float* 値の文字列表現。
• 2進数および16進数による値の文字列表現。例: SELECT toUInt8('0xc0fe');。

注記

入力値が UInt8 の範囲内で表現できない場合、結果のオーバーフローまたはアンダーフローが発生します。 これはエラーとは見なされません。 例: SELECT toUInt8(256) == 0;。

注記

この関数はゼロ方向への丸めを使用します。これは数値の小数部を切り捨てることを意味します。

関連項目:

• toUInt8OrZero。
• toUInt8OrNull。
• toUInt8OrDefault。

構文

toUInt8(expr)

引数

• expr — 数値、または数値を表す文字列を返す式。 Expression

戻り値

8ビット符号なし整数値を返します。 UInt8

例

使用例

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

toUInt8OrDefault

導入バージョン: v21.11

toUInt8 と同様に、この関数は入力値を UInt8 型の値に変換しますが、エラー発生時にはデフォルト値を返します。 default 引数が指定されていない場合、エラー発生時には 0 が返されます。

構文

toUInt8OrDefault(expr[, default])

引数

• expr — 数値、または数値を表す文字列を返す式。String または (U)Int* または Float*
• default — 省略可。変換に失敗した場合に返されるデフォルト値。UInt8

戻り値

成功した場合は UInt8 型の値を返し、失敗した場合は指定されていればデフォルト値を、指定されていなければ 0 を返します。UInt8

例

変換が成功する例

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

8

変換に失敗

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

0

toUInt8OrNull

導入バージョン: v1.1

toUInt8 と同様に、この関数は入力値を UInt8 型の値に変換しますが、エラーが発生した場合は NULL を返します。

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（NULL を返す）:

• NaN や Inf を含む、通常の Float* 値の文字列表現。
• 2 進数および 16 進数値の文字列表現。例: SELECT toUInt8OrNull('0xc0fe');。

注記

入力値が UInt8 の範囲内で表現できない場合、結果はオーバーフローまたはアンダーフローします。 この場合もエラーとは見なされません。

関連項目:

• toUInt8。
• toUInt8OrZero。
• toUInt8OrDefault。

構文

toUInt8OrNull(x)

引数

• x — 数値を表す文字列。String

戻り値

変換が成功した場合は型 UInt8 の値を返し、失敗した場合は NULL を返します。UInt8 または NULL

例

使用例

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): \N

toUInt8OrZero

導入バージョン: v1.1

toUInt8 と同様に、この関数は入力値を UInt8 型の値に変換しますが、エラーが発生した場合は 0 を返します。

サポートされる引数:

• (U)Int8/16/32/128/256 の文字列表現。

サポートされない引数（0 を返す）:

• 通常の Float* 型の値（NaN や Inf を含む）の文字列表現。
• 2 進数および 16 進数値の文字列表現（例: SELECT toUInt8OrZero('0xc0fe');）。

注記

入力値が UInt8 の範囲内で表現できない場合、結果がオーバーフローまたはアンダーフローします。 これはエラーとは見なされません。

参照:

• toUInt8。
• toUInt8OrNull。
• toUInt8OrDefault。

構文

toUInt8OrZero(x)

引数

• x — 数値を表す文字列。String

返り値

変換に成功した場合は UInt8 型の値を返し、失敗した場合は 0 を返します。UInt8

例

使用例

SELECT
    toUInt8OrZero('-8'),
    toUInt8OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

toUUID

バージョン v1.1 で導入。

String の値を UUID 型の値に変換します。

構文

toUUID(string)

引数

• string — UUID を表す文字列。String または FixedString

返される値

UUID の文字列表現から UUID 型の値を返します。UUID

例

使用例

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

toUUIDOrZero

導入バージョン: v20.12

入力値を UUID 型の値に変換しますが、エラーが発生した場合はゼロ UUID を返します。 toUUID と同様ですが、変換エラー時に例外をスローする代わりにゼロ UUID（00000000-0000-0000-0000-000000000000）を返します。

サポートされる引数:

• 標準形式の UUID の文字列表現（8-4-4-4-12 個の 16 進数）。
• ハイフンなしの UUID の文字列表現（32 個の 16 進数）。

サポートされない引数（ゼロ UUID を返す）:

• 無効な文字列形式。
• 文字列以外の型。

構文

toUUIDOrZero(x)

引数

• x — UUID を表す文字列表現。String

戻り値

成功した場合は UUID 値を返し、失敗した場合はゼロ UUID（00000000-0000-0000-0000-000000000000）を返します。UUID

例

使用例

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

toUnixTimestamp64Micro

導入バージョン: v20.5

DateTime64 を、マイクロ秒精度が固定された Int64 値に変換します。 入力値は、その精度に応じて適切にスケーリングされて拡大または縮小されます。

注記

出力値は、入力値のタイムゾーンではなく、UTC を基準にしています。

構文

toUnixTimestamp64Micro(value)

引数

• value — 任意の精度を持つ DateTime64 型の値。DateTime64

戻り値

マイクロ秒単位の Unix タイムスタンプを返します。Int64

例

使用例

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

┌─toUnixTimestamp64Micro(dt64)─┐
│               1739489491011123 │
└────────────────────────────────┘

toUnixTimestamp64Milli

導入バージョン: v20.5

DateTime64 を固定ミリ秒精度の Int64 値に変換します。 入力値は、その精度に応じて適切にスケールアップまたはスケールダウンされます。

注記

出力値は、入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Milli(value)

引数

• value — 任意の精度を持つ DateTime64 値。DateTime64

戻り値

ミリ秒単位の Unix タイムスタンプを返します。Int64

例

使用例

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

toUnixTimestamp64Nano

導入バージョン: v20.5

DateTime64 を、ナノ秒の固定精度を持つ Int64 値に変換します。 入力値は、その精度に応じて適切に拡大または縮小されます。

注記

出力値は、入力値のタイムゾーンではなく、UTC を基準としています。

構文

toUnixTimestamp64Nano(value)

引数

• value — 任意の精度を持つ DateTime64 値。DateTime64

戻り値

ナノ秒精度の Unix タイムスタンプを返します。Int64

例

使用例

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

┌─toUnixTimestamp64Nano(dt64)────┐
│            1739489491011123456 │
└────────────────────────────────┘

toUnixTimestamp64Second

導入バージョン: v24.12

DateTime64 を秒単位の固定精度を持つ Int64 値に変換します。 入力値は、その小数精度に応じて適切にスケールアップまたはスケールダウンされます。

注記

出力値は入力値のタイムゾーンではなく、UTC を基準とします。

構文

toUnixTimestamp64Second(value)

引数

• value — 任意の精度を持つ DateTime64 型の値。DateTime64

戻り値

秒単位の Unix タイムスタンプを返します。Int64

例

使用例

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘