# Amazon Ion SerDe 속성 참조
<a name="ion-serde-using-ion-serde-properties"></a>

이 주제는 Athena에서 `CREATE TABLE` 문에 대한 SerDe 속성에 대한 정보가 포함되어 있습니다. Amazon Ion SerDe 속성 사용에 대한 자세한 내용 및 예제는 [GitHub](https://github.com/amzn/ion-hive-serde/tree/master/docs)에서 Amazon Ion Hive SerDe 설명서의 [SerDe 속성](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md)을 참조하세요.

## Amazon Ion SerDe 속성을 지정하는 방법
<a name="ion-serde-specifying-ion-serde-properties"></a>

`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 속성
<a name="ion-serde-ion-serde-properties"></a>

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

**ion.encoding**  
선택 사항  
기본값: `BINARY`  
값: `BINARY`, `TEXT`   
이 속성은 추가된 새 값이 [Amazon Ion 이진](https://amzn.github.io/ion-docs/docs/binary.html) 또는 Amazon Ion 텍스트 형식으로 직렬화되는지 여부를 선언합니다.  
다음 SerDe 속성 예제는 Amazon Ion 텍스트 형식을 지정합니다.  

```
'ion.encoding' = 'TEXT'
```

**ion.fail\$1on\$1overflow**  
선택 사항  
기본값: `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\$1extractor.case\$1sensitive**  
선택 사항  
기본값: `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\$1extractor**  
선택 사항  
기본값: NA  
값: 검색 경로가 있는 문자열  
주어진 열에 대한 지정된 검색 경로로 경로 추출기를 생성합니다. 경로 추출기는 Amazon Ion 필드를 Hive 열에 매핑합니다. 경로 추출기를 지정하지 않으면 Athena는 열 이름을 기반으로 런타임에 동적으로 경로 추출기를 만듭니다.  
다음 예제 경로 추출기는 `example_ion_field`를 `example_hive_column`에 매핑합니다.  

```
'ion.example_hive_column.path_extractor' = '(example_ion_field)'
```
경로 추출기 및 검색 경로에 대한 자세한 내용은 [경로 추출기 사용](ion-serde-using-path-extractors.md)을 참조하세요.

**ion.timestamp.serialization\$1offset**  
선택 사항  
기본값: `'Z'`  
값: `OFFSET`, `OFFSET `는 `<signal>hh:mm`과 같이 표시됩니다. 예제 값: `01:00`, `+01:00`, `-09:30`, `Z`(UTC, 00:00과 동일)  
기본 제공 시간대가 없고 UNIX Epoch에서 오프셋으로 저장되는 Apache Hive [타임스탬프](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-timestamp)와는 달리 Amazon Ion 타임스탬프는 오프셋이 있습니다. 이 속성을 사용하여 Amazon Ion으로 직렬화할 때 오프셋을 지정합니다.  
다음 예제에서는 오프셋을 1시간 추가합니다.  

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

**ion.serialize\$1null**  
선택 사항  
기본값: `OMIT`  
값: `OMIT`, `UNTYPED`, `TYPED`   
Amazon Ion SerDE는 값이 null인 열을 직렬화하거나 생략하도록 구성할 수 있습니다. 강력한 형식의 null(`TYPED`) 또는 형식이 지정되지 않은 null(`UNTYPED`)을 쓰도록 선택할 수 있습니다. 강력한 형식의 null은 기본 Amazon Ion-Hive 형식 매핑에 따라 결정됩니다.  
다음 예제에서는 강력한 형식의 null을 지정합니다.  

```
'ion.serialize_null'='TYPED'
```

**ion.ignore\$1malformed**  
선택 사항  
기본값: `false`  
값: `true`, `false`   
`true`이면 잘못된 형식의 항목 또는 SerDE에서 읽을 수 없는 경우 전체 파일을 무시합니다. 자세한 내용은 GitHub에서 설명서의 [Ignore malformed](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md#ignore-malformed)(잘못된 형식 무시)를 참조하세요.

**ion.*<column>*.serialize\$1as**  
선택 사항  
기본값: 열의 기본 형식.  
값: Amazon Ion 형식을 포함하는 문자열  
값이 직렬화되는 Amazon Ion 데이터 형식을 결정합니다. Amazon Ion 및 Hive 형식이 항상 직접 매핑되는 것은 아니기 때문에 몇몇 Hive 형식에는 직렬화를 위한 여러 유효한 데이터 형식이 있습니다. 데이터를 기본이 아닌 데이터 형식으로 직렬화하려면 이 속성을 사용합니다. 형식 매핑에 대한 자세한 내용은 GitHub의 Amazon Ion [Type mapping](https://github.com/amzn/ion-hive-serde/blob/master/docs/type-mapping.md)(형식 매핑) 페이지를 참조하세요.  
기본적으로 이진 Hive 열은 Amazon Ion blob으로 직렬화되지만 [Amazon Ion clob](https://amzn.github.io/ion-docs/docs/stringclob.html#ion-clob)(문자 대용량 객체)으로 직렬화될 수도 있습니다. 다음 예제에서는 `example_hive_binary_column` 열을 clob으로 직렬화합니다.  

```
'ion.example_hive_binary_column.serialize_as' = 'clob'       
```