高级连接参数 - Amazon Athena
结果加密参数结果提取参数结果配置参数查询结果重用参数查询执行轮询参数端点覆盖参数代理配置参数日志记录参数应用程序名称连接测试重试次数网络超时
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

高级连接参数

以下各节旨在介绍 JDBC 3.x 驱动程序的高级连接参数。

结果加密参数

请注意以下几点：

  • 当 EncryptionOption 为 SSE_KMS 或 CSE_KMS 时，必须指定 Amazon KMS 密钥。

  • 当未指定 EncryptionOption 或当 EncryptionOption 为 SSE_S3 时，无法指定 Amazon KMS 密钥。

加密选项

查询结果存储在 Amazon S3 中时使用的加密类型。有关查询结果加密的信息，请参阅《Amazon Athena API Reference》中的 EncryptionConfiguration。

参数名称 别名 参数类型 默认 值 可能的值
EncryptionOption S3OutputEncOption（已弃用） 可选 none SSE_S3、SSE_KMS、CSE_KMS

KMS 密钥

KMS 密钥 ARN 或 ID（如果选择 SSE_KMS 或 CSE_KMS 作为加密选项）。有关更多信息，请参阅《Amazon Athena API Reference》中的 EncryptionConfiguration。

参数名称 别名 参数类型 默认 值
KmsKey S3OutputEncKMSKey（已弃用） 可选 none

结果提取参数

结果提取器

将用于下载查询结果的提取器。

默认的结果提取器 auto 会直接从 Amazon S3 下载查询结果，无需使用 Athena API。无法直接下载 S3 时（例如查询结果使用 CSE_KMS 选项进行加密时），将会自动回退到使用 GetQueryResultsStream API。

在大多数情况下，建议使用 auto 提取器。如果 IAM 策略或 S3 存储桶策略使用 s3:CalledVia 条件来限制从 Athena 对 S3 对象请求的访问，则 auto 提取器会首先尝试从 S3 下载结果，然后回退使用 GetQueryResultsStream API。在这种情况下，您可以将 ResultFetcher 设置为 GetQueryResultsStream，从而避免额外的 API 调用。

参数名称 别名 参数类型 默认 值 可能的值
ResultFetcher none 可选 自动 auto、S3、GetQueryResults、GetQueryResultsStream

提取大小

此参数的值用作内部缓冲区的最小值，也在提取结果时用作目标页面大小。值 0（零）表示驱动程序应使用其默认值，如下所述。最大值为 1,000,000。

参数名称 别名 参数类型 默认 值
FetchSize RowsToFetchPerBlock（已弃用） 可选 0

  • GetQueryResults 提取器将始终使用 1,000 的页面大小，因为这是 API 调用支持的最大值。当提取大小超出 1,000 时，为了填充超过最小值的缓冲区，会连续进行多次 API 调用。

  • GetQueryResultsStream 提取器将使用配置的提取大小或默认值 10,000 作为页面大小。

  • S3 提取器将使用配置的提取大小或默认值 10,000 作为页面大小。

结果配置参数

预期存储桶拥有者

预期的 S3 存储桶拥有者的账户 ID。如果您提供的账户 ID 与存储桶的实际拥有者不匹配，则请求将失败。有关验证 S3 存储桶拥有者的更多信息，请参阅验证存储桶所有权。

参数名称 别名 参数类型 默认 值
ExpectedBucketOwner none 可选 none

Acl 选项

表示应设置 Amazon S3 标准 ACL 以控制存储的查询结果的所有权。有关 AclOption 的更多信息，请参阅 AclConfiguration。

参数名称 别名 参数类型 默认 值 可能的值
AclOption none 可选 none BUCKET_OWNER_FULL_CONTROL

查询结果重用参数

启用结果重用

指定在运行查询时是否可以重用同一查询的先前结果。有关查询结果重用的信息，请参阅 ResultReuseByAgeConfiguration。

参数名称 别名 参数类型 默认 值
EnableResultReuseByAge none 可选 FALSE

结果重用最长使用期限

Athena 应考虑的先前查询结果的重用最长使用期限（以分钟为单位）。有关结果重用最长使用期限的信息，请参阅 ResultReuseByAgeConfiguration。

参数名称 别名 参数类型 默认 值
MaxResultReuseAgeInMinutes none 可选 60

查询执行轮询参数

查询执行的最小轮询间隔

在 Athena 中轮询查询执行状态之前要等待的最短时间（以毫秒为单位）。

参数名称 别名 参数类型 默认 值
MinQueryExecutionPollingIntervalMillis MinQueryExecutionPollingInterval（已弃用） 可选 100

查询执行的最大轮询间隔

在 Athena 中轮询查询执行状态之前要等待的最长时间（以毫秒为单位）。

参数名称 别名 参数类型 默认 值
MaxQueryExecutionPollingIntervalMillis MaxQueryExecutionPollingInterval（已弃用） 可选 5000

查询执行轮询间隔乘数

用于增加轮询期的系数。默认情况下，轮询将以 MinQueryExecutionPollingIntervalMillis 的值开始，每次轮询时都翻倍，直到达到 MaxQueryExecutionPollingIntervalMillis 的值。

参数名称 别名 参数类型 默认 值
QueryExecutionPollingIntervalMultiplier none 可选 2

端点覆盖参数

Athena 端点覆盖

驱动程序用于对 Athena 进行 API 调用的端点。

请注意以下几点：

  • 如果未在提供的 URL 中指定 https:// 或 http:// 协议，则驱动程序会插入 https:// 前缀。

  • 如果未指定此参数，驱动程序会使用默认的端点。

参数名称 别名 参数类型 默认 值
AthenaEndpoint EndpointOverride（已弃用） 可选 none

Athena 流式传输服务端点覆盖

驱动程序在使用 Athena 流式传输服务时用于下载查询结果的端点。Athena 流式传输服务在端口 444 上可用。

请注意以下几点：

  • 如果未在提供的 URL 中指定 https:// 或 http:// 协议，则驱动程序会插入 https:// 前缀。

  • 如果未在提供的 URL 中指定端口，则驱动程序会插入流式传输服务端口 444。

  • 如果未指定 AthenaStreamingEndpoint 参数，则驱动程序将使用 AthenaEndpoint 覆盖。如果既未指定 AthenaStreamingEndpoint 也未指定 AthenaEndpoint 覆盖，则驱动程序将使用默认的流式传输端点。

参数名称 别名 参数类型 默认 值
AthenaStreamingEndpoint StreamingEndpointOverride（已弃用） 可选 none

Lake Formation 端点覆盖

当使用 Amazon Lake Formation AssumeDecoratedRoleWithSAML API 检索临时凭证时，驱动程序将为 Lake Formation 服务使用的端点。如果未指定此参数，驱动程序会使用默认的 Lake Formation 端点。

请注意以下几点：

  • 如果未在提供的 URL 中指定 https:// 或 http:// 协议，则驱动程序会插入 https:// 前缀。

参数名称 别名 参数类型 默认 值
LakeFormationEndpoint

LfEndpointOverride（已弃用）

 可选 none

S3 端点覆盖

驱动程序在使用 Amazon S3 提取器时用于下载查询结果的端点。如果未指定此参数，驱动程序会使用默认的 Amazon S3 端点。

请注意以下几点：

  • 如果未在提供的 URL 中指定 https:// 或 http:// 协议，则驱动程序会插入 https:// 前缀。

参数名称 别名 参数类型 默认 值
S3Endpoint 无 可选 none

STS 端点覆盖

当使用 Amazon STS AssumeRoleWithSAML API 检索临时凭证时，驱动程序将为 Amazon STS 服务使用的端点。如果未指定此参数，驱动程序会使用默认的 Amazon STS 端点。

请注意以下几点：

  • 如果未在提供的 URL 中指定 https:// 或 http:// 协议，则驱动程序会插入 https:// 前缀。

参数名称 别名 参数类型 默认 值
StsEndpoint StsEndpointOverride（已弃用） 可选 none

SSO OIDC 端点覆盖

使用 ClientConfiguration.endpointOverride 覆盖 SSO OIDC 客户端的默认 HTTP 端点时驱动程序会使用的端点。有关更多信息，请参阅 ClientConfiguration。

参数名称 别名 参数类型 默认 值
SSOOIDCEndpointOverride 可选 none

SSO 管理端点覆盖

使用 ClientConfiguration.endpointOverride 覆盖 SSO 管理客户端的默认 HTTP 端点时驱动程序会使用的端点。有关更多信息，请参阅 ClientConfiguration。

参数名称 别名 参数类型 默认 值
SSOAdminEndpointOverride 可选 none

代理配置参数

代理主机

代理主机的 URL。如果需要 Athena 请求来通过代理，请使用此参数。

注意

请务必在 ProxyHost 的 URL 的开头处包含 https:// 或 http:// 协议。

参数名称 别名 参数类型 默认 值
ProxyHost none 可选 none

代理端口

要在代理主机上使用的端口。如果需要 Athena 请求来通过代理，请使用此参数。

参数名称 别名 参数类型 默认 值
ProxyPort none 可选 none

代理用户名

用于对代理服务器进行身份验证的用户名。如果需要 Athena 请求来通过代理，请使用此参数。

参数名称 别名 参数类型 默认 值
ProxyUsername ProxyUID（已弃用） 可选 none

代理密码

用于对代理服务器进行身份验证的密码。如果需要 Athena 请求来通过代理，请使用此参数。

参数名称 别名 参数类型 默认 值
ProxyPassword ProxyPWD（已弃用） 可选 none

代理豁免主机

启用代理后（即设置了 ProxyHost 和 ProxyPort 连接参数），驱动程序在不使用代理的情况下连接到的一组主机名。主机应用管道 (|) 字符分隔（例如 host1.com|host2.com）。

参数名称 别名 参数类型 默认 值
ProxyExemptHosts NonProxyHosts 可选 none

为身份提供者启用代理

指定当驱动程序连接到身份提供者时是否应使用代理。

参数名称 别名 参数类型 默认 值
ProxyEnabledForIdP UseProxyForIdP 可选 FALSE

日志记录参数

本节旨在介绍与日志记录相关的参数。

日志级别

指定驱动程序日志记录的级别。除非还设置了 LogPath 参数，否则不会记录任何内容。

注意

除非有特殊要求，否则建议仅设置 LogPath 参数。仅设置 LogPath 参数即可启用日志记录并使用默认的 TRACE 日志级别。TRACE 日志级别提供了最详细的日志记录。

参数名称 别名 参数类型 默认 值 可能的值
LogLevel none 可选 TRACE OFF、ERROR、WARN、INFO、DEBUG、TRACE

日志路径

运行驱动程序的计算机上存储驱动程序日志的目录路径。将在指定目录中创建的具有唯一名称的日志文件。如果已设置，则启用驱动程序日志记录。

参数名称 别名 参数类型 默认 值
LogPath none 可选 none

应用程序名称

使用该驱动程序的应用程序的名称。如果为此参数指定了值，则该值将包含在驱动程序对 Athena 进行的 API 调用的用户代理字符串中。

注意

您也可以通过调用 DataSource 对象上的 setApplicationName 来设置应用程序名称。

参数名称 别名 参数类型 默认 值
ApplicationName none 可选 none

连接测试

如果设置为 TRUE，则每次创建 JDBC 连接时，驱动程序都会执行连接测试，即使未对该连接执行查询也是如此。

参数名称 别名 参数类型 默认 值
ConnectionTest none 可选 TRUE
注意

连接测试会向 Athena 提交 SELECT 1 查询来验证连接配置是否正确。这意味着两个文件将存储在 Amazon S3 中（结果集和元数据），并且可能会根据Amazon Athena 定价策略收取额外费用。

重试次数

驱动程序应向 Athena 重新发送可检索请求的最大次数。

参数名称 别名 参数类型 默认 值
NumRetries MaxErrorRetry（已弃用） 可选 none

网络超时

网络超时控制驱动程序等待建立网络连接的时间。这包括发送 API 请求所需的时间。在极少数情况下，更改网络超时可能会有用。例如，您可能想要增加长时间垃圾回收暂停的超时时间。设置此连接参数等同于在 Connection 对象上使用 setNetworkTimeout 方法。

参数名称 别名 参数类型 默认 值

NetworkTimeoutMillis

 none 可选 none