View a markdown version of this page

Amazon Ion SerDe 属性参考 - Amazon Athena
如何指定 Amazon Ion SerDe 属性Amazon Ion SerDe 属性
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

Amazon Ion SerDe 属性参考

本主题包含有关 Athena 中 CREATE TABLE 语句的 SerDe 属性信息。有关 Amazon Ion SerDe 属性用法的更多信息和示例，请参阅 GitHub 上 Amazon Ion Hive SerDe 文档中的 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',
...
)

请注意，如果要使用 ROW FORMAT SERDE，尽管需要 WITH SERDEPROPERTIES 子句，但您可以使用 STORED AS ION 或者更长的 INPUTFORMAT 和 OUTPUTFORMAT 语法来指定 Amazon Ion 格式。

Amazon Ion SerDe 属性

以下是可以在 Athena 中的 CREATE TABLE 语句中使用的 Amazon Ion 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 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_extractor

可选

默认：NA

值：带搜索路径的字符串

使用给定列的指定搜索路径创建路径提取器。路径提取器将 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 纪元的偏移量，而 Amazon Ion 时间戳则有偏移量。序列化到 Amazon Ion 时，使用此属性指定偏移量。

以下示例添加一小时的偏移量。

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

可选

默认值：OMIT

值：OMIT、UNTYPED、TYPED

Amazon Ion SerDe 可以配置为序列化或省略具有空值的列。您可以选择写出强类型空值（TYPED）或无类型空值（UNTYPED）。基于默认的 Amazon Ion 到 Hive 类型映射确定强类型空值。

以下示例指定强类型空值。

'ion.serialize_null'='TYPED'
ion.ignore_malformed

可选

默认值：false

值：true、false

true 时，如果 SerDe 无法读取格式错误的条目或整个文件，则忽略条目或整个文件。有关更多信息，请参阅 GibHub 上文档中的忽略格式错误。

ion.<column>.serialize_as

可选

默认：列的默认类型。

值：包含 Amazon Ion 类型的字符串

确定序列化值的 Amazon Ion 数据类型。由于 Amazon Ion 和 Hive 类型并不总是具有直接映射关系，因此一些 Hive 类型具有多个用于序列化的有效数据类型。若要将数据序列化为非默认数据类型，请使用此属性。有关类型映射的更多信息，请参阅 GitHub 上的 Amazon Ion 类型映射页面。

默认情况下，二进制 Hive 列序列化为 Amazon Ion Blob，但也可以序列化为 Amazon Ion Clob（字符大对象）。以下示例将列 example_hive_binary_column 序列化为 Clob。

'ion.example_hive_binary_column.serialize_as' = 'clob'