Advanced connection parameters - Amazon Athena
Result encryption parametersResult fetching parametersQuery result reuse parametersQuery execution polling parametersEndpoint override parametersProxy configuration parametersLogging parametersApplication nameConnection TestNumber of retries
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Advanced connection parameters

The following sections describe the advanced connection parameters for the JDBC 3.x driver.

Result encryption parameters

Note the following points:

  • The Amazon KMS Key must be specified when EncryptionOption is SSE_KMS or CSE_KMS.

  • The Amazon KMS Key cannot be specified when EncryptionOption is not specified or when EncryptionOption is SSE_S3.

Encryption option

The type of encryption to be used for query results as they are stored in Amazon S3. For information about query result encryption, see EncryptionConfiguration in the Amazon Athena API Reference.

Parameter name Alias Parameter type Default value Possible values
EncryptionOption S3OutputEncOption (deprecated) Optional none SSE_S3, SSE_KMS, CSE_KMS

KMS Key

The KMS key ARN or ID, if SSE_KMS or CSE_KMS is chosen as the encryption option. For more information, see EncryptionConfiguration in the Amazon Athena API Reference.

Parameter name Alias Parameter type Default value
KmsKey S3OutputEncKMSKey (deprecated) Optional none

Result fetching parameters

Result fetcher

The fetcher that will be used to download query results.

The default result fetcher, S3, downloads query results directly from Amazon S3 without using the Athena APIs. This is the fastest option in most cases. This option is not available if your query results are encrypted with CSE_KMS or if the policy that allows the user access to query results only allows calls from Athena using s3:CalledVia.

Parameter name Alias Parameter type Default value Possible values
ResultFetcher none Optional S3 S3, GetQueryResults, GetQueryResultsStream
Note

In the JDBC 2.x driver, the UseResultsetStreaming = 1 setting configures the driver to use the result set streaming API. In the JDBC 3.x driver, the equivalent setting is ResultFetcher=GetQueryResultsStream.

Fetch size

The value of this parameter is used as the minimum for internal buffers and as the target page size when fetching results. The value 0 (zero) means that the driver should use its defaults as described below. The maximum value is 1,000,000.

Parameter name Alias Parameter type Default value
FetchSize RowsToFetchPerBlock (deprecated) Optional 0

  • The GetQueryResults fetcher will always use a page size of 1,000, which is the maximum value supported by the API call. When the fetch size is higher than 1,000, multiple successive API calls are made to fill the buffer above the minimum.

  • The GetQueryResultsStream fetcher will use the configured fetch size as the page size, or 10,000 by default.

  • The S3 fetcher will use the configured fetch size as the page size, or 10,000 by default.

Query result reuse parameters

Enable result reuse

Specifies whether previous results for the same query can be reused when a query is run. For information about query result reuse, see ResultReuseByAgeConfiguration.

Parameter name Alias Parameter type Default value
EnableResultReuseByAge none Optional FALSE

Result reuse max age

The maximum age, in minutes, of a previous query result that Athena should consider for reuse. For information about result reuse max age, see ResultReuseByAgeConfiguration.

Parameter name Alias Parameter type Default value
MaxResultReuseAgeInMinutes none Optional 60

Query execution polling parameters

Minimum query execution polling interval

The minimum time, in milliseconds, to wait before polling Athena for the query execution status.

Parameter name Alias Parameter type Default value
MinQueryExecutionPollingIntervalMillis MinQueryExecutionPollingInterval (deprecated) Optional 100

Maximum query execution polling interval

The maximum time, in milliseconds, to wait before polling Athena for the query execution status.

Parameter name Alias Parameter type Default value
MaxQueryExecutionPollingIntervalMillis MaxQueryExecutionPollingInterval (deprecated) Optional 5000

Query execution polling interval multiplier

The factor for increasing the polling period. By default, polling will begin with the value for MinQueryExecutionPollingIntervalMillis and double with each poll until it reaches the value for MaxQueryExecutionPollingIntervalMillis.

Parameter name Alias Parameter type Default value
QueryExecutionPollingIntervalMultiplier none Optional 2

Endpoint override parameters

Athena endpoint override

The endpoint that the driver will use to make API calls to Athena.

Note the following points:

  • If the https:// or http:// protocols are not specified in the provided URL, the driver inserts the https:// prefix.

  • If this parameter is not specified, the driver uses a default endpoint.

Parameter name Alias Parameter type Default value
AthenaEndpoint EndpointOverride (deprecated) Optional none

Athena streaming service endpoint override

The endpoint that the driver will use to download query results when it uses the Athena streaming service. The Athena streaming service is available on port 444.

Note the following points:

  • If the https:// or http:// protocols are not specified in the provided URL, the driver inserts the https:// prefix.

  • If a port is not specified in the provided URL, the driver inserts the streaming service port 444.

  • If the AthenaStreamingEndpoint parameter is not specified, the driver uses the AthenaEndpoint override. If neither the AthenaStreamingEndpoint nor the AthenaEndpoint override is specified, the driver uses a default streaming endpoint.

Parameter name Alias Parameter type Default value
AthenaStreamingEndpoint StreamingEndpointOverride (deprecated) Optional none

LakeFormation endpoint override

The endpoint that the driver will use for the Lake Formation service when using the Amazon Lake Formation AssumeDecoratedRoleWithSAML API to retrieve temporary credentials. If this parameter is not specified, the driver uses a default Lake Formation endpoint.

Note the following points:

  • If the https:// or http:// protocols are not specified in the provided URL, the driver inserts the https:// prefix.

Parameter name Alias Parameter type Default value
LakeFormationEndpoint

LfEndpointOverride (deprecated)

 Optional none

S3 endpoint override

The endpoint that the driver will use to download query results when it uses the Amazon S3 fetcher. If this parameter is not specified, the driver uses a default Amazon S3 endpoint.

Note the following points:

  • If the https:// or http:// protocols are not specified in the provided URL, the driver inserts the https:// prefix.

Parameter name Alias Parameter type Default value
S3Endpoint None Optional none

STS endpoint override

The endpoint that the driver will use for the Amazon STS service when using the Amazon STS AssumeRoleWithSAML API to retrieve temporary credentials. If this parameter is not specified, the driver uses a default Amazon STS endpoint.

Note the following points:

  • If the https:// or http:// protocols are not specified in the provided URL, the driver inserts the https:// prefix.

Parameter name Alias Parameter type Default value
StsEndpoint StsEndpointOverride(deprecated) Optional none

Proxy configuration parameters

Proxy host

The URL of the proxy host. Use this parameter if you require Athena requests to go through a proxy.

Note

Make sure to include the protocol https:// or http:// at the beginning of the URL for ProxyHost.

Parameter name Alias Parameter type Default value
ProxyHost none Optional none

Proxy port

The port to be used on the proxy host. Use this parameter if you require Athena requests to go through a proxy.

Parameter name Alias Parameter type Default value
ProxyPort none Optional none

Proxy username

The username to authenticate on the proxy server. Use this parameter if you require Athena requests to go through a proxy.

Parameter name Alias Parameter type Default value
ProxyUsername ProxyUID (deprecated) Optional none

Proxy password

The password to authenticate on the proxy server. Use this parameter if you require Athena requests to go through a proxy.

Parameter name Alias Parameter type Default value
ProxyPassword ProxyPWD (deprecated) Optional none

Proxy-exempt hosts

A set of host names that the driver connects to without using a proxy when proxying is enabled (that is, when the ProxyHost and ProxyPort connection parameters are set). The hosts should be separated by the pipe (|) character (for example, host1.com|host2.com).

Parameter name Alias Parameter type Default value
ProxyExemptHosts NonProxyHosts Optional none

Proxy enabled for identity providers

Specifies whether a proxy should be used when the driver connects to an identity provider.

Parameter name Alias Parameter type Default value
ProxyEnabledForIdP UseProxyForIdP Optional FALSE

Logging parameters

This section describes parameters related to logging.

Log level

Specifies the level for the driver logging. Nothing is logged unless the LogPath parameter is also set.

Note

We recommend setting only the LogPath parameter unless you have special requirements. Setting only the LogPath parameter enables logging and uses the default TRACE log level. The TRACE log level provides the most detailed logging.

Parameter name Alias Parameter type Default value Possible values
LogLevel none Optional TRACE OFF, ERROR, WARN, INFO, DEBUG, TRACE

Log path

The path to a directory on the computer that runs the driver where driver logs will be stored. A log file with a unique name will be created within the specified directory. If set, enables driver logging.

Parameter name Alias Parameter type Default value
LogPath none Optional none

Application name

The name of the application that uses the driver. If a value for this parameter is specified, the value is included in the user agent string of the API calls that the driver makes to Athena.

Note

You can also set the application name by calling setApplicationName on the DataSource object.

Parameter name Alias Parameter type Default value
ApplicationName none Optional none

Connection Test

If set to TRUE, the driver performs a connection test each time a JDBC connection is created, even if a query is not executed on the connection.

Parameter name Alias Parameter type Default value
ConnectionTest none Optional TRUE
Note

A connection test submits a SELECT 1 query to Athena to verify that the connection has been configured correctly. This means that two files will be stored in Amazon S3 (the result set and metadata), and additional charges can apply in accordance with the Amazon Athena pricing policy.

Number of retries

The maximum number of times the driver should resend a retriable request to Athena.

Parameter name Alias Parameter type Default value
NumRetries MaxErrorRetry (deprecated) Optional none