進階選項 - Amazon Athena
擷取大小結果擷取程式啟用結果重複使用結果重複使用最長期限使用多個 S3 執行緒使用單一目錄和結構描述使用查詢列出資料表針對字串類型使用 WCHAR查詢外部目錄驗證 SSLS3 結果區塊大小字串資料欄長度複雜類型資料欄長度可信 CA 憑證最短輪詢期間最長輪詢期間輪詢乘數最長輪詢持續時間連線逾時。請求逾時

進階選項

擷取大小

本次請求傳回結果 (列) 的最大數量。如需參數資訊，請參閱 GetQuery MaxResults。對於串流 API，最大值為 10000000。

連線字串名稱 參數類型 預設值 連線字串範例
RowsToFetchPerBlock 選用

非串流為 1000

串流為 20000

 RowsToFetchPerBlock=20000;

結果擷取程式

預設的結果擷取程式會直接從 Amazon S3 下載查詢結果，而無需透過 Athena API 操作。當其偵測到無法直接下載 S3 的情況時，即會自動回退至使用 GetQueryResultsStream API 操作。例如，當使用 CSE_KMS 選項加密查詢結果時，就會發生這種情況。

在大多數情況下，建議使用 auto 擷取程式。不過，如果您的 IAM 政策或 S3 儲存貯體政策使用 s3:CalledVia 條件來限制存取來自 Athena 的 S3 物件請求，則自動擷取程式會先嘗試從 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 用戶端達到 1 Gbps，而多執行緒 S3 用戶端則達到 4 Gbps 的網路輸送量。

連線字串名稱 參數類型 預設值 連線字串範例

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

控制是否在使用 AWS SDK 時驗證 SSL 憑證。這個值會傳遞給 ClientConfiguration.verifySSL 參數。如需詳細資訊，請參閱《適用於 C++ 的 AWS SDK 開發人員指南》中的 AWS 用戶端組態。

連線字串名稱 參數類型 預設值 連線字串範例
VerifySSL 選用 1 VerifySSL=0;

S3 結果區塊大小

指定單一 Amazon S3 GetObject API 請求下載的區塊大小 (以位元組為單位)。預設值為 67108864 (64 MB)。允許的最小值和最大值為 10485760 (10 MB) 和 2146435072 (約 2 GB)。

連線字串名稱 參數類型 預設值 連線字串範例
S3ResultBlockSize 選用 67108864 S3ResultBlockSize=268435456;

字串資料欄長度

為具有 string 資料類型的資料欄指定資料欄長度。由於 Athena 使用沒有定義精確度的 Apache Hive 字串資料類型，因此 Athena 報告的預設長度為 2147483647 (INT_MAX)。由於 BI 工具通常會為資料欄預先配置記憶體，這可能會導致記憶體耗用量過高。若要避免這種情況，Athena ODBC 驅動器會限制報告的 string 資料類型的資料欄精確度，並公開 StringColumnLength 連線參數，以便可以變更預設值。

連線字串名稱 參數類型 預設值 連線字串範例
StringColumnLength 選用 255 StringColumnLength=65535;

複雜類型資料欄長度

為具有複雜資料類型 (例如 map、struct 和 array) 的資料欄指定資料欄長度。與 StringColumnLength 類似，Athena 會針對具有複雜資料類型的資料欄報告 0 精確度。Athena ODBC 驅動器會設定複雜資料類型的資料欄預設精確度，並公開 ComplexTypeColumnLength 連線參數，以便可以變更預設值。

連線字串名稱 參數類型 預設值 連線字串範例
ComplexTypeColumnLength 選用 65535 ComplexTypeColumnLength=123456;

可信 CA 憑證

指示 HTTP 用戶端在何處找到您的 SSL 憑證信任存放區。這個值會傳遞給 ClientConfiguration.caFile 參數。如需詳細資訊，請參閱《適用於 C++ 的 AWS SDK 開發人員指南》中的 AWS 用戶端組態。

連線字串名稱 參數類型 預設值 連線字串範例
TrustedCerts 選用 %INSTALL_PATH%/bin TrustedCerts=C:\\Program Files\\Amazon Athena ODBC Driver\\bin\\cacert.pem;

最短輪詢期間

指定輪詢 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 的 AWS SDK 開發人員指南》中的用戶端組態。

連線字串名稱 參數類型 預設值 連線字串範例
ConnectionTimeout 選用 0 ConnectionTimeout=2000;

請求逾時

指定 HTTP 用戶端的通訊端讀取逾時。此值是為 Athena 用戶端的 ClientConfiguration.requestTimeoutMs 參數設定的。如需參數資訊，請參閱《適用於 Java 的 AWS SDK 開發人員指南》中的用戶端組態。

連線字串名稱 參數類型 預設值 連線字串範例
RequestTimeout 選用 10000 RequestTimeout=30000;