# Amazon Athena SAP HANA 连接器
<a name="connectors-sap-hana"></a>

此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。

## 先决条件
<a name="connectors-saphana-prerequisites"></a>
+ 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。

## 限制
<a name="connectors-sap-hana-limitations"></a>
+ 不支持写入 DDL 操作。
+ 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。
+ 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
+ 在 SAP HANA 中，当对象名称存储在 SAP HANA 数据库中时，它们会转换为大写形式。但是，由于引号中的名称区分大小写，因此两个表能分别以小写和大写形式具有相同的名称（例如 `EMPLOYEE` 和 `employee`)。

  在 Athena 联合查询中，架构表名称以小写形式提供给 Lambda 函数。要解决此问题，您可以提供 `@schemaCase` 查询提示，用于从名称区分大小写的表中检索数据。以下是两个带有查询提示的示例查询。

  ```
  SELECT * 
  FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=upper"
  ```

  ```
  SELECT * 
  FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=lower"
  ```

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

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

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

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

**注意**  
2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。  
下面列出的参数名称和定义适用于在 2024 年 12 月 3 日之前创建的 Athena 数据来源连接器，可能与相应的 [AWS Glue 连接属性](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)不同。从 2024 年 12 月 3 日起，仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器时才使用以下参数。

### Glue 连接（推荐）
<a name="connectors-sap-hana-gc"></a>

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

**Glue 连接属性**

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

```
aws glue describe-connection-type --connection-type SAPHANA
```

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

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

### 旧连接
<a name="connectors-sap-hana-legacy"></a>

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

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

```
saphana://${jdbc_connection_string}
```

#### 使用多路复用处理程序
<a name="connectors-sap-hana-using-a-multiplexing-handler"></a>

您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。


****  

| 处理程序 | 类 | 
| --- | --- | 
| 复合处理程序 | SaphanaMuxCompositeHandler | 
| 元数据处理程序 | SaphanaMuxMetadataHandler | 
| 记录处理程序 | SaphanaMuxRecordHandler | 

##### 多路复用处理程序参数
<a name="connectors-sap-hana-multiplexing-handler-parameters"></a>


****  

| 参数 | 说明 | 
| --- | --- | 
| \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 mysaphanacatalog，则环境变量名称是 mysaphanacatalog\$1connection\$1string。 | 
| default | 必需。默认连接字符串。目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 

以下示例属性适用于支持两个数据库实例的 Saphana MUX Lambda 函数：`saphana1`（默认）和 `saphana2`。


****  

| 属性 | 值 | 
| --- | --- | 
| default | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 | 
| saphana\$1catalog1\$1connection\$1string | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 | 
| saphana\$1catalog2\$1connection\$1string | saphana://jdbc:sap://saphana2.host:port/?user=sample2&password=sample2 | 

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

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

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

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

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

**带有密钥名称的示例连接字符串**  
以下字符串带有密钥名称 `${Test/RDS/Saphana1}`。

```
saphana://jdbc:sap://saphana1.host:port/?${Test/RDS/Saphana1}&...
```

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

```
saphana://jdbc:sap://saphana1.host:port/?user=sample2&password=sample2&...
```

目前，SAP HANA 连接器可以识别 `user` 和 `password` JDBC 属性。

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

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


****  

| 处理程序类型 | 类 | 
| --- | --- | 
| 复合处理程序 | SaphanaCompositeHandler | 
| 元数据处理程序 | SaphanaMetadataHandler | 
| 记录处理程序 | SaphanaRecordHandler | 

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


****  

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

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

以下示例属性适用于 Lambda 函数支持的单个 SAP HANA 实例。


****  

| 属性 | 值 | 
| --- | --- | 
| default | saphana://jdbc:sap://saphana1.host:port/?secret=Test/RDS/Saphana1 | 

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

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


****  

| 参数 | 说明 | 
| --- | --- | 
| spill\$1bucket | 必需。溢出桶名称。 | 
| spill\$1prefix | 必需。溢出桶密钥前缀。 | 
| spill\$1put\$1request\$1headers | （可选）用于溢出的 Amazon S3 putObject 请求的请求标头和值的 JSON 编码映射（例如，\$1"x-amz-server-side-encryption" : "AES256"\$1)。有关其他可能的标头，请参阅《Amazon Simple Storage Service API 参考》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 | 

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

下表显示了适用于 JDBC 和 Apache Arrow 的相应数据类型。


****  

| JDBC | Arrow | 
| --- | --- | 
| 布尔值 | Bit | 
| 整数 | Tiny | 
| 短型 | Smallint | 
| 整数 | Int | 
| 长整型 | Bigint | 
| 浮点数 | Float4 | 
| 双精度 | Float8 | 
| 日期 | DateDay | 
| Timestamp | DateMilli | 
| 字符串 | Varchar | 
| 字节 | Varbinary | 
| BigDecimal | 十进制 | 
| ARRAY | 列表 | 

## 数据类型转换
<a name="connectors-sap-hana-data-type-conversions"></a>

除了 JDBC 到 Arrow 的转换外，连接器还执行某些其他转换，以使 SAP HANA 源和 Athena 数据类型兼容。这些转换有助于确保成功执行查询。下表显示了这些转换。


****  

| 源数据类型 (SAP HANA) | 转换后的数据类型 (Athena) | 
| --- | --- | 
| DECIMAL | BIGINT | 
| INTEGER | INT | 
| DATE | DATEDAY | 
| TIMESTAMP | DATEMILLI | 

所有其他不支持的数据类型都转换为 `VARCHAR`。

## 分区和拆分
<a name="connectors-sap-hana-partitions-and-splits"></a>

分区由类型为 `Integer` 的单个分区列表示。该列包含在 SAP HANA 表上定义的分区的分区名称。对于没有分区名称的表，返回 \$1，相当于单个分区。分区等同于拆分。


****  

| 名称 | Type | 说明 | 
| --- | --- | --- | 
| PART\$1ID | 整数 | SAP HANA 中的命名分区。 | 

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

SAP HANA 支持本机分区。Athena SAP HANA 连接器可从这些分区并行检索数据。如果您想查询具有统一分区分布的超大型数据集，强烈建议使用本机分区。选择列的子集可以显著减少查询运行时及扫描的数据。由于并发，连接器显示出严重的节流，有时还会出现查询失败。

Athena SAP HANA 连接器执行谓词下推，以减少查询扫描的数据量。`LIMIT` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。

### LIMIT 子句
<a name="connectors-saphana-performance-limit-clauses"></a>

`LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。

### Predicates
<a name="connectors-saphana-performance-predicates"></a>

谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena SAP HANA 连接器可以组合这些表达式并将其直接推送到 SAP HANA，以增强功能并减少扫描的数据量。

以下 Athena SAP HANA 连接器运算符支持谓词下推：
+ **布尔值：**AND、OR、NOT
+ **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN

### 组合下推示例
<a name="connectors-saphana-performance-pushdown-example"></a>

要增强查询功能，组合下推类型，如以下示例所示：

```
SELECT * 
FROM my_table 
WHERE col_a > 10 
    AND ((col_a + col_b) > (col_c % col_d))
    AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') 
LIMIT 10;
```

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

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

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

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

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

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

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

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

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

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

有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-saphana)。