SQL とハンドラー言語間のデータ型マッピング

このトピックの内容:

記述したストアドプロシージャまたはユーザー定義関数は SQL から呼び出されるため、 SQL データ型で値を受け取り、返します。ただし、その基になるハンドラーは、Java、Python、またはScalaなどのハンドラー言語のデータ型を使用します。実行時に、Snowflakeは SQL 型とハンドラー型の間で引数と戻り値を変換します。

Snowflakeでは、これらの変換が次のケースでも実行されることに注意してください。

  • ハンドラー変数内の値を使用する SQL ステートメントを動的に構築する場合。

  • ハンドラー変数の値を準備されたステートメントにバインドする場合。

このトピックでは、 SQL のデータと型の間の有効なマッピングと、サポートされているハンドラー言語からのマッピングについて説明します。このコンテンツを使用して、ハンドラーを作成するときにデータ型を選択します。

Snowflake SQL データ型の詳細については、 データ型の概要 をご参照ください。

SQL-Javaデータ型マッピング

次のテーブルは、 SQL とJavaの間の型マッピングを示しています。これらのマッピングは通常、プロシージャに渡される引数または関数とそれから返される値の両方に適用されます。ただし、脚注に記載されているいくつかの例外があります。

一部の SQL データ型（例: NUMBER）は、複数のJavaデータ型（例: int、 long など）と互換性があることに注意してください。このような場合、渡される実際の値を保持するための十分な容量がある、任意のJavaデータ型を使用できます。互換性のないJavaデータ型に SQL 値を渡すと（またはその逆）、Snowflakeはエラーをスローします。

SQL 型

Java型

メモ

ARRAY

String[]

配列の要素を文字列としてフォーマットします。

ARRAY

String

配列を JSON 文字列（例: [1, "foo", null]）としてフォーマットします。

BINARY

byte[]

BINARY

String

バイナリ文字列を16進数でエンコードします。 [4]

BINARY

InputStream

BINARY 値をバイトのシーケンスとして公開します。

BOOLEAN

boolean

nullにはできません。

BOOLEAN

Boolean

BOOLEAN

String

[4]

DATE

java.sql.Date

DATE

String

日付を YYYY-MM-DD としてフォーマットします。 [4]

FLOAT

double

nullにはできません。

FLOAT

Double

FLOAT

float

nullにはできません。精度が低下する可能性があります。

FLOAT

Float

精度が低下する可能性があります。

FLOAT

String

精度が低下する可能性があります（floatから文字列への変換で損失が発生）。

GEOGRAPHY

String

地理を GeoJSON としてフォーマットします。

GEOGRAPHY

Geography

[5]

NUMBER

short

nullにはできません。shortの範囲内に収まる必要があります（小数部分なし。整数部分は、shortの最大値/最小値を超えることはできません）。

NUMBER

Short

shortの範囲内に収まる必要があります（小数部分なし。整数部分は、shortの最大値/最小値を超えることはできません）。

NUMBER

int

nullにはできません。intの範囲内に収まる必要があります（小数部分なし。整数部分は、intの最大値/最小値を超えることはできません）。

NUMBER

Integer

intの範囲内に収まる必要があります（小数部分なし。整数部分は、intの最大値/最小値を超えることはできません）。

NUMBER

long

nullにはできません。longの範囲内に収まる必要があります（小数部分なし。整数部分は、longの最大値/最小値を超えることはできません）。

NUMBER

Long

longの範囲内に収まる必要があります（小数部分なし。整数部分は、longの最大値/最小値を超えることはできません）。

NUMBER

java.math.BigDecimal

NUMBER

java.math.BigInteger

BigInteger の範囲内に収まる必要があります（小数部分なし）。

NUMBER

String

OBJECT

Map<文字列、文字列>

マップのキーはオブジェクトのキーであり、値は文字列としてフォーマットされます。

OBJECT

String

オブジェクトを JSON 文字列（例: {"x": 3, "y": true}）としてフォーマットします。

TIME

java.sql.Time

[3]

TIME

String

時刻を HH:MI:SS.SSSSSSSSS としてフォーマットします。秒の小数部は、時刻の精度に依存します。 [3]

TIMESTAMP_LTZ

java.sql.Timestamp

java.sql.Timestampの範囲内に収まる必要があります。 [3]

TIMESTAMP_LTZ

String

出力形式は DY, DD MON YYYY HH24:MI:SS TZHTZM です。 [1]、 [3]、 [4]

TIMESTAMP_NTZ

java.sql.Timestamp

java.sql.Timestampの範囲内に収まる必要があります。実時間をUnixエポックからのオフセットとして扱います（事実上、 UTCタイムゾーンを強制）。 [3]

TIMESTAMP_NTZ

String

実時間をUnixエポックからのオフセットとして扱います（事実上、 UTC タイムゾーンを強制）。出力形式は DY, DD MON YYYY HH:MI:SS です。[2]、[3]、[4]

TIMESTAMP_TZ

java.sql.Timestamp

java.sql.Timestampの範囲内に収まる必要があります。 [3]

TIMESTAMP_TZ

String

出力形式は DY, DD MON YYYY HH24:MI:SS TZHTZM です。 [1]、 [3]、 [4]

VARCHAR

String

VARIANT

バリアント

バリアント データ型は、Snowparkパッケージのクラスです。詳細については、 ユーザー定義関数でサポートされるSnowparkパッケージ型 をご参照ください。例については、 VARIANT 値のインラインJava UDF への引き渡し をご参照ください。

配列

Java UDFs は、次に挙げるJavaデータ型のいずれかの配列を受け取ることができます。

データ型

メモ

String

boolean

Snowflake ARRAY には、 BOOLEAN 要素のみが含まれている必要があり、 NULL 値を含めることはできません。

double

float

Snowflake ARRAY には、次のいずれかを含める必要があり、 NULL 値を含めることはできません。

int

long

short

Snowflake ARRAY には、スケールが0の 固定小数点 要素のみが含まれている必要があり、 NULL 値を含めることはできません。

NULL 値

Snowflakeは、 SQL NULL と VARIANT の JSON null という2つの異なる NULL 値をサポートしています。（Snowflake VARIANT NULL については、 NULL 値 を参照。）

Javaは、1つの null 値をサポートします。これは、非プリミティブデータ型専用です。

Javaハンドラーに対する SQL NULL 引数は、 null をサポートするJavaデータ型の場合にのみ、Java null 値に変換されます。

返されたJava null 値は、 SQL NULL に変換されます。

TIMESTAMP_LTZ 値とタイムゾーン

Java UDF は多くの場合、呼び出される環境から分離されています。ただし、タイムゾーンは呼び出し元の環境から継承されます。呼び出し元のセッションがJava UDF を呼び出す前にデフォルトのタイムゾーンを設定した場合、Java UDF のデフォルトのタイムゾーンは同じになります。Java UDF は、ネイティブ TIMEZONE Snowflake SQL が使用するのと同じ IANA タイムゾーンデータベース データを使用します（つまり、タイムゾーンデータベースのリリース 2021a からのデータ）。

ユーザー定義関数でサポートされるSnowparkパッケージ型

ユーザー定義関数では、Snowflake SnowparkJavaパッケージ に含まれている型の特定のサブセットを使用できます。これらの型はSnowparkコードで使用するように設計されていますが、 UDFs での使用をサポートしてこれらが提供する利便性も提供します。（Snowparkの詳細については、 Snowparkドキュメント をご参照ください。）

注釈

Snowparkライブラリは、Java、Python、およびScalaで記述されたストアドプロシージャの要件です。そのため、Snowparkの型は制限なしで使用できます。

次のテーブルのSnowpark型は、 UDF コードでサポートされています。他のSnowpark型はサポートされていないため、 UDF コードでは使用しないでください。

Snowpark型

Snowparkバージョンが必要

説明

Geography

1.2.0以降

Snowflake GEOGRAPHY 型を表します。 Geography データ型を使用する例については、 GEOGRAPHY 値のインラインJava UDF への引き渡し をご参照ください。

バリアント

1.4.0以降

Snowflake VARIANT データを表します。 Variant データ型を使用する例については、 VARIANT 値のインラインJava UDF への引き渡し をご参照ください。

依存関係としてのSnowparkパッケージの指定

Snowparkパッケージを使用する UDF コードを開発するときは、Snowparkの依存関係を使用してコードをコンパイルおよび実行できるように、開発環境をセットアップする必要があります。詳細については、 Snowpark Java用その他開発環境の設定 をご参照ください。

CREATE FUNCTION ステートメントを実行して UDF を展開する場合は、 JAR ファイルをステージにアップロードせずにSnowparkパッケージを依存関係として指定できます（ライブラリはすでにSnowflakeにあります）。これを実行するには、 PACKAGES 句でパッケージ名とバージョンを指定します。構文例については、 GEOGRAPHY 値のインラインJava UDF への引き渡し をご参照ください。

SQL-JavaScript データ型マッピング

次の表は、Snowflake SQL データ型と対応する JavaScript データ型を示しています。

SQL データ型

JavaScript データ型

メモ

ARRAY

JSON

BOOLEAN

boolean

DATE

date

GEOGRAPHY, GEOMETRY

JSON

REAL, FLOAT, FLOAT8, FLOAT4, DOUBLE, DOUBLE PRECISION

number

TIME

string

TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ

date または SfDate

タイムスタンプが引数としてストアドプロシージャに渡されると、タイムスタンプは JavaScript date オブジェクトに変換されます。他の状況（ ResultSet から取得する場合など）では、タイムスタンプは SfDate オブジェクトに変換されます。標準の JavaScript データ型ではない SfDate データ型の詳細については、 JavaScript ストアドプロシージャ API をご参照ください。

VARCHAR, CHAR, CHARACTER, STRING, TEXT

string

VARIANT

JSON

メモ

Snowflake SQL データ型すべてに、対応する JavaScript データ型があるわけではありません。たとえば、 JavaScript は、 INTEGER または NUMBER データ型を直接サポートしていません。このような場合は、 SQL データ型を適切な代替データ型に変換する必要があります。たとえば、 SQL INTEGER を SQL FLOAT に変換し、それをデータ型 number の JavaScript 値に変換することができます。

以下の表は、互換性のない SQL データ型の適切な変換を示しています。

互換性のない SQL データ型

互換性のある SQL データ型

BINARY

Uint8Array

INTEGER

FLOAT

NUMBER, NUMERIC, DECIMAL

FLOAT

OBJECT

Uint8Array

値を返すとき

JavaScript の return ステートメントが、ストアドプロシージャの宣言された戻り型と異なるデータ型を返す場合、可能であれば JavaScript 値は SQL データ型にキャストされます。たとえば、数値が返されるが、ストアドプロシージャが文字列を返すと宣言されている場合、数値は JavaScript 内の文字列に変換され、 SQL ステートメントで返される文字列にコピーされます。（誤ったデータ型を返すなどの一部の JavaScript プログラミングエラーは、この動作によって隠される可能性があります。）

変換に有効なキャストが存在しない場合は、エラーが発生します。

値をバインドするとき

JavaScript 変数を SQL ステートメントにバインドすると、Snowflakeは JavaScript データ型を SQL データ型に変換します。次の JavaScript データ型の変数をバインドできます。

いくつかの例を含むバインディングの詳細については、 変数のバインド をご参照ください。

次のトピックには、関連項目が記載されています。

SQL-Pythonデータ型マッピング

次のテーブルは、 SQL とPythonの間の型マッピングを示しています。これらのマッピングは通常、Pythonハンドラーに渡される引数とそれから返される値の両方に適用されます。

SQL 型

Python型

メモ

ARRAY

list

Pythonのデータ型が ARRAY に変換される場合、Pythonのdecimalデータが​​埋め込まれていると、埋め込まれているPythonのdecimalは ARRAY の文字列に変換されます。

BINARY

bytes

BOOLEAN

bool

DATE

datetime.date

FLOAT

float

浮動小数点演算には小さな丸め誤差があり、特に集計関数が多数の行を処理する場合に累積する可能性があります。行が異なる順序で処理される場合は、クエリが実行されるたびに丸め誤差が変化する可能性があります。詳細については、 数値データ型: 浮動小数点 をご参照ください。

GEOGRAPHY, GEOMETRY

dict

geographyを GeoJSON としてフォーマットしてから、Python dictに変換します。

NUMBER

int または decimal.Decimal

NUMBER 型のスケールが0の場合は、int Python型が使用されます。それ以外の場合は、decimal.Decimal型が使用されます。

OBJECT

dict

Pythonのデータ型が OBJECT に変換される場合、Pythonのdecimalデータが​​埋め込まれていると、埋め込まれているPythonのdecimalは OBJECT の文字列に変換されます。

TIME

datetime.time

Snowflakeはナノ秒の精度で時間値を保存できますが、Python datetime.timeはミリ秒の精度しか維持できません。SnowflakeとPythonの間でデータ型を変換すると、実効精度がミリ秒に低下する可能性があります。

TIMESTAMP_LTZ

datetime.datetime

ローカルタイムゾーンを使用して、内部 UTC 時刻をローカルの「naive」datetimeに変換します。戻り型として「naive」datetimeが必要です。

TIMESTAMP_NTZ

datetime.datetime

「naive」datetimeに直接変換します。戻り型として「naive」datetimeが必要です。

TIMESTAMP_TZ

datetime.datetime

タイムゾーン情報を含む「aware」datetimeに変換します。戻り型として「aware」datetimeが必要です。

VARCHAR

str

VARIANT

dict、 list、 int、 float、 str、または bool

各バリアント行は、引数の場合は動的にPythonの型に変換され、戻り値の場合はその逆に変換されます。decimal、binary、date、time、timestamp_ltz、timestamp_ntz、timestamp_tzの型は、ネイティブPython型ではなく文字列に変換されます。Pythonのデータ型が VARIANT に変換されるときにPythonのdecimalデータが​​埋め込まれていると、埋め込まれているPythonのdecimalは VARIANT の文字列に変換されます。

SQL-Scalaデータ型マッピング

Snowflakeは、 SQL-Javaデータ型マッピング にリストされているJava型に 加えて、次のScalaデータ型をサポートしています。

SQL データ型

Scala型

メモ

ARRAY

Array[String]

BINARY

Array[Byte]

BOOLEAN

Boolean または Option[Boolean]

DOUBLE

Double または Option[Double]

FLOAT

Float または Option[Float]

NUMBER

次の型がサポートされています。

  • Int または Option[Int]

  • Long または Option[Long]

OBJECT

Map[String, String]

VARCHAR

String

VARIANT

String

表示されるタイプに応じて値をフォーマットします。 バリアントnull は、文字列「null」としてフォーマットされます。

DATE と TIMESTAMP には、 SQL-Javaデータ型マッピング にリストされているJava型を使用します。

言語: 日本語