Skip to main content

​
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
  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: 
{
  "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:
{
  "Sid": "AthenaAccess",
  "Effect": "Allow",
  "Action": [
    "athena:StartQueryExecution",
    "athena:GetQueryExecution",
    "athena:GetQueryResults",
    "athena:StopQueryExecution",
    "athena:GetWorkGroup"
  ],
  "Resource": "arn:aws:athena:<region>:<account-id>:workgroup/<workgroup-name>"
}
Glue — restrict to a specific database and its tables:
{
  "Sid": "GlueAccess",
  "Effect": "Allow",
  "Action": [
    "glue:GetDatabase",
    "glue:GetDatabases",
    "glue:GetTable",
    "glue:GetTables",
    "glue:GetPartitions"
  ],
  "Resource": [
    "arn:aws:glue:<region>:<account-id>:catalog",
    "arn:aws:glue:<region>:<account-id>:database/<database-name>",
    "arn:aws:glue:<region>:<account-id>:table/<database-name>/*"
  ]
}
Replace <region>, <account-id>, <workgroup-name>, and <database-name> 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
  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 DirectoryAthena 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
  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 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