> For the complete documentation index, see [llms.txt](https://docs.upriverdata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.upriverdata.com/integrations/aws/athena.md).

# Athena

## Integrating Amazon Athena with Upriver

Amazon Athena is a serverless, interactive query service provided by Amazon Web Services (AWS) that allows you to analyze data stored in Amazon S3 using standard SQL. By integrating Athena with Upriver, you can enhance data governance and maintain high data quality across your data lake. This integration enables efficient data monitoring, traceability, and consistency, ensuring that queries and analytics built on your S3 datasets remain accurate and reliable without requiring infrastructure management.

## Configure the Athena integration in the Upriver's Platform

The integration is configured **per catalog.** The CloudFormation stack does not need to be redeployed for each catalog, but must be updated whenever the list of monitored S3 buckets changes.

In the Upriver app, navigate to `Settings->Data Integrations` , click **"+ Add"** in the top-right corner.

### Step 1: Name and type

* Name - A user defined name for the integration.
* Type - Select **Athena** integration type.

### Step 2: Deploy CloudFormation

{% hint style="info" %}
**The CloudFormation stack must be deployed or updated whenever the list of monitored S3 buckets changes.**
{% endhint %}

#### **What should you do?**

{% columns %}
{% column width="50%" %}

<p align="center"><strong>First time connecting?</strong><br>↓<br>Download and deploy the CloudFormation template</p>
{% endcolumn %}

{% column width="50%" %}

<p align="center"><strong>Updating monitored buckets?</strong><br>↓<br>Update the existing stack in AWS CloudFormation</p>
{% endcolumn %}
{% endcolumns %}

If you already deployed this stack before and only want to add or remove buckets, update the existing stack instead of deploying a new one.

#### **Step a:** Deploy or Update CloudFormation

Deploy the provided CloudFormation template in your AWS account.

**First-time setup** - Download the CloudFormation template and deploy it as a new stack.

{% file src="/files/IyA7OTFw89yGZCh35Giy" %}

**Updating bucket access** - If the stack already exists:

Open AWS CloudFormation\
Select the existing Upriver stack\
Click Update stack\
Update the relevant parameters

**Enter the required parameters:**

* `ExistingUpriverAccessRoleName (optional)`\
  Existing Upriver access role name for this AWS account (only available if already ran another CloudFormation stack)
* `OriginTablesBucketArns`

  S3 bucket ARNs for table data locations (read-only). Include both bucket and object ARNs, same pattern as query results. Example:

  ```yaml
  arn:aws:s3:::tables-bucket
  arn:aws:s3:::tables-bucket/*
  ```
* `QueryResultBucketArns`\
  S3 bucket ARNs for query results. Make sure to include **both** bucket and its content.\
  Example:

  ```yaml
  arn:aws:s3:::query-bucket,
  arn:aws:s3:::query-bucket/*
  ```

#### **Step b: Copy outputs**

Copy Upriver access role from the stack outputs to enter in the next step.

### **Step 3: Lake Formation grants**

{% hint style="info" %}
Complete this step only if Lake Formation governs access to the Glue Data Catalog or underlying tables.
{% endhint %}

If your AWS account uses Lake Formation for data access control, the Upriver role also needs Lake Formation grants.

CloudFormation does not support wildcard Lake Formation grants across all databases. Your Lake Formation admin must grant these permissions manually for each database that Upriver needs to access:

* `DESCRIBE` on the database
* `SELECT` and `DESCRIBE` on all tables in the database

Set the role ARN from the CloudFormation stack outputs:

Then run the following commands for **each database**, make sure to:

* ROLE\_ARN - UpriverAccessRoleArn recieved from the CloudFormation stack outputs
* DATABASE\_NAME\_FOR\_UPRIVER - Replace \<DATABSE\_NAME> to the desired database
* REGION\_FOR\_UPRIVER - Replace \<REGION> to the matching region

```bash
ROLE_ARN=<upriver-access-role ARN from stack outputs>
DATABASE_NAME_FOR_UPRIVER=<DATABASE_NAME>
REGION_FOR_UPRIVER=<REGION>

aws lakeformation grant-permissions \
  --principal '{"DataLakePrincipalIdentifier": "'"$ROLE_ARN"'"}' \
  --resource '{"Database": {"Name": "'"$DATABASE_NAME_FOR_UPRIVER"'"}}' \
  --permissions DESCRIBE \
  --region "${REGION_FOR_UPRIVER}"

aws lakeformation grant-permissions \
  --principal '{"DataLakePrincipalIdentifier": "'"$ROLE_ARN"'"}' \
  --resource '{"Table": {"DatabaseName": "'"$DATABASE_NAME_FOR_UPRIVER"'", "TableWildcard": {}}}' \
  --permissions SELECT DESCRIBE \
  --region "${REGION_FOR_UPRIVER}"
```

{% hint style="warning" %}
`grant-permissions` command require that the CloudFormation deployer (the IAM principal executing the stack) has Lake Formation administrator rights or the necessary grant permissions (WITH GRANT OPTION) on those databases/tables.
{% endhint %}

### **Step 4: Finalize the integration**

Copy the CloudFormation output values and enter them in the next step of the integration wizard:

* **AthenaCatalog**\
  Athena catalog name of the catalog id used for `GlueCatalogId`
* **AthenaWorkGroup**

  The name of the workgroup to use for queries (it is recommended to create a dedicated workgroup).
* **AthenaQueryResultBucketPath**

  S3 URI to query result (from CloudFormation output)
* **UpriverAccessRoleArn**

  Upriver role with required permissions (from CloudFormation output). Example: `arn:aws:iam::<AWSAccountID>:role/upriver-access-role`

{% hint style="warning" %}
Athena workgroups expose a "override client-side settings" configuration flag. If set, it will cause Athena to use the workgroup's query results location regardless of the client request. To mitigate this Upriver recommends setting up a dedicated workgroup for its queries, with the query result path of that workgroup set to match the path described by `QueryResultBucketArns` from [#step-2-deploy-cloudformation](#step-2-deploy-cloudformation "mention").
{% endhint %}

## **Required Permissions**

The CloudFormation template creates an IAM role that grants Upriver the permissions required to query Athena and read metadata from the AWS Glue Data Catalog.

If Lake Formation governs access in your environment, that IAM role also needs Lake Formation `GetDataAccess` permission and specific database grants as specified in the terraform template and in [#step-3-lake-formation-grants](#step-3-lake-formation-grants "mention").

These permissions allow Upriver to:

* Execute and monitor Athena queries
* Retrieve query results
* Access Athena workgroups and data catalogs
* Read database and table metadata from the AWS Glue Data Catalog
* Access partitions and table versions
* Read and write Athena query results in the configured S3 results bucket
* Access Lake Formation-governed databases and tables when manual Lake Formation grants are applied

Additionally, the role includes S3 permissions that allow Athena query results to be written to and retrieved from the configured results bucket.