sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Athena/ Query.ts

import type * as athena from "@distilled.cloud/aws/athena";
import * as Binding from "alchemy/Binding";
import * as Data from "effect/Data";
import type * as Effect from "effect/Effect";
import type { Bucket } from "../S3/Bucket.ts";
import type { WorkGroup } from "./WorkGroup.ts";

/**
 * The query request — the workgroup is injected by the binding (which also
 * supplies the enforced result location), so callers pass the SQL text and any
 * execution context/parameters as the raw distilled shape.
 */
export interface RunQueryRequest extends Omit<
  athena.StartQueryExecutionInput,
  "WorkGroup" | "ResultConfiguration"
> {}

/**
 * The fully-resolved result of a query: the terminal state plus the decoded
 * result set (column names + rows of string cells, exactly as Athena returns
 * them — the first row of a `SELECT` is the header).
 */
export interface QueryResult {
  readonly queryExecutionId: string;
  readonly state: athena.QueryExecutionState;
  readonly stateChangeReason: string | undefined;
  readonly columns: string[];
  readonly rows: string[][];
}

/**
 * Raised when a query reaches a terminal non-`SUCCEEDED` state (FAILED or
 * CANCELLED), or does not settle within the bounded poll window.
 */
export class AthenaQueryFailed extends Data.TaggedError("AthenaQueryFailed")<{
  readonly queryExecutionId: string;
  readonly state: string;
  readonly reason: string | undefined;
}> {}

/**
 * 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`.
 *
 * ### Running Queries
 * **Example:** Query and read the result rows
 * ```typescript
 * const runQuery = yield* AWS.Athena.Query(workGroup, resultsBucket);
 * const result = yield* runQuery({ QueryString: "SELECT 1" });
 * // result.rows[0] === ["_col0"] (header), result.rows[1] === ["1"]
 * ```
 *
 * **Example:** Bind a WorkGroup to a Lambda Function
 * ```typescript
 * import * as Athena from "@alchemy.run/aws/Athena";
 * import * as Lambda from "@alchemy.run/aws/Lambda";
 * import * as S3 from "@alchemy.run/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)),
 * );
 * ```
 *
 * @binding
 */
export interface Query extends Binding.Service<
  Query,
  "AWS.Athena.Query",
  (
    workGroup: WorkGroup,
    resultsBucket: Bucket,
  ) => Effect.Effect<
    (
      request: RunQueryRequest,
    ) => Effect.Effect<
      QueryResult,
      | athena.StartQueryExecutionError
      | athena.GetQueryExecutionError
      | athena.GetQueryResultsError
      | AthenaQueryFailed
    >
  >
> {}
export const Query = Binding.Service<Query>("AWS.Athena.Query");