TIMESTAMP_NS 型へのキャスト
説明
TIMESTAMP_NS の精度はナノ秒に固定され、取り得る範囲は厳密に [1677-09-21 00:12:43.145224192, 2262-04-11 23:47:16.854775807] です。精度パラメータは指定できません。
文字列値と数値では、通常 DATETIME と同じフィールドの対応付けを使用します。厳密キャストモードと非厳密キャストモードのどちらでも、TIMESTAMP_NS がサポートする文字列形式は、対応するモードの DATETIME とまったく同じです。文字列形式に関する唯一の違いは、小数秒の精度が TIMESTAMP_NS では最大九桁、DATETIME では最大六桁であることです。
構文
CAST(<source_expr> AS TIMESTAMP_NS)
TRY_CAST(<source_expr> AS TIMESTAMP_NS)
サポートされる変換元の型
| 変換元の型 | 変換動作 |
|---|---|
CHAR, VARCHAR, STRING | 対応する厳密または非厳密モードの DATETIME 文字列構文に従って日時文字列を解析します。小数秒は最大九桁まで扱えます。 |
| 整数型 | 値を短縮表記の日付または日時として解釈します。 |
FLOAT | 単精度の入力で実際に表現された値を使用します。有効桁数が失われると、桁数の多い短縮表記の日時が無効になる場合があります。 |
DOUBLE | 倍精度の入力で実際に表現された値を使用します。小数部は小数秒を表します。 |
DECIMAL 型 | 整数部を短縮表記の日付または日時として、小数部を小数秒として解釈します。 |
DATE | 00:00:00.000000000 を付加します。 |
DATETIME(p) | 暦上の日付と時刻を保持し、小数部をゼロで埋めて九桁にします。 |
TIME(p) | 現在の日付の午前零時に入力の時間幅を加算します。 |
TIMESTAMPTZ(p) | 時点を現在のセッションタイムゾーンに変換してから、タイムゾーンを取り除きます。 |
TIMESTAMP_NS | 値を変更せずに返します。 |
VARIANT | 互換性のあるスカラー値を取り出し、対応する文字列、数値、または日時の変換規則を適用します。 |
NULL | NULL を返します。 |
BOOLEAN、JSON、IP、バイナリ型、複合型など、サポートされない型からの変換は解析時に失敗します。これは値の変換エラーではなく型エラーであるため、非厳密モードの CAST でも TRY_CAST でも NULL には変わりません。
文字列からの変換
厳密モード
enable_strict_cast = true の場合、サポートされる形式と解析規則は、厳密モードでの DATETIME への文字列変換とまったく同じです。これには、日付と時刻のフィールド、二桁の年、省略された時刻フィールド、連続した数字、空白、タイムゾーン接尾辞に関する規則が含まれます。
非厳密モード
enable_strict_cast = false の場合、サポートされる形式と解析規則は、非厳密モードでの DATETIME への文字列変換とまったく同じです。厳密モードで有効な形式はすべて有効であり、非厳密モードの DATETIME で許容される追加の区切り文字や、先頭・末尾の空白も TIMESTAMP_NS で許容されます。
TIMESTAMP_NS へのキャストにおける両モードの違いは DATETIME と同じです。形式または値域のエラーは、厳密モードではエラーになり、非厳密モードでは NULL を返します。
小数秒
対応する DATETIME の文字列形式との唯一の違いは、サポートされる小数秒の精度です。
- 変換先のスケールは常に 9 です。小数部が九桁未満の場合は、右側をゼロで埋めます。
- 小数部が九桁を超える場合は、四捨五入します。十桁目が九桁目を切り上げるかどうかを決め、それ以降の桁は結果に影響しません。
- 丸めによる桁上がりは、秒、日付、年へ通常どおり繰り上がります。
- Doris は小数秒の丸めとタイムゾーン変換の後に、
TIMESTAMP_NSの範囲を検証します。
タイムゾーンの扱い
TIMESTAMP_NS はタイムゾーンを保存しません。
- タイムゾーン接尾辞がない場合、解析された暦上の日付と時刻を変更せずに保存します。
- 数値オフセット、UTC を表す記号、または IANA タイムゾーン名がある場合、Doris は入力の時点を現在のセッションタイムゾーンに変換し、得られた暦上の日付と時刻をタイムゾーンなしで保存します。
- 値を保存した後にセッションタイムゾーンを変更しても、保存済みの値は変わりません。
使用できるタイムゾーン接尾辞と名前については、DATETIME の文字列変換規則およびタイムゾーンを参照してください。
以下の例では、time_zone = '+08:00' とします。
| 文字列 | モード | 結果 | 説明 |
|---|---|---|---|
2024-02-29 12:34:56.123456 | 両方 | 2024-02-29 12:34:56.123456000 | 小数部を九桁になるまでゼロで埋めます。 |
2024-02-29 12:34:56.1234567894 | 両方 | 2024-02-29 12:34:56.123456789 | 十桁目が 5 未満のため、切り捨てます。 |
2024-02-29 12:34:56.1234567895 | 両方 | 2024-02-29 12:34:56.123456790 | 十桁目が 5 のため、切り上げます。 |
2024-02-29 12:34:56.9999999995 | 両方 | 2024-02-29 12:34:57.000000000 | 丸めによる桁上がりが次の秒に及びます。 |
2024-02-29T04:34:56.123456789Z | 両方 | 2024-02-29 12:34:56.123456789 | UTC からセッションタイムゾーンに変換し、タイムゾーンを取り除きます。 |
2023-7-4T9-5-3.1Z | 非厳密モードのみ | 2023-07-04 17:05:03.100000000 | 非厳密モードで許容される区切り文字と、先頭・末尾の空白を使用します。 |
2024-02-30 12:34:56 | 両方 | 無効 | 二月 30 日はグレゴリオ暦の日付ではありません。 |
2024-01-01 00:00:00.123.456 | 両方 | 無効 | 小数秒の構文が無効です。 |
境界値での丸め
丸めは最終的な範囲チェックの前に行われます。そのため、境界のすぐ外にある入力が丸めによって有効になる場合があります。一方、上限にある入力が切り上げによって無効になる場合もあります。
| 文字列 | 結果 |
|---|---|
1677-09-21 00:12:43.1452241914 | 無効：丸め後も下限を下回ります |
1677-09-21 00:12:43.1452241915 | 1677-09-21 00:12:43.145224192 |
2262-04-11 23:47:16.8547758074 | 2262-04-11 23:47:16.854775807 |
2262-04-11 23:47:16.8547758075 | 無効：丸め後に上限を超えます |
数値からの変換
すべての整数型、浮動小数点型、十進数型を TIMESTAMP_NS に変換できます。BOOLEAN はサポートされません。
整数部のフィールドへの対応付け、二桁の年に関する規則、有効な短縮表記は、数値から DATETIME への変換と同じです。具体的には、整数部の桁数が 3、4、5、6、8、14 桁の表記が有効です。小数部は小数秒を表します。
短縮表記の日時と小数部から得られる値は、TIMESTAMP_NS の範囲内でなければなりません。小数秒は、文字列入力と同じ四捨五入の規則に従い、正確に九桁になるようゼロで埋めるか丸めます。
整数型からの変換
整数型には小数部がありません。Doris は短縮表記の数値を各フィールドに対応付け、結果に .000000000 を付加します。
| 整数値 | 結果 | 説明 |
|---|---|---|
123 | 2000-01-23 00:00:00.000000000 | 三桁の短縮表記の日付です。 |
20240229 | 2024-02-29 00:00:00.000000000 | 八桁の短縮表記の日付です。 |
20240229123456 | 2024-02-29 12:34:56.000000000 | 十四桁の短縮表記の日時です。 |
16770921001243 | 無効 | 変換後の時刻が下限を下回ります。 |
22620412000000 | 無効 | 変換後の時刻が上限を超えます。 |
FLOAT からの変換
FLOAT では、キャスト前に単精度の入力で表現された十進数値を使用します。有効桁数が限られるため、通常は 14 桁の短縮表記の日時を表すには不十分で、桁数の多い入力では桁が失われて無効な日時になる場合があります。桁数の多い短縮表記の値には DOUBLE または DECIMAL を使用してください。
| FLOAT の入力式 | 厳密モードの結果 | 非厳密モードの結果 | 説明 |
|---|---|---|---|
CAST(123 AS FLOAT) | 2000-01-23 00:00:00.000000000 | 2000-01-23 00:00:00.000000000 | 表現された値は正確です。 |
CAST(20240229123456.125 AS FLOAT) | エラー | NULL | 有効桁数が失われ、表現された短縮表記の日時が無効になります。 |
DOUBLE からの変換
DOUBLE では、キャスト前に倍精度の入力で表現された十進数値を使用します。14 桁の短縮表記で示す TIMESTAMP_NS 値の整数部はすべて正確に表現できますが、二進数で正確に表現できない小数部は、変換前に丸められる場合があります。入力の小数部の各桁をすべて保持する必要がある場合は、DECIMAL を使用してください。
| DOUBLE の入力式 | 結果 | 説明 |
|---|---|---|
CAST(20240229123456.125 AS DOUBLE) | 2024-02-29 12:34:56.125000000 | 整数部と小数部のどちらも正確に表現できます。 |
DECIMAL からの変換
DECIMAL はリテラルの十進表現を保持します。ナノ秒精度を超える桁は、小数第九位で四捨五入します。
| DECIMAL の入力式 | 結果 | 説明 |
|---|---|---|
CAST(20240229123456.1234567895 AS DECIMAL(24, 10)) | 2024-02-29 12:34:56.123456790 | 小数部をナノ秒単位に丸めます。 |
エラー処理
厳密モードと非厳密モードでは、数値を同じ規則で各フィールドに対応付けます。表現された数値から範囲内の有効な TIMESTAMP_NS 値を得られない場合、厳密モードではエラーを報告し、非厳密モードでは NULL を返します。入力が NULL の場合は、どちらのモードでも NULL を返します。
日付・時刻型からの変換
DATE からの変換
Doris は入力の日付に 00:00:00.000000000 を付加してから、TIMESTAMP_NS の範囲をチェックします。下限の日付の午前零時は範囲外であるため、1677-09-21 は変換できません。変換できる最も早い DATE は 1677-09-22、最も遅い DATE は 2262-04-11 です。
入力の DATE | 結果 |
|---|---|
1677-09-21 | 無効 |
1677-09-22 | 1677-09-22 00:00:00.000000000 |
2262-04-11 | 2262-04-11 00:00:00.000000000 |
2262-04-12 | 無効 |
DATETIME からの変換
DATETIME と TIMESTAMP_NS はどちらもタイムゾーンを持たないため、Doris はタイムゾーンによる調整を行わず、暦上の日付と時刻を保持します。DATETIME(p) の小数部は、右側をゼロで埋めて九桁にします。変換元の値にない精度が新たに加わるわけではありません。
ゼロで埋めた結果は、TIMESTAMP_NS の範囲内でなければなりません。DATETIME の精度は最大でマイクロ秒であるため、下限の日付で変換できる最も早い値は 1677-09-21 00:12:43.145225、上限の日付で変換できる最も遅い値は 2262-04-11 23:47:16.854775 です。
入力の DATETIME(6) | 結果 |
|---|---|
1677-09-21 00:12:43.145224 | 無効 |
1677-09-21 00:12:43.145225 | 1677-09-21 00:12:43.145225000 |
2024-02-29 12:34:56.123456 | 2024-02-29 12:34:56.123456000 |
2262-04-11 23:47:16.854775 | 2262-04-11 23:47:16.854775000 |
2262-04-11 23:47:16.854776 | 無効 |
TIME からの変換
Doris はセッションタイムゾーンでの現在の日付の午前零時を起点として、符号付きの TIME の時間幅を加算します。時間幅によっては日付の境界をまたぎます。小数部の精度は最大でマイクロ秒であり、ゼロで埋めて九桁にします。その後、Doris は最終的な日時が TIMESTAMP_NS の範囲内かどうかをチェックします。
たとえば、現在の日付が 2025-04-29 の場合は次のようになります。
入力の TIME(6) | 結果 |
|---|---|
12:34:56.123456 | 2025-04-29 12:34:56.123456000 |
500:00:00.000000 | 2025-05-19 20:00:00.000000000 |
-128:00:00.000000 | 2025-04-23 16:00:00.000000000 |
この変換は現在の日付に依存するため、再現可能な暦上の日付が必要な場合は、代わりに明示的な DATE または DATETIME を使用してください。
TIMESTAMPTZ からの変換
Doris は表現された時点を現在のセッションタイムゾーンに変換し、タイムゾーンを取り除いてから、変換元の小数部をゼロで埋めて九桁にします。最終的なローカル日時は TIMESTAMP_NS の範囲内でなければなりません。
そのため、time_zone を変更するとキャスト結果が変わり、境界付近の値がサポート範囲に入ったり、範囲外になったりする場合があります。
SET time_zone = '+08:00';
SELECT CAST(CAST('2024-02-29 04:34:56.123456+00:00' AS TIMESTAMPTZ(6)) AS TIMESTAMP_NS) AS ts;
+-------------------------------+
| ts |
+-------------------------------+
| 2024-02-29 12:34:56.123456000 |
+-------------------------------+
TIMESTAMP_NS と VARIANT からの変換
TIMESTAMP_NS 値を同じ型にキャストしても、値は正確に保持されます。VARIANT に格納された互換性のある文字列、数値、日付、タイムスタンプの値には、上記の対応する規則が適用されます。タイムゾーン付きのタイムスタンプ値は現在のセッションタイムゾーンに変換され、タイムゾーンのないタイムスタンプ値は暦上の各フィールドが保持されます。互換性のない VARIANT の内容は、キャストモードに応じて NULL を返すか、エラーを報告します。
関連する変換
TIMESTAMP_NS から DATETIME(p) または TIMESTAMPTZ(p) に変換すると、小数部は変換先の精度に丸められます。たとえば、2024-02-29 12:34:56.123456789 を精度 6 に変換すると、2024-02-29 12:34:56.123457 になります。
TIMESTAMP_NS と DATETIME の値を比較、結合、CASE、COALESCE、または集合演算で組み合わせると、Doris は値を正確に保持できる場合に TIMESTAMP_NS を共通の型として使用します。
エラー処理
| 状況 | enable_strict_cast = true | enable_strict_cast = false | TRY_CAST |
|---|---|---|---|
| 無効な形式または暦上の値 | エラー | NULL | NULL |
TIMESTAMP_NS の範囲外の値 | エラー | NULL | NULL |
変換元の値が NULL | NULL | NULL | NULL |
| サポートされない変換元と変換先の型の組み合わせ | 解析エラー | 解析エラー | 解析エラー |
文字列入力では、enable_strict_cast によって、対応する厳密または非厳密モードの DATETIME 解析規則が選択され、変換失敗時の処理が決まります。数値入力では、エラー処理のみが変わり、数値の対応付けは両モードで同じです。
例
文字列をナノ秒精度に変換し、丸めを確認します。
SELECT
CAST('2024-02-29 12:34:56.123456' AS TIMESTAMP_NS) AS padded,
CAST('2024-02-29 12:34:56.1234567895' AS TIMESTAMP_NS) AS rounded;
+-------------------------------+-------------------------------+
| padded | rounded |
+-------------------------------+-------------------------------+
| 2024-02-29 12:34:56.123456000 | 2024-02-29 12:34:56.123456790 |
+-------------------------------+-------------------------------+
短縮表記の数値の日時を変換します。
SELECT CAST(CAST(20240229123456.1234567895 AS DECIMAL(24, 10)) AS TIMESTAMP_NS) AS ts;
+-------------------------------+
| ts |
+-------------------------------+
| 2024-02-29 12:34:56.123456790 |
+-------------------------------+
非厳密モードでは、無効な値や範囲外の値は NULL を返します。
SET enable_strict_cast = false;
SELECT
CAST('2024-02-30 00:00:00' AS TIMESTAMP_NS) AS invalid_date,
CAST('2262-04-11 23:47:16.8547758075' AS TIMESTAMP_NS) AS overflow;
+--------------+----------+
| invalid_date | overflow |
+--------------+----------+
| NULL | NULL |
+--------------+----------+