AWS.Athena reference

BatchGetQueryExecution

Source: src/AWS/Athena/BatchGetQueryExecution.ts

Runtime binding for athena:BatchGetQueryExecution.

Reads up to 50 query executions from the bound workgroup in one call. Provide the implementation with Effect.provide(AWS.Athena.BatchGetQueryExecutionHttp).

BatchGetQueryExecution: Inspecting Query Executions

// init — bind the operation to the workgroup
const batchGetQueryExecution =
  yield* AWS.Athena.BatchGetQueryExecution(workGroup);

// runtime
const res = yield* batchGetQueryExecution({ QueryExecutionIds: ids });
console.log(res.QueryExecutions?.map((qe) => qe.Status?.State));

DataCatalog

Source: src/AWS/Athena/DataCatalog.ts

An Amazon Athena data catalog — registers an external metadata source (a federated Lambda connector, an external Hive metastore, or a cross-account Glue Data Catalog) that Athena queries can reference as a catalog.

DataCatalog: Registering Catalogs

const catalog = yield* AWS.Athena.DataCatalog("Cmdb", {
  name: "cmdb_connector",
  type: "LAMBDA",
  parameters: {
    "metadata-function": connector.functionArn,
    "record-function": connector.functionArn,
  },
});

GetDatabase

Source: src/AWS/Athena/GetDatabase.ts

Runtime binding for athena:GetDatabase.

Reads a single database’s metadata from the bound data catalog — the catalog name is injected automatically. Provide the implementation with Effect.provide(AWS.Athena.GetDatabaseHttp).

GetDatabase: Browsing Catalog Metadata

// init — bind the operation to the data catalog
const getDatabase = yield* AWS.Athena.GetDatabase(catalog);

// runtime
const res = yield* getDatabase({ DatabaseName: "analytics" });
console.log(res.Database?.Name);

GetQueryExecution

Source: src/AWS/Athena/GetQueryExecution.ts

Runtime binding for athena:GetQueryExecution.

Reads the state, statistics, and configuration of a single query execution that ran in the bound workgroup. Provide the implementation with Effect.provide(AWS.Athena.GetQueryExecutionHttp).

GetQueryExecution: Inspecting Query Executions

// init — bind the operation to the workgroup
const getQueryExecution = yield* AWS.Athena.GetQueryExecution(workGroup);

// runtime
const res = yield* getQueryExecution({ QueryExecutionId: id });
console.log(res.QueryExecution?.Status?.State);

GetQueryResults

Source: src/AWS/Athena/GetQueryResults.ts

Runtime binding for athena:GetQueryResults.

Reads one page of a completed query’s result set (raw rows + column metadata) — use NextToken/MaxResults to paginate large results. For the common run-and-decode flow, prefer the composite Query binding. Provide the implementation with Effect.provide(AWS.Athena.GetQueryResultsHttp).

GetQueryResults: Reading Results

// init — bind the operation to the workgroup
const getQueryResults = yield* AWS.Athena.GetQueryResults(workGroup);

// runtime
const page = yield* getQueryResults({ QueryExecutionId: id, MaxResults: 100 });
console.log(page.ResultSet?.Rows?.length, page.NextToken);

GetQueryRuntimeStatistics

Source: src/AWS/Athena/GetQueryRuntimeStatistics.ts

Runtime binding for athena:GetQueryRuntimeStatistics.

Reads the runtime statistics (timeline, rows/bytes processed, stage tree) of a query that ran in the bound workgroup. Provide the implementation with Effect.provide(AWS.Athena.GetQueryRuntimeStatisticsHttp).

GetQueryRuntimeStatistics: Inspecting Query Executions

// init — bind the operation to the workgroup
const getQueryRuntimeStatistics =
  yield* AWS.Athena.GetQueryRuntimeStatistics(workGroup);

// runtime
const res = yield* getQueryRuntimeStatistics({ QueryExecutionId: id });
console.log(res.QueryRuntimeStatistics?.Timeline?.TotalExecutionTimeInMillis);

GetTableMetadata

Source: src/AWS/Athena/GetTableMetadata.ts

Runtime binding for athena:GetTableMetadata.

Reads a single table’s metadata (columns, partition keys, table type) from the bound data catalog — the catalog name is injected automatically. Provide the implementation with Effect.provide(AWS.Athena.GetTableMetadataHttp).

GetTableMetadata: Browsing Catalog Metadata

// init — bind the operation to the data catalog
const getTableMetadata = yield* AWS.Athena.GetTableMetadata(catalog);

// runtime
const res = yield* getTableMetadata({
  DatabaseName: "analytics",
  TableName: "orders",
});
console.log(res.TableMetadata?.Columns?.map((c) => c.Name));

ListDatabases

Source: src/AWS/Athena/ListDatabases.ts

Runtime binding for athena:ListDatabases.

Lists the databases in the bound data catalog — the catalog name is injected automatically. Provide the implementation with Effect.provide(AWS.Athena.ListDatabasesHttp).

ListDatabases: Browsing Catalog Metadata

// init — bind the operation to the data catalog
const listDatabases = yield* AWS.Athena.ListDatabases(catalog);

// runtime
const res = yield* listDatabases({});
console.log(res.DatabaseList?.map((db) => db.Name));

ListNamedQueries

Source: src/AWS/Athena/ListNamedQueries.ts

Runtime binding for athena:ListNamedQueries.

Lists the IDs of the saved (named) queries in the bound workgroup — the workgroup name is injected automatically. Provide the implementation with Effect.provide(AWS.Athena.ListNamedQueriesHttp).

ListNamedQueries: Saved Queries

// init — bind the operation to the workgroup
const listNamedQueries = yield* AWS.Athena.ListNamedQueries(workGroup);

// runtime
const res = yield* listNamedQueries({ MaxResults: 50 });
console.log(res.NamedQueryIds);

ListPreparedStatements

Source: src/AWS/Athena/ListPreparedStatements.ts

Runtime binding for athena:ListPreparedStatements.

Lists the prepared statements (name + last-modified time) in the bound workgroup — the workgroup name is injected automatically. Provide the implementation with Effect.provide(AWS.Athena.ListPreparedStatementsHttp).

ListPreparedStatements: Prepared Statements

// init — bind the operation to the workgroup
const listPreparedStatements =
  yield* AWS.Athena.ListPreparedStatements(workGroup);

// runtime
const res = yield* listPreparedStatements({ MaxResults: 50 });
console.log(res.PreparedStatements?.map((s) => s.StatementName));

ListQueryExecutions

Source: src/AWS/Athena/ListQueryExecutions.ts

Runtime binding for athena:ListQueryExecutions.

Lists recent query execution IDs in the bound workgroup (newest first) — the workgroup name is injected automatically. Provide the implementation with Effect.provide(AWS.Athena.ListQueryExecutionsHttp).

ListQueryExecutions: Inspecting Query Executions

// init — bind the operation to the workgroup
const listQueryExecutions = yield* AWS.Athena.ListQueryExecutions(workGroup);

// runtime
const res = yield* listQueryExecutions({ MaxResults: 10 });
console.log(res.QueryExecutionIds);

ListTableMetadata

Source: src/AWS/Athena/ListTableMetadata.ts

Runtime binding for athena:ListTableMetadata.

Lists table metadata for a database in the bound data catalog — the catalog name is injected automatically; Expression filters table names. Provide the implementation with Effect.provide(AWS.Athena.ListTableMetadataHttp).

ListTableMetadata: Browsing Catalog Metadata

// init — bind the operation to the data catalog
const listTableMetadata = yield* AWS.Athena.ListTableMetadata(catalog);

// runtime
const res = yield* listTableMetadata({ DatabaseName: "analytics" });
console.log(res.TableMetadataList?.map((t) => t.Name));

NamedQuery

Source: src/AWS/Athena/NamedQuery.ts

An Amazon Athena named (saved) query — a reusable SQL statement stored against a Glue database inside a workgroup. Its identity is the server-assigned NamedQueryId; the name, description, and queryString are updatable in place, while changing database or workGroup replaces it.

NamedQuery: Saving Queries

const query = yield* AWS.Athena.NamedQuery("TopCustomers", {
  database: "analytics",
  queryString: "SELECT customer_id, SUM(amount) AS total " +
    "FROM orders GROUP BY customer_id ORDER BY total DESC LIMIT 10",
  workGroup: wg.workGroupName,
});

PreparedStatement

Source: src/AWS/Athena/PreparedStatement.ts

An Amazon Athena prepared statement — a named, parameterized SQL statement saved in a workgroup and run with EXECUTE name USING .... Identity is the (workGroup, statementName) pair; the queryStatement and description are updatable in place.

PreparedStatement: Preparing Statements

const stmt = yield* AWS.Athena.PreparedStatement("TopN", {
  workGroup: wg.workGroupName,
  queryStatement: "SELECT * FROM analytics.orders WHERE customer_id = ?",
});
// then at runtime: EXECUTE <stmt.statementName> USING 'customer-123'

Query

Source: src/AWS/Athena/Query.ts

Run an Athena query end-to-end from a Lambda/Task: start the execution against a bound workgroup, poll GetQueryExecution until it reaches a terminal state (bounded), then read and decode the result set. Results are written to the workgroup’s enforced S3 output location in resultsBucket.

Query: Running Queries

Query and read the result rows

const runQuery = yield* AWS.Athena.Query(workGroup, resultsBucket);
const result = yield* runQuery({ QueryString: "SELECT 1" });
// result.rows[0] === ["_col0"] (header), result.rows[1] === ["1"]

Bind a WorkGroup to a Lambda Function

import * as Athena from "alchemy/AWS/Athena";
import * as Lambda from "alchemy/AWS/Lambda";
import * as S3 from "alchemy/AWS/S3";
import * as Output from "alchemy/Output";

export class QueryFunction extends Lambda.Function<Lambda.Function>()(
  "QueryFunction",
) {}

export default QueryFunction.make(
  { main: import.meta.url, functionUrl: true, timeout: Duration.seconds(60) },
  Effect.gen(function* () {
    const bucket = yield* S3.Bucket("Results", { forceDestroy: true });
    const workGroup = yield* Athena.WorkGroup("Analytics", {
      outputLocation: Output.interpolate`s3://${bucket.bucketName}/results/`,
      enforceWorkGroupConfiguration: true,
    });

    // grants athena:StartQueryExecution/GetQueryExecution/GetQueryResults
    // on the workgroup, S3 access on the results bucket, and Glue catalog
    // reads for table-backed queries
    const runQuery = yield* Athena.Query(workGroup, bucket);

    return {
      fetch: Effect.gen(function* () {
        const result = yield* runQuery({
          QueryString: "SELECT COUNT(*) AS c FROM my_db.people",
        });
        return yield* HttpServerResponse.json({ rows: result.rows });
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(Athena.QueryHttp)),
);

StopQueryExecution

Source: src/AWS/Athena/StopQueryExecution.ts

Runtime binding for athena:StopQueryExecution.

Cancels a running query in the bound workgroup. Stopping an already finished query is a no-op, so the call is safely idempotent. Provide the implementation with Effect.provide(AWS.Athena.StopQueryExecutionHttp).

StopQueryExecution: Cancelling Queries

// init — bind the operation to the workgroup
const stopQueryExecution = yield* AWS.Athena.StopQueryExecution(workGroup);

// runtime
yield* stopQueryExecution({ QueryExecutionId: id });

WorkGroup

Source: src/AWS/Athena/WorkGroup.ts

An Amazon Athena workgroup — an isolation boundary for queries that pins the S3 result-output location, result encryption, a bytes-scanned cutoff, and whether that configuration is enforced over per-query client settings.

WorkGroup: Creating Workgroups

Workgroup with an enforced result location

const results = yield* AWS.S3.Bucket("AthenaResults", {});
const wg = yield* AWS.Athena.WorkGroup("Analytics", {
  outputLocation: results.bucketName.pipe(
    Output.map((b) => `s3://${b}/results/`),
  ),
  enforceWorkGroupConfiguration: true,
});

Workgroup with a bytes-scanned cost guardrail

const wg = yield* AWS.Athena.WorkGroup("Guarded", {
  outputLocation: "s3://my-results-bucket/prefix/",
  bytesScannedCutoffPerQuery: 10_000_000, // 10 MB per query
  publishCloudWatchMetricsEnabled: true,
});