# Amazon Athena Oracle 连接器 适用于 Oracle 的 Amazon Athena 连接器使 Amazon Athena 能够对存储在 Oracle（在本地或在 Amazon EC2 或 Amazon RDS 上运行）中的数据运行 SQL 查询。您还可以使用该连接器查询存储在 [Oracle Exadata](https://www.oracle.com/engineered-systems/exadata/) 上的数据。 此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。 ## 先决条件 + 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。 ## 限制 + 不支持写入 DDL 操作。 + 在多路复用器设置中，溢出桶和前缀在所有数据库实例之间共享。 + 任何相关的 Lambda 限制。有关更多信息，请参阅《*AWS Lambda 开发人员指南*》中的 [Lambda 配额](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 仅支持 12.1.0.2 版本的 Oracle 数据库。 + 如果 Oracle 连接器不使用 Glue 连接，则该连接器会将数据库、表和列的名称转换为大写字母。 如果 Oracle 连接器使用 Glue 连接，则该连接器在默认情况下不会将数据库、表和列的名称转换为大写字母。要更改这种大小写行为，请根据需要将 Lambda 环境变量 `casing_mode` 更改为 `upper` 或 `lower`。 使用 Glue 连接的 Oracle 连接器不支持使用多路复用处理程序。 + 在没有定义精度和刻度的情况下使用 Oracle `NUMBER` 时，Athena 会将其视为 `BIGINT`。要获取 Athena 中必需的小数位数，请在 Lambda 环境变量中指定 `default_scale=`。 ## 术语 以下术语与 Oracle 连接器有关。 + **数据库实例** - 部署在本地、Amazon EC2 或 Amazon RDS 上的任何数据库实例。 + **处理程序** — 访问您数据库实例的 Lambda 处理程序。处理程序可以用于元数据或数据记录。 + **元数据处理程序** — 从您的数据库实例中检索元数据的 Lambda 处理程序。 + **记录处理程序** — 从您的数据库实例中检索数据记录的 Lambda 处理程序。 + **复合处理程序** — 从您的数据库实例中检索元数据和数据记录的 Lambda 处理程序。 + **属性或参数** — 处理程序用来提取数据库信息的数据库属性。您可以将这些属性配置为 Lambda 环境变量。 + **连接字符串** — 用于建立数据库实例连接的文本字符串。 + **目录** — 向 Athena 注册的非 AWS Glue 目录，是 `connection_string` 属性的必要前缀。 + **多路复用处理程序** — 可以接受和使用多个数据库连接的 Lambda 处理程序。 ## 参数 使用本节中的参数来配置 Oracle 连接器。 ### Glue 连接（推荐） 我们建议您使用 Glue 连接对象来配置 Oracle 连接器。要执行此操作，请将 Oracle 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。 **Glue 连接属性** 使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。 ``` aws glue describe-connection-type --connection-type ORACLE ``` **Lambda 环境属性** + **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。 + **is\$1fips\$1enabled** —（可选）启用 FIPS 模式时设为 true。默认值为 false。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **小写** – 所有给定的架构和表名全部小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。对于未关联 Glue 连接的连接器，这是默认设置。 + **搜索不区分大小写** – 对 Oracle 中的架构和表名执行不区分大小写的搜索。如果查询包含的架构或表名与连接器的默认大小写模式不一致，请使用此值。 **注意** 所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。 使用 Glue 连接创建的 Oracle 连接器不支持使用多路复用处理程序。 使用 Glue 连接创建的 Oracle 连接器仅支持 `ConnectionSchemaVersion` 2。 ### 旧连接 **注意** 2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。 下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。 **Lambda 环境属性** + **默认** — 用于连接至 Oracle 数据库实例的 JDBC 连接字符串。例如，`oracle://${jdbc_connection_string}` + **catalog\$1connection\$1string** — 供多路复用处理程序使用（使用 Glue 连接时不支持）。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myoraclecatalog，则环境变量名称是 myoraclecatalog\$1connection\$1string。 + **spill\$1bucket** - 为超出 Lambda 函数限制的数据指定 Amazon S3 存储桶。 + **spill\$1prefix** -（可选）默认为指定 `spill_bucket`（称为 `athena-federation-spill`）中的子文件夹。我们建议您在此位置配置 Amazon S3 [存储生命周期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)，以删除早于预定天数或小时数的溢出内容。 + **spill\$1put\$1request\$1headers** —（可选）用于溢出的 Amazon S3 `putObject` 请求的请求标头和值的 JSON 编码映射（例如 `{"x-amz-server-side-encryption" : "AES256"}`)。有关其他可能的标头，请参阅《[Amazon Simple Storage Service API 参考](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)》中的 *PutObject*。 + **kms\$1key\$1id** -（可选）默认情况下，将使用经过 AES-GCM 身份验证的加密模式和随机生成的密钥对溢出到 Amazon S3 的任何数据进行加密。要让您的 Lambda 函数使用 KMS 生成的更强的加密密钥（如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`），您可以指定 KMS 密钥 ID。 + **disable\$1spill\$1encryption** -（可选）当设置为 `True` 时，将禁用溢出加密。默认值为 `False`，此时将使用 AES-GCM 对溢出到 S3 的数据使用进行加密 - 使用随机生成的密钥，或者使用 KMS 生成密钥。禁用溢出加密可以提高性能，尤其是当您的溢出位置使用[服务器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)时。 + **is\$1fips\$1enabled** —（可选）启用 FIPS 模式时设为 true。默认值为 false。 + **大小写模式** –（可选）指定如何处理架构和表名的大小写。`casing_mode` 参数使用以下值来指定大小写行为： + **小写** – 所有给定的架构和表名全部小写。对于关联了 Glue 连接的连接器，这是默认设置。 + **大写** – 所有给定的架构和表名全部大写。对于未关联 Glue 连接的连接器，这是默认设置。 + **搜索不区分大小写** – 对 Oracle 中的架构和表名执行不区分大小写的搜索。如果查询包含的架构或表名与连接器的默认大小写模式不一致，请使用此值。 #### 连接字符串 使用以下格式的 JDBC 连接字符串连接到数据库实例。 ``` oracle://${jdbc_connection_string} ``` **注意** 如果您的密码包含特殊字符（例如，`some.password`），则在将密码传递给连接字符串时将密码包含在双引号中（例如，`"some.password"`）。否则，可能会导致指定的 Oracle URL 无效错误。 #### 使用单个连接处理程序 您可以使用以下单个连接元数据和记录处理程序连接到单个 Oracle 实例。 **** | 处理程序类型 | 类 | | --- | --- | | 复合处理程序 | OracleCompositeHandler | | 元数据处理程序 | OracleMetadataHandler | | 记录处理程序 | OracleRecordHandler | ##### 单个连接处理程序参数 **** | 参数 | 说明 | | --- | --- | | default | 必需。默认连接字符串。 | | IsFIPSEnabled | 可选。在启用 FIPS 模式时设置为 true。默认值为 false。 | 单个连接处理程序支持一个数据库实例，并且必须提供 `default` 连接字符串参数。将忽略所有其他连接字符串。 该连接器支持基于 SSL 的与 Amazon RDS 实例的连接。支持仅限于传输层安全性协议（TLS）以及客户端对服务器的身份验证。在 Amazon RDS 中不支持相互身份验证。下表中的第二行显示了使用 SSL 的语法。 以下示例属性适用于 Lambda 函数支持的单个 Oracle 实例。 **** | 属性 | 值 | | --- | --- | | default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@//hostname:port/servicename | | | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS) (HOST=)(PORT=))(CONNECT\$1DATA=(SID=))(SECURITY=(SSL\$1SERVER\$1CERT\$1DN=))) | #### 提供凭证 要在 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}"} ``` **注意** 如果您的密码包含特殊字符（例如，`some.password`），则在将密码存储在 Secrets Manager 中时将密码包含在双引号中（例如，`"some.password"`）。否则，可能会导致指定的 Oracle URL 无效错误。 **带有密钥名称的示例连接字符串** 以下字符串带有密钥名称 `${Test/RDS/Oracle}`。 ``` oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename ``` 该连接器使用该密钥名称来检索密钥，并提供用户名和密码，如以下示例所示。 ``` oracle://jdbc:oracle:thin:username/password@//hostname:port/servicename ``` 目前，Oracle 连接器可以识别 `UID` 和 `PWD` JDBC 属性。 #### 使用多路复用处理程序 您可以使用多路复用器通过单个 Lambda 函数连接到多个数据库实例。按目录名称来路由请求。在 Lambda 中使用以下类。 **** | 处理程序 | 类 | | --- | --- | | 复合处理程序 | OracleMuxCompositeHandler | | 元数据处理程序 | OracleMuxMetadataHandler | | 记录处理程序 | OracleMuxRecordHandler | ##### 多路复用处理程序参数 **** | 参数 | 说明 | | --- | --- | | \$1catalog\$1connection\$1string | 必需。数据库实例连接字符串。将 Athena 中使用的目录的名称作为环境变量前缀。例如，如果向 Athena 注册的目录是 myoraclecatalog，则环境变量名称是 myoraclecatalog\$1connection\$1string。 | | default | 必需。默认连接字符串。当目录为 lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 时使用此字符串。 | 以下示例属性适用于支持两个数据库实例的 Oracle MUX Lambda 函数：`oracle1`（默认值）和 `oracle2`。 **** | 属性 | 值 | | --- | --- | | default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename | | oracle\$1catalog1\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename | | oracle\$1catalog2\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle2\$1@//oracle2.hostname:port/servicename | ## 数据类型支持 下表显示了适用于 JDBC、Oracle 和 Arrow 的相应数据类型。 **** | JDBC | Oracle | Arrow | | --- | --- | --- | | 布尔值 | 布尔值 | Bit | | 整数 | 不适用 | Tiny | | 短型 | smallint | Smallint | | 整数 | 整数 | Int | | 长整型 | bigint | Bigint | | 浮点数 | float4 | Float4 | | 双精度 | float8 | Float8 | | 日期 | date | DateDay | | Timestamp | timestamp | DateMilli | | 字符串 | 文本 | Varchar | | 字节 | bytes | Varbinary | | BigDecimal | numeric(p,s) | 十进制 | | ARRAY | 不适用（见注释） | 列表 | ## 分区和拆分 分区用于确定如何为该连接器生成拆分。Athena 将构建一个 `varchar` 类型的合成列，它将展示表的分区方案，以帮助该连接器生成拆分。该连接器不会修改实际的表定义。 ## 性能 Oracle 支持本机分区。Athena Oracle 连接器可从这些分区并行检索数据。如果您想查询具有统一分区分布的超大型数据集，强烈建议使用本机分区。选择列的子集可以显著减少查询运行时及扫描的数据。Oracle 连接器能够灵活地应对并发造成的节流。但是，查询运行时往往很长。 Athena Oracle 连接器可执行谓词下推，以减少查询扫描的数据量。简单谓词和复杂表达式将下推到连接器，以减少扫描的数据量并缩短查询执行的运行时间。 ### Predicates 谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Oracle 连接器可以组合这些表达式并将其直接推送到 Oracle，以增强功能并减少扫描的数据量。 以下 Athena Oracle 连接器运算符支持谓词下推： + **布尔值：**AND、OR、NOT + **相等：**EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL + **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、NEGATE + **其他：**LIKE\$1PATTERN、IN ### 组合下推示例 要增强查询功能，组合下推类型，如以下示例所示： ``` 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%'); ``` ## 传递查询 Oracle 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。 要在 Oracle 中执行传递查询，可以使用以下语法： ``` SELECT * FROM TABLE( system.query( query => 'query string' )) ``` 以下示例查询将查询下推到 Oracle 中的数据来源。该查询会选择 `customer` 表中的所有列。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer' )) ``` ## 许可证信息 使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。 ## 其他资源 有关最新 JDBC 驱动程序版本信息，请参阅 GitHub.com 上适用于 Oracle 连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 文件。 有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-oracle)。