This page provides a guide to Establishing a Connection to Amazon Athena in CData Cloud, as well as information on the available resources, and a reference to the available connection properties.

Connecting to Amazon Athena

Establishing a Connection shows how to authenticate to Amazon Athena and configure any necessary connection properties to create a database in CData Cloud

Accessing Data from CData Cloud Services

Accessing data from Amazon Athena through the available standard services and CData Cloud administration is documented in further details in the CData Cloud Documentation.

Connect to Amazon Athena by selecting the corresponding icon in the Database tab. Required properties are listed under Settings. The Advanced tab lists connection properties that are not typically required.

Connecting to Amazon Athena

• DataSource: The name of the Amazon Athena data source to connect to.
• Database: The name of the Amazon Athena database to connect to.
• AWSRegion: Set this to the region where your Amazon Athena data is hosted.
• S3StagingDirectory: Set this to a folder in S3 where you would like to store the results of queries.

If Database and DataSource are not specified, the Cloud tries to list all databases from the available data sources in Amazon Athena. Setting both properties improves the performance of the Cloud.

Authenticating to Amazon Athena

Obtain AWS Keys

1. Sign into the IAM console.
2. In the navigation pane, select Users.
3. To create or manage the access keys for a user, select the user and then go to the Security Credentials tab.

1. Sign into the AWS Management console with the credentials for your root account.
2. Select your account name or number.
3. In the menu that displays, select My Security Credentials.
4. To manage or create root account access keys, click Continue to Security Credentials and expand the "Access Keys" section.

Root Credentials

To authenticate using account root credentials, set these configuration parameters:

• AuthScheme: AwsRootKeys.
• AWSAccessKey: The access key associated with the AWS root account.
• AWSSecretKey: The secret key associated with the AWS root account.

Note: Use of this authentication scheme is discouraged by Amazon for anything but simple tests. The account root credentials have the full permissions of the user, making this the least secure authentication method.

If multi-factor authentication is required, specify the following:

• CredentialsLocation: The location of the settings file where MFA credentials are saved. See the Credentials File Location page under Connection String Options for more information.
• MFASerialNumber: The serial number of the MFA device if one is being used.
• MFAToken: The temporary token available from your MFA device.

Note: If you want to control the duration of the temporary credentials, set the TemporaryTokenDuration property (default: 3600 seconds).

Temporary Credentials

To authenticate using temporary credentials, specify the following:

• AuthScheme: TemporaryCredentials.
• AWSAccessKey: The access key of the IAM user to assume the role for.
• AWSSecretKey: The secret key of the IAM user to assume the role for.
• AWSSessionToken: Your AWS session token, provided with your temporary credentials. For details, see AWS Identity and Access Management User Guide.

The Cloud can now request resources using the same permissions provided by long-term credentials (such as IAM user credentials) for the lifespan of the temporary credentials.

To authenticate using both temporary credentials and an IAM role, set all the parameters described above, and specify these additional parameters:

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This prompts the Cloud to retrieve credentials for the specified role.
• AWSExternalId (optional): Only required if you are assuming a role in another AWS account.

If multi-factor authentication is required, specify the following:

• CredentialsLocation: The location of the settings file where MFA credentials are saved. See the Credentials File Location page under Connection String Options for more information.
• MFASerialNumber: The serial number of the MFA device if one is being used.
• MFAToken: The temporary token available from your MFA device.

Note: If you want to control the duration of the temporary credentials, set the TemporaryTokenDuration property (default: 3600 seconds).

EC2 Instances

Set AuthScheme to AwsEC2Roles.

If you are using the Cloud from an EC2 Instance and have an IAM Role assigned to the instance, you can use the IAM Role to authenticate. Since the Cloud automatically obtains your IAM Role credentials and authenticates with them, it is not necessary to specify AWSAccessKey and AWSSecretKey.

If you are also using an IAM role to authenticate, you must additionally specify the following:

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the Cloud to attempt to retrieve credentials for the specified role.
• AWSExternalId (optional): Only required if you are assuming a role in another AWS account.

IMDSv2 Support

The Amazon Athena Cloud now supports IMDSv2. Unlike IMDSv1, the new version requires an authentication token. Endpoints and response are the same in both versions.

In IMDSv2, the Amazon Athena Cloud first attempts to retrieve the IMDSv2 metadata token and then uses it to call AWS metadata endpoints. If it is unable to retrieve the token, the Cloud reverts to IMDSv1.

AWS Web Identity

Set AuthScheme to AwsWebIdentity.

If you are using the Cloud from a container configured to assume role with web identity (such as a Pod in an EKS cluster with an OpenID Provider) or have obtained an identity token by authenticating with a web identity provider associated with an IAM role, you can exchange the web identity token and IAM role information for temporary security credentials to authenticate and access AWS services. The Cloud automatically obtains the credentials if the container has AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE specified in the environment variables. Alternatively, you can specify both AWSRoleARN and AWSWebIdentityToken to execute the AssumeRoleWithWebIdentity API operation and authenticate.

AWS IAM Roles

Set AuthScheme to AwsIAMRoles.

In many situations, it may be preferable to use an IAM role for authentication instead of the direct security credentials of an AWS root user. If you are specifying the AWSAccessKey and AWSSecretKey of an AWS root user, you may not use roles.

To authenticate as an AWS role, set these properties:

• AWSAccessKey: The access key of the IAM user to assume the role for.
• AWSSecretKey: The secret key of the IAM user to assume the role for.
• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the Cloud to attempt to retrieve credentials for the specified role.
• AWSExternalId (optional): Only required if you are assuming a role in another AWS account.

If multi-factor authentication is required, specify the following:

• CredentialsLocation: The location of the settings file where MFA credentials are saved. See the Credentials File Location page under Connection String Options for more information.
• MFASerialNumber: The serial number of the MFA device if one is being used.
• MFAToken: The temporary token available from your MFA device.

Note: If you want to control the duration of the temporary credentials, set the TemporaryTokenDuration property (default: 3600 seconds).

ADFS

To connect to ADFS, set the AuthScheme to ADFS, and set these properties:

• User: The ADFS user.
• Password: The ADFS user's password.
• SSOLoginURL: The SSO provider's login url.

Example connection string:

AuthScheme=ADFS; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://adfs.domain.com'; AWSRoleArn=arn:aws:iam::1234:role/ADFS_SSO; AWSPrincipalArn=arn:aws:iam::1234:saml-provider/ADFSProvider; S3StagingDirectory=s3://athena/staging;

ADFS Integrated

The ADFS Integrated flow indicates you are connecting with the currently logged in Windows user credentials. To use the ADFS Integrated flow, do not specify the User and Password, but otherwise follow the same steps in the ADFS guide above.

Okta

To connect to Okta, set the AuthScheme to Okta, and set these properties:

• User: The Okta user.
• Password: The Okta user's password.
• SSOLoginURL: The SSO provider's login URL.

If you are using a trusted application or proxy that overrides the Okta client request OR configuring MFA, you must use combinations of SSOProperties to authenticate using Okta. Set any of the following, as applicable:

• APIToken: When authenticating a user via a trusted application or proxy that overrides the Okta client request context, set this to the API Token the customer created from the Okta organization.
• MFAType: If you have configured the MFA flow, set this to one of the following supported types: OktaVerify, Email, or SMS.
• MFAPassCode: If you have configured the MFA flow, set this to a valid passcode.
  If you set this to empty or an invalid value, the Cloud issues a one-time password challenge to your device or email. After the passcode is received, reopen the connection where the retrieved one-time password value is set to the MFAPassCode connection property.
• MFARememberDevice: True by default. Okta supports remembering devices when MFA is required. If remembering devices is allowed according to the configured authentication policies, the Cloud sends a device token to extend MFA authentication lifetime. If you do not want MFA to be remembered, set this variable to False.

Example connection string:

AuthScheme=Okta; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://cdata-us.okta.com/home/amazon_aws/0oa35m8arsAL5f5NrE6NdA356/272'; SSOProperties='ApiToken=01230GGG2ceAnm_tPAf4MhiMELXZ0L0N1pAYrO1VR-hGQSf;'; AWSRoleArn=arn:aws:iam::1234:role/Okta_SSO; AWSPrincipalARN=arn:aws:iam::1234:saml-provider/OktaProvider; S3StagingDirectory=s3://athena/staging;

To connect to PingFederate, set AuthScheme to PingFederate, and set these properties:

• User: The PingFederate user.
• Password: The PingFederate user's password.
• SSOLoginURL: The SSO provider's login url.
• AWSRoleARN (optional): If you have multiple role ARNs, specify the one you want to use for authorization.
• AWSPrincipalARN (optional): If you have multiple principal ARNs, specify the one you want to use for authorization.
• SSOExchangeUrl: The Partner Service Identifier URI configured in your PingFederate server instance under: SP Connections > SP Connection > WS-Trust > Protocol Settings. This should uniquely identify a PingFederate SP Connection, so it is a good idea to set it to your AWS SSO ACS URL. You can find it under AWS SSO > Settings > View Details next to the Authentication field.
• SSOProperties (optional): Authscheme=Basic if you want to include your username and password as an authorization header in requests to Amazon S3.

To enable mutual SSL authentication for SSOLoginURL, the WS-Trust STS endpoint, configure these SSOProperties:

• SSLClientCert
• SSLClientCertType
• SSLClientCertSubject
• SSLClientCertPassword

Example connection string:

authScheme=pingfederate;SSOLoginURL=https://mycustomserver.com:9033/idp/sts.wst;SSOExchangeUrl=https://us-east-1.signin.aws.amazon.com/platform/saml/acs/764ef411-xxxxxx;user=admin;password=PassValue;AWSPrincipalARN=arn:aws:iam::215338515180:saml-provider/pingFederate;AWSRoleArn=arn:aws:iam::215338515180:role/SSOTest2;AWSRegion=Ireland;S3StagingDirectory=s3://somedirectory/staging;Database=athenadatabase;

Credentials Files

You can use a credentials file to authenticate. Any configurations related to AccessKey/SecretKey authentication, temporary credentials, role authentication, or MFA can be used. To do so, set the following properties to authenticate:

• AuthScheme: AwsCredentialsFile.
• AWSCredentialsFile: The location of your credentials file.
• AWSCredentialsFileProfile (optional): The name of the profile you would like to use from the specified credentials file. If not specified, the default profile is used.

AWS Cognito Credentials

If you want to use the Cloud with a user registered in a User Pool in AWS Cognito, set the following properties to authenticate:

• AuthScheme: Set this to AwsCognitoSrp (recommended). You can also use AwsCognitoBasic.
• AWSCognitoRegion: Set this to the region of the User Pool.
• AWSUserPoolId: Set this to the User Pool Id.
• AWSUserPoolClientAppId: Set this to the User Pool Client App Id.
• AWSUserPoolClientAppSecret: Set this to the User Pool Client Secret.
• AWSIdentityPoolId: Set this to the Identity Pool Id of the Identity Pool that is linked with the User Pool.
• User: Set this to the username of the user registered in the User Pool.
• Password: Set this to the password of the user registered in the User Pool.

Azure Active Directory/Microsoft Entra ID

This configuration uses 2.0 On-Behalf-Of flow (Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow ), which requires two Microsoft Entra applications:

• the "Amazon Athena" application used for single sign-on
• a separate "connector" application with user_impersonation permission on the "Amazon Athena" application

You must follow the steps outlined in Microsoft's AWS Single-Account Access documentation to create the SSO application and set Microsoft Entra ID as the SAML IdP for an AWS single-account app.

To create an application with user_impersonation permission on the SSO application, follow these steps:

1. Sign into the Microsoft Entra admin center as at least a Cloud Application Administrator.
2. Navigate to Identity > Applications > App registrations.
3. Click New application at the top of the page.
4. Enter a name and select supported account types as desired.
5. Select Web in the Redirect URI dropdown, and enter http://localhost:33333.
6. Select Register.
7. In the "Overview" section, you can see your OAuthClientId (Application ID).
8. Select API permissions > Add a permission.
9. Select the API of your SSO application by specifying its name or Application Id in the "APIs my organization uses" tab.
10. Select user_impersonation from the available list of Permissions.
11. Select Add permissions.
12. Select Certificates & secrets.
13. Select New client secret.
14. Optionally, enter a description and change the default Expires value, then select Add.
15. Save your client secret (the Value field of the OAuth secret that is displayed).

• OAuthClientId: The application Id of the connector application, listed in the Overview section of the application registration.
• OAuthClientSecret : The client secret value of the connector application. Azure AD displays this when you create a new client secret.
• CallbackURL: Set this to the redirect URI of the connector application. For example: https://localhost:33333.
• InitiateOAuth: GETANDREFRESH.

Use the following SSOProperties to authenticate to AzureAD:

• Resource: The application Id URI of the Amazon Athena application, listed in the Overview section of the application registration. In most cases this is the URL of your custom Amazon Athena domain.
• AzureTenant: The Id of the Azure AD tenant where the applications are registered.

The following is an example connection string:

AuthScheme=AzureAD;InitiateOAuth=GETANDREFRESH;OAuthClientId=3ea1c786-d527-4399-8c3b-2e3696ae4b48;OauthClientSecret=xxx;CallbackUrl=https://localhost:33333;SSOProperties='Resource=https://signin.aws.amazon.com/saml;AzureTenant=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

Customizing Amazon Athena Behavior

Follow the steps below to configure the Cloud defaults for querying Amazon Athena.

Using QueryPassthrough

Amazon Athena supports a set of queries that are not specified in the regular SQL-92 standard; to execute these queries simply set QueryPassthrough to true. This will pass the query directly to Amazon Athena without parsing it internally.

Flattening Nested Objects and Arrays

The Cloud is capable of flattening array elements and object properties into columns. See the pages for FlattenArrays and FlattenObjects for more information.

Encrypting Query Results to S3

Set EncryptionKey and EncryptionType if you would like to encrypt the result set stored in S3 after query execution.

To encrypt results stored in S3, follow the steps below:

1. Navigate to Amazon Athena Console.
2. Click Settings.
3. Enable the Encrypt Query Results option.
4. Select the Encryption type and set EncryptionType when you connect.
5. If you selected SSE-KMS or CSE-KMS, set both EncryptionType and EncryptionKey: select an encryption key in the menu or click Create KMS Key.

Cleaning Query Results

Amazon Athena stores the results of every query you execute in CSV files in S3StagingDirectory; these can quickly rack up a lot of space in Amazon S3. You can use CleanQueryResults, enabled by default, to clean these files for every query executed.

Note that this behavior will add a minor performance hit when you disconnect the last connection in a process.

Using Athena's Query Caching

You configure QueryCachingLevel to modify the usage of the query results stored in S3StagingDirectory; note that you have to keep the connection open to benefit from this feature. This is especially helpful when executing a certain query multiple times. This means Amazon Athena will not scan the same data again and simply use the results from the previous execution. These results are cleaned in the amount of seconds specified in QueryTolerance.

Note that failing to properly disconnect the connection when QueryCachingLevel is set to Cloud may lead to a large amount of saved queries in Athena. For most use cases setting QueryCachingLevel to Local should be enough.

Fine Tuning Performance

You can use the PageSize property to optimize use of your provisioned throughput, based on the size of your items and Amazon Athena's 1000MB page size. Set this property to the number of items to return.

Generally, a smaller page size reduces spikes in throughput that cause throttling. A smaller page size also inserts pauses between requests. This interval evens out the distribution of requests and allows more requests to be successful by avoiding throttling.

We recommend using predefined roles for services rather than creating custom IAM policies, but it if you want to create custom polices, use the roles described in the table below. Note that the specific policies required by the Amazon Athena driver are subject to change in future releases. Amazon Athena requires at a minimum the following permissions:

"arn:aws:athena:us-east-1:987654321098:datacatalog/*"

            "Resource": [
                "arn:aws:glue:region123:111111111111:table/*/*",
                "arn:aws:glue:region123:111111111111:database/*",
                "arn:aws:glue:region123:111111111111:catalog"
            ]
			

Federated Queries

    {
        "Effect": "Allow",
        "Action": [
            "lambda:InvokeFunction"
        ],
        "Resource": [
            "arn:aws:lambda:us-east-1:987654321098:function:cloudwatchtest1"
        ]
    }
 

Customizing the SSL Configuration

By default, the Cloud attempts to negotiate TLS with the server. The server certificate is validated against the default system trusted certificate store. You can override how the certificate gets validated using the SSLServerCert connection property.

To specify another certificate, see the SSLServerCert connection property.

Connecting Through a Firewall or Proxy

HTTP Proxies

To authenticate to an HTTP proxy, set the following:

• ProxyServer: the hostname or IP address of the proxy server that you want to route HTTP traffic through.
• ProxyPort: the TCP port that the proxy server is running on.
• ProxyAuthScheme: the authentication method the Cloud uses when authenticating to the proxy server.
• ProxyUser: the username of a user account registered with the proxy server.
• ProxyPassword: the password associated with the ProxyUser.

Other Proxies

Set the following properties:

• To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
• To tunnel the connection, set FirewallType to TUNNEL.
• To authenticate, specify FirewallUser and FirewallPassword.
• To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.

Stored Procedures

System Tables

CData Cloud - Amazon Athena Data Model

The Cloud dynamically extracts all relevant schema information from Amazon Athena via the REST API.

Discovering Schemas

By default, all Amazon Athena entities will be exposed as views. However, the Cloud is also capable of dividing object types into the following types from the Amazon Athena API :

• TABLE
• VIEW

You can enable this functionality by setting MetadataDiscoveryMethod to Glue. This method will require you to also add the necessary IAM profiles for the user.

Alternatively, you can use the Athena discovery method, though this method is slower.

• MetadataDiscoveryMethod: Set this to Athena.
• IncludeTableTypes: Set this to True.

Note that while the Cloud can break Amazon Athena objects into these types, they are all considered to be read-only. Reconnect to load any changes in the metadata, such as added or removed columns or changes in data type.

Stored procedures are function-like interfaces that extend the functionality of the Cloud beyond simple SELECT/INSERT operations with Amazon Athena.

Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Amazon Athena, along with an indication of whether the procedure succeeded or failed.

CData Cloud - Amazon Athena Stored Procedures

You can query the system tables described in this section to access schema information, information on data source functionality, and batch operation statistics.

Schema Tables

The following tables return database metadata for Amazon Athena:

• sys_catalogs: Lists the available databases.
• sys_schemas: Lists the available schemas.
• sys_tables: Lists the available tables and views.
• sys_tablecolumns: Describes the columns of the available tables and views.
• sys_procedures: Describes the available stored procedures.
• sys_procedureparameters: Describes stored procedure parameters.
• sys_keycolumns: Describes the primary and foreign keys.
• sys_indexes: Describes the available indexes.

Data Source Tables

The following tables return information about how to connect to and query the data source:

• sys_connection_props: Returns information on the available connection properties.
• sys_sqlinfo: Describes the SELECT queries that the Cloud can offload to the data source.

Query Information Tables

The following table returns query statistics for data modification queries, including batch operations::

• sys_identity: Returns information about batch operations or single updates.

Lists the available databases.

The following query retrieves all databases determined by the connection string:

SELECT * FROM sys_catalogs

Columns

Lists the available schemas.

The following query retrieves all available schemas:

          SELECT * FROM sys_schemas
          

Columns

Lists the available tables.

The following query retrieves the available tables and views:

          SELECT * FROM sys_tables
          

Columns

Describes the columns of the available tables and views.

The following query returns the columns and data types for the [AwsDataCatalog].[sampledb].Customers table:

SELECT ColumnName, DataTypeName FROM sys_tablecolumns WHERE TableName='Customers' AND CatalogName='AwsDataCatalog' AND SchemaName='sampledb'

Columns

Lists the available stored procedures.

The following query retrieves the available stored procedures:

          SELECT * FROM sys_procedures
          

Columns

Describes stored procedure parameters.

The following query returns information about all of the input parameters for the SelectEntries stored procedure:

SELECT * FROM sys_procedureparameters WHERE ProcedureName='SelectEntries' AND Direction=1 OR Direction=2

Columns

Describes the primary and foreign keys.

The following query retrieves the primary key for the [AwsDataCatalog].[sampledb].Customers table:

         SELECT * FROM sys_keycolumns WHERE IsKey='True' AND TableName='Customers' AND CatalogName='AwsDataCatalog' AND SchemaName='sampledb'
          

Columns

Describes the foreign keys.

The following query retrieves all foreign keys which refer to other tables:

         SELECT * FROM sys_foreignkeys WHERE ForeignKeyType = 'FOREIGNKEY_TYPE_IMPORT'
          

Columns

Describes the primary keys.

The following query retrieves the primary keys from all tables and views:

         SELECT * FROM sys_primarykeys
          

Columns

Describes the available indexes. By filtering on indexes, you can write more selective queries with faster query response times.

The following query retrieves all indexes that are not primary keys:

          SELECT * FROM sys_indexes WHERE IsPrimary='false'
          

Columns

Returns information on the available connection properties and those set in the connection string.

The following query retrieves all connection properties that have been set in the connection string or set through a default value:

SELECT * FROM sys_connection_props WHERE Value <> ''

Columns

Describes the SELECT query processing that the Cloud can offload to the data source.

See SQL Compliance for SQL syntax details.

Discovering the Data Source's SELECT Capabilities

Below is an example data set of SQL capabilities. Some aspects of SELECT functionality are returned in a comma-separated list if supported; otherwise, the column contains NO.

The following query retrieves the operators that can be used in the WHERE clause:

SELECT * FROM sys_sqlinfo WHERE Name = 'SUPPORTED_OPERATORS'

Columns

Returns information about attempted modifications.

The following query retrieves the Ids of the modified rows in a batch operation:

         SELECT * FROM sys_identity
          

Columns

Describes the available system information.

The following query retrieves all columns:

SELECT * FROM sys_information

Columns

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider. Click the links for further details.

Authentication

Connection

AWS Authentication

SSO

OAuth

SSL

Logging

Schema

Miscellaneous

This section provides a complete list of the Authentication properties you can configure in the connection string for this provider.

Your Athena VPC Endpoint. It will override the default athena.{region}.amazonaws.com endpoint.

Data Type

string

Default Value

""

Remarks

Your Athena VPC Endpoint. It will override the default athena.{region}.amazonaws.com endpoint.

Specifies the location Amazon Athena will use to store the results of a query.

Data Type

string

Default Value

""

Remarks

Specifies the location Amazon Athena will use to store the results of a query. This folder can occupy space over the course of time and you may want to clean it manually if CleanQueryResults is not enabled.

Specifies the encryption option for query results in Athena.

Possible Values

Data Type

string

Default Value

"None"

Remarks

Specifies the encryption option for query results in Athena. This option is required if you have configured Amazon Athena to encrypt query results; Set EncryptionType and EncryptionKey if you would like to encrypt the result set stored in S3 after query execution. Note that setting these properties does not encrypt the result set in S3StagingDirectory.

To encrypt Amazon Athena query results, follow the following steps:

1. Navigate to Amazon Athena Console.
2. Click Settings.
3. Enable the Encrypt Query Results option.
4. Select the Encryption type.
5. If you selected SSE-KMS or CSE-KMS, select an encryption key in the menu or click Create KMS Key. Set EncryptionKey in addition to EncryptionType when you connect.

Specifies the encryption key when encrypting results stored in S3.

Data Type

string

Default Value

""

Remarks

Specifies the encryption key when encrypting results stored in S3. This option is required if the EncryptionType is set to SSE_KMS or CSE_KMS.

Set EncryptionType and EncryptionKey if you would like to encrypt the result set stored in S3 after query execution. Note that this does not encrypt the result set in S3StagingDirectory.

Enabling Encryption

To enable the encryption of results stored in S3, see Fine-Tuning Data Access.

Obtaining an Encryption Key

You can create a key when you enable encryption. Or, create a key in the IAM console: Click Encryption Keys, select a region, and then click Create Key. To obtain the key, sign into the AWS Management console and click Services -> IAM -> Encryption Keys -> Create Key.

The name of the Athena Data Source.

Data Type

string

Default Value

""

Remarks

The data source to connect to when querying Athena. For MetadataDiscoveryMethod=Glue, AwsDataCatalog is used as the default data source.

The name of the Athena database.

Data Type

string

Default Value

""

Remarks

The database to connect to when querying Athena.

This section provides a complete list of the Connection properties you can configure in the connection string for this provider.

The Account Id to use when retrieving metadata from Glue. Default is current account id.

Data Type

string

Default Value

""

Remarks

When the property MetadataDiscoveryMethod has been set to 'Glue' then user is able to specify a Cross Account Id which they have permissions to access, and this account will be used to retrieve metadata. See more information here: https://docs.aws.amazon.com/glue/latest/dg/cross-account-access.html

This setting specifies the threshold, in bytes, above which the provider will choose to perform a multipart upload rather than uploading everything in one request.

Data Type

string

Default Value

""

Remarks

This setting specifies the threshold, in bytes, above which the Cloud will choose to perform a multipart upload rather than uploading everything in one request.

When this property is set to true, AWSLakeFormation service will be used to retrieve temporary credentials, which enforce access policies against the user based on the configured IAM role. The service can be used when authenticating through OKTA, ADFS, AzureAD, PingFederate, while providing a SAML assertion.

Data Type

bool

Default Value

false

Remarks

When this property is set to true, AWSLakeFormation service will be used to retrieve temporary credentials, which enforce access policies against the user based on the configured IAM role. The service can be used when authenticating through OKTA, ADFS, AzureAD, PingFederate, while providing a SAML assertion.

This section provides a complete list of the AWS Authentication properties you can configure in the connection string for this provider.

Specifies the type of authentication to use when connecting to Amazon Athena. If this property is left blank, the default authentication is used.

Possible Values

Data Type

string

Default Value

"AwsRootKeys"

Remarks

• TemporaryCredentials: Authenticate using temporary security credentials alongside a session token.
• AwsRootKeys: Authenticate using the root user access key and secret, to test something quickly. (Production use cases are encouraged to use something with narrowed permissions.)
• AwsIAMRoles: Authenticate using IAM Roles.
• AwsEC2Roles: Automatically use IAM Roles assigned to the EC2 machine where Cloud is currently running.
• Okta: Set to use a single sign on connection with OKTA as the identity provider.
• ADFS: Set to use a single sign on connection with ADFS as the identity provider.
• PingFederate: Set to use a single sign on connection with PingFederate as the identity provider.
• AwsCredentialsFile: Set to use a credential file for authentication.
• AwsCognitoSrp: Set to use Cognito based authentication. This is recommended over AwsCognitoBasic because this option does NOT send the password to the server for authentication, instead it uses the SRP protocol.
• AwsCognitoBasic: Set to use Cognito based authentication.

Specifies your AWS account access key. This value is accessible from your AWS security credentials page.

Data Type

string

Default Value

""

Remarks

To find your AWS account access key:

1. Sign into the AWS Management console with the credentials for your root account.
2. Select your account name or number.
3. Select My Security Credentials in the menu.
4. Click Continue to Security Credentials.
5. To view or manage root account access keys, expand the Access Keys section.

Your AWS account secret key. This value is accessible from your AWS security credentials page.

Data Type

string

Default Value

""

Remarks

Your AWS account secret key. This value is accessible from your AWS security credentials page:

1. Sign into the AWS Management console with the credentials for your root account.
2. Select your account name or number and select My Security Credentials in the menu that is displayed.
3. Click Continue to Security Credentials and expand the Access Keys section to manage or create root account access keys.

The Amazon Resource Name of the role to use when authenticating.

Data Type

string

Default Value

""

Remarks

When authenticating outside of AWS, it is common to use a Role for authentication instead of your direct AWS account credentials. Entering the AWSRoleARN will cause the CData Cloud to perform a role based authentication instead of using the AWSAccessKey and AWSSecretKey directly. The AWSAccessKey and AWSSecretKey must still be specified to perform this authentication. You cannot use the credentials of an AWS root user when setting RoleARN. The AWSAccessKey and AWSSecretKey must be those of an IAM user.

The ARN of the SAML Identity provider in your AWS account.

Data Type

string

Default Value

""

Remarks

The ARN of the SAML Identity provider in your AWS account.

The hosting region for your Amazon Web Services.

Possible Values

Data Type

string

Default Value

"NORTHERNVIRGINIA"

Remarks

The hosting region for your Amazon Web Services. Available values are OHIO, NORTHERNVIRGINIA, NORTHERNCALIFORNIA, OREGON, CAPETOWN, HONGKONG, HYDERABAD, JAKARTA, MALAYSIA, MELBOURNE, MUMBAI, OSAKA, SEOUL, SINGAPORE, SYDNEY, TOKYO, CENTRAL, CALGARY, BEIJING, NINGXIA, FRANKFURT, IRELAND, LONDON, MILAN, PARIS, SPAIN, STOCKHOLM, ZURICH, TELAVIV, BAHRAIN, UAE, SAOPAULO, GOVCLOUDEAST, GOVCLOUDWEST, ISOLATEDUSEAST, ISOLATEDUSEASTB, ISOLATEDUSWEST, and ISOLATEDEUWEST.

Your AWS session token.

Data Type

string

Default Value

""

Remarks

Your AWS session token. This value can be retrieved in different ways. See this link for more info.

A unique identifier that might be required when you assume a role in another account.

Data Type

string

Default Value

""

Remarks

A unique identifier that might be required when you assume a role in another account.

The serial number of the MFA device if one is being used.

Data Type

string

Default Value

""

Remarks

You can find the device for an IAM user by going to the AWS Management Console and viewing the user's security credentials. For virtual devices, this is actually an Amazon Resource Name (such as arn:aws:iam::123456789012:mfa/user).

The temporary token available from your MFA device.

Data Type

string

Default Value

""

Remarks

If MFA is required, this value will be used along with the MFASerialNumber to retrieve temporary credentials to login. The temporary credentials available from AWS will only last up to 1 hour by default (see TemporaryTokenDuration). Once the time is up, the connection must be updated to specify a new MFA token so that new credentials may be obtained.

The amount of time (in seconds) a temporary token will last.

Data Type

string

Default Value

"3600"

Remarks

Temporary tokens are used with both MFA and Role based authentication. Temporary tokens will eventually time out, at which time a new temporary token must be obtained. For situations where MFA is not used, this is not a big deal. The CData Cloud will internally request a new temporary token once the temporary token has expired.

However, for MFA required connection, a new MFAToken must be specified in the connection to retrieve a new temporary token. This is a more intrusive issue since it requires an update to the connection by the user. The maximum and minimum that can be specified will depend largely on the connection being used.

For Role based authentication, the minimum duration is 900 seconds (15 minutes) while the maximum if 3600 (1 hour). Even if MFA is used with role based authentication, 3600 is still the maximum.

For MFA authentication by itself (using an IAM User or root user), the minimum is 900 seconds (15 minutes), the maximum is 129600 (36 hours).

The hosting region for AWS Cognito.

Possible Values

Data Type

string

Default Value

"NORTHERNVIRGINIA"

Remarks

The hosting region for AWS Cognito. Available values are OHIO, NORTHERNVIRGINIA, NORTHERNCALIFORNIA, OREGON, CAPETOWN, HONGKONG, HYDERABAD, JAKARTA, MALAYSIA, MELBOURNE, MUMBAI, OSAKA, SEOUL, SINGAPORE, SYDNEY, TOKYO, CENTRAL, CALGARY, BEIJING, NINGXIA, FRANKFURT, IRELAND, LONDON, MILAN, PARIS, SPAIN, STOCKHOLM, ZURICH, TELAVIV, BAHRAIN, UAE, SAOPAULO, GOVCLOUDEAST, GOVCLOUDWEST, ISOLATEDUSEAST, ISOLATEDUSEASTB, ISOLATEDUSWEST, and ISOLATEDEUWEST.

The User Pool Id.

Data Type

string

Default Value

""

Remarks

You can find this in AWS Cognito -> Manage User Pools -> select your user pool -> General settings -> Pool Id.

The User Pool Client App Id.

Data Type

string

Default Value

""

Remarks

You can find this in AWS Cognito -> Manage Identity Pools -> select your user pool -> General settings -> App clients -> App client Id.

Optional. The User Pool Client App Secret.

Data Type

string

Default Value

""

Remarks

You can find this in AWS Cognito -> Manage Identity Pools -> select your user pool -> General settings -> App clients -> App client secret.

The Identity Pool Id.

Data Type

string

Default Value

""

Remarks

You can find this in AWS Cognito -> Manage Identity Pools -> select your identity pool -> Edit identity pool -> Identity Pool Id

The OAuth 2.0 access token or OpenID Connect ID token that is provided by an identity provider.

Data Type

string

Default Value

""

Remarks

The OAuth 2.0 access token or OpenID Connect ID token that is provided by an identity provider. An application can get this token by authenticating a user with a web identity provider. If not specified, the value for this connection property is automatically obtained from the value of the 'AWS_WEB_IDENTITY_TOKEN_FILE' environment variable.

This section provides a complete list of the SSO properties you can configure in the connection string for this provider.

The IDP user used to authenticate the IDP via SSO.

Data Type

string

Default Value

""

Remarks

Together with Password, this field is used to authenticate in SSO connections against the Amazon Athena server.

The password used to authenticate the IDP user via SSO.

Data Type

string

Default Value

""

Remarks

The User and Password are together used in SSO connections to authenticate with the server.

The identity provider's login URL.

Data Type

string

Default Value

""

Remarks

The identity provider's login URL.

Additional properties required to connect to the identity provider in a semicolon-separated list.

Data Type

string

Default Value

""

Remarks

Additional properties required to connect to the identity provider in a semicolon-separated list. SSOProperties is used in conjunction with the the AWSRoleARN and AWSPrincipalARN. The following section provides an example using the OKTA identity provider.

ADFS

To connect to ADFS, set the AuthScheme to ADFS, and set these properties:

• User: The ADFS user.
• Password: The ADFS user's password.
• SSOLoginURL: The SSO provider's login url.

Example connection string:

AuthScheme=ADFS; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://adfs.domain.com'; AWSRoleArn=arn:aws:iam::1234:role/ADFS_SSO; AWSPrincipalArn=arn:aws:iam::1234:saml-provider/ADFSProvider; S3StagingDirectory=s3://athena/staging;

ADFS Integrated

The ADFS Integrated flow indicates you are connecting with the currently logged in Windows user credentials. To use the ADFS Integrated flow, do not specify the User and Password, but otherwise follow the same steps in the ADFS guide above.

Okta

To connect to Okta, set the AuthScheme to Okta, and set these properties:

• User: The Okta user.
• Password: The Okta user's password.
• SSOLoginURL: The SSO provider's login URL.

If you are using a trusted application or proxy that overrides the Okta client request OR configuring MFA, you must use combinations of SSOProperties to authenticate using Okta. Set any of the following, as applicable:

• APIToken: When authenticating a user via a trusted application or proxy that overrides the Okta client request context, set this to the API Token the customer created from the Okta organization.
• MFAType: If you have configured the MFA flow, set this to one of the following supported types: OktaVerify, Email, or SMS.
• MFAPassCode: If you have configured the MFA flow, set this to a valid passcode.
  If you set this to empty or an invalid value, the Cloud issues a one-time password challenge to your device or email. After the passcode is received, reopen the connection where the retrieved one-time password value is set to the MFAPassCode connection property.
• MFARememberDevice: True by default. Okta supports remembering devices when MFA is required. If remembering devices is allowed according to the configured authentication policies, the Cloud sends a device token to extend MFA authentication lifetime. If you do not want MFA to be remembered, set this variable to False.

Example connection string:

AuthScheme=Okta; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://cdata-us.okta.com/home/amazon_aws/0oa35m8arsAL5f5NrE6NdA356/272'; SSOProperties='ApiToken=01230GGG2ceAnm_tPAf4MhiMELXZ0L0N1pAYrO1VR-hGQSf;'; AWSRoleArn=arn:aws:iam::1234:role/Okta_SSO; AWSPrincipalARN=arn:aws:iam::1234:saml-provider/OktaProvider; S3StagingDirectory=s3://athena/staging;

The URL used for consuming the SAML response and exchanging it for service specific credentials.

Data Type

string

Default Value

""

Remarks

The CData Cloud will use the URL specified here to consume a SAML response and exchange it for service specific credentials. The retrieved credentials are the final piece during the SSO connection that are used to communicate with Amazon Athena.

This section provides a complete list of the OAuth properties you can configure in the connection string for this provider.

Specifies the client Id that was assigned the custom OAuth application was created. (Also known as the consumer key.) This ID registers the custom application with the OAuth authorization server.

Data Type

string

Default Value

""

Remarks

OAuthClientId is one of a handful of connection parameters that need to be set before users can authenticate via OAuth. For details, see Establishing a Connection.

Specifies the client secret that was assigned when the custom OAuth application was created. (Also known as the consumer secret ). This secret registers the custom application with the OAuth authorization server.

Data Type

string

Default Value

""

Remarks

OAuthClientSecret is one of a handful of connection parameters that need to be set before users can authenticate via OAuth. For details, see Establishing a Connection.

This section provides a complete list of the SSL properties you can configure in the connection string for this provider.

Specifies the certificate to be accepted from the server when connecting using TLS/SSL.

Data Type

string

Default Value

""

Remarks

If using a TLS/SSL connection, this property can be used to specify the TLS/SSL certificate to be accepted from the server. Any other certificate that is not trusted by the machine is rejected.

This property can take the following forms:

If not specified, any certificate trusted by the machine is accepted.

Use '*' to signify to accept all certificates. Note that this is not recommended due to security concerns.

This section provides a complete list of the Logging properties you can configure in the connection string for this provider.

Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.

Data Type

string

Default Value

"1"

Remarks

This property defines the level of detail the Cloud includes in the log file. Higher verbosity levels increase the detail of the logged information, but may also result in larger log files and slower performance due to the additional data being captured.

The default verbosity level is 1, which is recommended for regular operation. Higher verbosity levels are primarily intended for debugging purposes. For more information on each level, refer to Logging.

When combined with the LogModules property, Verbosity can refine logging to specific categories of information.

This section provides a complete list of the Schema properties you can configure in the connection string for this provider.

Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .

Data Type

string

Default Value

""

Remarks

Listing all available database schemas can take extra time, thus degrading performance. Providing a list of schemas in the connection string saves time and improves performance.

By default, arrays are returned as strings of JSON. The FlattenArrays property can be used to flatten the elements of arrays into columns of their own. Set FlattenArrays to the number of elements you want to return from arrays.

Data Type

int

Default Value

0

Remarks

By default, arrays are returned as strings of JSON. The FlattenArrays property can be used to flatten the elements of arrays into columns of their own. This is only recommended for arrays that are expected to be short.

Set FlattenArrays to the number of elements you want to return from arrays. The specified elements are returned as columns. The zero-based index is concatenated to the column name. Other elements are ignored.

For example, you can return an arbitrary number of elements from an array of strings:

["FLOW-MATIC","LISP","COBOL"]

Setting FlattenArrays to -1 will flatten all the elements of arrays.

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON.

Data Type

bool

Default Value

false

Remarks

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON. To generate the column name, the Cloud concatenates the property name onto the object name with a dot.

For example, you can flatten the nested objects below at connection time:

[
     { "grade": "A", "score": 2 },
     { "grade": "A", "score": 6 },
     { "grade": "A", "score": 10 },
     { "grade": "A", "score": 9 },
     { "grade": "B", "score": 14 }
]

This section provides a complete list of the Miscellaneous properties you can configure in the connection string for this provider.

Amazon Athena produces cache files with every query, in the folder specified in S3StagingDirectory . CleanQueryResults specifies whether these files should be deleted once the connection is closed.

Data Type

bool

Default Value

true

Remarks

Amazon Athena stores the results of every query you execute as a CSV file in S3StagingDirectory. These CSV files can quickly rack up a lot of space in Amazon S3.

You can use CleanQueryResults, enabled by default, to clean these files for every query executed. Note that this behavior will add a minor performance hit when you disconnect the last connection in a process.

See Also

See Fine-Tuning Data Access for more information on configuring Athena's query caching.

A boolean indicating if FIPS URLs should be enabled.

Data Type

bool

Default Value

false

Remarks

FIPS or Federal Information Processing Standard are seperate endpoints in Amazon that may be required for certain government organizations. Set EnableFIPSMode to true to switch to using these endpoints. See more information here: https://aws.amazon.com/compliance/fips/.

The maximum column size.

Data Type

int

Default Value

255

Remarks

Some tools restrain the largest size of a column or the total size of all the columns selected. You can set the MaximumColumnSize to overcome these schema-based restrictions. The Cloud will not report any column to be larger than the MaximumColumnSize.

Set a MaximumColumnSize of zero to eliminate limits on column size, as shown in the following example:

Specifies the maximum rows returned for queries without aggregation or GROUP BY.

Data Type

int

Default Value

-1

Remarks

This property sets an upper limit on the number of rows the Cloud returns for queries that do not include aggregation or GROUP BY clauses. This limit ensures that queries do not return excessively large result sets by default.

When a query includes a LIMIT clause, the value specified in the query takes precedence over the MaxRows setting. If MaxRows is set to "-1", no row limit is enforced unless a LIMIT clause is explicitly included in the query.

This property is useful for optimizing performance and preventing excessive resource consumption when executing queries that could otherwise return very large datasets.

The number of results to return per page of data retrieved from Amazon Athena.

Data Type

string

Default Value

""

Remarks

This property determines the number of results to return per page of data retrieved from Amazon Athena. See Fine-Tuning Data Access for more information on settings this property to avoid request throttling. When using ResultFetcher=GetQueryResults, the default and maximum allowed value is 1000.

This determines the polling interval in milliseconds to check whether the result is ready to be retrieved.

Data Type

string

Default Value

"100"

Remarks

This property determines how long to wait between checking whether or not the query's results are ready. Very large resultsets or complex queries may take longer to process, and a low polling interval may result in many unnecessary requests being made to check the query status.

Specifies the pseudocolumns to expose as table columns. Use the format 'TableName=ColumnName;TableName=ColumnName'. The default is an empty string, which disables this property.

Data Type

string

Default Value

""

Remarks

This property allows you to define which pseudocolumns the Cloud exposes as table columns.

To specify individual pseudocolumns, use the following format: "Table1=Column1;Table1=Column2;Table2=Column3"

To include all pseudocolumns for all tables use: "*=*"

Indicates whether to read the empty values as empty or as null.

Data Type

bool

Default Value

false

Remarks

Indicates whether to read the empty values as empty or as null.

Modifies the usage of query results stored in S3StagingDirectory . Cached queries will not be scanned again by Amazon Athena until the amount of seconds specified in QueryTolerance has passed.

Possible Values

Data Type

string

Default Value

"Local"

Remarks

Modifies the usage of query results stored in S3StagingDirectory. Cached queries will not be scanned again by Amazon Athena until the amount of seconds specified in QueryTolerance has passed. The casing of the queries must match exactly to trigger the behavior, which is explained below:

The timeout in seconds for requests issued by the provider to download large result sets.

Data Type

int

Default Value

1800

Remarks

If the QueryTimeout property is set to 0, operations will not time out; instead, they will run until they complete successfully or encounter an error condition. This property is distinct from Timeout which applies to individual HTTP operations while QueryTimeout applies to execution time of the operation as a whole.

If QueryTimeout expires and the request has not finished being processed, the Cloud raises an error condition.

Specifies the amount of time in seconds queries cache for if QueryCachingLevel is not set to None.

Data Type

string

Default Value

"600"

Remarks

Specifies the amount of time in seconds queries will cache for if QueryCachingLevel is not set to None. Values lower than 1 are not accepted.

The fetcher that will be used to download query results.

Possible Values

Data Type

string

Default Value

"S3"

Remarks

This property determines how query results are fetched. If set to S3, query results are downloaded directly from Amazon S3. If set to GetQueryResults, query results are fetched utilizing the Athena APIs. If set to GetQueryResultsStream, results are fetched utilizing the Athena Stream API.

Whether or not to expose the _S3Path column for the Amazon Athena tables.

Data Type

bool

Default Value

false

Remarks

The _S3Path column refers to the Amazon Athena's $path column, which returns the path of the source Amazon S3 file for each row in the output.

The Cloud will expose the _S3Path column for each table, only if this connection property is set to TRUE.

Specifies the number of header rows to skip for SELECT queries.

Data Type

string

Default Value

""

Remarks

Specifies the number of header rows to skip for SELECT queries. This most commonly used for Athena tables that point towards a CSV data source. If the CSV data source has headers, set SkipHeaderLineCount to 1.

If you have used AWS Glue to generate tables in Athena you can find this in the "skip.header.line.count" table property.

Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error. The default is 60 seconds. Set to 0 to disable the timeout.

Data Type

int

Default Value

60

Remarks

This property controls the maximum time, in seconds, that the Cloud waits for an operation to complete before canceling it. If the timeout period expires before the operation finishes, the Cloud cancels the operation and throws an exception.

The timeout applies to each individual communication with the server rather than the entire query or operation. For example, a query could continue running beyond 60 seconds if each paging call completes within the timeout limit.

Setting this property to 0 disables the timeout, allowing operations to run indefinitely until they succeed or fail due to other conditions such as server-side timeouts, network interruptions, or resource limits on the server. Use this property cautiously to avoid long-running operations that could degrade performance or result in unresponsive behavior.

Work group of the executed queries.

Data Type

string

Default Value

""

Remarks

Work group of the executed queries.