Amazon 離子 SerDe 屬性參考

本主題包含 Athena CREATE TABLE 陳述式 SerDe 屬性的相關資訊。如需 Amazon Ion SerDe 屬性使用情況的詳細資訊和範例，請參閱上的 Amazon Ion Hive SerDe 文件中的SerDe 屬性GitHub。

如何指定 Amazon 離子 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 離子 SerDe 屬性

以下是可以在 Athena CREATE TABLE 語句中使用的 Amazon 離子 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 離子字段名稱的大小寫。

例如，假設您有 Hive 資料表結構描述，它以小寫形式定義了欄位 alias，而 Amazon Ion 文件則包含 alias 欄位和 ALIAS 欄位，如下列範例所示。

-- Hive Table Schema
alias: STRING

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

下列範例顯示當區分大小寫設定為時， SerDe 屬性和產生的擷取表格false：

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

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

下列範例顯示當區分大小寫設定為時， SerDe 屬性和產生的擷取表格true：

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

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

在第二種情況下，當區分大小寫設定為 true 且路徑擷取器指定為 alias 時，會忽略 ALIAS 欄位的 value1。

離子。<column>. 路徑提取器

選用

預設：不適用

值：含搜尋路徑的字串

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

與 Apache Hive 時間戳不同，它沒有內置時區並作為距時UNIX代的偏移量存儲，Amazon 離子時間戳確實具有偏移量。在序列化到 Amazon Ion 時，使用此屬性指定偏移。

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

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

ion.serialize_null

選用

預設：OMIT

值：OMIT、UNTYPED、TYPED

Amazon Ion SerDe 可以設定為序列化或省略具有空值的資料行。您可以選擇寫出強類型的 null 值 (TYPED) 或無類型的 null 值 (UNTYPED)。強類型 null 值是根據預設的 Amazon Ion 到 Hive 類型映射來決定的。

以下範例指定了強類型的 null 值。

'ion.serialize_null'='TYPED'

ion.ignore_malformed

選用

預設：false

值：true、false

何時true，忽略格式錯誤的條目或整個檔案 (如果 SerDe 無法讀取)。如需詳細資訊，請參閱的文件中的 ＜ 略過格式錯誤 ＞。 GitHub

離子。<column>. 序列化為

選用

預設：資料欄的預設類型。

值：包含 Amazon Ion 類型的字串

確定在其中序列化值的 Amazon Ion 資料類型。由於 Amazon Ion 和 Hive 類型並不總是具有直接映射，因此少數 Hive 類型具有多種用於序列化的有效資料類型。要將資料序列化為非預設資料類型，請使用此屬性。如需有關類型對應的詳細資訊，請參閱上的 Amazon Ion 類型對應頁面 GitHub。

依預設，二進位 Hive 資料欄序列化為 Amazon Ion blob，但它們也可以序列化為 Amazon Ion clob (字元大型物件)。以下範例將資料欄 example_hive_binary_column 序列化為 clob。

'ion.example_hive_binary_column.serialize_as' = 'clob'