カテゴリ：

変換関数 、 日付と時刻の関数

TO_TIMESTAMP / TO_TIMESTAMP_*

入力式を対応するタイムスタンプに変換します：

  • TO_TIMESTAMP_LTZ （現地時間帯のタイムスタンプ）

  • TO_TIMESTAMP_NTZ （タイムゾーンなしのタイムスタンプ）

  • TO_TIMESTAMP_TZ （タイムゾーン付きのタイムスタンプ）

注釈

TO_TIMESTAMP は、 TIMESTAMP_TYPE_MAPPING セッションパラメーターに基づいて、他のタイムスタンプ関数の1つにマップします。パラメーターのデフォルトは TIMESTAMP_NTZ であるため、 TO_TIMESTAMP はデフォルトで TO_TIMESTAMP_NTZ にマップされます。

こちらもご参照ください。

TRY_TO_TIMESTAMP / TRY_TO_TIMESTAMP_* 、

AS_TIMESTAMP_* 、 IS_TIMESTAMP_* 、

TO_DATE , DATE 、 TO_TIME , TIME

構文

timestampFunction ( <numeric_expr> [ , <scale> ] )

timestampFunction ( <date_expr> )

timestampFunction ( <timestamp_expr> )

timestampFunction ( <string_expr> [ , <format> ] )

timestampFunction ( '<integer>' )

timestampFunction ( <variant_expr> )
Copy

条件：

timestampFunction ::=
    TO_TIMESTAMP | TO_TIMESTAMP_LTZ | TO_TIMESTAMP_NTZ | TO_TIMESTAMP_TZ
Copy

引数

必須：

次のいずれか:

numeric_expr

Unixエポック（1970-01-01 00:00:00 UTC）の開始からの秒数（スケール= 0または存在しない場合）または秒の小数部（ミリ秒またはナノ秒など）。非整数の10進数式が入力されると、結果のスケールが継承されます。

date_expr

タイムスタンプに変換される日付。

timestamp_expr

別のタイムスタンプに変換されるタイムスタンプ（例： TIMESTAMP_LTZ を TIMESTAMP_NTZに変換）。

string_expr

タイムスタンプの抽出元の文字列。例: '2019-01-31 01:02:03.004'。

'integer'

整数を含む 文字列 に評価される式。例: '15000000'。文字列の大きさに応じて、秒、ミリ秒、マイクロ秒、またはナノ秒として解釈できます。詳細については、 使用上の注意 をご参照ください。

variant_expr

VARIANT 型の式。 VARIANT には次のいずれかが含まれている必要があります。

  • タイムスタンプの抽出元の文字列。

  • タイムスタンプ。

  • 秒、ミリ秒、マイクロ秒、またはナノ秒の数値を表す整数。

  • 秒、ミリ秒、マイクロ秒、またはナノ秒の数値を表す整数を含む文字列。

TO_TIMESTAMP は DATE 値を受け入れますが、 VARIANT内の DATE は受け入れません。

オプション:

format

フォーマット指定子（string_expr のみ）。詳細については、 変換関数の日付と時刻の形式 をご参照ください。

デフォルト値は、 TIMESTAMP_INPUT_FORMAT パラメーターの現在の値（デフォルトは AUTO）です。

scale

スケール指定子（numeric_expr のみ）。指定されている場合、提供される数値のスケールを定義します。例：

  • 秒の場合は、スケール= 0。

  • ミリ秒の場合は、スケール= 3。

  • マイクロ秒の場合は、スケール = 6。

  • ナノ秒の場合は、スケール= 9。

デフォルト: 0

戻り値

返される値のデータ型は、 TIMESTAMP データ型のいずれかです。デフォルトでは、データ型は TIMESTAMP_NTZ です。これを変更するには、セッションパラメーター TIMESTAMP_TYPE_MAPPING を設定します。

入力が NULL の場合、結果は NULL です。

使用上の注意

  • この関数ファミリーは、タイムスタンプ値を返します。詳細は次のとおりです。

    • string_expr の場合: 指定された文字列で表されるタイムスタンプ。文字列に時刻コンポーネントがない場合は、午前0時が使用されます。

    • date_expr の場合: 特定のタイムスタンプのマッピング（NTZ/LTZ/TZ）セマンティクスに従って、特定の日の午前0時を表すタイムスタンプが使用されます。

    • timestamp_expr の場合: 元のタイムスタンプのマッピングとは異なる可能性のあるタイムスタンプ型。

    • numeric_expr の場合: ユーザーが提供する秒数（または秒の小数部）を表すタイムスタンプ。UTC 時間は常に結果の作成に使用されます。

    • variant_expr の場合:

      • VARIANT に JSON のNULL値が含まれていると、結果は NULL になります。

      • VARIANT に結果と同じ種類のタイムスタンプ値が含まれている場合は、この値がそのまま保持されます。

      • VARIANT に異なる種類のタイムスタンプ値が含まれる場合は、 timestamp_expr と同じ方法で変換が実行されます。

      • VARIANT に文字列が含まれている場合は、文字列値からの変換が実行されます（自動フォーマットを使用）。

      • VARIANT に数字が含まれている場合は、 numeric_expr からの変換が実行されます。

        注釈

        INTEGER値が直接TIMESTAMP_NTZにキャストされると、整数はLinuxエポックの開始からの秒数として扱われ、ローカルタイムゾーンは考慮されません。ただし、以下に示す例のように INTEGER 値が VARIANT 値内に格納されている場合、変換は間接的であり、最終結果が TIMESTAMP_NTZ であってもローカルタイムゾーンの影響を受けます。

        SELECT TO_TIMESTAMP(31000000);
SELECT TO_TIMESTAMP(PARSE_JSON(31000000));
SELECT PARSE_JSON(31000000)::TIMESTAMP_NTZ;
        Copy

        最初のクエリが返すタイムスタンプは、2番目と3番目のクエリが返すタイムスタンプとは異なります。

        ローカルタイムゾーンとは独立して変換するには、以下に示すように、式の整数に明示的なキャストを追加します。

        SELECT TO_TIMESTAMP(31000000);
SELECT TO_TIMESTAMP(PARSE_JSON(31000000)::INT);
SELECT PARSE_JSON(31000000)::INT::TIMESTAMP_NTZ;
        Copy

        3つのクエリが返すタイムスタンプはすべて同じです。これは、 TIMESTAMP_NTZ にキャストするか、関数 TO_TIMESTAMP_NTZ を呼び出すかのいずれかに適用されます。 TIMESTAMP_TYPE_MAPPING パラメーターが TIMESTAMP_NTZ に設定されているときに、 TO_TIMESTAMP を呼び出す場合にも適用されます。

        出力の例については、このトピックの最後にある例をご参照ください。

    • 変換できない場合、エラーが返されます。

  • タイムゾーンのあるタイムスタンプの場合、 TIMEZONE パラメーターの設定は戻り値に影響します。返されるタイムスタンプは、セッションのタイムゾーンです。

  • 出力のタイムスタンプの表示形式は、関数（TIMESTAMP_OUTPUT_FORMAT、 TIMESTAMP_LTZ_OUTPUT_FORMAT、 TIMESTAMP_NTZ_OUTPUT_FORMAT、 または TIMESTAMP_TZ_OUTPUT_FORMAT）に対応するタイムスタンプ出力形式によって決定されます。

  • 入力パラメーターの形式が整数を含む文字列の場合：

    • 文字列が整数に変換された後、Unixエポックの開始後の秒数、ミリ秒、マイクロ秒、またはナノ秒として整数が扱われます（1970-01-01 00:00:00.000000000 UTC）。

      • 整数が31536000000（1年のミリ秒数）より小さい場合、値は秒数として扱われます。

      • 値が31536000000以上で31536000000000未満の場合、値はミリ秒として扱われます。

      • 値が31536000000000以上で31536000000000000より小さい場合、値はマイクロ秒として扱われます。

      • 値が31536000000000000以上の場合、値はナノ秒として扱われます。

    • 複数の行が評価される場合（例: 入力が複数の行を含むテーブルの列名である場合）、値が秒、ミリ秒、マイクロ秒、またはナノ秒を表しているかどうかを判断するために、各値が個別に検査されます。

  • TO_TIMESTAMP_NTZ または TRY_TO_TIMESTAMP_NTZ 関数を使用してタイムゾーン情報を含むタイムスタンプを変換すると、タイムゾーン情報が失われます。タイムスタンプをタイムゾーン情報付きのタイムスタンプに変換し直すと（例: TO_TIMESTAMP_TZ を使用して）、タイムゾーン情報は復元できません。

例

この例は、 TO_TIMESTAMP_TZ がセッションのタイムゾーンを含むタイムスタンプを作成しますが、 TO_TIMESTAMP_NTZ の値にはタイムゾーンがないことを示しています。

ALTER SESSION SET TIMEZONE = 'America/Los_Angeles';
Copy
SELECT TO_TIMESTAMP_TZ('2024-04-05 01:02:03');
Copy
+----------------------------------------+
| TO_TIMESTAMP_TZ('2024-04-05 01:02:03') |
|----------------------------------------|
| 2024-04-05 01:02:03.000 -0700          |
+----------------------------------------+

SELECT TO_TIMESTAMP_NTZ('2024-04-05 01:02:03');
Copy
+-----------------------------------------+
| TO_TIMESTAMP_NTZ('2024-04-05 01:02:03') |
|-----------------------------------------|
| 2024-04-05 01:02:03.000                 |
+-----------------------------------------+

次の例は、様々な形式があいまいな日付の解析にどのように影響するかを示しています。 TIMESTAMP_TZ_OUTPUT_FORMAT が設定されていないと推測されるため、 TIMESTAMP_OUTPUT_FORMAT が使用され、デフォルト（YYYY-MM-DD HH24:MI:SS.FF3 TZHTZM）に設定されます。

この例では、入力形式が mm/dd/yyyy hh24:mi:ss （月/日/年）の場合の結果を示しています。

SELECT TO_TIMESTAMP_TZ('04/05/2024 01:02:03', 'mm/dd/yyyy hh24:mi:ss');
Copy
+-----------------------------------------------------------------+
| TO_TIMESTAMP_TZ('04/05/2024 01:02:03', 'MM/DD/YYYY HH24:MI:SS') |
|-----------------------------------------------------------------|
| 2024-04-05 01:02:03.000 -0700                                   |
+-----------------------------------------------------------------+

この例では、入力形式が dd/mm/yyyy hh24:mi:ss （日/月/年）の場合の結果を示しています。

SELECT TO_TIMESTAMP_TZ('04/05/2024 01:02:03', 'dd/mm/yyyy hh24:mi:ss');
Copy
+-----------------------------------------------------------------+
| TO_TIMESTAMP_TZ('04/05/2024 01:02:03', 'DD/MM/YYYY HH24:MI:SS') |
|-----------------------------------------------------------------|
| 2024-05-04 01:02:03.000 -0700                                   |
+-----------------------------------------------------------------+

この例では、1970年1月1日の午前0時（Unixエポックの開始）からおよそ40年を表す数値入力の使用方法を示しています。スケールが指定されていないため、デフォルトのスケール 0 （秒）が使用されます。

ALTER SESSION SET TIMESTAMP_OUTPUT_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF9 TZH:TZM';
Copy
SELECT TO_TIMESTAMP_NTZ(40 * 365.25 * 86400);
Copy
+---------------------------------------+
| TO_TIMESTAMP_NTZ(40 * 365.25 * 86400) |
|---------------------------------------|
| 2010-01-01 00:00:00.000               |
+---------------------------------------+

この例は前述の例と似ていますが、 3 というスケール値を指定して、値をミリ秒として提供します。

SELECT TO_TIMESTAMP_NTZ(40 * 365.25 * 86400 * 1000 + 456, 3);
Copy
+-------------------------------------------------------+
| TO_TIMESTAMP_NTZ(40 * 365.25 * 86400 * 1000 + 456, 3) |
|-------------------------------------------------------|
| 2010-01-01 00:00:00.456                               |
+-------------------------------------------------------+

この例では、同じ数値に対して異なるスケール値を指定した場合に、結果がどのように変化するかを示しています。

SELECT TO_TIMESTAMP(1000000000, 0) AS "Scale in seconds",
       TO_TIMESTAMP(1000000000, 3) AS "Scale in milliseconds",
       TO_TIMESTAMP(1000000000, 6) AS "Scale in microseconds",
       TO_TIMESTAMP(1000000000, 9) AS "Scale in nanoseconds";
Copy
+-------------------------+-------------------------+-------------------------+-------------------------+
| Scale in seconds        | Scale in milliseconds   | Scale in microseconds   | Scale in nanoseconds    |
|-------------------------+-------------------------+-------------------------+-------------------------|
| 2001-09-09 01:46:40.000 | 1970-01-12 13:46:40.000 | 1970-01-01 00:16:40.000 | 1970-01-01 00:00:01.000 |
+-------------------------+-------------------------+-------------------------+-------------------------+

この例では、値の大きさに基づいて、入力に整数を含む文字列が使用されている場合に、関数が使用する単位（秒、ミリ秒、マイクロ秒、またはナノ秒）を決定する方法を示しています。

異なる範囲内の整数を含む文字列を使用してテーブルを作成し、ロードします。

CREATE OR REPLACE TABLE demo1 (
  description VARCHAR,
  value VARCHAR -- string rather than bigint
);

INSERT INTO demo1 (description, value) VALUES
  ('Seconds',      '31536000'),
  ('Milliseconds', '31536000000'),
  ('Microseconds', '31536000000000'),
  ('Nanoseconds',  '31536000000000000');
Copy

文字列を関数に渡します。

SELECT description,
       value,
       TO_TIMESTAMP(value),
       TO_DATE(value)
  FROM demo1
  ORDER BY value;
Copy
+--------------+-------------------+-------------------------+----------------+
| DESCRIPTION  | VALUE             | TO_TIMESTAMP(VALUE)     | TO_DATE(VALUE) |
|--------------+-------------------+-------------------------+----------------|
| Seconds      | 31536000          | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Milliseconds | 31536000000       | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Microseconds | 31536000000000    | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Nanoseconds  | 31536000000000000 | 1971-01-01 00:00:00.000 | 1971-01-01     |
+--------------+-------------------+-------------------------+----------------+

次の例では、値を TIMESTAMP_NTZ にキャストします。この例では、整数を使用する場合と整数を含むバリアントを使用する場合の動作の違いを示しています。

SELECT 0::TIMESTAMP_NTZ, PARSE_JSON(0)::TIMESTAMP_NTZ, PARSE_JSON(0)::INT::TIMESTAMP_NTZ;
Copy
+-------------------------+------------------------------+-----------------------------------+
| 0::TIMESTAMP_NTZ        | PARSE_JSON(0)::TIMESTAMP_NTZ | PARSE_JSON(0)::INT::TIMESTAMP_NTZ |
|-------------------------+------------------------------+-----------------------------------|
| 1970-01-01 00:00:00.000 | 1969-12-31 16:00:00.000      | 1970-01-01 00:00:00.000           |
+-------------------------+------------------------------+-----------------------------------+

返されたタイムスタンプは、最初の列と3番目の列の整数と整数にキャストされたバリアントでは一致しますが、2番目の列の整数にキャストされていないバリアントでは異なります。詳細については、 使用上の注意 をご参照ください。

この動作は、 TO_TIMESTAMP_NTZ 関数を呼び出すときにも当てはまります。

SELECT TO_TIMESTAMP_NTZ(0), TO_TIMESTAMP_NTZ(PARSE_JSON(0)), TO_TIMESTAMP_NTZ(PARSE_JSON(0)::INT);
Copy
+-------------------------+---------------------------------+--------------------------------------+
| TO_TIMESTAMP_NTZ(0)     | TO_TIMESTAMP_NTZ(PARSE_JSON(0)) | TO_TIMESTAMP_NTZ(PARSE_JSON(0)::INT) |
|-------------------------+---------------------------------+--------------------------------------|
| 1970-01-01 00:00:00.000 | 1969-12-31 16:00:00.000         | 1970-01-01 00:00:00.000              |
+-------------------------+---------------------------------+--------------------------------------+
言語: 日本語