View a markdown version of this page

高级选项 - Amazon Athena
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

高级选项

提取大小

要在此请求中返回的最大结果(行)数。有关参数信息,请参阅 GetQuery MaxResults。对于流式处理 API,最大值为 10000000。

连接字符串名称 参数类型 默认 值 连接字符串示例
RowsToFetchPerBlock 可选

1000(对于非流式处理)

20000(对于流式处理)

RowsToFetchPerBlock=20000;

结果提取器

默认结果提取器直接从 Amazon S3 下载查询结果,而无需通过 Athena API 操作获取。当它检测到无法直接下载 S3 的情况时,它会自动回退到使用 GetQueryResultsStream API 操作。例如,当使用 CSE_KMS 选项加密查询结果时,就会发生这种情况。

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

注意

驱动程序仍可识别“启用流式处理 API”(UseResultsetStreaming=1;) 和“启用 S3 提取器”(EnableS3Fetcher=1;) 参数。但是,我们鼓励您使用 ResultFetcher 参数以获得更好的体验。

连接字符串名称 参数类型 默认 值 可能的值 连接字符串示例

ResultFetcher

可选 auto auto, S3, GetQueryResults, GetQueryResultsStream ResultFetcher=auto

启用结果重用

指定运行查询时是否可以重用先前查询结果。有关参数信息,请参阅 ResultReuseByAgeConfiguration。

连接字符串名称 参数类型 默认 值 连接字符串示例
EnableResultReuse 可选 0 EnableResultReuse=1;

结果重用最长使用期限

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

连接字符串名称 参数类型 默认 值 连接字符串示例
ReusedResultMaxAgeInMinutes 可选 60 ReusedResultMaxAgeInMinutes=90;

使用多个 S3 线程

使用多个线程从 Amazon S3 获取数据。启用此选项后,存储在 Amazon S3 存储桶中的结果文件将使用多个线程并行获取。

仅当网络带宽适合时,才启用此选项。例如,在我们对 EC2 c5.2xlarge 实例进行的测量中,单线程 S3 客户端的网络吞吐量达到了 1Gbps,而多线程 S3 客户端达到了 4Gbps。

连接字符串名称 参数类型 默认 值 连接字符串示例

UseMultipleS3Threads

可选 0 UseMultipleS3Threads=1;

使用单一目录和架构

默认情况下,ODBC 驱动程序会查询 Athena 以获取可用目录和架构列表。此选项将强制驱动程序使用 ODBC 数据来源管理器配置对话框或连接参数指定的目录和架构。

连接字符串名称 参数类型 默认 值 连接字符串示例
UseSingleCatalogAndSchema 可选 0 UseSingleCatalogAndSchema=1;

使用查询来列出表

对于 LAMBDA 目录类型,允许 ODBC 驱动程序提交SHOW TABLES查询来获取可用表的列表。此设置是默认设置。如果此参数设置为 0,则 ODBC 驱动程序将使用 Athena ListTableMetadata API 来获取可用表的列表。请注意,对于 LAMBDA 目录类型,使用 ListTableMetadata 会导致性能下降。

连接字符串名称 参数类型 默认 值 连接字符串示例
UseQueryToListTables 可选 1 UseQueryToListTables=1;

使用 WCHAR 作为字符串类型

默认情况下,ODBC 驱动程序在 Athena 中使用 SQL_CHAR 和 SQL_VARCHAR 字符串数据类型 char、varchar、string、array、map<>、struct<> 和 row。将此参数设置为 1,会强制驱动程序将 SQL_WCHAR 和 SQL_WVARCHAR 作为字符串数据类型。使用宽字符和宽可变字符类型,可确保正确存储和检索不同语言的字符。

连接字符串名称 参数类型 默认 值 连接字符串示例
UseWCharForStringTypes 可选 0 UseWCharForStringTypes=1;

查询外部目录

指定驱动程序是否需要从 Athena 查询外部目录。有关更多信息,请参阅 迁移到 ODBC 2.x 驱动程序。

连接字符串名称 参数类型 默认 值 连接字符串示例
QueryExternalCatalogs 可选 0 QueryExternalCatalogs=1;

验证 SSL

控制在使用 Amazon SDK 时是否验证 SSL 证书。此值将传递给 ClientConfiguration.verifySSL 参数。有关更多信息,请参阅《适用于 C++ 的 Amazon SDK 开发人员指南》中的 Amazon 客户端配置。

连接字符串名称 参数类型 默认 值 连接字符串示例
VerifySSL 可选 1 VerifySSL=0;

S3 结果块大小

以字节为单位指定要为单一 Amazon S3 GetObject API 请求下载的数据块大小。默认值为 67108864(64MB)。允许的最小值和最大值分别为 10485760(10MB)和 2146435072(约 2GB)。

连接字符串名称 参数类型 默认 值 连接字符串示例
S3ResultBlockSize 可选 67108864 S3ResultBlockSize=268435456;

字符串列长度

为具有 string 数据类型的列指定列长度。由于 Athena 使用 Apache Hive 字符串数据类型,但该数据类型并未定义精度,所以 Athena 报告的默认长度为 2147483647 (INT_MAX)。商业智能工具通常会为列预先分配内存,这可能会导致内存消耗较高。为避免这种情况,Athena ODBC 驱动程序会限制 string 数据类型列的报告精度,也会公开 StringColumnLength 连接参数,以便可以更改默认值。

连接字符串名称 参数类型 默认值 连接字符串示例
StringColumnLength 可选 255 StringColumnLength=65535;

复杂类型列长度

为具有复杂数据类型(如 map、struct 和 array)的列指定列长度。与 StringColumnLength 一样,对于具有复杂数据类型的列,Athena 报告的精度为 0。Athena ODBC 驱动程序会为具有复杂数据类型的列设置默认精度,也会公开 ComplexTypeColumnLength 连接参数,以便可以更改默认值。

连接字符串名称 参数类型 默认值 连接字符串示例
ComplexTypeColumnLength 可选 65535 ComplexTypeColumnLength=123456;

可信 CA 证书

利用以下操作系统指南,使用 TrustedCerts 参数配置证书验证。有关更多信息,请参阅 Encryption in transit。

按操作系统划分的 TrustedCerts 行为
操作系统 默认行为 私有 CA 配置
Windows 该驱动程序使用操作系统信任存储进行证书验证。Windows WinHTTP 客户端不使用 TrustedCerts 参数中的路径。 在 Windows 中配置私有 CA,以便 WinHTTP 对其产生信任。
Linux 如果未设置此参数,则驱动程序会检查 CURL_CA_BUNDLE 和 SSL_CERT_FILE 环境变量。然后检查一系列众所周知的系统路径。驱动程序将在进程的整个生命周期内缓存所解析的 CA 路径。更改任一环境变量后重新启动应用程序。 将 TrustedCerts 或其中一个环境变量设置为 CA 捆绑包的路径。该参数优先于环境变量和系统路径。
macOS 如果未设置此参数,证书验证将使用系统 curl 库的默认信任存储。 将 TrustedCerts 设置为信任存储文件的路径。
连接字符串名称 参数类型 默认 值 连接字符串示例
TrustedCerts 可选 未设置。证书验证遵循按操作系统划分的 TrustedCerts 行为中的平台行为。 TrustedCerts=/etc/ssl/certs/cacert.pem;

User-Agent 隐私模式

使用此参数可控制驱动程序发送给身份提供商请求的 User-Agent 标头中是否包含运行时环境元数据。默认情况下,该驱动程序包含此元数据。将此参数设置为 1 可省略身份提供商请求中的操作系统、架构和执行环境元数据。标头继续以 lib/AmazonAthenaODBC#<version> 的格式包含驱动程序标识符。只有字面值为 1 才会启用隐私模式。

此参数仅适用于身份提供商请求。无论此设置如何,向 Amazon 服务(包括 Athena、Amazon Glue 和 Amazon S3)发送的请求始终包含完整的 User-Agent 标头。Windows 集成身份验证继续使用浏览器 User-Agent。

如果旧版身份提供商策略不接受 User-Agent 标头含有运行时环境元数据,则使用此参数。

连接字符串名称 参数类型 默认 值 连接字符串示例
UserAgentPrivacyMode 可选 0 UserAgentPrivacyMode=1;

最小轮询期

指定在 Athena 中轮询查询执行状态之前要等待的最小时间值(以毫秒为单位)。

连接字符串名称 参数类型 默认 值 连接字符串示例
MinQueryExecutionPollingInterval 可选 100 MinQueryExecutionPollingInterval=200;

最大轮询期

指定在 Athena 中轮询查询执行状态之前要等待的最大时间值(以毫秒为单位)。

连接字符串名称 参数类型 默认 值 连接字符串示例
MaxQueryExecutionPollingInterval 可选 60000 MaxQueryExecutionPollingInterval=1000;

轮询乘数

指定增加轮询期的系数。默认情况下,轮询以最小轮询期值开始,每次轮询时都翻倍,直到达到最大轮询期值。

连接字符串名称 参数类型 默认 值 连接字符串示例
QueryExecutionPollingIntervalMultiplier 可选 2 QueryExecutionPollingIntervalMultiplier=2;

最长轮询持续时间

指定驱动程序可以在 Athena 中轮询查询执行状态的最大时间值(以毫秒为单位)。

连接字符串名称 参数类型 默认 值 连接字符串示例
MaxPollDuration 可选 1800000 MaxPollDuration=1800000;

连接超时

HTTP 连接等待建立连接的时间长度(以毫秒为单位)。此值是为 ClientConfiguration.connectTimeoutMs Athena 客户端设置的。如果未指定,则使用 curl 的默认值。有关连接参数的信息,请参阅《适用于 Java 的 Amazon SDK 开发人员指南》中的客户端配置。

连接字符串名称 参数类型 默认 值 连接字符串示例
ConnectionTimeout 可选 0 ConnectionTimeout=2000;

请求超时

指定 HTTP 客户端的套接字读取超时。此值是为 Athena 客户端的 ClientConfiguration.requestTimeoutMs 参数设置的。有关更多信息,请参阅《适用于 Java 的 Amazon SDK 开发人员指南》中的客户端配置。

连接字符串名称 参数类型 默认 值 连接字符串示例
RequestTimeout 可选 10000 RequestTimeout=30000;