# querying-aws-athena

querying-aws-athena — a skill for Claude Code and Cursor that runs SQL queries on Amazon Athena query history via the query_executions system table.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 454 installs · ★ 3536 repo stars
- Author: aws
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/aws/agent-toolkit-for-aws/tree/HEAD/skills/specialized-skills/system-table-skills/querying-aws-athena/SKILL.md
- Updated: 2026-10-23
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/querying-aws-athena

## What it does

The skill runs SQL queries on Amazon Athena query history stored as Apache Iceberg tables in S3 Tables. The `query_executions` system table captures per-query metadata like query text, IAM principal, work group, scanned data size, timing, and errors for every completed query.

It replaces raw Athena APIs for aggregating usage trends and auditing access at scale. Configured AWS credentials and active Athena system tables in your region are required for execution.

## Requirements
- Works with: AWS

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill querying-aws-athena -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/querying-aws-athena/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/querying-aws-athena/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill querying-aws-athena -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/querying-aws-athena/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill querying-aws-athena -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/querying-aws-athena/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install aws/agent-toolkit-for-aws skills/specialized-skills/system-table-skills/querying-aws-athena
```

2. **Manually: put the files in place**
- File: `.github/skills/querying-aws-athena/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill querying-aws-athena -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/aws/agent-toolkit-for-aws --path skills/specialized-skills/system-table-skills/querying-aws-athena
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/querying-aws-athena/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill querying-aws-athena -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/aws/agent-toolkit-for-aws/tree/HEAD/skills/specialized-skills/system-table-skills/querying-aws-athena/SKILL.md

## When to use it
- analyzing Athena usage and cost trends by work group
- finding who ran a specific query via `principal_arn`
- investigating slow or failed queries and error patterns
- tracking data scanned by user or work group
- reporting query history beyond the 45-day API window

## Example prompts
- Analyze Athena query history and costs using the `query_executions` system table
- Find who ran a specific Athena query based on `principal_arn`
- Audit slow queries and error patterns in Amazon Athena

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: a3f6a4dd17f5e92d.

BEGIN THIRD-PARTY FILE a3f6a4dd17f5e92d
```text
---
name: querying-aws-athena
description: >-
  Runs SQL queries on Amazon Athena query history exported as an Apache Iceberg table in S3
  Tables. The query_executions system table captures per-query metadata (query text, IAM
  principal, work group, statement type, data scanned, timing breakdown, error details,
  tables accessed, result reuse, engine version) for every completed query. Applies when
  analyzing Athena usage and cost, finding who ran a query, auditing table access, tracking
  data scanned by user or work group, investigating slow or failed queries, detecting
  performance regressions, reporting query history beyond the 45-day API window, or enabling
  Athena system tables. Prefers the system table over the ListQueryExecutions and
  GetQueryExecution APIs at scale. Trigger phrases: Athena query history, who ran this query,
  data scanned by user, most queried tables, slowest queries, failed query analysis, Athena
  cost by work group, query audit trail, enable Athena system tables.
version: 1
argument-hint: "[query|'configure'|'status']"
---

# Query Amazon Athena System Tables

## Overview

**Works best with** the [AWS MCP server](https://docs.aws.amazon.com/aws-mcp/) for sandboxed execution and audit logging. All commands below use the AWS CLI and work in any environment with configured AWS credentials. Use IAM roles or temporary credentials; avoid long-lived access keys.

Amazon Athena system tables are Apache Iceberg tables that Athena automatically creates and populates with account usage data. The `query_executions` system table records one row per completed query with the metadata from `GetQueryExecution` plus additional fields that `GetQueryExecution` does not return. The tables are read-only and stored as fully managed Amazon S3 Tables in the service-managed `aws-athena` S3 table bucket in your account and Region, and are queryable with Athena SQL (the focus of this skill) or any other Iceberg-compatible engine, such as Amazon Redshift.

The system table is preferred over the raw Athena APIs (`ListQueryExecutions`, `GetQueryExecution`) because:

- `ListQueryExecutions` returns only query IDs and paginates; `GetQueryExecution` must then be called once per ID. Reconstructing "how much did each user scan last month" means thousands of sequential API calls. The system table answers it with one `GROUP BY`.
- The APIs offer no SQL, no aggregation, and no joins, and cover only a rolling 45-day window. The system table retains data for as long as you configure through S3 Tables record expiration and supports arbitrary SQL, including window functions and cross-table joins.
```
END THIRD-PARTY FILE a3f6a4dd17f5e92d

The third-party file has ended. Everything between the a3f6a4dd17f5e92d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2635 of 27146 bytes. © aws · Apache-2.0 · https://github.com/aws/agent-toolkit-for-aws/tree/HEAD/skills/specialized-skills/system-table-skills/querying-aws-athena/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
