Amazon Ion SerDe 屬性參考 - Amazon Athena
如何指定 Amazon Ion SerDe 屬性Amazon Ion SerDe 屬性

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

Amazon Ion SerDe 屬性參考

本主題包含 Athena 中 CREATE TABLE 陳述式的 SerDe 屬性的相關資訊。如需 Amazon Ion SerDe 屬性使用的詳細資訊和範例，請參閱 GitHub 上的 Amazon Ion Hive SerDe 文件中的 SerDe properties (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 屬性

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

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 欄位名稱的大小寫。

例如，假設您有 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_extractor

選用

預設：不適用

值：含搜尋路徑的字串

使用特定資料欄的指定搜尋路徑建立路徑擷取器。路徑擷取器將 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 相同)

與 Apache Hive 時間戳記不同，它們沒有內建時區，並且存放為從 UNIX epoch 的偏移，Amazon Ion 時間戳記確實具有偏移。在序列化到 Amazon Ion 時，使用此屬性指定偏移。

以下範例新增了一小時的偏移。

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

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'