カテゴリ:

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

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 , DATETO_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。

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

戻り値

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

使用上の注意

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

    • NULL 入力の場合、結果は NULLになります。

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

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

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

    • numeric_expr の場合: ユーザーが提供する秒数(または秒の小数部)を表すタイムスタンプ。 UTC 時間は常に結果の作成に使用されることに注意してください。

    • variant_expr の場合:

      • バリアントに JSON null 値が含まれる場合、結果は NULLになります。

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

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

      • バリアントに文字列が含まれている場合、文字列値からの変換が実行されます(自動フォーマットを使用)。

      • バリアントに数値が含まれている場合は、あたかも numeric_expr からのように変換されます。

        注釈

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

        select to_timestamp(parse_json(31000000));
        select parse_json(31000000)::timestamp_ntz;
        
        Copy

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

        select to_timestamp(parse_json(31000000)::int);
        select parse_json(31000000)::int::timestamp_ntz;
        
        Copy

        これは、 TIMESTAMP_NTZ にキャストするか、関数 TO_TIMESTAMP_NTZ()を呼び出すかのいずれかに適用されます。 TIMESTAMP_TYPE_MAPPING パラメーターが TIMESTAMP_NTZに設定されているときに、 TO_TIMESTAMP()を呼び出す場合にも適用されます。

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

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

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

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

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

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

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

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

      ご用心

      現在、負の値は常に秒として扱われます。例えば、-31536000000000000000は1970年の前の秒数として扱われますが、そのスケールは、ナノ秒として使用することを意図していることを示しています。

      この動作は将来変更される可能性があります。

      注釈

      非推奨の警告: Snowflakeの将来のバージョンでは、文字列化された整数値をミリ秒、マイクロ秒、ナノ秒ではなく、秒として自動的に解釈する可能性があります。Snowflakeは、整数を秒として解釈することが意図されている場合にのみ、整数を含む文字列で TO_DATE、 TO_TIME または TO_TIMESTAMP を呼び出すことをお勧めします。

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

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

ALTER SESSION SET TIMEZONE = 'America/Los_Angeles';
+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+
SELECT TO_TIMESTAMP_TZ('2013-04-05 01:02:03');
+----------------------------------------+
| TO_TIMESTAMP_TZ('2013-04-05 01:02:03') |
|----------------------------------------|
| 2013-04-05 01:02:03.000 -0700          |
+----------------------------------------+

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

これは、さまざまな形式があいまいな日付の解析にどのように影響するかを示しています:

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

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

これは、1970年1月1日の深夜( UNIX EPOCHの始まり)からおよそ40年を表す数値入力の使用方法を示しています:

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

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

ALTER SESSION SET TIMESTAMP_OUTPUT_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF9 TZH:TZM';
+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+
SELECT TO_TIMESTAMP_NTZ(40 * 365.25 * 86400 * 1000 + 456, 3);
+-------------------------------------------------------+
| TO_TIMESTAMP_NTZ(40 * 365.25 * 86400 * 1000 + 456, 3) |
|-------------------------------------------------------|
| 2010-01-01 00:00:00.456                               |
+-------------------------------------------------------+
Copy

この例は、値の大きさに基づいて、関数が使用する単位(秒、ミリ秒、マイクロ秒、またはナノ秒)を決定する方法を示しています。

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

CREATE TABLE demo1 (
    description VARCHAR,
    value VARCHAR -- yes, 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
    ;
+--------------+-------------------+-------------------------+----------------+
| 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     |
+--------------+-------------------+-------------------------+----------------+
Copy

次の例は、整数を使用する場合と整数を含むバリアントを使用する場合の動作の違いを示しています。

SELECT 0::TIMESTAMP_NTZ, PARSE_JSON(0)::TIMESTAMP_NTZ, PARSE_JSON(0)::INT::TIMESTAMP_NTZ;
+-------------------------+------------------------------+-----------------------------------+
| 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           |
+-------------------------+------------------------------+-----------------------------------+
Copy
SELECT TO_TIMESTAMP_NTZ(0), TO_TIMESTAMP_NTZ(PARSE_JSON(0)), TO_TIMESTAMP_NTZ(PARSE_JSON(0)::INT);
+-------------------------+---------------------------------+--------------------------------------+
| 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              |
+-------------------------+---------------------------------+--------------------------------------+
Copy