# Athena Add an Athena Source Datastore

Source: https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/how-tos/add-source/

A source datastore is a storage location Qualytics connects to so it can profile, scan, and monitor data. Adding Athena as a source lets Qualytics query your AWS data lake through the Athena JDBC driver and run quality operations on the tables it discovers.

Before you start, review the [Athena Permissions](https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/permissions/) and the available [Authentication](https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/authentication/) methods.

> **Warning**
>
> Athena cannot be used as an enrichment datastore. After you add it as a source, link a separate enrichment datastore (such as BigQuery or PostgreSQL) as its destination to store anomalies and metadata: either during creation via [Link Enrichment on Datastore Creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/), or afterward via [Link an Enrichment Destination](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-enrichment/).

## Field reference

The **Add Datastore** page shows the sections below when Athena is selected. When reusing an existing connection, the **Connection Properties**, **Authentication**, and **Secrets Management** sections come already filled in and read-only: Qualytics has already validated those credentials, so you fill in only the **Location** and the **General** fields. To change a saved connection's credentials, edit the connection through the [Manage Connections](https://userguide.qualytics.io/settings/connections/manage-connections/) page; edits there apply to every datastore that reuses the connection.

### Connection Properties

These fields define the Athena endpoint and where Athena writes query results. They belong to the connection: when reusing an existing connection, they come already filled in and read-only.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Connection Name** | Yes | Text | A label for the saved connection (e.g., `acme_athena_warehouse`), so other datastores can reuse it later. |
| **Host** | Yes | Text | The canonical Athena endpoint for your region. Comes already filled in with `athena.us-east-1.amazonaws.com`; change the region part if needed. VPC endpoint URLs and private DNS aliases are not supported. |
| **Port** | Yes | Number | The Athena HTTPS port. Accepts numbers only. Defaults to `443`. |
| **S3 Output Location** | Yes | Text | The S3 path where Athena writes query results (e.g., `s3://acme-athena-results/query-output/`). The IAM identity used by Qualytics needs read and write access to this bucket. Equivalent to `parameters.output` in the API. |
| **Max Parallelization** | No | Number | Caps how many queries Qualytics runs at the same time against a datastore reached through this connection, from 1 to 100. Leave it empty for no explicit limit. The cap applies per datastore, so datastores sharing this connection each get their own allowance. Sits in the collapsed **Advanced** section of the form. See [Max Parallelization](https://userguide.qualytics.io/source-datastore/datastore/connection/how-it-works/#max-parallelization). |

> **Tip**
>
> For the IAM permissions Qualytics needs on Athena, Glue, and the S3 query-results bucket, see [Athena Permissions](https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/permissions/).

### Authentication

Choose how Qualytics authenticates to AWS. Setting **Type** changes the credential fields shown below it. These fields also belong to the connection: already filled in and read-only when reusing one.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Type** | No | Option | Authentication mode. Comes set to **Access Key**; switch to **IAM Role** to authenticate with an assumed role instead. |
| **Access Key ID** | Yes | Text | The AWS Access Key ID for an IAM user with Athena, Glue, and S3 permissions. Shown when **Type** is **Access Key**. |
| **Secret Access Key** | Yes | Text | The matching Secret Access Key. Shown when **Type** is **Access Key**. |

> **Note: IAM Role variant**
>
> When you set **Type** to **IAM Role**, the **Access Key ID** and **Secret Access Key** fields are replaced by:
>
> - **Role ARN** (required): the IAM role ARN Qualytics will assume via AWS STS.
> - **External ID** (optional): include only if your role's trust policy requires one.
>
> See [Athena Authentication](https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/authentication/) for the assume-role flow walkthrough.
>
> **AWS-only:** the **IAM Role** option in **Type** is shown only on AWS and local Qualytics deployments. On Azure and GCP deployments, only **Access Key** authentication is available.

### Secrets Management

This group is optional: use it only if you want Qualytics to pull credentials from a secrets manager instead of typing them into the form. Turn on **HashiCorp Vault** to show the fields below. Despite the label, any secrets manager that exposes a compatible REST API works, not only HashiCorp Vault; see [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/). It also belongs to the connection: read-only when reusing an existing connection.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Login URL** | Yes | Text | The full URL of the login endpoint (e.g., `https://vault.example.com/v1/auth/approle/login`). With Vault namespaces, add the namespace after `/v1/`, as in `/v1/<namespace>/auth/approle/login`. |
| **Credentials Payload** | Yes | Text | A JSON body containing the credentials Vault expects (e.g., `{"role_id":"...","secret_id":"..."}`). |
| **Token JSONPath** | Yes | Text | The JSONPath that extracts the client token from Vault's response. Defaults to `$.auth.client_token`. |
| **Secret URL** | Yes | Text | The full URL of the secret, including `https://` and the host (e.g., `https://vault.example.com/v1/secret/data/athena`). With Vault namespaces, add the namespace after `/v1/`. |
| **Token Header Name** | Yes | Text | The HTTP header name used to send the token. Defaults to `X-Vault-Token`. |
| **Data JSONPath** | Yes | Text | The JSONPath that extracts the key/value pairs from Vault's response. Use `$.data.data` for a KV version 2 secret (its API path contains `/data/`) and `$.data` for KV version 1 or the database secrets engine. The form pre-fills `$.data`. |

> **Note**
>
> Once the secrets manager is configured, reference any secret value in the **Connection Properties** or **Authentication** fields using `${key}` (e.g., `${secret_access_key}`). Qualytics resolves the secret at the moment the connection is opened, so changed keys take effect on the next connection. Write the reference with braces (`${key}`, never `$.key`) and match the key name's case. Setup steps, the namespace rule, and a troubleshooting page are on the [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/) pages.

### Location

Pick the catalog and database(s) Qualytics should read from. You fill these in on both flows.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Catalog** | Yes | Option | The Athena data catalog to read from. The field starts empty: select or type a catalog, such as `AwsDataCatalog`, the catalog every Athena account has. Click the refresh icon to fetch the catalogs visible to the credentials. |
| **Database** | Yes | Option | One or more databases inside the selected catalog. Each database you pick becomes its own Qualytics datastore. Click the refresh icon to load the available databases. |

### General

Common fields for every source datastore, shown below the **Location** section. You fill these in on both flows.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Name Template** | No | Text | Defines the naming pattern for each source datastore being created. Use `{{schema}}` as a placeholder that gets replaced with the actual database name (e.g., `athena_{{schema}}` becomes `athena_data_lake_curated`). Left empty, the datastore is named from the connection name and the database. |
| **Group** | No | Option | Organizes your datastores under a shared group in the navigation tree. Select an existing group or create a new one with the **Add New Group** toggle. |
| **Teams** | Yes | Option | Select one or more teams to associate with this source datastore. |
| **Initiate Sync** | No | Checkbox | Automatically sync the datastore to detect containers and fields after creation. |

Below the form, an information banner lists the **Public addresses** and **Private addresses** your datastore connections originate from. Allow the ones that match your network setup through your security groups or firewall rules; see [How Connections Work](https://userguide.qualytics.io/source-datastore/datastore/connection/how-it-works/#finding-the-addresses-to-allow) for where the addresses come from.

## Steps

There are two ways to set up the connection: reuse a connection you already saved (**Existing Connection**) or create a new one from scratch (**New Connection**). The tabs below walk through each option; pick the one you want to follow. Each field is described in the [Field reference](https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/how-tos/add-source/#field-reference) above.

**Tab: New Connection**

**Step 1**: Navigate to the **Datastores** page.

**Step 2**: Click the **Add**  button at the top-right corner and choose **Source** .

**Step 3**: The **Add Datastore** page opens.

**Step 4**: Select **New Connection** next to the **Search**  field.

**Step 5**: Select **Athena** from the connector grid. Use the search field to filter connectors by name.

**Step 6**: Fill in the **Connection Properties**: the **Connection Name**, **Host**, **Port**, and **S3 Output Location**.

**Step 7**: Choose the **Authentication** **Type** and fill in its credential fields.

**Step 8**: Optionally, expand **Secrets Management** to retrieve credentials from a secrets manager.

**Step 9**: Fill in the **Location** fields (**Catalog** and **Database**) and the **General** fields.

**Step 10**: Click **Test connection**. A success message confirms that the connection has been verified.

> **Info**
>
> The **Finish** and **Next** buttons stay disabled until the connection test passes on the current values. If you change a connection field after a successful test, test again. If the test fails, see [Troubleshooting](https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/troubleshooting/).

**Step 11**: Click **Finish** to create the datastore.

> **Tip**
>
> To link an enrichment destination so Qualytics can store anomalies and metadata from the first operation, click **Next** instead of **Finish**. See [Link Enrichment on Datastore Creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/).

**Step 12**: A success dialog confirms that your datastore has been added. Click **Go to your datastore** to open its page.

**Tab: Existing Connection**

**Step 1**: Navigate to the **Datastores** page.

**Step 2**: Click the **Add**  button at the top-right corner and choose **Source** .

**Step 3**: The **Add Datastore** page opens.

**Step 4**: Select **Existing Connection** next to the **Search**  field.

**Step 5**: Select the saved Athena connection from the grid. Use the search field to filter connections by name. The **Connection Properties**, **Authentication**, and **Secrets Management** sections come already filled in and read-only.

> **Tip: Start a new connection from this one**
>
> To use the selected connection as a starting point for a brand-new connection instead, click the **Duplicate as a new connection**  button on the selected connection. The form switches to **New Connection** mode with the connection's settings already filled in for you to adjust.

**Step 6**: Fill in the **Location** fields (**Catalog** and **Database**) and the **General** fields. These are the only fields left to fill in: **Teams** is the only required one, while **Name Template**, **Group**, and **Initiate Sync** are optional.

**Step 7**: Click **Test connection**. A success message confirms that the connection has been verified.

> **Info**
>
> The **Finish** and **Next** buttons stay disabled until the connection test passes on the current values. If the test fails, see [Troubleshooting](https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/troubleshooting/).

**Step 8**: Click **Finish** to create the datastore.

> **Tip**
>
> To link an enrichment destination so Qualytics can store anomalies and metadata from the first operation, click **Next** instead of **Finish**. See [Link Enrichment on Datastore Creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/).

**Step 9**: A success dialog confirms that your datastore has been added. Click **Go to your datastore** to open its page.

*Last updated: November 3, 2026.*
