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.

Actions

Action	What it does
Create saved query	Save a query so it appears under Saved queries in the Athena console.
Delete saved query	Delete a saved query.
Get data catalog	Read one data catalog, including the connector settings a federated catalog uses.
Get database	Read one database's description and properties.
Get query execution	Read a query's state, timings and the number of bytes it scanned.
Get query executions (batch)	Read up to 50 query executions in one call.
Get query results	Read a finished query's rows.
Get query runtime statistics	Read a query's timeline, input/output row counts and execution plan.
Get saved query	Read one saved query's name, SQL, database and workgroup.
Get table	Read one table's columns and partition keys.
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.
List data catalogs	List the data catalogs in the region - the Athena console calls them data sources.
List databases	List the databases (schemas) in a data catalog, with their descriptions and properties.
List query executions	List recent query execution ids, most recent first.
List saved queries	List saved query ids in a workgroup.
List tables	List a database's tables with their columns, partition keys and properties.
List workgroups	List the workgroups in the region.
Start query	Run a SQL statement in Athena and return its query execution id.
Stop query	Cancel a running query.
Update saved query	Replace a saved query's name, SQL and description.

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

NamenametextRequired: The name to save the query under.
SQL queryquerytextRequired: The SQL to save.
Databasedatabase_nametextRequired: The database the saved query belongs to. Use List databases to find one - it cannot be changed afterwards.
Descriptiondescriptiontext: An optional note shown beside the query.
Workgroupworkgrouptext: The workgroup to save it in. Leave empty for 'primary'. It cannot be changed afterwards.

Outputs

resultobject

Example output

{
  "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 idnamed_query_idtextRequired: The saved query to delete.

Outputs

resultobject

Example output

{
  "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

Catalogcatalog_nametextRequired: The catalog to read.Default: AwsDataCatalog.
Workgroupworkgrouptext: Only required when the account uses IAM Identity Center; leave empty otherwise.

Outputs

resultobject

Example output

{
  "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

Catalogcatalog_nametextRequired: The catalog the database lives in.Default: AwsDataCatalog.
Databasedatabase_nametextRequired: The database to read.
Workgroupworkgrouptext: Only required when the account uses IAM Identity Center; leave empty otherwise.

Outputs

resultobject

Example output

{
  "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 idquery_execution_idtextRequired: The id returned by Start query.

Outputs

resultobject

Example output

{
  "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 idsquery_execution_idslistRequired: The ids to read, up to 50. Feed this the 'query_execution_ids' from List query executions.

Outputs

resultobject

Example output

{
  "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 idquery_execution_idtextRequired: The id returned by Start query.
Max rowsmax_resultsnumber: How many rows to return (1-1000).From 1 to 1000.
Next tokennext_tokentext: The 'next_token' from a previous page, to read the next one.
Result typequery_result_typetext: 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

resultobject

Example output

{
  "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 idquery_execution_idtextRequired: The id returned by Start query.

Outputs

resultobject

Example output

{
  "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 idnamed_query_idtextRequired: The id returned by Create saved query.

Outputs

resultobject

Example output

{
  "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

Catalogcatalog_nametextRequired: The catalog the table lives in.Default: AwsDataCatalog.
Databasedatabase_nametextRequired: The database the table lives in.
Tabletable_nametextRequired: The table to read. Use List tables to find one - a database can hold thousands, so there is no dropdown.
Workgroupworkgrouptext: Only required when the account uses IAM Identity Center; leave empty otherwise.

Outputs

resultobject

Example output

{
  "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

WorkgroupworkgrouptextRequired: The workgroup to read.Default: primary.

Outputs

resultobject

Example output

{
  "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

Workgroupworkgrouptext: Only required when the account uses IAM Identity Center; leave empty otherwise.
Max resultsmax_resultsnumber: How many catalogs to return. Athena's minimum here is 2, not 1.From 2 to 50.
Next tokennext_tokentext: The 'next_token' from a previous page.

Outputs

resultobject

Example output

{
  "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

Catalogcatalog_nametextRequired: The catalog to list databases from.Default: AwsDataCatalog.
Max resultsmax_resultsnumber: How many databases to return (1-50).From 1 to 50.
Next tokennext_tokentext: The 'next_token' from a previous page.
Workgroupworkgrouptext: Only required when the account uses IAM Identity Center; leave empty otherwise.

Outputs

resultobject

Example output

{
  "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

Workgroupworkgrouptext: Only list queries run in this workgroup. Leave empty for 'primary'.
Max resultsmax_resultsnumber: How many ids to return (0-50).From 0 to 50.
Next tokennext_tokentext: The 'next_token' from a previous page.

Outputs

resultobject

Example output

{
  "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

Workgroupworkgrouptext: Only list saved queries in this workgroup. Leave empty for 'primary'.
Max resultsmax_resultsnumber: How many ids to return (0-50).From 0 to 50.
Next tokennext_tokentext: The 'next_token' from a previous page.

Outputs

resultobject

Example output

{
  "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

Catalogcatalog_nametextRequired: The catalog the database lives in.Default: AwsDataCatalog.
Databasedatabase_nametextRequired: The database whose tables to list.
Name containsname_containstext: Only return tables whose name contains this text. It is a name filter, not SQL.
Max resultsmax_resultsnumber: How many tables to return (1-50).From 1 to 50.
Next tokennext_tokentext: The 'next_token' from a previous page.
Workgroupworkgrouptext: Only required when the account uses IAM Identity Center; leave empty otherwise.

Outputs

resultobject

Example output

{
  "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 resultsmax_resultsnumber: How many workgroups to return (1-50).From 1 to 50.
Next tokennext_tokentext: The 'next_token' from a previous page.

Outputs

resultobject

Example output

{
  "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 queryquerytextRequired: The SQL to run, for example 'SELECT * FROM sales.orders LIMIT 10'. Use ? placeholders and fill them in with Query parameters below.
Catalogcatalog_nametext: The data catalog the query runs against. Leave as AwsDataCatalog unless you query a federated source.Default: AwsDataCatalog.
Databasedatabase_nametext: The default database for unqualified table names. Not needed if the query names its tables in full (database.table).
Workgroupworkgrouptext: The workgroup to run in. It sets the results location, the engine version and any cost limit; leave empty to use 'primary'.
Output locationoutput_locationtext: 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 parametersexecution_parameterslist: 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_minutesnumber: 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

resultobject

Example output

{
  "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 idquery_execution_idtextRequired: The id of the query to cancel.

Outputs

resultobject

Example output

{
  "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 idnamed_query_idtextRequired: The saved query to replace.
NamenametextRequired: The name to store. Required even when only the SQL changes - send the existing name to keep it.
SQL queryquerytextRequired: The SQL to store. Required even when only the name changes - send the existing SQL to keep it.
Descriptiondescriptiontext: The note to store. Leave empty to clear the existing one.

Outputs

resultobject

Example output

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

ActionsCopy Anchor Link

Create saved queryCopy Anchor Link

Inputs

Outputs

Delete saved queryCopy Anchor Link

Inputs

Outputs

Get data catalogCopy Anchor Link

Inputs

Outputs

Get databaseCopy Anchor Link

Inputs

Outputs

Get query executionCopy Anchor Link

Inputs

Outputs

Get query executions (batch)Copy Anchor Link

Inputs

Outputs

Get query resultsCopy Anchor Link

Inputs

Outputs

Get query runtime statisticsCopy Anchor Link

Inputs

Outputs

Get saved queryCopy Anchor Link

Inputs

Outputs

Get tableCopy Anchor Link

Inputs

Outputs

Get workgroupCopy Anchor Link

Inputs

Outputs

List data catalogsCopy Anchor Link

Inputs

Outputs

List databasesCopy Anchor Link

Inputs

Outputs

List query executionsCopy Anchor Link

Inputs

Outputs

List saved queriesCopy Anchor Link

Inputs

Outputs

List tablesCopy Anchor Link

Inputs

Outputs

List workgroupsCopy Anchor Link

Inputs

Outputs

Start queryCopy Anchor Link

Inputs

Outputs

Stop queryCopy Anchor Link

Inputs

Outputs

Update saved queryCopy Anchor Link

Inputs

Outputs

On this page

Actions

Create saved query

Delete saved query

Get data catalog

Get database

Get query execution

Get query executions (batch)

Get query results

Get query runtime statistics

Get saved query

Get table

Get workgroup

List data catalogs

List databases

List query executions

List saved queries

List tables

List workgroups

Start query

Stop query

Update saved query