日付および時刻の入力/出力

このトピックの内容:

日付、時刻、およびタイムスタンプのセッションパラメーター

一連のセッションパラメーターは、日付、時刻、タイムスタンプデータがSnowflakeに出入りする方法、およびタイムゾーンをサポートするタイムおよびタイムスタンプ形式で使用されるタイムゾーンを決定します。

パラメーターは、アカウント、ユーザー、およびセッションレベルで設定できます。 SHOW PARAMETERS コマンドを実行して、現在のセッションのすべての操作に適用される現在のパラメーター設定を表示します。

入力形式

以下のパラメーターは、 COPY、 INSERT、および MERGE 操作を含む、 DMLで認識される日付、時刻、およびタイムスタンプの形式を定義します。

3つのパラメーターすべてのデフォルトは AUTO です。パラメーター値を AUTO に設定すると、Snowflakeは、 AUTO 検出でサポートされる形式 にリストされている形式のいずれかを使用して、入力式の日付、時刻、またはタイムスタンプ文字列を照合します。

  • 一致する形式が見つかった場合、Snowflakeは文字列を受け入れます。

  • 一致する形式が見つからない場合、Snowflakeはエラーを返します。

出力形式

次のパラメーターは、Snowflakeからの日付および時刻出力の形式を定義します。

さらに、次のパラメーターは TIMESTAMP データ型エイリアスを3つの TIMESTAMP_ *バリエーションのいずれかにマップします。

タイムゾーン

次のパラメーターはタイムゾーンを決定します。

日付、時刻、およびタイムスタンプのロード/アンロードのファイル形式オプション

Snowflakeは、入力および出力形式パラメーターとは別に、Snowflakeテーブルにデータをロードまたはアンロードするときに使用する、3つのファイル形式オプションを提供します。

  • DATE_FORMAT

  • TIME_FORMAT

  • TIMESTAMP_FORMAT

オプションは、 COPY コマンドで直接指定するか、 COPY コマンドで参照される名前付きステージまたはファイル形式オブジェクトで指定できます。指定するとこれらのオプションは、対応する入力形式(データのロード時)または出力形式(データのアンロード時)を上書きします。

データのロード

データのロードで使用する場合、オプションはステージングされたデータファイルの日付、時刻、およびタイムスタンプの文字列の形式を指定します。オプションは、 DATE_INPUT_FORMAT、 TIME_INPUT_FORMAT、または TIMESTAMP_INPUT_FORMAT パラメーター設定を上書きします。

これらのすべてのオプションのデフォルトは AUTOです。 COPY INTO <テーブル> コマンドは、 AUTO 検出でサポートされている形式 にリストされている形式のいずれかで、ステージングされたデータファイル内のすべての日付とタイムスタンプ文字列を照合しようとします。

  • 一致する形式が見つかった場合、Snowflakeは文字列を受け入れます。

  • 一致する形式が見つからない場合、Snowflakeはエラーを返し、 ON_ERROR コピーオプションに指定されたアクションを実行します。

警告

Snowflakeは、最も一般的な日付、時刻、およびタイムスタンプ形式の自動検出をサポートしています(以下のテーブルを参照)。ただし、一部の形式ではあいまいな結果が生成される場合があり、データのロードに AUTO を使用するとSnowflakeが誤った形式を適用する可能性があります。

データの正しいロードを保証するため、データロードのファイル形式オプションを明示的に設定することを、Snowflakeは 強く お勧めします。

データのアンロード

データのアンロードで使用する場合、オプションは、指定されたステージのファイルにアンロードされた日付、時刻、およびタイムスタンプに適用される形式を指定します。

これらすべてのオプションのデフォルトは AUTO です。つまり、Snowflakeは次のパラメーターで指定されたフォーマットを適用します。

  • DATE_OUTPUT_FORMAT

  • TIME_OUTPUT_FORMAT

  • TIMESTAMP_*_OUTPUT_FORMAT ( TIMESTAMP_TYPE_MAPPING の設定による)

AUTO 検出でサポートされている形式

Snowflakeは、そうするように指示された場合、日付、時刻、およびタイムスタンプの入力文字列について次の形式を自動的に検出して処理します。

注意

一部の文字列は、複数の形式に一致させることができます。例えば、「07-04-2016」は MM-DD-YYYYDD-MM-YYYY の両方と互換性がありますが、各形式で異なる意味を持ちます(7月4日と4月7日)。一致する形式が見つかった場合でも、ユーザーが意図したとおりに文字列が解析されることは 保証されたません

日付形式の自動検出は便利ですが、日付が誤って解釈される可能性が高くなります。Snowflakeは、自動日付検出に依存せず、形式を明示的に指定することを強くお勧めします。

日付形式

形式

メモ

ISO 日付形式

YYYY-MM-DD

2013-04-28

その他の日付形式

DD-MON-YYYY

17-DEC-1980

MM/DD/YYYY

12/17/1980

一般的なヨーロッパ形式(つまり、 DD/MM/YYYY)の日付をロードまたは操作すると、誤った日付が生成される可能性があります。たとえば、05/02/2013は、2013年2月5日ではなく、2013年5月2日と解釈される場合があります。

AUTO 日付フォーマットを使用する場合、ダッシュとスラッシュは交換できません。スラッシュは MM/DD/YYYY 形式を意味し、ダッシュは YYYY-MM-DD 形式を意味します。「2019/01/02」または「01-02-2019」などの文字列は、予想どおりに解釈されません。

時刻形式

形式

メモ

ISO 時刻形式

HH24:MI:SS.FFTZH:TZM

20:57:01.123456789+07:00

HH24:MI:SS.FF

20:57:01.123456789

HH24:MI:SS

20:57:01

HH24:MI

20:57

インターネット(RFC)時間形式

HH12:MI:SS.FF AM

07:57:01.123456789 AM

HH12:MI:SS AM

04:01:07 AM

HH12:MI AM

04:01 AM

AM フォーマット指定子は、 AM または PM のいずれかの値を許可します。

タイムスタンプ形式

形式

メモ

ISO タイムスタンプ形式

YYYY-MM-DD"T"HH24:MI:SS.FFTZH:TZM

2013-04-28T20:57:01.123456789+07:00

T を囲む二重引用符はオプションです(詳細については、この表の後のヒントをご参照ください)。

YYYY-MM-DD HH24:MI:SS.FFTZH:TZM

2013-04-28 20:57:01.123456789+07:00

YYYY-MM-DD HH24:MI:SS.FFTZH

2013-04-28 20:57:01.123456789+07

YYYY-MM-DD HH24:MI:SS.FF TZH:TZM

2013-04-28 20:57:01.123456789 +07:00

YYYY-MM-DD HH24:MI:SS.FF TZHTZM

2013-04-28 20:57:01.123456789 +0700

YYYY-MM-DD HH24:MI:SS TZH:TZM

2013-04-28 20:57:01 +07:00

YYYY-MM-DD HH24:MI:SS TZHTZM

2013-04-28 20:57:01 +0700

YYYY-MM-DD"T"HH24:MI:SS.FF

2013-04-28T20:57:01.123456

T を囲む二重引用符はオプションです(詳細については、この表の後のヒントをご参照ください)。

YYYY-MM-DD HH24:MI:SS.FF

2013-04-28 20:57:01.123456

YYYY-MM-DD"T"HH24:MI:SS

2013-04-28T20:57:01

T を囲む二重引用符はオプションです(詳細については、この表の後のヒントをご参照ください)。

YYYY-MM-DD HH24:MI:SS

2013-04-28 20:57:01

YYYY-MM-DD"T"HH24:MI

2013-04-28T20:57

T を囲む二重引用符はオプションです(詳細については、この表の後のヒントをご参照ください)。

YYYY-MM-DD HH24:MI

2013-04-28 20:57

YYYY-MM-DD"T"HH24

2013-04-28T20

T を囲む二重引用符はオプションです(詳細については、この表の後のヒントをご参照ください)。

YYYY-MM-DD HH24

2013-04-28 20

YYYY-MM-DD"T"HH24:MI:SSTZH:TZM

2013-04-28T20:57:01-07:00

T を囲む二重引用符はオプションです(詳細については、この表の後のヒントをご参照ください)。

YYYY-MM-DD HH24:MI:SSTZH:TZM

2013-04-28 20:57:01-07:00

YYYY-MM-DD HH24:MI:SSTZH

2013-04-28 20:57:01-07

YYYY-MM-DD"T"HH24:MITZH:TZM

2013-04-28T20:57+07:00

T を囲む二重引用符はオプションです(詳細については、この表の後のヒントをご参照ください)。

YYYY-MM-DD HH24:MITZH:TZM

2013-04-28 20:57+07:00

インターネット(RFC)タイムスタンプ形式

DY, DD MON YYYY HH24:MI:SS TZHTZM

Thu, 21 Dec 2000 16:01:07 +0200

DY, DD MON YYYY HH24:MI:SS.FF TZHTZM

Thu, 21 Dec 2000 16:01:07.123456789 +0200

DY, DD MON YYYY HH12:MI:SS AM TZHTZM

Thu, 21 Dec 2000 04:01:07 PM +0200

DY, DD MON YYYY HH12:MI:SS.FF AM TZHTZM

Thu, 21 Dec 2000 04:01:07.123456789 PM +0200

DY, DD MON YYYY HH24:MI:SS

Thu, 21 Dec 2000 16:01:07

DY, DD MON YYYY HH24:MI:SS.FF

Thu, 21 Dec 2000 16:01:07.123456789

DY, DD MON YYYY HH12:MI:SS AM

Thu, 21 Dec 2000 04:01:07 PM

DY, DD MON YYYY HH12:MI:SS.FF AM

Thu, 21 Dec 2000 04:01:07.123456789 PM

その他のタイムスタンプ形式

MM/DD/YYYY HH24:MI:SS

2/18/2008 02:36:48

一般的なヨーロッパ形式(つまり、 DD/MM/YYYY)の日付をロードまたは操作すると、誤った日付が生成される可能性があります。たとえば、05/02/2013は、2013年2月5日ではなく、2013年5月2日と解釈される場合があります。

DY MON DD HH24:MI:SS TZHTZM YYYY

Mon Jul 08 18:09:51 +0000 2013

ちなみに

一部のタイムスタンプ形式では、文字 T が日付と時刻の区切り文字として使用されます(例: 'YYYY-MM-DD"T"HH24:MI:SS')。

T を囲む二重引用符はオプションです。ただし、Snowflakeは、あいまいさを避けるために、 T (および他のリテラル)を二重引用符で囲むことをお勧めします。

二重引用符は、実際の値では なく 、書式指定子のみに含める必要があります。例:

SELECT TO_TIMESTAMP('2019-02-28T23:59:59', 'YYYY-MM-DD"T"HH24:MI:SS');

また、 T を囲む引用符は二重引用符である必要があります。

追加情報

以下のセクションでは、日付、時刻、およびタイムスタンプの個々のフィールドの要件とベストプラクティスについて説明します。

フィールドの有効な値の範囲

各フィールドの推奨値の範囲を以下に示します。

フィールド

メモ

00019999

一部のコンテキストでは、この範囲外の値が受け入れられる場合がありますが、Snowflakeはこの範囲内の値のみを使用することをお勧めします。例えば、0000年は受け入れられますが、グレゴリオ暦では西暦1年が紀元前1年の直後に来るため、誤っています。0年は存在しません。

0112

0131

31日未満の月の実際の最大値は、その月の日数です。

時間

0023

または、 HH12 形式を使用している場合は 0011

0059

0059

Snowflakeは、うるう秒またはダブルうるう秒をサポートしていません。値 60 および 61 は拒否されます。

分数

0999999999

小数点以下の桁数は、正確な書式指定子に一部依存します(たとえば、 FF3 は小数点以下3桁までサポートし、 FF9 は小数点以下9桁までサポート)。指定した数字よりも少ない数字を入力できます(例: FF9 を使用する場合でも1桁を許可)。フィールドを指定した幅まで埋めるための、後続のゼロは必要ありません。

書式要素で正しい桁数を使用する

ほとんどのフィールド(年、月、日、時間、分、秒)の場合、書式指定子の要素(YYYYMMDD など)は2または4文字です。

リテラル値で実際に指定する必要がある桁数のルールが次に示されています。

  • YYYY:年には、1桁、2桁、3桁、または4桁を指定できます。ただし、Snowflakeは4桁を指定することをお勧めします。必要に応じて、先頭にゼロを追加します。たとえば、西暦536は「0536」になります。

  • YY:年には、1桁または2桁を指定します。ただし、Snowflakeは2桁を指定することをお勧めします。必要に応じて、先頭にゼロを追加します。

  • MM:1桁または2桁を指定します。例えば、1月は「01」または「1」として表すことができます。Snowflakeでは、2桁の数字を使用することをお勧めします。

  • DD:1桁または2桁を指定します。Snowflakeでは、2桁の数字を使用することをお勧めします。

  • HH:1桁または2桁を指定します。Snowflakeでは、2桁の数字を使用することをお勧めします。

  • MI:1桁または2桁を指定します。Snowflakeでは、2桁の数字を使用することをお勧めします。

  • SS:1桁または2桁を指定します。Snowflakeでは、2桁の数字を使用することをお勧めします。

  • FF9:1〜9桁(この値を含む)の間で指定します。Snowflakeは、実際の有効な桁数を指定することをお勧めします。後続のゼロは必要ありません。

  • TZH:1桁または2桁を指定します。Snowflakeでは、2桁の数字を使用することをお勧めします。

  • TZM:1桁または2桁を指定します。Snowflakeでは、2桁の数字を使用することをお勧めします。

すべてのフィールド(秒の小数部を除く)について、Snowflakeは最大桁数を指定することをお勧めします。必要に応じて先行ゼロを使用します。たとえば、「0001-02-03 04:05:06 -07:00」は推奨形式に従っています。

秒の小数部の場合、後続のゼロはオプションです。一般に、信頼できて意味のある桁数のみを指定することをお勧めします。たとえば、時間の測定値が3小数点以下の精度(ミリ秒)である場合、9桁(例:「.123000000」)と指定すると誤解を招く可能性があります。

値と書式指定子の空白

Snowflakeは、すべてではないものの、一部の状況で空白のマッチングを強制します。たとえば、次のステートメントは指定された値の日と時間の間にスペースがないためエラーを生成しますが、書式指定子の DDHH の間にはスペースがあります。

SELECT TO_TIMESTAMP('2019-02-2823:59:59 -07:00', 'YYYY-MM-DD HH24:MI:SS TZH:TZM');

ただし、次のステートメントでは、指定子にない空白が値に含まれていてもエラーを生成しません。

SELECT TO_TIMESTAMP('2019-02-28 23:59:59.000000000 -07:00', 'YYYY-MM-DDHH24:MI:SS.FF TZH:TZM');

異なる原因は、前者の場合、フィールドがすべて最大幅ではない場合に値があいまいになるためです。たとえば、「213」は2日と13時間、または21日と3時間と解釈できます。ただし、 DDHH は、 DD HH と明らかに同一です(空白以外)。

ちなみに

さまざまな形式のデータを処理するために一部の空白の違いが許容されますが、Snowflakeは、値と指定子がスペースを含めて完全に一致することをお勧めします。

コンテキスト依存

すべてのコンテキストですべての制限が等しく適用されるわけではありません。例えば、2月31日をロールオーバーする式と、しない式の場合があります。

ベストプラクティスの概要

これらのベストプラクティスは、Snowflakeの過去、現在、および将来のバージョンのあいまいさおよびその他の潜在的な問題を最小限に抑えます。

  • 異なる形式を使用するソースからのデータが混在する恐れに注意してください(例: 一般的な米国形式 MM-DD-YYYY に従うデータと、一般的なヨーロッパ形式 DD-MM-YYYY に従うデータ)。

  • 各フィールドの最大桁数を指定します(小数秒を除く)。たとえば、4桁の年を使用し、必要に応じて先頭にゼロを指定します。

  • タイムスタンプの日付と時刻の間に空白または文字 T を指定します。

  • 空白(およびオプションの日付と時刻の T 区切り文字)は、値と形式指定子が同じである必要があります。

  • ロールオーバーと同等のものが必要な場合は、区間演算を使用します。

  • AUTO フォーマットを使用する場合は注意してください。可能な場合は、形式を指定し、値が常に指定された形式と一致するようにします。

  • コマンドで形式を指定する方が、例えば DATE_INPUT_FORMATなどのパラメーターでコマンドの外部で形式を指定するよりも安全です。(以下をご参照ください。)

  • スクリプトをある環境から別の環境に移動するときは、 DATE_INPUT_FORMAT などの日付関連のパラメーターが古い環境と同じであることを確認してください(値も同じ形式であると想定)。

日付と時刻の関数

Snowflakeには、 DATE/TIME/TIMESTAMP データを作成、変換、抽出、または変更するための一連の関数が用意されています。詳細については、 日付と時刻の関数 をご参照ください。

AUTO 整数で保存された日付、時刻、タイムスタンプ値の検出

文字列に保存された秒またはミリ秒の整数の場合、Snowflakeは値の長さに基づいて正しい時間測定値を決定しようとします。例えば、Unixエポックの開始から1487654321秒に相当するタイムスタンプを計算するには:

select to_timestamp('1487654321');
-------------------------------+
  TO_TIMESTAMP('1487654321')   |
-------------------------------+
 2017-02-20 21:18:41.000000000 |
-------------------------------+

エポックの開始からミリ秒を使用した同様の計算を次に示します。

select to_timestamp('1487654321321');
-------------------------------+
 TO_TIMESTAMP('1487654321321') |
-------------------------------+
 2017-02-20 21:18:41.321000000 |
-------------------------------+

ターゲットのデータ型に応じて、異なる入力スケールが想定されます。

  • TIME:Snowflakeは、スケールとして秒を使用します。

  • DATE および TIMESTAMP:

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

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

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

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

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

    • 複数の行が評価される場合(例えば、入力が3つ以上の行を含むテーブルの列名である場合)、最初に処理される値は、後続のすべての値が秒、ミリ秒、マイクロ秒、またはナノ秒として扱われるかどうかを決定します。

      最初の値が31536000000以上の場合、残りの値が31536000000未満であっても、すべての値はミリ秒として扱われます。同様のロジックがマイクロ秒とナノ秒に適用されます。

    ご用心

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

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

    ご用心

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

誤った形式の検出の可能性を減らすために、整数のみの形式が他の形式とともに検出された場合、Snowflakeはエラーを発生します。例:

select to_timestamp(column1) from values('1487654321');
-------------------------------+
     TO_TIMESTAMP(COLUMN1)     |
-------------------------------+
 2017-02-20 21:18:41.000000000 |
-------------------------------+

select to_timestamp(column1) from values('2013-04-05');
-------------------------------+
     TO_TIMESTAMP(COLUMN1)     |
-------------------------------+
 2013-04-05 00:00:00.000000000 |
-------------------------------+

select to_timestamp(column1) from values('1487654321'),('2013-04-05');
FAILURE: Timestamp '2013-04-05' is not recognized

select to_timestamp(column1) from values ('2013-04-05'), ('1487654321');
FAILURE: Timestamp '1487654321' is not recognized

ご用心

予期しない結果を回避するために、秒スケールおよびミリ秒スケールの整数など、同じ列に異なるスケールの整数を混在させないでください。例:

select to_timestamp(column1) from values('1487654321321'),('1487654321');
-------------------------------+
     TO_TIMESTAMP(COLUMN1)     |
-------------------------------+
 2017-02-20 21:18:41.321000000 |
 1970-01-17 21:14:14.321000000 |
-------------------------------+

select to_timestamp(column1) from values('1487654321'),('1487654321321');
--------------------------------+
     TO_TIMESTAMP(COLUMN1)      |
--------------------------------+
 2017-02-20 21:18:41.000000000  |
 49111-11-21 23:28:41.000000000 |
--------------------------------+

日付と時刻の関数形式のベストプラクティス

AUTO 検出は通常、正しい入力形式を決定します。ただし、正しい判断ができない場合があります。

これを回避するために、Snowflakeは次のベストプラクティスを強くお勧めします(必要に応じて、 TO_TIMESTAMPTO_DATE , DATE または TO_TIME , TIME に置き換える)。

  • 結果があいまいになる可能性がある場合は、 AUTO 形式の使用を避けてください。その代わりに、次の方法で明示的なフォーマット文字列を指定します。

  • 整数値を含む文字列の場合、次の構文を使用してスケールを指定します。

    TO_TIMESTAMP(TO_NUMBER(<string_column>), <scale>)