Athena Intake Agent
The Athena Intake Agent connects AWS Athena to DCH. You point it at an Athena data catalog with AWS credentials, choose the tables, views, or custom queries you want, and DCH imports the rows they return.
Like every agent, it is built on the Intake Agent Core and shares the Home, Data Preview, and Data Jobs screens described there. It adds four screens of its own:
- Database Connections: the AWS account and region to query, and the credentials to query with.
- Datasource Configurations: which tables, views, and queries to read.
- Query Lookup: what a past Athena query execution did, and what it cost.
- Query History: the queries the agent ran recently, with their sizes.
How the agent reads data
Athena is not a database that the agent holds a connection open to. It is a query service that writes its results to S3. Understanding that shape explains most of this agent's behaviour.
For every fetch, the agent:
- Submits one query to Athena, telling it to write the results to the connection's S3 Output Location.
- Polls until the query succeeds, fails, or is cancelled.
- Reads the resulting CSV file back out of S3 and streams it into DCH in chunks of Job Batch Size rows.
Three consequences follow, and they are worth keeping in mind:
- The S3 Output Location is not optional. It is how results get back to the agent, not just a place logs land. Any operation that runs a query needs it, including Test Connection and every data preview.
- The query runs once, in full. Batching happens while reading the CSV, after Athena has already finished. Unlike the SQL Intake Agent, the agent does not re-run a query with changing offsets to page through a table, so there is no
@skipor@limitplaceholder for custom queries. - Each fetch scans data once, and Athena bills per byte scanned. A narrower Where Clause on a partitioned table is the main lever you have over that cost. The Query History screen shows you what recent executions actually scanned.
Database Connections
A connection is one AWS account, in one region, with one S3 location to write results to. The list shows Name, AWS Region, S3 Output Location, SSL, and Created. Each row has three actions: Edit, Test Connection, and Delete.
The SSL column reports whether certificate validation is on, not the state of the checkbox in the window. Ticking Ignore untrusted SSL certificates makes this column read Disabled.
Click Add New to create a connection.

- Name: How the connection appears in the agent. It must be unique.
- AWS Region: Where your Athena service lives. The list is the full set of regions the AWS SDK knows about, so it also includes GovCloud, China, and isolated partitions that ordinary commercial credentials cannot reach.
- AWS Access Key ID and AWS Secret Access Key: The credentials to query with. The secret is masked, with an eye icon to reveal it, and is never shown in the list.
- S3 Output Location: Where Athena writes query results, in the form
s3://bucket-name/path/. - Command Timeout (sec): How long the agent waits for a query to finish before giving up. Defaults to
300. - Connection Timeout (sec): How long a single AWS call may take. Defaults to
30. - Max Result Size (MB): The largest query result the agent accepts. Leave it empty for no limit. Individual entities can set a higher or lower limit.
- Ignore untrusted SSL certificates: Turns off certificate validation for both the Athena and S3 calls.
Give the connection credentials with read-only permissions on your data, plus read and write access to the S3 Output Location. These permissions are the only thing that keeps a custom query from changing data, see Custom queries.
Ignore untrusted SSL certificates disables certificate validation entirely, not just for expired or self-signed certificates. Leave it off unless you are pointing the agent at a trusted internal endpoint that requires it.
There is no workgroup or data catalog field. The agent always queries the AwsDataCatalog catalog and lets Athena apply your AWS account's default workgroup. When you add source entities, the database list can also show databases from other catalogs, but the agent's queries only use AwsDataCatalog.
Testing and saving
Test Connection is available both from the window and from the row in the list. It checks that your credentials work, then runs SELECT 1 and writes the result to your S3 Output Location. If it fails, the message distinguishes bad credentials, a malformed request, and denied permissions.
The test has two limits. It waits only about a second for the query, so a slower connection can report that the test timed out even though it works. And it does not read the result back from S3, so a connection without S3 read access can pass the test and fail later.
Save does not test the connection. Unlike the SQL Intake Agent, which refuses to save a connection it cannot reach, this agent saves whatever you type after checking only that the name is unique. Run Test Connection yourself before relying on a new or edited connection.
After you change the AWS Secret Access Key on an existing connection, restart the agent.
The agent reuses cached AWS clients, and the secret is not part of what identifies a cached client. If you rotate the secret while leaving the access key ID, region, and S3 output location as they were, imports keep using the old secret until the agent restarts. Test Connection always builds a fresh client, so it reports success against the new secret while imports continue to fail against the old one.
Deleting a connection is not blocked when Datasource Configurations still use it. Those configurations keep pointing at a connection that no longer exists. They continue to look healthy in the list and fail only when they next try to fetch or preview data.
Datasource Configurations
A configuration is a named set of source entities read through one or more connections. The list shows Name, Slug, Enabled, Job Batch Size, and Created. You can filter it by name, or by connection, which matches any configuration with at least one entity on that connection.
The Enabled switch in the list saves as soon as you flip it. This also validates the configuration, so it runs one Athena query per entity. It reports success even if saving failed, so check the switch after reloading the list.
Click Add Configuration to create one.

- Name: Must be unique.
- Slug: The stable identifier DCH refers to the configuration by. It is generated from the name as you type, and stops following it the moment you edit the slug yourself. It must be unique and may contain only lowercase letters, digits, and hyphens.
- Enabled: Whether the configuration is offered to DCH.
- Job Batch Size: How many rows the agent hands to DCH at a time while reading the result file. Defaults to
1000.
Validate before saving is ticked by default. With it on, saving re-runs each entity's query, refreshes the columns it knows about, and updates the cached preview. That means saving a configuration with many entities costs one Athena query per entity. Clear it to save immediately without touching Athena, at the price of leaving stale columns and previews in place.
Validation reports mismatches as warnings, but it does not stop the save. The window then stays open with the message Saved with warnings. Read the warnings rather than assuming a successful save means every entity is still valid.
Adding source entities
Inside a configuration, the Source Entities grid holds what you actually read. Add opens a window that walks down the hierarchy.

Pick a Database Connection, then a Database name, then the objects you want under Select db objects. You can select several at once, and each becomes its own source entity.
Prefix names with database name controls what those entities are called. Off, an entity is named after the object, such as orders. On, it becomes <database>_<object>, such as default_orders. Turn it on when you read objects with the same name from two different databases, since entity names have to be unique within a configuration.
The object list mixes tables and views without distinguishing them. Athena reports both through the same call, and the agent does not label which is which.
Custom queries
Turn on Custom query to define an entity from SQL instead of picking an object. You give it an Entity Name and a SQL Query.

Your query must be read-only and must return a single-table result set. OK runs it once to confirm that it executes and returns at least one row, and takes the entity's columns from the result.
The agent does not enforce the read-only rule. It passes your query to Athena as written, and it runs the query whenever it checks it: when you add it, test it, confirm your edits with OK or save with validation. A statement that changes data does so at that moment, even if the entity is never saved. Only the permissions of the connection's credentials prevent this.
Every run scans data and is billed like any other query. For these checks, the agent adds a LIMIT to your query, but only if the text does not already contain the word "limit" anywhere. A column called delimiter is enough to make a check run the query in full. In any case, a LIMIT does not always reduce what Athena scans.
Athena custom queries take no batching placeholders. The whole query runs once and the agent chunks the result file afterwards, so you do not write @skip or @limit the way you would in the SQL Intake Agent.
Editing a query
To test a query or get help with it, add it first and then use Edit query in its row.

- Test Query: Runs the query with a limit of ten rows and shows the result and its Execution ID, which you can look up in Query Lookup.
- AI assistant: Helps you write the query, see Query Assist. The assistant opens by itself when Test Query fails.
- Timeout (s) and Max size (MB): See Timeout and max size.
OK runs the query again to check it and keeps your changes in the configuration. They only take effect once you save the configuration.
Working with entities
Each row in the Source Entities grid carries its Name, an icon showing whether it is an object or a custom query, its DbObject, its Connection / DB, its Where Clause, and its Order By column. Five actions sit at the end of the row:
- Edit: Edits the row in place. Only Name and Order By can be changed here.
- Edit Settings, or Edit query for a custom query.
- Refresh Properties: Runs the entity's query and updates its preview, and for custom queries its columns. Refresh All, in the toolbar, does the same for every entity in turn.
- Preview Data: Shows the cached preview. It is disabled until a preview exists.
- Delete.
An entity's connection, database, and object are fixed once it is added. To move an entity to a different table or connection, delete it and add it again.
Refresh Properties does not find new columns of a table or view, because the agent only queries the columns it already knows. To pick up a new column, delete the entity and add it again. A column that no longer exists makes the query fail.
Where Clause, under Edit Settings, is pasted into the generated query as you type it, so write the WHERE keyword yourself, as in WHERE year = 2026. It is the main way to keep a fetch from scanning an entire table.
Order By decides the column the generated query sorts on, which is what makes the rows come back in a stable order. New entities start with their first column, so set it deliberately if that column is not a sensible one to sort by. It has no effect on custom queries, whose ordering lives in the query itself.
Timeout and max size
Edit Settings and Edit query have two optional limits for a single entity. Leave them empty to use the values of the connection.
- Timeout (s): Overrides Command Timeout (sec), for example to let a long-running query finish.
- Max size (MB): Overrides Max Result Size (MB), higher or lower. The agent rejects a larger result instead of importing it.
The agent checks the size after Athena has finished the query. The limit protects the import, not your bill: a rejected query has already been charged.
Deleting a configuration asks you to confirm and is not blocked by anything that references it.
Query Lookup
Every query this agent runs is an Athena query execution with an id. Query Lookup, titled Query Execution Lookup on the screen itself, lets you inspect one of them without leaving DCH or opening the AWS console.

Choose the Database Connection the query ran under, paste a Query Execution ID, and click Look Up. The screen reports:
- Status, with the reason for the state if Athena gave one.
- Database and Work Group.
- Submitted, Completed, and Execution Time.
- Data Scanned, which is what Athena bills on.
- Output Location, and the full Query text.
If the query succeeded, Preview Results reads the result file from S3 and shows the first 100 rows.
You find execution ids in Query History, and in the Execution ID that Test Query shows. Use this screen for the details: which query ran, and what happened.
Query History
Query History lists the queries the agent ran, so you can see how large their results are over time. It keeps them for 10 days.

Filter by From (UTC), To (UTC) and Source, then select Apply. By default, it shows the last seven days.
- Source:
Ingestionfor imports,Previewfor previews, refreshes and Test Query. The sizes of previews are not representative, because they read only a few rows. - Status:
Succeeded,Failed, orRejectedif the result exceeded the max size. Hover over the Execution ID to see the error message. - Result Size and Data Scanned: The size of the result file, and what Athena bills on.
The check that OK runs in Edit query is not listed.
Data Preview
The Athena Intake Agent supports the shared Data Preview screen.
Previews are cached. Adding a custom query, refreshing an entity, or saving with Validate before saving on stores a small sample of rows, and that is what you normally see.
Bypass cached preview runs a real Athena query against the live table. It scans data and is billed like any other query, so use it when you need to know what the source holds right now, not as the default way to look at an entity.