本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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 properties](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md) (SerDe 屬性)。

## 如何指定 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>

以下是 Amazon Ion SerDe 屬性，可用於 Athena 中的 `CREATE TABLE` 陳述式。

**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`，而 Amazon Ion 文件則包含 `alias` 欄位和 `ALIAS` 欄位，如下列範例所示。  

```
-- 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**  
選用  
預設：不適用  
值：含搜尋路徑的字串  
使用特定資料欄的指定搜尋路徑建立路徑擷取器。路徑擷取器將 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 epoch 的偏移，Amazon Ion 時間戳記確實具有偏移。在序列化到 Amazon Ion 時，使用此屬性指定偏移。  
以下範例新增了一小時的偏移。  

```
'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 上文件中的[忽略格式錯誤](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'       
```