Athena

datarelix.ai connects to AWS Athena through a read-only query service. Athena speaks Trino/Presto SQL and reads table metadata from the AWS Glue Data Catalog — see Getting started with Athena.

Prerequisites

An AWS account with Athena enabled in your target region.
An S3 bucket for query result staging in the same region as Athena (Athena writes intermediate results there before datarelix.ai downloads them).
A Glue Data Catalog with the databases/tables you want to analyze. Tables must be cataloged — Athena does not auto-discover schema from raw S3 objects.
IAM permissions on the principal used for auth. At minimum: athena:StartQueryExecution, athena:GetQueryExecution, athena:GetQueryResults, glue:GetDatabase(s), glue:GetTable(s), s3:GetObject on the data S3 paths, and s3:GetObject/s3:PutObject on the staging S3 prefix.

Connection form

AWS region:           us-east-1
S3 output location:   s3://your-bucket/athena-staging/
Workgroup:            primary             (default)
Catalog:              AwsDataCatalog      (default)
Auth mode:            one of the two below

The Allowed schema field (set per-connection) scopes introspection and queries to one Glue database.

Auth modes

IAM access keys

Long-lived AWS access key + secret. The credentials are stored encrypted. Simplest path for connecting from outside AWS where no ambient IAM role is available.

Setup — create a dedicated IAM user

In the AWS Console, create an IAM user (IAM → Users → Create user). Give it a descriptive name (e.g. datarelix-athena-reader).

Choose Attach policies directly and attach a policy with the following minimum permissions (or create a custom policy — see Athena IAM policies):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "athena:StartQueryExecution",
        "athena:GetQueryExecution",
        "athena:GetQueryResults",
        "athena:StopQueryExecution",
        "athena:GetWorkGroup"
      ],
      "Resource": "arn:aws:athena:<region>:<account-id>:workgroup/primary"
    },
    {
      "Effect": "Allow",
      "Action": ["glue:GetDatabase", "glue:GetDatabases", "glue:GetTable", "glue:GetTables", "glue:GetPartitions"],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetBucketLocation"],
      "Resource": "arn:aws:s3:::your-data-bucket"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::your-data-bucket/*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::your-bucket/athena-staging/*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::your-bucket"
    }
  ]
}

After the user is created, create an access key (user → Security credentials → Access keys → Create access key). Choose Application running outside AWS. Copy the Access key ID and Secret access key — the secret is only shown once.

Where to find your credentials

Access key ID and Secret access key: IAM → Users → [your user] → Security credentials → Access keys (you must create a new key if you didn’t copy the secret at creation time).

What to enter

AWS region:           us-east-1
S3 output location:   s3://your-bucket/athena-staging/
Auth mode:            IAM access keys
Access Key ID:        AKIAIOSFODNN7EXAMPLE
Secret Access Key:    ••••••••

Assume Role

The calling identity assumes a target IAM role via AWS STS before querying Athena. Best for cross-account access: your credentials live in one account; the Athena data and permissions live in another account’s IAM role.

Setup — create the assumable role in the data account

In the data-owner AWS account, go to IAM → Roles → Create role.
Choose Another AWS account as the trusted entity and enter your calling account ID.
Attach the same Athena + Glue + S3 policy as in the IAM access keys mode above.

If you want to use an External ID (recommended to prevent confused-deputy attacks), add a condition to the trust policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::<your-calling-account>:root" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "sts:ExternalId": "your-external-id" }
    }
  }]
}

Copy the Role ARN from the role’s summary page.

The calling identity (resolved from your IAM access keys connection or ambient credentials) must have sts:AssumeRole permission on the target role ARN.

Where to find your credentials

Field	Where to get it
Role ARN	IAM (data account) → Roles → [your role] → ARN in the summary (e.g. `arn:aws:iam::123456789012:role/AthenaReaderRole`)
External ID	The value you set in the trust policy condition (if any)

What to enter

AWS region:           us-east-1
S3 output location:   s3://your-bucket/athena-staging/
Auth mode:            Assume Role
Role ARN:             arn:aws:iam::123456789012:role/AthenaReaderRole
External ID:          your-external-id    (leave blank if not required by the trust policy)

Glue Data Catalog

Athena reads schema and table metadata from the Glue Data Catalog. Tables don’t exist in Athena until they’re cataloged in Glue.

Verify your tables are visible: AWS Console → Glue → Data Catalog → Databases → click your database → see Tables.
If your data is in S3 but no Glue tables exist, run an AWS Glue crawler once to populate the catalog.
The connection’s Allowed schema field corresponds to a Glue database.
Custom catalogs (federated Glue catalogs, Hive Metastore via Lake Formation) work via the Catalog field — default is AwsDataCatalog.

IAM-only vs Lake Formation

How you grant read access depends on whether the database is governed by AWS Lake Formation:

IAM-managed catalog — the glue:Get* + s3:GetObject permissions in the IAM policy above are sufficient.
Lake Formation-governed catalog — IAM permissions are not enough. You must also grant the principal SELECT (and DESCRIBE) on the database/tables in Lake Formation, and grant DESCRIBE on the default database. Without these, queries fail with Insufficient Lake Formation permissions even when IAM is correct.

If you’re unsure, AWS Console → Lake Formation → Data lake locations: if your S3 paths are registered there, the catalog is Lake Formation-governed.

S3 staging directory

Athena writes query results to S3 before they can be downloaded. The location can also be set on the workgroup.

Region must match Athena’s region. A us-west-2 bucket with a us-east-1 Athena query fails with Query result location is invalid.
Athena does not auto-delete result files. Add an S3 lifecycle policy on the staging prefix (e.g. expire after 7 days) to keep costs bounded.

Scope semantics

The Allowed schema field limits introspection and queries to one Glue database. Blank scope is not supported — you must explicitly set a database. To analyze multiple databases, create multiple connections.

Discovery

The introspector queries INFORMATION_SCHEMA via Athena (these are small Athena queries that count toward your workgroup). Glue doesn’t track foreign keys — the LLM enrichment pass infers relationships from column-name conventions if you opt in.

Limitations

Read-only — the validator rejects write and DDL statements.
One Glue database per connection.
Query result download latency — Athena always stages to S3, then datarelix.ai fetches. Adds ~100–500 ms per query on top of compute time.

Troubleshooting

Symptom	Likely cause	Fix
`AccessDenied` on `glue:GetDatabase`/`GetTables`	Missing Glue permissions	Add the IAM actions from the policy snippet above.
`Insufficient permissions to execute the query`	Missing `s3:GetObject` on source data	Ensure the IAM principal can read the S3 paths registered in Glue.
`Query result location not set` / `is invalid`	Empty staging dir or region mismatch	Set S3 output location to an `s3://bucket/prefix/` in the same region as Athena.
`AccessDenied: ... is not authorized to perform sts:AssumeRole`	Calling identity not allowed by target role trust policy	Update the role’s trust policy to allow the calling principal.
`AccessDenied` with ExternalId	External ID missing or mismatched	Set the External ID field to the value the trust policy expects (case-sensitive).
`Insufficient Lake Formation permissions`	Lake Formation enabled on the catalog	Grant the principal `SELECT` via the Lake Formation console in addition to IAM.
`Table not found` despite Glue listing it	Wrong catalog	Confirm the Catalog field matches the catalog name in Glue (usually `AwsDataCatalog`).