> For the complete documentation index, see [llms.txt](https://docs.getuntitled.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getuntitled.ai/custom-connections/athena-database-legacy.md).

# Athena Database (legacy)

{% hint style="warning" %}
As of Q1 2026, new database connections will be set up in Postgres. This guide is maintained for posterity, as a resource for existing Athena database users. Athena database connections will continue to function.
{% endhint %}

{% hint style="info" %}
This is a feature exclusively for enterprise accounts.
{% endhint %}

## Database Connection Overview

Untitled offers a premium feature that grants users access to a managed data warehouse, enabling integration at the data layer. All raw visitor data collected via the Untitled ID tag is exposed through a client-specific Athena database connection, which can be accessed using the credential set available in your portal.

Follow the step-by-step guide below to test your connection to the Untitled Athena database using a common method, and refer to the accompanying [documentation for schema and table structure](broken://pages/uNPCciDfD1QZMf8aIrlG) details.

## SQL Client Connection Instructions

{% hint style="info" %}
These instructions cover how to connect to the Untitled Athena database using an open-source SQL client DBeaver. We selected DBeaver for this guide because it’s free **and includes a pre-installed Athena driver.**

If you prefer to use a different SQL client, check whether it includes support for Athena. If not, you may need to install an Athena driver prior to testing your connection credentials as outlined in this guide.
{% endhint %}

### Locate your Untitled Athena Database Connection Credentials  <a href="#find-your-distilled-database-connection-credentials" id="find-your-distilled-database-connection-credentials"></a>

1. Log in to your Untitled account.
2. Select "Custom Connections" on the left-side navigation menu.
3. Your Athena credentials will be located in the tile component titled "Tag Data Warehouse"&#x20;

<figure><img src="/files/g37WfOG1cRJFYZY7WNYs" alt=""><figcaption></figcaption></figure>

### Authentication Credentials

In order to authenticate any SQL client, you'll need the following 5 details located within the Custom Connections > Tag Data Warehouse module in your Untitled Account:&#x20;

* **Region:** Enter the AWS region provided by Untitled (e.g., `us-east-1`).
* **S3 Staging Directory:** Enter the S3 bucket path provided by Untitled (e.g., `s3://your-bucket-name/`).
* **Workgroup:** Enter the workgroup name `DistilledResolutions`&#x20;
* **aws\_access\_key\_id:** `Your AWS Access Key ID.`
* **aws\_secret\_access\_key:** `Your AWS Secret Access Key.`&#x20;

## Download & Setup DBeaver (Example SQL Client)

1. DBeaver is a free and open source tool used to interact with various databases. To start, [download](https://dbeaver.io/download/) the version of DBeaver corresponding to your operating system. Once downloaded, continue to the next step.
2. Create a new database connection by selecting the plug icon in the top left corner of your screen. Once clicked a new dialog box will appear. Select `Athena` and then click `Next`.

<figure><img src="/files/NSYXqTvWlre4fFLHOXex" alt=""><figcaption></figcaption></figure>

3. Using the credentials found in the Custom Connections > Tag Data Warehouse page of your Untitled account, enter the following information into the DBeaver AWS Athena Connection Settings.

<figure><img src="/files/adi7y2KermDk3dnmQEYm" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The `Access Key` in Untitled will be your `Username` in DBeaver.

The `Secret Access Key` in Untitled will be your `Password` in DBeaver.
{% endhint %}

<figure><img src="/files/b3h8JM2H97sUcB3pHKj1" alt=""><figcaption></figcaption></figure>

4. You must edit the workgroup in order to complete the connection process. To do that, Navigate to `Driver properties` and scroll to the bottom.&#x20;
5. Next to Workgroup enter `DistilledResolutions` and then click `Finish`&#x20;

<figure><img src="/files/H464rqqpeFRGYDKp9Vql" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
If you fail to complete step 4-5 of this section, you'll recieve the following error when attempting to query the DB: *you are not authorized to perform: athena:StartQueryExecution on the resource. After your AWS administrator or you have updated your permissions, please try again. (Service: AmazonAthena; Status Code: 400; Error Code: AccessDeniedException; Request ID: da51650a-9c91-43fc-9c2c-b51588dde369;Proxy:null)*
{% endhint %}

6. You should now see your connection listed in the Database Navigator and can begin writing SQL to query your tables. To test your setup, enter the following in the SQL editor: `SELECT * FROM resolutions.visitors LIMIT 10`  Running this query should return the first 10 rows of data, confirming that your connection is working correctly.

<figure><img src="/files/CNyFJwbq7TNU0Z8B6RIf" alt=""><figcaption></figcaption></figure>

Congratulations! You’ve successfully connected to your visitor database using DBeaver. If you have questions about building a replication pipeline from this database, feel free to reach out via the Support Desk—we’re happy to assist with your specific use case.

To review the Tag Data Warehouse schema, please proceed to the following [knowledge base article. ](broken://pages/uNPCciDfD1QZMf8aIrlG)

### Manual Export (DBeaver Example)

Once you've successfully connected to the Athena Database, test the following actions to save your query results locally.&#x20;

#### Write and Execute Query <a href="#write-and-execute-query" id="write-and-execute-query"></a>

1. Write your SQL Query: Write the SQL query in DBeaver to select the data you want to export from the Untitled Athena database.
2. Execute the Query: Execute the SQL query to retrieve the results from the Untitled Athena database.

#### Export Query Results <a href="#export-query-results" id="export-query-results"></a>

1. Select Results to Export from the above query steps.
2. Export Results: *Right-click* and select the `export` option. Choose the appropriate format (e.g., CSV, Excel, etc.) and specify the export location.
3. Save Exported File: Save the exported file to the desired location on your local system.

## Connecting the Athena Database to the Looker BI Platform

{% hint style="info" %}
You can also view [Looker’s guide](https://cloud.google.com/looker/docs/db-config-amazon-athena) for setting up an integration with an Athena database.
{% endhint %}

#### Set Up Looker Connection <a href="#set-up-looker-connection" id="set-up-looker-connection"></a>

1. Log in to your Looker instance.
2. In Looker's main menu, navigate to the `Admin` section.
3. Click on `Connections` and then `Database` to create a new database connection.
4. Choose `Amazon Athena` as the database dialect.&#x20;

#### Configure Looker Connection Settings <a href="#configure-looker-connection-settings" id="configure-looker-connection-settings"></a>

{% hint style="info" %}
Where to find your Athena Database Authentication credentials within the Untitled portal was detailed in [the above steps](#find-your-distilled-database-connection-credentials).&#x20;
{% endhint %}

1. Provide a Connection Name that identifies the connection (e.g., "*Untitled Visitor Database*").
2. In Looker’s `Host` field, copy and paste the following: `athena.us-east-1.amazonaws.com`
3. Set Looker’s `Database` field to `Athena`.
4. Navigate to back to Untitled.
   1. Copy the `Access Key ID` provided under the Tag Data Warehouse and paste in the Looker `Username` field.
   2. Copy the `Secret Key` provided under Tag Data Warehouse and paste in the Looker `Password` field.
   3. Copy the `S3 Location` URL provided under Tag Data Warehouse and paste in the Looker `Connection String Extras` field.

#### Test the Connection <a href="#test-the-connection" id="test-the-connection"></a>

1. Click the `Test` button to ensure that Looker can successfully connect to the database.
2. If the test is successful, `save` the connection settings.

Congratulations! You have successfully connected your Tag Data Warehouse from Untitled to Looker, allowing you to explore and visualize your data through Looker's intuitive interface. Remember to follow best practices for data security and access control when configuring IAM roles and permissions.

## Need Further Support or Have Additional Questions?

Check out our[ <mark style="color:blue;">FAQs</mark> ](/misc/frequently-asked-questions.md)to get some answers, start a chat on our [website](https://getuntitled.ai/), or get connected directly with our team [<mark style="color:blue;">here</mark>](https://getuntitled.ai/contact/).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.getuntitled.ai/custom-connections/athena-database-legacy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.