# 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',
...
)
```

请注意，如果要使用 `ROW FORMAT SERDE`，尽管需要 `WITH SERDEPROPERTIES` 子句，但您可以使用 `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 字段名称的大小写。  
例如，假设您有一个 Hive 表架构，其定义小写 `alias` 字段和包含 `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" |
```
在第二种情况下，区分大小写设置为 `true` 并且路径提取器指定为 `alias` 时，将忽略 `ALIAS` 字段的 `value1`。

**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 相同）  
Apache Hive [时间戳](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-timestamp)没有内置时区，并且存储为 UNIX 纪元的偏移量，而 Amazon Ion 时间戳则有偏移量。序列化到 Amazon Ion 时，使用此属性指定偏移量。  
以下示例添加一小时的偏移量。  

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

**ion.serialize\$1null**  
可选  
默认值：`OMIT`  
值：`OMIT`、`UNTYPED`、`TYPED`  
Amazon Ion SerDe 可以配置为序列化或省略具有空值的列。您可以选择写出强类型空值（`TYPED`）或无类型空值（`UNTYPED`）。基于默认的 Amazon Ion 到 Hive 类型映射确定强类型空值。  
以下示例指定强类型空值。  

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

**ion.ignore\$1malformed**  
可选  
默认值：`false`  
值：`true`、`false`  
`true` 时，如果 SerDe 无法读取格式错误的条目或整个文件，则忽略条目或整个文件。有关更多信息，请参阅 GibHub 上文档中的[忽略格式错误](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 [类型映射](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'       
```