SQL 및 처리기 언어 간의 데이터 타입 매핑

이 항목의 내용:

작성한 저장 프로시저 또는 사용자 정의 함수는 SQL에서 호출되므로 SQL 데이터 타입의 값을 수신하고 반환합니다. 그러나 기본 처리기는 Java, Python 또는 Scala와 같은 처리기 언어의 데이터 타입을 사용합니다. 런타임에 Snowflake는 인자 및 반환 값에 대해 SQL 타입과 처리기 타입 사이에서 변환합니다.

Snowflake는 다음과 같은 경우에도 이러한 변환을 수행합니다.

  • 처리기 변수의 값을 사용하는 SQL 문을 동적으로 생성할 경우.

  • 처리기 변수의 값을 준비된 문에 바인딩할 경우.

이 항목에서는 SQL 데이터 및 타입과 지원되는 처리기 언어의 데이터 및 타입 간 유효한 매핑에 대해 설명합니다. 처리기를 작성할 때 이 콘텐츠를 사용하여 데이터 타입을 선택하십시오.

Snowflake SQL 데이터 타입에 대한 자세한 내용은 데이터 타입 요약 을 참조하십시오.

SQL-Java 데이터 타입 매핑

아래 표는SQL과 Java 간의 형식 매핑을 보여줍니다. 이러한 매핑은 일반적으로 프로시저나 함수에 전달된 인자, 그리고 프로시저나 함수에서 반환된 값 모두에 적용됩니다. 그러나 몇 가지 예외가 있으며, 이는 각주에 나열되어 있습니다.

일부 SQL 데이터 타입(예: NUMBER)은 여러 Java 데이터 타입(예: int, long 등)과 호환됩니다. 이러한 경우, 전달될 실제 값을 보유하기에 충분한 용량이 있는 모든 Java 데이터 타입을 사용할 수 있습니다. SQL 값을 호환되지 않는 Java 데이터 타입에 전달하면(또는 그 반대로) 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 -> string 변환에서 손실 발생).

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 범위에 맞아야 합니다. wallclock 시간을 Unix epoch(UTC 타임존을 효과적으로 부과)의 오프셋으로 처리합니다. [3]

TIMESTAMP_NTZ

String

wallclock 시간을 Unix epoch(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 패키지 유형 섹션을 참조하십시오. 예를 보려면 인라인 Java UDF에 VARIANT 값 전달 섹션을 참조하십시오.

배열

Java UDF는 다음 Java 데이터 타입의 배열을 수신할 수 있습니다.

데이터 타입

참고

String

boolean

Snowflake ARRAY는 BOOLEAN 요소만 포함해야 하며 NULL 값을 포함해서는 안 됩니다.

double

float

Snowflake ARRAY는 다음 중 하나를 포함해야 하며 NULL 값을 포함하면 안 됩니다.

int

long

short

Snowflake ARRAY는 스케일이 0인 고정 소수점 요소만 포함해야 하며 NULL 값을 포함해서는 안 됩니다.

NULL 값

Snowflake는 두 가지 고유한 NULL 값을 지원하는데, 이는 SQL NULL 과 VARIANT의 JSON null 입니다. (Snowflake VARIANT NULL에 대한 자세한 내용은 NULL 값 을 참조하십시오.)

Java는 기본이 아닌 데이터 타입에만 해당하는 하나의 null 값을 지원합니다.

Java 처리기에 대한 SQL NULL 인자는 Java null 값으로 변환되지만, null 을 지원하는 Java 데이터 타입에만 해당됩니다.

반환된 Java null 값은 SQL NULL 로 다시 변환됩니다.

TIMESTAMP_LTZ 값 및 타임존

Java UDF는 호출되는 환경과 크게 분리되어 있습니다. 그러나 타임존은 호출 환경에서 상속됩니다. 호출자의 세션이 Java UDF 호출 전에 기본 타임존을 설정한 경우, Java UDF는 동일한 기본 타임존을 갖습니다. Java UDF는 기본 TIMEZONE Snowflake SQL이 사용하는 것과 동일한 IANA타임존 데이터베이스 데이터(즉, 타임존 데이터베이스의 릴리스 2021a 에서 가져온 데이터)를 사용합니다.

사용자 정의 함수에 지원되는 Snowpark 패키지 유형

사용자 정의 함수에서 Snowflake Snowpark Java 패키지 에 포함된 타입 중 특정한 일부 타입을 사용할 수 있습니다. 이러한 타입은 Snowpark 코드에서 사용하도록 설계되었지만, 일부 타입은 제공 가능한 편의를 위해 UDF에서도 사용하도록 지원됩니다. (Snowpark에 대한 자세한 내용은 Snowpark 설명서 를 참조하십시오.)

참고

Snowpark 라이브러리는 Java, Python 및 Scala로 작성된 저장 프로시저의 요구 사항입니다. 그 결과, Snowpark 타입을 제한 없이 사용할 수 있습니다.

다음 표의 Snowpark 유형은 UDF 코드에서 지원됩니다. 다른 Snowpark 유형은 UDF 코드에서 지원되지 않으므로 이 코드에서 사용하면 안 됩니다.

Snowpark 유형

필요한 Snowpark 버전

설명

Geography

1.2.0 이상

Snowflake GEOGRAPHY 유형을 나타냅니다. Geography 데이터 타입을 사용하는 예는 인라인 Java UDF에 GEOGRAPHY 값 전달 섹션을 참조하십시오.

베리언트

1.4.0 이상

Snowflake VARIANT 데이터를 나타냅니다. Variant 데이터 타입을 사용하는 예는 인라인 Java UDF에 VARIANT 값 전달 섹션을 참조하십시오.

Snowpark 패키지를 종속 항목으로 지정하기

Snowpark 패키지를 사용하는 UDF 코드 개발 시, Snowpark 종속 항목이 있는 코드를 컴파일하고 실행할 수 있도록 개발 환경을 설정해야 합니다. 자세한 내용은 Snowpark Java를 위한 기타 개발 환경 설정하기 섹션을 참조하십시오.

CREATE FUNCTION 문을 실행하여 UDF를 배포할 때 JAR 파일을 스테이지에 업로드하지 않고 Snowpark 패키지를 종속 항목으로 지정할 수 있습니다(라이브러리는 이미 Snowflake에 있음). 이렇게 하려면 PACKAGES 절에 패키지 이름과 버전을 지정하십시오. 구문 예제는 인라인 Java UDF에 GEOGRAPHY 값 전달 섹션을 참조하십시오.

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 데이터 타입의 변수를 바인딩할 수 있습니다.

  • 숫자

  • 문자열

  • SfDate

    표준 JavaScript 데이터 타입이 아닌 SfDate 데이터 타입에 대한 자세한 내용은 JavaScript 저장 프로시저 API 를 참조하십시오.

몇 가지 예를 포함하여 바인딩에 대한 자세한 내용은 변수 바인딩하기 를 참조하십시오.

다음 항목이 도움이 될 수도 있습니다.

SQL-Python 데이터 타입 매핑

아래 표는SQL과 Python 간의 형식 매핑을 보여줍니다. 이러한 매핑은 일반적으로 Python 처리기에 전달된 인자, 그리고 이 처리기에서 반환된 값 모두에 적용됩니다.

SQL 형식

Python 형식

참고

ARRAY

list

Python 데이터 타입이 ARRAY로 변환될 때 포함된 Python 10진수 데이터가 있는 경우 포함된 Python 10진수는 ARRAY에서 String으로 변환됩니다.

BINARY

bytes

BOOLEAN

bool

DATE

datetime.date

FLOAT

float

부동 소수점 연산에는 특히 집계 함수가 많은 수의 행을 처리할 때 작은 반올림 오차가 누적될 수 있습니다. 행이 다른 순서로 처리되는 경우 쿼리가 실행될 때마다 반올림 오차가 달라질 수 있습니다. 자세한 내용은 숫자 데이터 타입: 부동 소수점 을 참조하십시오.

GEOGRAPHY, GEOMETRY

dict

지리 형식을 GeoJSON 으로 지정한 다음 Python dict로 변환합니다.

NUMBER

int 또는 decimal.Decimal

NUMBER 형식의 소수 자릿수가 0이면 int Python 형식이 사용됩니다. 그렇지 않으면 decimal.Decimal 형식이 사용됩니다.

OBJECT

dict

Python 데이터 타입이 OBJECT로 변환될 때 포함된 Python 10진수 데이터가 있는 경우 포함된 Python 10진수는 OBJECT에서 String으로 변환됩니다.

TIME

datetime.time

Snowflake는 나노초 정밀도로 시간 값을 저장할 수 있지만, Python datetime.time 타입은 밀리초 정밀도만 유지합니다. Snowflake와 Python 데이터 타입 간의 변환은 유효 정밀도를 밀리초로 줄일 수 있습니다.

TIMESTAMP_LTZ

datetime.datetime

현지 타임존을 사용하여 내부 UTC 시간을 현지 “naive” 날짜/시간으로 변환합니다. 반환 형식으로 “naive” 날짜/시간이 필요합니다.

TIMESTAMP_NTZ

datetime.datetime

“naive” 날짜/시간으로 직접 변환합니다. 반환 형식으로 “naive” 날짜/시간이 필요합니다.

TIMESTAMP_TZ

datetime.datetime

타임존 정보가 있는 “aware” 날짜/시간으로 변환합니다. 반환 형식으로 “aware” 날짜/시간이 필요합니다.

VARCHAR

str

VARIANT

dict, list, int, float, str 또는 bool

각 베리언트 행은 인자에 대해 동적으로 Python 형식으로 변환되고 반환 값에 대해서는 그 반대로 변환됩니다. decimal, binary, date, time, timestamp_ltz, timestamp_ntz, timestamp_tz 형식은 기본 Python 형식이 아닌 문자열로 변환됩니다. Python 데이터 타입이 VARIANT로 변환될 때 포함된 Python 10진수 데이터가 있는 경우 포함된 Python 10진수는 VARIANT에서 String으로 변환됩니다.

SQL-Scala 데이터 타입 매핑

Snowflake는 SQL-Java 데이터 타입 매핑 에 나열된 Java 타입 외에 다음 Scala 데이터 타입을 지원합니다.

SQL 데이터 타입

스칼라 타입

참고

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” 문자열로 형식이 지정됩니다.

DATETIMESTAMP 의 경우, SQL-Java 데이터 타입 매핑 에 나열된 Java 타입을 사용합니다.