> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Amazon Athena
> Connect Amazon Athena to ClarityQ
## Setup
### Prerequisites in AWS
Before connecting Athena to ClarityQ, you need to set up the required AWS resources and permissions.
#### Step 1: Create an IAM user for ClarityQ
1. Go to the [AWS Management Console](https://console.aws.amazon.com/)
2. Navigate to **IAM** → **Users**
3. Click **Create user**
4. Enter a descriptive name (e.g., `clarityq-athena-user`)
5. Click **Next**
#### Step 2: Assign permissions
Attach the following permissions to the IAM user. You can create a custom IAM policy with the minimum required permissions:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AthenaAccess",
"Effect": "Allow",
"Action": [
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:StopQueryExecution",
"athena:GetWorkGroup"
],
"Resource": "*"
},
{
"Sid": "GlueAccess",
"Effect": "Allow",
"Action": [
"glue:GetDatabase",
"glue:GetDatabases",
"glue:GetTable",
"glue:GetTables",
"glue:GetPartitions"
],
"Resource": "*"
},
{
"Sid": "S3StagingAccess",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:ListBucket",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::your-staging-bucket",
"arn:aws:s3:::your-staging-bucket/*"
]
},
{
"Sid": "S3DataReadAccess",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::your-data-bucket",
"arn:aws:s3:::your-data-bucket/*"
]
}
]
}
```
**Why does ClarityQ need `s3:PutObject` if it only reads data?**
Athena is a serverless query engine — it doesn't store data itself. When you run a query, Athena reads
your data from S3, processes it, and writes the results to a separate S3 staging directory. The `s3:PutObject`
permission on the staging bucket is required by Athena for this results step. ClarityQ does not write to your
data buckets.
**Important:**
* Replace `your-staging-bucket` with the S3 bucket for Athena query results.
* Replace `your-data-bucket` with the S3 bucket(s) where your source data lives. If your data spans multiple buckets, add each one to the `S3DataReadAccess` statement.
* If you use **AWS Lake Formation** to manage data access, the `S3DataReadAccess` statement may not be needed — Lake Formation can grant table-level permissions independently of S3 IAM policies.
The policy above uses `"Resource": "*"` for Athena and Glue, which grants access to all workgroups and databases.
For tighter security, you can scope permissions to specific resources by replacing `"*"` with resource ARNs.
**Athena — restrict to a single workgroup:**
```json theme={null}
{
"Sid": "AthenaAccess",
"Effect": "Allow",
"Action": [
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:StopQueryExecution",
"athena:GetWorkGroup"
],
"Resource": "arn:aws:athena:::workgroup/"
}
```
**Glue — restrict to a specific database and its tables:**
```json theme={null}
{
"Sid": "GlueAccess",
"Effect": "Allow",
"Action": [
"glue:GetDatabase",
"glue:GetDatabases",
"glue:GetTable",
"glue:GetTables",
"glue:GetPartitions"
],
"Resource": [
"arn:aws:glue:::catalog",
"arn:aws:glue:::database/",
"arn:aws:glue:::table//*"
]
}
```
Replace ``, ``, ``, and `` with your values.
The Glue `catalog` resource is required for any Glue API call to succeed.
To attach the policy:
1. In the IAM user creation flow, select **Attach policies directly**
2. Click **Create policy**, paste the JSON above, and save it (e.g., `ClarityQAthenaAccess`)
3. Attach the newly created policy to the user
4. Click **Next** then **Create user**
#### Step 3: Generate access keys
1. Select the IAM user you just created
2. Go to the **Security credentials** tab
3. Under **Access keys**, click **Create access key**
4. Select **Third-party service** as the use case
5. Click **Create access key**
6. **Save both the Access Key ID and Secret Access Key** — the secret key will not be shown again
#### Step 4: Set up the S3 staging directory
Athena requires an S3 location to store query results. If you don't already have one:
1. Go to [Amazon S3](https://console.aws.amazon.com/s3/)
2. Click **Create bucket**
3. Choose a name (e.g., `clarityq-athena-results`) and select the same region as your Athena workgroup
4. Keep the default settings (Block all public access enabled) and click **Create bucket**
Make sure the IAM user has read/write access to this bucket (already covered in the policy above).
**Workgroup query results location vs. ClarityQ S3 Staging Directory**
Athena workgroups can have their own **"Query result location"** configured in the AWS console.
If your workgroup has **"Override client-side settings"** enabled, the workgroup's location is used
and the S3 Staging Directory value you enter in ClarityQ is ignored.
Make sure the IAM policy grants `S3StagingAccess` permissions to whichever bucket actually receives
the query results — whether that's the bucket configured in ClarityQ or the one set on the workgroup.
#### Step 5: Verify your Athena workgroup
1. Go to [Amazon Athena](https://console.aws.amazon.com/athena/)
2. Navigate to **Workgroups** in the left sidebar
3. Note the workgroup name you want ClarityQ to use (default is `primary`)
4. Ensure the workgroup's **State** is **Enabled**
5. If you scoped the IAM policy to a specific workgroup (see [Restrict permissions to specific resources](#optional-restrict-permissions-to-specific-resources) above), make sure the workgroup name matches the ARN in your policy
***
### Configure connection in ClarityQ
In the ClarityQ interface, fill out the connection form with the following fields:
#### Required Fields
* **Connection Name**: Choose a name for this connection (e.g., "Production Athena")
* **AWS Region**: The AWS region where your Athena workgroup runs (e.g., `us-east-1`)
* **S3 Staging Directory**: The S3 path for query results (e.g., `s3://your-staging-bucket/athena-results/`)
* **Database**: The Athena database (Glue catalog database) to query (e.g., `default`). You can find your database name in the **Athena Query Editor** under the "Database" dropdown in the left sidebar
* **AWS Access Key ID**: The access key ID generated in Step 3
* **AWS Secret Access Key**: The corresponding secret access key
#### Optional Fields
* **Catalog**: The data catalog name (defaults to `AwsDataCatalog` — only change this if you use a custom or federated catalog)
* **Workgroup**: The Athena workgroup to use (defaults to `primary`)
## Troubleshooting
### Common connection issues
**Access Denied on S3 staging directory**
* Ensure the IAM user has `s3:PutObject` and `s3:GetObject` permissions on the staging bucket
* Verify the S3 path includes a trailing slash (e.g., `s3://bucket/prefix/`)
* Confirm the bucket is in the same region as your Athena workgroup
**Database not found**
* Check that the database exists in the AWS Glue Data Catalog for the specified region
* Verify the catalog name is correct (use `AwsDataCatalog` unless you have a custom catalog)
**Query execution timeout or workgroup errors**
* Confirm the workgroup exists and is enabled in the Athena console
* Ensure the IAM user has `athena:GetWorkGroup` permission for the specified workgroup
**InvalidIdentityToken or credential errors**
* Double-check that the Access Key ID and Secret Access Key are correct
* Ensure the IAM user is active (not deactivated) in the AWS console
* If you rotated keys, update the credentials in ClarityQ