# Amazon Athena

> Query data in Amazon S3 with Amazon Athena's serverless SQL: run a query and read its rows, track or cancel a running query, browse the data catalogs, databases and tables available to it, read workgroup settings, and manage saved queries.

App · Analytics · 20 actions. Web page: https://docs.lodol.com/docs/integrations/amazon-athena

## Actions

### Create saved query

Save a query so it appears under Saved queries in the Athena console. Nothing runs, and the SQL is not checked.

**Inputs**

- Name (`name`, text, required): The name to save the query under.
- SQL query (`query`, text, required): The SQL to save.
- Database (`database_name`, text, required): The database the saved query belongs to. Use List databases to find one - it cannot be changed afterwards.
- Description (`description`, text): An optional note shown beside the query.
- Workgroup (`workgroup`, text): The workgroup to save it in. Leave empty for 'primary'. It cannot be changed afterwards.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "named_query_id": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
  }
}
```

### Delete saved query

Delete a saved query. Deleting an id that does not exist is an error, not a silent no-op.

**Inputs**

- Saved query id (`named_query_id`, text, required): The saved query to delete.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "deleted": true,
    "named_query_id": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
  }
}
```

### Get data catalog

Read one data catalog, including the connector settings a federated catalog uses.

**Inputs**

- Catalog (`catalog_name`, text, required): The catalog to read. Default: `AwsDataCatalog`.
- Workgroup (`workgroup`, text): Only required when the account uses IAM Identity Center; leave empty otherwise.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "data_catalog": {
      "connection_type": null,
      "description": "The AWS Glue Data Catalog",
      "error": null,
      "name": "AwsDataCatalog",
      "parameters": null,
      "status": null,
      "type": "GLUE"
    }
  }
}
```

### Get database

Read one database's description and properties.

**Inputs**

- Catalog (`catalog_name`, text, required): The catalog the database lives in. Default: `AwsDataCatalog`.
- Database (`database_name`, text, required): The database to read.
- Workgroup (`workgroup`, text): Only required when the account uses IAM Identity Center; leave empty otherwise.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "database": {
      "description": "Order and revenue tables.",
      "name": "sales",
      "parameters": null
    }
  }
}
```

### Get query execution

Read a query's state, timings and the number of bytes it scanned. States are QUEUED, RUNNING, SUCCEEDED, FAILED and CANCELLED; results can only be read once it is SUCCEEDED.

**Inputs**

- Query execution id (`query_execution_id`, text, required): The id returned by Start query.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "query_execution": {
      "catalog": "AwsDataCatalog",
      "completed_at": "2026-09-16T09:14:04.905000Z",
      "database": "sales",
      "engine_version": {
        "effective_engine_version": "Athena engine version 3",
        "selected_engine_version": "AUTO"
      },
      "error": null,
      "execution_parameters": [],
      "managed_query_results_enabled": null,
      "output_location": "s3://my-athena-results/Unsaved/2026/09/16/",
      "query": "SELECT city, orders FROM sales.daily_totals LIMIT 10",
      "query_execution_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "result_reuse": null,
      "state": "SUCCEEDED",
      "state_change_reason": null,
      "statement_type": "DML",
      "statistics": {
        "data_manifest_location": null,
        "data_scanned_bytes": 10485760,
        "dpu_count": null,
        "engine_execution_time_millis": 1893,
        "query_planning_time_millis": 118,
        "query_queue_time_millis": 142,
        "reused_previous_result": false,
        "service_pre_processing_time_millis": 231,
        "service_processing_time_millis": 227,
        "total_execution_time_millis": 2493
      },
      "submitted_at": "2026-09-16T09:14:02.412000Z",
      "substatement_type": "SELECT",
      "workgroup": "primary"
    }
  }
}
```

### Get query executions (batch)

Read up to 50 query executions in one call. An id Athena does not recognise is reported under 'unprocessed' instead of failing the whole call.

**Inputs**

- Query execution ids (`query_execution_ids`, list, required): The ids to read, up to 50. Feed this the 'query_execution_ids' from List query executions.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "query_executions": [
      {
        "catalog": "AwsDataCatalog",
        "completed_at": "2026-09-16T09:14:04.905000Z",
        "database": "sales",
        "engine_version": {
          "effective_engine_version": "Athena engine version 3",
          "selected_engine_version": "AUTO"
        },
        "error": null,
        "execution_parameters": [],
        "managed_query_results_enabled": null,
        "output_location": "s3://my-athena-results/Unsaved/2026/09/16/",
        "query": "SELECT city, orders FROM sales.daily_totals LIMIT 10",
        "query_execution_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "result_reuse": null,
        "state": "SUCCEEDED",
        "state_change_reason": null,
        "statement_type": "DML",
        "statistics": {
          "data_manifest_location": null,
          "data_scanned_bytes": 10485760,
          "dpu_count": null,
          "engine_execution_time_millis": 1893,
          "query_planning_time_millis": 118,
          "query_queue_time_millis": 142,
          "reused_previous_result": false,
          "service_pre_processing_time_millis": 231,
          "service_processing_time_millis": 227,
          "total_execution_time_millis": 2493
        },
        "submitted_at": "2026-09-16T09:14:02.412000Z",
        "substatement_type": "SELECT",
        "workgroup": "primary"
      }
    ],
    "unprocessed": []
  }
}
```

### Get query results

Read a finished query's rows. Each row comes back as a mapping of column name to value, with Athena's repeated header row removed. The query must have reached SUCCEEDED.

**Inputs**

- Query execution id (`query_execution_id`, text, required): The id returned by Start query.
- Max rows (`max_results`, number): How many rows to return (1-1000). From 1 to 1000.
- Next token (`next_token`, text): The 'next_token' from a previous page, to read the next one.
- Result type (`query_result_type`, text): Return the query's rows, or the manifest file it wrote. Manifests exist only for CREATE TABLE AS SELECT, UNLOAD and INSERT queries - asking for one on any other query fails. One of: `DATA_ROWS` (Rows (default)), `DATA_MANIFEST` (Manifest file (CTAS, UNLOAD and INSERT queries only)).

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "columns": [
      {
        "case_sensitive": true,
        "catalog_name": "hive",
        "label": "city",
        "name": "city",
        "nullable": "UNKNOWN",
        "precision": 2147483647,
        "scale": 0,
        "schema_name": null,
        "table_name": null,
        "type": "varchar"
      },
      {
        "case_sensitive": false,
        "catalog_name": "hive",
        "label": "orders",
        "name": "orders",
        "nullable": "UNKNOWN",
        "precision": 19,
        "scale": 0,
        "schema_name": null,
        "table_name": null,
        "type": "bigint"
      }
    ],
    "count": 2,
    "has_more": false,
    "header_row_removed": true,
    "next_token": null,
    "rows": [
      {
        "city": "Lisbon",
        "orders": "412"
      },
      {
        "city": "Porto",
        "orders": "198"
      }
    ],
    "update_count": null
  }
}
```

### Get query runtime statistics

Read a query's timeline, input/output row counts and execution plan. Athena keeps the full statistics for about 30 days; an older query returns the timeline only.

**Inputs**

- Query execution id (`query_execution_id`, text, required): The id returned by Start query.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "query_execution_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "statistics": {
      "output_stage": {
        "OutputRows": 10,
        "StageId": 0,
        "State": "FINISHED"
      },
      "rows": {
        "input_bytes": 10485760,
        "input_rows": 12045,
        "output_bytes": 1284,
        "output_rows": 10
      },
      "timeline": {
        "engine_execution_time_millis": 1893,
        "query_planning_time_millis": 118,
        "query_queue_time_millis": 142,
        "service_pre_processing_time_millis": 231,
        "service_processing_time_millis": 227,
        "total_execution_time_millis": 2493
      }
    }
  }
}
```

### Get saved query

Read one saved query's name, SQL, database and workgroup.

**Inputs**

- Saved query id (`named_query_id`, text, required): The id returned by Create saved query.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "named_query": {
      "database": "sales",
      "description": "Top ten cities by order count.",
      "name": "Daily totals by city",
      "named_query_id": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
      "query_string": "SELECT city, orders FROM sales.daily_totals LIMIT 10",
      "workgroup": "primary"
    }
  }
}
```

### Get table

Read one table's columns and partition keys. Partition columns appear only under 'partition_keys', never in 'columns'.

**Inputs**

- Catalog (`catalog_name`, text, required): The catalog the table lives in. Default: `AwsDataCatalog`.
- Database (`database_name`, text, required): The database the table lives in.
- Table (`table_name`, text, required): The table to read. Use List tables to find one - a database can hold thousands, so there is no dropdown.
- Workgroup (`workgroup`, text): Only required when the account uses IAM Identity Center; leave empty otherwise.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "table": {
      "columns": [
        {
          "comment": null,
          "name": "city",
          "type": "string"
        },
        {
          "comment": "Orders placed that day.",
          "name": "orders",
          "type": "bigint"
        }
      ],
      "created_at": "2026-04-02T11:20:31Z",
      "last_accessed_at": null,
      "name": "daily_totals",
      "parameters": {
        "classification": "parquet"
      },
      "partition_keys": [
        {
          "comment": null,
          "name": "dt",
          "type": "string"
        }
      ],
      "table_type": "EXTERNAL_TABLE"
    }
  }
}
```

### Get workgroup

Read a workgroup's settings - most usefully where its query results go, whether managed query results are on, and whether its settings override anything a query asks for.

**Inputs**

- Workgroup (`workgroup`, text, required): The workgroup to read. Default: `primary`.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "work_group": {
      "bytes_scanned_cutoff_per_query": null,
      "configuration": {
        "EnforceWorkGroupConfiguration": false,
        "EngineVersion": {
          "EffectiveEngineVersion": "Athena engine version 3",
          "SelectedEngineVersion": "AUTO"
        },
        "PublishCloudWatchMetricsEnabled": true,
        "ResultConfiguration": {
          "OutputLocation": "s3://my-athena-results/"
        }
      },
      "created_at": "2026-01-08T16:02:11Z",
      "description": null,
      "enforce_work_group_configuration": false,
      "engine_version": {
        "effective_engine_version": "Athena engine version 3",
        "selected_engine_version": "AUTO"
      },
      "execution_role": null,
      "identity_center_application_arn": null,
      "managed_query_results_enabled": null,
      "name": "primary",
      "output_location": "s3://my-athena-results/",
      "publish_cloud_watch_metrics_enabled": true,
      "requester_pays_enabled": null,
      "state": "ENABLED"
    }
  }
}
```

### List data catalogs

List the data catalogs in the region - the Athena console calls them data sources. Every account has the built-in AwsDataCatalog, backed by AWS Glue.

**Inputs**

- Workgroup (`workgroup`, text): Only required when the account uses IAM Identity Center; leave empty otherwise.
- Max results (`max_results`, number): How many catalogs to return. Athena's minimum here is 2, not 1. From 2 to 50.
- Next token (`next_token`, text): The 'next_token' from a previous page.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "data_catalogs": [
      {
        "connection_type": null,
        "error": null,
        "name": "AwsDataCatalog",
        "status": null,
        "type": "GLUE"
      }
    ],
    "has_more": false,
    "next_token": null
  }
}
```

### List databases

List the databases (schemas) in a data catalog, with their descriptions and properties.

**Inputs**

- Catalog (`catalog_name`, text, required): The catalog to list databases from. Default: `AwsDataCatalog`.
- Max results (`max_results`, number): How many databases to return (1-50). From 1 to 50.
- Next token (`next_token`, text): The 'next_token' from a previous page.
- Workgroup (`workgroup`, text): Only required when the account uses IAM Identity Center; leave empty otherwise.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "databases": [
      {
        "description": "Order and revenue tables.",
        "name": "sales",
        "parameters": null
      }
    ],
    "has_more": false,
    "next_token": null
  }
}
```

### List query executions

List recent query execution ids, most recent first. Ids only - follow with Get query executions (batch) for the detail.

**Inputs**

- Workgroup (`workgroup`, text): Only list queries run in this workgroup. Leave empty for 'primary'.
- Max results (`max_results`, number): How many ids to return (0-50). From 0 to 50.
- Next token (`next_token`, text): The 'next_token' from a previous page.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 2,
    "has_more": false,
    "next_token": null,
    "query_execution_ids": [
      "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "a0e1b2c3-4d5e-4f6a-8b9c-0d1e2f3a4b5c"
    ]
  }
}
```

### List saved queries

List saved query ids in a workgroup. Ids only - follow with Get saved query for each one's SQL.

**Inputs**

- Workgroup (`workgroup`, text): Only list saved queries in this workgroup. Leave empty for 'primary'.
- Max results (`max_results`, number): How many ids to return (0-50). From 0 to 50.
- Next token (`next_token`, text): The 'next_token' from a previous page.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "has_more": false,
    "named_query_ids": [
      "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
    ],
    "next_token": null
  }
}
```

### List tables

List a database's tables with their columns, partition keys and properties.

**Inputs**

- Catalog (`catalog_name`, text, required): The catalog the database lives in. Default: `AwsDataCatalog`.
- Database (`database_name`, text, required): The database whose tables to list.
- Name contains (`name_contains`, text): Only return tables whose name contains this text. It is a name filter, not SQL.
- Max results (`max_results`, number): How many tables to return (1-50). From 1 to 50.
- Next token (`next_token`, text): The 'next_token' from a previous page.
- Workgroup (`workgroup`, text): Only required when the account uses IAM Identity Center; leave empty otherwise.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "has_more": false,
    "next_token": null,
    "tables": [
      {
        "columns": [
          {
            "comment": null,
            "name": "city",
            "type": "string"
          },
          {
            "comment": "Orders placed that day.",
            "name": "orders",
            "type": "bigint"
          }
        ],
        "created_at": "2026-04-02T11:20:31Z",
        "last_accessed_at": null,
        "name": "daily_totals",
        "parameters": {
          "classification": "parquet"
        },
        "partition_keys": [
          {
            "comment": null,
            "name": "dt",
            "type": "string"
          }
        ],
        "table_type": "EXTERNAL_TABLE"
      }
    ]
  }
}
```

### List workgroups

List the workgroups in the region. Every account has one called 'primary' that queries use by default.

**Inputs**

- Max results (`max_results`, number): How many workgroups to return (1-50). From 1 to 50.
- Next token (`next_token`, text): The 'next_token' from a previous page.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "count": 1,
    "has_more": false,
    "next_token": null,
    "work_groups": [
      {
        "created_at": "2026-01-08T16:02:11Z",
        "description": null,
        "engine_version": {
          "effective_engine_version": "Athena engine version 3",
          "selected_engine_version": "AUTO"
        },
        "identity_center_application_arn": null,
        "name": "primary",
        "state": "ENABLED"
      }
    ]
  }
}
```

### Start query

Run a SQL statement in Athena and return its query execution id. The query runs asynchronously: follow this with Get query execution until the state is SUCCEEDED, then Get query results.

**Inputs**

- SQL query (`query`, text, required): The SQL to run, for example 'SELECT * FROM sales.orders LIMIT 10'. Use ? placeholders and fill them in with Query parameters below.
- Catalog (`catalog_name`, text): The data catalog the query runs against. Leave as AwsDataCatalog unless you query a federated source. Default: `AwsDataCatalog`.
- Database (`database_name`, text): The default database for unqualified table names. Not needed if the query names its tables in full (database.table).
- Workgroup (`workgroup`, text): The workgroup to run in. It sets the results location, the engine version and any cost limit; leave empty to use 'primary'.
- Output location (`output_location`, text): S3 URI for the results, for example 's3://my-bucket/athena-results/'. Leave empty to use the workgroup's own location or its managed query results. A workgroup with 'Enforce settings' turned on ignores this.
- Query parameters (`execution_parameters`, list): Values for the ? placeholders in the query, in the order they appear. Athena quotes them for you, so this is the safe way to put a workflow value into SQL.
- Reuse results up to (minutes) (`reuse_results_max_age_minutes`, number): Reuse a cached result from an equivalent query run in the last N minutes instead of scanning again (0-10080). Ignored on a workgroup that uses managed query results, which does not support reuse. From 0 to 10080.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "query_execution_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  }
}
```

### Stop query

Cancel a running query. Athena still bills for the data the query had scanned when it stopped.

**Inputs**

- Query execution id (`query_execution_id`, text, required): The id of the query to cancel.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "query_execution_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "stopped": true
  }
}
```

### Update saved query

Replace a saved query's name, SQL and description. Athena requires all of them on every update and drops a description that is not resent, so read the query first and pass back what you are not changing. Its database and workgroup cannot be changed.

**Inputs**

- Saved query id (`named_query_id`, text, required): The saved query to replace.
- Name (`name`, text, required): The name to store. Required even when only the SQL changes - send the existing name to keep it.
- SQL query (`query`, text, required): The SQL to store. Required even when only the name changes - send the existing SQL to keep it.
- Description (`description`, text): The note to store. Leave empty to clear the existing one.

**Outputs**

- `result` (object)

**Example output**

```json
{
  "result": {
    "named_query_id": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "updated": true
  }
}
```