# Amazon Athena Vertica 连接器
<a name="connectors-vertica"></a>

Vertica 是一个列存数据库平台，可以部署在云中或在支持 EB 级数据仓库的本地部署。您可以在联合查询中使用 Amazon Athena Vertica 连接器来查询来自 Athena 的 Vertica 数据来源。例如，您可以通过 Vertica 上的数据仓库和 Amazon S3 中的数据湖运行分析查询。

此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。

## 先决条件
<a name="connectors-vertica-prerequisites"></a>
+ 可以使用 Athena 控制台或 Amazon Serverless Application Repository 将该连接器部署到您的 Amazon Web Services 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 Amazon Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。
+ 使用此连接器前，请先设置 VPC 和安全组。有关更多信息，请参阅 [为数据来源连接器或 Amazon Glue 连接创建 VPC](athena-connectors-vpc-creation.md)。

## 限制
<a name="connectors-vertica-limitations"></a>
+ 由于 Athena Vertica 连接器从 Amazon S3 读取导出的 Parquet 文件，因此连接器的性能可能很慢。查询大型表时，我们建议您使用[创建表为（选择...）](ctas.md)查询和 SQL 谓词。
+ 目前，由于 Athena 联合查询中存在一个已知问题，连接器会让 Vertica 将查询表的所有列导出到 Amazon S3，但在 Athena 控制台的结果中只能看到被查询的列。
+ 不支持写入 DDL 操作。
+ 任何相关的 Lambda 限制。有关更多信息，请参阅《Amazon Lambda 开发人员指南》**中的 [Lambda 配额](https://docs.amazonaws.cn/lambda/latest/dg/gettingstarted-limits.html)。

## 工作流
<a name="connectors-vertica-workflow"></a>

以下图表显示了使用 Vertica 连接器运行查询的工作流程。

![Amazon Athena 的 Vertica 查询的工作流程](http://docs.amazonaws.cn/athena/latest/ug/images/connectors-vertica-1.png)


1. 针对 Vertica 中的一个或多个表发出 SQL 查询。

1. 连接器解析 SQL 查询，以通过 JDBC 连接将相关部分发送到 Vertica。

1. 连接字符串使用存储在 Amazon Secrets Manager 中的用户名和密码，以获得 Vertica 的访问权限。

1. 连接器使用 Vertica `EXPORT` 命令包装 SQL 查询，如以下示例所示。

   ```
   EXPORT TO PARQUET (directory = 's3://amzn-s3-demo-bucket/{{folder_name}}, 
      Compression='Snappy', fileSizeMB=64) OVER() as 
   SELECT
   PATH_ID,
   ...
   SOURCE_ITEMIZED,
   SOURCE_OVERRIDE
   FROM DELETED_OBJECT_SCHEMA.FORM_USAGE_DATA
   WHERE PATH_ID <= 5;
   ```

1. Vertica 处理 SQL 查询并将结果集发送到 Amazon S3 存储桶。为了提高吞吐量，Vertica 使用 `EXPORT` 选项并行处理多个 Parquet 文件的写入操作。

1. Athena 扫描 Amazon S3 存储桶，以确定要为结果集读取的文件数。

1. Athena 对 Lambda 函数进行多次调用，并使用 Apache `ArrowReader` 从结果数据集中读取 Parquet 文件。多次调用使 Athena 能够并行读取 Amazon S3 文件，实现高达每秒 100GB 的吞吐量。

1. Athena 使用数据湖扫描的数据处理从 Vertica 返回的数据并返回结果。

## 术语
<a name="connectors-vertica-terms"></a>

以下术语与 Vertica 连接器有关。
+ **数据库实例** — 部署在 Amazon EC2 上的 Vertica 数据库的任何实例。
+ **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。
+ **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。
+ **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。
+ **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。
+ **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。
+ **连接字符串** — 用于建立数据库实例连接的文本字符串。
+ **目录** — 向 Athena 注册的非 Amazon Glue 目录，是 `connection_string` 属性的必要前缀。

## 参数
<a name="connectors-vertica-parameters"></a>

使用本节中的参数来配置 Vertica 连接器。

### Amazon Glue Data Catalog 联合连接器
<a name="connectors-vertica-gc"></a>

我们建议您使用 Glue 连接对象来配置 Vertica 连接器。要执行此操作，请将 Vertica 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。

**Glue 连接属性**

使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。

```
aws glue describe-connection-type --connection-type VERTICA
```

**Lambda 环境属性**

只有您在账户中使用带有 Lambda 函数的连接器时，以下 Lambda 环境属性才适用。
+ **glue\_connection** – 指定与联合连接器关联的 Glue 连接的名称。
+ **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为：
  + **无** – 不更改给定架构和表名的大小写。对于关联了 Glue 连接的连接器，这是默认设置。
  + **大写** – 所有给定的架构和表名全部大写。
  + **小写** – 所有给定的架构和表名全部小写。

**注意**  
所有使用 Amazon Glue Data Catalog 联合连接的连接器都必须使用 Amazon Secrets Manager 来存储凭证。
使用 Amazon Glue Data Catalog 联合连接创建的 Vertica 连接器不支持使用多路复用处理程序。
使用 Amazon Glue Data Catalog 联合连接创建的 Vertica 连接器仅支持 `ConnectionSchemaVersion` 2。

### Athena 数据目录联合连接器
<a name="connectors-vertica-legacy"></a>

Amazon Athena Vertica 连接器通过 Lambda 环境变量显示了配置选项。您可以使用以下 Lambda 环境变量来配置连接器。
+  **AthenaCatalogName** — Lambda 函数名称 
+  **ExportBucket** — 将 Vertica 查询结果导出到的 Amazon S3 存储桶。
+  **SpillBucket** — 此函数可以溢出数据的 Amazon S3 存储桶的名称。
+  **SpillPrefix** — 此函数可以溢出数据的 `SpillBucket` 位置的前缀。
+  **SecurityGroupIds** — 与应该应用于 Lambda 函数的安全组对应的一个或多个 ID（例如 `sg1`、`sg2` 或 `sg3`)。
+  **SubnetIds** — 与 Lambda 函数可用于访问您数据来源的子网对应的一个或多个子网 ID（例如 `subnet1` 或 `subnet2`)。
+  **SecretNameOrPrefix** — 此函数有权访问的 Secrets Manager 中一组密钥的名称或前缀（例如 `vertica-*`) 
+  **VerticaConnectionString** — 如果未定义特定于目录的连接，则默认使用的 Vertica 连接详细信息。该字符串可以选择使用 Amazon Secrets Manager 语法（例如 `${secret_name}`)。
+  **VPC ID** — 要附加到 Lambda 函数的 VPC ID。

#### 连接字符串
<a name="connectors-vertica-connection-string"></a>

使用以下格式的 JDBC 连接字符串连接到数据库实例。

```
vertica://jdbc:vertica://{{host_name}}:{{
                        port}}/{{database}}?user={{vertica-username}}&password=
                        {{vertica-password}}
```

#### 使用单个连接处理程序
<a name="connectors-vertica-using-a-single-connection-handler"></a>

您可以使用以下单个连接元数据和记录处理程序连接到单个 Vertica 实例。


****  

| 处理程序类型 | 类 | 
| --- | --- | 
| 复合处理程序 | VerticaCompositeHandler | 
| 元数据处理程序 | VerticaMetadataHandler | 
| 记录处理程序 | VerticaRecordHandler | 

#### 单个连接处理程序参数
<a name="connectors-vertica-single-connection-handler-parameters"></a>


****  

| 参数 | 说明 | 
| --- | --- | 
| default | 必需。默认连接字符串。 | 

单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。

#### 提供凭证
<a name="connectors-vertica-providing-credentials"></a>

要在 JDBC 连接字符串中为数据库提供用户名和密码，可以使用连接字符串属性或 Amazon Secrets Manager。
+ **连接字符串** — 可以将用户名和密码指定为 JDBC 连接字符串中的属性。
**重要**  
作为安全最佳实践，请勿在环境变量或连接字符串中使用硬编码凭证。有关将硬编码密钥移至 Amazon Secrets Manager 的信息，请参阅《*Amazon Secrets Manager 用户指南*》中的[将硬编码密钥移至 Amazon Secrets Manager](https://docs.amazonaws.cn/secretsmanager/latest/userguide/hardcoded.html)。
+ **Amazon Secrets Manager** - 要将 Athena 联合查询功能与 Amazon Secrets Manager 配合使用，连接到您的 Lambda 函数的 VPC 应该拥有[互联网访问权限](https://www.amazonaws.cn/premiumsupport/knowledge-center/internet-access-lambda-function/)或者 [VPC 端点](https://docs.amazonaws.cn/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以连接到 Secrets Manager。

  您可以将 Amazon Secrets Manager 中的密钥名称放入您的 JDBC 连接字符串中。连接器将该密钥名称替换为来自 Secrets Manager 的 `username` 和 `password` 值。

  对于 Amazon RDS 数据库实例，将紧密集成这种支持。如果您使用 Amazon RDS，我们强烈建议您使用 Amazon Secrets Manager 和凭证轮换。如果您的数据库不使用 Amazon RDS，请按以下格式将凭证存储为 JSON：

  ```
  {"username": "${username}", "password": "${password}"}
  ```

**带有密钥名称的示例连接字符串**  
以下字符串带有密钥名称 ${`vertica-username`} 和 `${vertica-password}`。

```
vertica://jdbc:vertica://{{
                        host_name}}:{{port}}/{{database}}?user=${vertica-username}&password=${vertica-password}
```

该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。

```
vertica://jdbc:vertica://{{
                        host_name}}:{{port}}/{{database}}?user=sample-user&password=sample-password
```

目前，Vertica 连接器可以识别 `vertica-username` 和 `vertica-password` JDBC 属性。

#### 溢出参数
<a name="connectors-vertica-spill-parameters"></a>

Lambda 开发工具包可以将数据溢出到 Amazon S3。由同一 Lambda 函数访问的所有数据库实例都会溢出到同一位置。


****  

| 参数 | 说明 | 
| --- | --- | 
| spill\_bucket | 必需。溢出存储桶名称。 | 
| spill\_prefix | 必需。溢出存储桶密钥前缀。 | 
| spill\_put\_request\_headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，{"x-amz-server-side-encryption" : "AES256"})。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.amazonaws.cn/AmazonS3/latest/API/API_PutObject.html)。 | 

## 数据类型支持
<a name="connectors-vertica-data-type-support"></a>

下表显示了 Vertica 连接器支持的数据类型。


****  

| 布尔值 | 
| --- | 
| BigInt | 
| 短型 | 
| 整数 | 
| 长整型 | 
| 浮点型 | 
| 双精度 | 
| 日期 | 
| Varchar | 
| 字节 | 
| BigDecimal | 
| 作为 Varchar 的时间戳 | 

## 性能
<a name="connectors-vertica-performance"></a>

Lambda 函数执行投影下推，以减少查询扫描的数据。`LIMIT` 子句会减少扫描的数据量，但如果未提供谓词，则预期要使用包含 `LIMIT` 子句的 `SELECT` 查询来扫描至少 16 MB 的数据。Vertica 连接器能够灵活地应对并发造成的节流。

## 传递查询
<a name="connectors-vertica-passthrough-queries"></a>

Vertica 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。

要在 Vertica 中执行传递查询，可以使用以下语法：

```
SELECT * FROM TABLE(
        system.query(
            query => '{{query string}}'
        ))
```

以下示例查询将查询下推到 Vertica 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。

```
SELECT * FROM TABLE(
        system.query(
            query => 'SELECT * FROM customer LIMIT 10'
        ))
```

## 许可证信息
<a name="connectors-vertica-license-information"></a>

使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。

## 其他资源
<a name="connectors-vertica-additional-resources"></a>

有关最新 JDBC 驱动程序版本信息，请参见 GitHub.com 上适用于 Vertica 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) 文件。

有关此连接器的更多信息，请参阅 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-vertica)，以及*Amazon 大数据博客*中的文章“[使用 Athena 联合查询 SDK 在 Amazon Athena 中查询 Vertica 数据来源](https://www.amazonaws.cn/blogs/big-data/querying-a-vertica-data-source-in-amazon-athena-using-the-athena-federated-query-sdk/)”。