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 값을 포함하면 안 됩니다. FLOAT 요소. 고정 소수점 요소(모든 스케일 포함).
`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” 문자열로 형식이 지정됩니다.

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