Amazon Ion SerDe 속성 참조

이 주제는 Athena에서 CREATE TABLE 문에 대한 SerDe 속성에 대한 정보가 포함되어 있습니다. Amazon Ion SerDe 속성 사용에 대한 자세한 내용 및 예제는 GitHub에서 Amazon Ion Hive SerDe 설명서의 SerDe 속성을 참조하세요.

Amazon Ion SerDe 속성을 지정하는 방법

CREATE TABLE 문에서 Amazon Ion Hive SerDe에 대한 속성을 지정하려면 WITH SERDEPROPERTIES 절을 사용합니다. WITH SERDEPROPERTIES가 ROW FORMAT SERDE 절의 하위 필드이므로 다음 구문과 같이 ROW FORMAT SERDE 및 Amazon Ion Hive SerDe 클래스 경로를 먼저 지정해야 합니다.

...
ROW FORMAT SERDE
 'com.amazon.ionhiveserde.IonHiveSerDe'
WITH SERDEPROPERTIES (
 'property' = 'value',
 'property' = 'value',
...
)

WITH SERDEPROPERTIES를 사용하려면 ROW FORMAT SERDE 절이 필요하지만 STORED AS ION 또는 더 긴 INPUTFORMAT 및 OUTPUTFORMAT 구문을 사용하여 Amazon Ion 형식을 지정할 수 있다는 점에 유의하세요.

Amazon Ion SerDe 속성

다음은 Athena에서 CREATE TABLE 문에 사용할 수 있는 Amazon Ion SerDe 속성입니다.

ion.encoding

선택 사항

기본값: BINARY

값: BINARY, TEXT

이 속성은 추가된 새 값이 Amazon Ion 이진 또는 Amazon Ion 텍스트 형식으로 직렬화되는지 여부를 선언합니다.

다음 SerDe 속성 예제는 Amazon Ion 텍스트 형식을 지정합니다.

'ion.encoding' = 'TEXT'

ion.fail_on_overflow

선택 사항

기본값: true

값: true, false

Amazon Ion은 임의의 큰 숫자 형식을 허용하지만 Hive는 허용하지 않습니다. 기본적으로 Amazon Ion 값이 Hive 열에 맞지 않으면 SerDE가 실패하지만 fail_on_overflow 구성 옵션을 사용하여 실패 대신 값이 오버플로되도록 할 수 있습니다.

이 속성은 테이블 또는 열 수준에서 설정될 수 있습니다. 테이블 수준에서 이를 지정하려면 다음 예제와 같이 ion.fail_on_overflow를 지정합니다. 이렇게 하면 모든 열의 기본 동작이 설정됩니다.

'ion.fail_on_overflow' = 'true'

특정 열을 제어하려면 다음 예와 같이 마침표로 구분하여 ion과 fail_on_overflow 사이에 열 이름을 지정합니다.

'ion.<column>.fail_on_overflow' = 'false'

ion.path_extractor.case_sensitive

선택 사항

기본값: false

값: true, false

Amazon Ion 필드 이름을 대/소문자를 구분하여 처리할지 여부를 결정합니다. false이면 SerDe는 Amazon Ion 필드 이름을 구문 분석할 때 대/소문자를 무시합니다.

예를 들어 다음 예제와 같이 소문자로 alias 필드를 정의하는 Hive 테이블 스키마와 alias 필드 및 ALIAS 필드가 있는 Amazon Ion 문서가 있다고 가정합니다.

-- Hive Table Schema
alias: STRING

-- Amazon Ion Document
{ 'ALIAS': 'value1'} 
{ 'alias': 'value2'}

다음 예제에서는 대/소문자 구분이 false로 설정된 경우 SerDe 속성 및 추출된 결과 테이블을 보여 줍니다.

-- Serde properties
'ion.alias.path_extractor' = '(alias)'
'ion.path_extractor.case_sensitive' = 'false'

--Extracted Table
| alias    |
|----------|
| "value1" |
| "value2" |

다음 예제에서는 대/소문자 구분이 true로 설정된 경우 SerDe 속성 및 추출된 결과 테이블을 보여 줍니다.

-- Serde properties
'ion.alias.path_extractor' = '(alias)'
'ion.path_extractor.case_sensitive' = 'true'

--Extracted Table
| alias    |
|----------|
| "value2" |

두 번째 경우 ALIAS 필드의 value1은 대/소문자 구분을 true로 설정한 경우 무시되며 경로 추출기는 alias로 지정됩니다.

ion.<column>.path_extractor

선택 사항

기본값: NA

값: 검색 경로가 있는 문자열

주어진 열에 대한 지정된 검색 경로로 경로 추출기를 생성합니다. 경로 추출기는 Amazon Ion 필드를 Hive 열에 매핑합니다. 경로 추출기를 지정하지 않으면 Athena는 열 이름을 기반으로 런타임에 동적으로 경로 추출기를 만듭니다.

다음 예제 경로 추출기는 example_ion_field를 example_hive_column에 매핑합니다.

'ion.example_hive_column.path_extractor' = '(example_ion_field)'

경로 추출기 및 검색 경로에 대한 자세한 내용은 경로 추출기 사용을 참조하세요.

ion.timestamp.serialization_offset

선택 사항

기본값: 'Z'

값: OFFSET, OFFSET 는 <signal>hh:mm과 같이 표시됩니다. 예제 값: 01:00, +01:00, -09:30, Z(UTC, 00:00과 동일)

기본 제공 시간대가 없고 UNIX Epoch에서 오프셋으로 저장되는 Apache Hive 타임스탬프와는 달리 Amazon Ion 타임스탬프는 오프셋이 있습니다. 이 속성을 사용하여 Amazon Ion으로 직렬화할 때 오프셋을 지정합니다.

다음 예제에서는 오프셋을 1시간 추가합니다.

'ion.timestamp.serialization_offset' = '+01:00'       

ion.serialize_null

선택 사항

기본값: OMIT

값: OMIT, UNTYPED, TYPED

Amazon Ion SerDE는 값이 null인 열을 직렬화하거나 생략하도록 구성할 수 있습니다. 강력한 형식의 null(TYPED) 또는 형식이 지정되지 않은 null(UNTYPED)을 쓰도록 선택할 수 있습니다. 강력한 형식의 null은 기본 Amazon Ion-Hive 형식 매핑에 따라 결정됩니다.

다음 예제에서는 강력한 형식의 null을 지정합니다.

'ion.serialize_null'='TYPED'

ion.ignore_malformed

선택 사항

기본값: false

값: true, false

true이면 잘못된 형식의 항목 또는 SerDE에서 읽을 수 없는 경우 전체 파일을 무시합니다. 자세한 내용은 GitHub에서 설명서의 Ignore malformed(잘못된 형식 무시)를 참조하세요.

ion.<column>.serialize_as

선택 사항

기본값: 열의 기본 형식.

값: Amazon Ion 형식을 포함하는 문자열

값이 직렬화되는 Amazon Ion 데이터 형식을 결정합니다. Amazon Ion 및 Hive 형식이 항상 직접 매핑되는 것은 아니기 때문에 몇몇 Hive 형식에는 직렬화를 위한 여러 유효한 데이터 형식이 있습니다. 데이터를 기본이 아닌 데이터 형식으로 직렬화하려면 이 속성을 사용합니다. 형식 매핑에 대한 자세한 내용은 GitHub의 Amazon Ion Type mapping(형식 매핑) 페이지를 참조하세요.

기본적으로 이진 Hive 열은 Amazon Ion blob으로 직렬화되지만 Amazon Ion clob(문자 대용량 객체)으로 직렬화될 수도 있습니다. 다음 예제에서는 example_hive_binary_column 열을 clob으로 직렬화합니다.

'ion.example_hive_binary_column.serialize_as' = 'clob'