feat(api): add Athena workgroups and a query editor to the cloud explorer

Create and delete Athena workgroups (with a result folder, optionally
enforced), and run SQL in one: pick a database from the Glue Data Catalog,
preview a table, run with Ctrl+Enter, cancel a running query, read up to 1,000
rows and download the full result CSV from S3. Recent queries in the workgroup
can be reopened. TheCloud runs the SQL for real over the files a Glue table
points at. The Glue page links to the editor.

packages/api/package.json

@@ -14,6 +14,7 @@
     "@aws-sdk/client-api-gateway": "^3.1076.0",
     "@aws-sdk/client-apigatewayv2": "^3.1076.0",
     "@aws-sdk/client-appconfig": "^3.1076.0",
+    "@aws-sdk/client-athena": "^3.1146.0",
     "@aws-sdk/client-auto-scaling": "^3.1146.0",
     "@aws-sdk/client-cloudformation": "^3.1111.0",
     "@aws-sdk/client-cloudfront": "^3.1146.0",

packages/api/src/adapter-aws/AwsQueryAdapter.test.ts

@@ -0,0 +1,166 @@
+import {describe, expect, test} from 'bun:test'
+import {
+    type AthenaClient,
+    CreateWorkGroupCommand,
+    DeleteWorkGroupCommand,
+    GetQueryExecutionCommand,
+    GetQueryResultsCommand,
+    GetWorkGroupCommand,
+    ListDatabasesCommand,
+    ListQueryExecutionsCommand,
+    ListTableMetadataCommand,
+    ListWorkGroupsCommand,
+    StartQueryExecutionCommand,
+    StopQueryExecutionCommand,
+} from '@aws-sdk/client-athena'
+import {AwsQueryAdapter} from './AwsQueryAdapter'
+import {NotFoundError, ValidationError} from '../cloud-spi/errors'
+
+type SendResult = Record<string, unknown>
+
+function execution(id: string, overrides: Record<string, unknown> = {}) {
+    return {
+        QueryExecutionId: id,
+        Query: 'SELECT name, amount FROM orders',
+        StatementType: 'DML',
+        WorkGroup: 'analysts',
+        QueryExecutionContext: {Database: 'shop', Catalog: 'AwsDataCatalog'},
+        ResultConfiguration: {OutputLocation: `s3://results/${id}.csv`},
+        Status: {State: 'SUCCEEDED', SubmissionDateTime: new Date('2026-10-25T21:00:00Z'), CompletionDateTime: new Date('2026-10-25T21:00:01Z')},
+        Statistics: {TotalExecutionTimeInMillis: 42, DataScannedInBytes: 0},
+        ...overrides,
+    }
+}
+
+const header = {Data: [{VarCharValue: 'name'}, {VarCharValue: 'amount'}]}
+const columnInfo = [{Name: 'name', Label: 'name', Type: 'varchar'}, {Name: 'amount', Label: 'amount', Type: 'double'}]
+const row = (name: string, amount: string) => ({Data: [{VarCharValue: name}, {VarCharValue: amount}]})
+
+function adapterWith(handler: (command: object) => SendResult | undefined = () => undefined) {
+    const sent: object[] = []
+    const client = {
+        async send(command: object) {
+            sent.push(command)
+            const result = handler(command)
+            if (result) return result
+            if (command instanceof GetQueryExecutionCommand) return {QueryExecution: execution(command.input.QueryExecutionId ?? '')}
+            if (command instanceof GetWorkGroupCommand) {
+                return {WorkGroup: {Name: command.input.WorkGroup, State: 'ENABLED', Description: 'Team', Configuration: {ResultConfiguration: {OutputLocation: 's3://results/'}, EnforceWorkGroupConfiguration: true, EngineVersion: {EffectiveEngineVersion: 'Athena engine version 3'}}}}
+            }
+            if (command instanceof StartQueryExecutionCommand) return {QueryExecutionId: 'q-new'}
+            return {}
+        },
+    }
+    return {sent, adapter: new AwsQueryAdapter(client as unknown as AthenaClient)}
+}
+
+describe('AwsQueryAdapter', () => {
+    test('lists workgroups across pages and describes one with its result location', async () => {
+        const {adapter} = adapterWith((command) => command instanceof ListWorkGroupsCommand
+            ? command.input.NextToken ? {WorkGroups: [{Name: 'analysts', State: 'ENABLED', Description: 'Team'}]} : {WorkGroups: [{Name: 'primary', State: 'ENABLED'}], NextToken: 'n'}
+            : undefined)
+
+        expect((await adapter.list()).map((wg) => [wg.name, wg.status])).toEqual([['primary', 'ENABLED'], ['analysts', 'ENABLED']])
+        expect((await adapter.list({search: 'team'})).map((wg) => wg.name)).toEqual(['analysts'])
+        expect((await adapter.get('analysts'))?.metadata).toEqual({description: 'Team', outputLocation: 's3://results/', enforceConfiguration: true, engineVersion: 'Athena engine version 3'})
+    })
+
+    test('creates a workgroup with a result folder, and keeps the primary workgroup', async () => {
+        const {adapter, sent} = adapterWith()
+        await adapter.create({values: {name: 'analysts', description: 'Team', outputLocation: 's3://results/athena', enforce: 'true'}})
+        expect((sent.find((command) => command instanceof CreateWorkGroupCommand) as CreateWorkGroupCommand).input).toEqual({
+            Name: 'analysts', Description: 'Team', Configuration: {ResultConfiguration: {OutputLocation: 's3://results/athena/'}, EnforceWorkGroupConfiguration: true},
+        })
+
+        await expect(adapter.create({values: {name: 'primary'}})).rejects.toBeInstanceOf(ValidationError)
+        await expect(adapter.create({values: {name: 'bad name'}})).rejects.toBeInstanceOf(ValidationError)
+        await expect(adapter.delete('primary')).rejects.toBeInstanceOf(ValidationError)
+        await adapter.delete('analysts')
+        expect((sent.find((command) => command instanceof DeleteWorkGroupCommand) as DeleteWorkGroupCommand).input).toEqual({WorkGroup: 'analysts', RecursiveDeleteOption: true})
+    })
+
+    test('starts a query in the workgroup against a database', async () => {
+        const {adapter, sent} = adapterWith()
+        const started = await adapter.startQuery('analysts', {sql: '  SELECT 1  ', database: 'shop'})
+
+        expect((sent.find((command) => command instanceof StartQueryExecutionCommand) as StartQueryExecutionCommand).input).toEqual({
+            QueryString: 'SELECT 1', WorkGroup: 'analysts', QueryExecutionContext: {Catalog: 'AwsDataCatalog', Database: 'shop'},
+        })
+        expect(started).toMatchObject({id: 'q-new', state: 'SUCCEEDED', runtimeMs: 42, outputLocation: 's3://results/q-new.csv'})
+        await expect(adapter.startQuery('analysts', {sql: '   '})).rejects.toBeInstanceOf(ValidationError)
+    })
+
+    test('returns a succeeded query with its columns and rows, without the header row', async () => {
+        const {adapter} = adapterWith((command) => command instanceof GetQueryResultsCommand
+            ? {ResultSet: {ResultSetMetadata: {ColumnInfo: columnInfo}, Rows: [header, row('alpha', '10'), row('beta', '25')]}}
+            : undefined)
+
+        const result = await adapter.getQueryResult('analysts', 'q1')
+        expect(result.columns).toEqual([{name: 'name', type: 'varchar'}, {name: 'amount', type: 'double'}])
+        expect(result.rows).toEqual([['alpha', '10'], ['beta', '25']])
+        expect(result.truncated).toBe(false)
+    })
+
+    test('stops reading after the row limit and says the result is truncated', async () => {
+        const page = Array.from({length: 1000}, (_, i) => row(`n${i}`, String(i)))
+        const {adapter, sent} = adapterWith((command) => command instanceof GetQueryResultsCommand
+            ? command.input.NextToken ? {ResultSet: {Rows: page}, NextToken: 'more'} : {ResultSet: {ResultSetMetadata: {ColumnInfo: columnInfo}, Rows: [header, ...page.slice(0, 999)]}, NextToken: 'p2'}
+            : undefined)
+
+        const result = await adapter.getQueryResult('analysts', 'q1')
+        expect(result.rows).toHaveLength(1000)
+        expect(result.truncated).toBe(true)
+        expect(sent.filter((command) => command instanceof GetQueryResultsCommand)).toHaveLength(2)
+    })
+
+    test('does not read results of a query that has not succeeded', async () => {
+        const {adapter, sent} = adapterWith((command) => command instanceof GetQueryExecutionCommand
+            ? {QueryExecution: execution('q1', {Status: {State: 'FAILED', StateChangeReason: 'Table orders not found'}})}
+            : undefined)
+
+        const result = await adapter.getQueryResult('analysts', 'q1')
+        expect(result.execution).toMatchObject({state: 'FAILED', stateReason: 'Table orders not found'})
+        expect(result.rows).toEqual([])
+        expect(sent.some((command) => command instanceof GetQueryResultsCommand)).toBe(false)
+    })
+
+    test('refuses a query from another workgroup', async () => {
+        const {adapter, sent} = adapterWith()
+        await expect(adapter.getQueryResult('primary', 'q1')).rejects.toBeInstanceOf(NotFoundError)
+        await expect(adapter.stopQuery('primary', 'q1')).rejects.toBeInstanceOf(NotFoundError)
+        expect(sent.some((command) => command instanceof StopQueryExecutionCommand)).toBe(false)
+
+        await adapter.stopQuery('analysts', 'q1')
+        expect(sent.some((command) => command instanceof StopQueryExecutionCommand)).toBe(true)
+    })
+
+    test('lists the workgroup queries newest first', async () => {
+        const {adapter} = adapterWith((command) => {
+            if (command instanceof ListQueryExecutionsCommand) return {QueryExecutionIds: ['old', 'new', 'other']}
+            if (command instanceof GetQueryExecutionCommand) {
+                const id = command.input.QueryExecutionId
+                return {QueryExecution: execution(id ?? '', {
+                    WorkGroup: id === 'other' ? 'primary' : 'analysts',
+                    Status: {State: 'SUCCEEDED', SubmissionDateTime: new Date(id === 'new' ? '2026-10-25T22:00:00Z' : '2026-10-25T21:00:00Z')},
+                })}
+            }
+            return undefined
+        })
+
+        expect((await adapter.listQueries('analysts')).map((query) => query.id)).toEqual(['new', 'old'])
+    })
+
+    test('lists databases and the tables of the chosen one', async () => {
+        const {adapter, sent} = adapterWith((command) => {
+            if (command instanceof ListDatabasesCommand) return {DatabaseList: [{Name: 'shop'}, {Name: 'logs'}]}
+            if (command instanceof ListTableMetadataCommand) {
+                return {TableMetadataList: [{Name: 'orders', Columns: [{Name: 'id', Type: 'int'}], PartitionKeys: [{Name: 'day', Type: 'string'}]}]}
+            }
+            return undefined
+        })
+
+        expect(await adapter.describeQueryCatalog('shop')).toEqual({databases: ['logs', 'shop'], database: 'shop', tables: [{name: 'orders', columns: [{name: 'id', type: 'int'}, {name: 'day', type: 'string'}]}]})
+        expect((await adapter.describeQueryCatalog('missing')).database).toBe('logs')
+        expect((sent.filter((command) => command instanceof ListTableMetadataCommand) as ListTableMetadataCommand[]).map((command) => command.input.DatabaseName)).toEqual(['shop', 'logs'])
+    })
+})

packages/api/src/adapter-aws/AwsQueryAdapter.ts

@@ -0,0 +1,268 @@
+import {
+    type AthenaClient,
+    CreateWorkGroupCommand,
+    DeleteWorkGroupCommand,
+    GetQueryExecutionCommand,
+    GetQueryResultsCommand,
+    type GetQueryResultsCommandOutput,
+    GetWorkGroupCommand,
+    ListDatabasesCommand,
+    ListQueryExecutionsCommand,
+    ListTableMetadataCommand,
+    type ListTableMetadataCommandOutput,
+    ListWorkGroupsCommand,
+    type QueryExecution,
+    StartQueryExecutionCommand,
+    StopQueryExecutionCommand,
+    type TableMetadata,
+    type WorkGroup,
+    type WorkGroupSummary,
+} from '@aws-sdk/client-athena'
+import {NotFoundError, RuntimeError, ValidationError} from '../cloud-spi/errors'
+import {
+    awsQuerySchema,
+    PRIMARY_WORKGROUP,
+    QUERY_HISTORY_LIMIT,
+    QUERY_RESULT_ROW_LIMIT,
+    WORKGROUP_NAME_PATTERN,
+} from '../cloud-spi/querySchema'
+import type {
+    CloudResource,
+    CloudServiceAdapter,
+    CreateResourceInput,
+    QueryCatalog,
+    QueryExecutionSummary,
+    QueryInput,
+    QueryResult,
+    ResourceQuery,
+    ServiceSchema,
+} from '../cloud-spi/types'
+
+/** Athena's own catalog name for the Glue Data Catalog. */
+const DATA_CATALOG = 'AwsDataCatalog'
+/** Athena's cap on a query string. */
+const MAX_QUERY_LENGTH = 262_144
+const S3_URI = /^s3:\/\/[a-z0-9.-]{3,63}(\/.*)?$/
+
+/**
+ * Talks to Amazon Athena, verified against Floci core (community, `latest`).
+ *
+ * Notes from probing the runtime:
+ *  - Queries really run: TheCloud executes the SQL with DuckDB over the files a
+ *    Glue table points at, and writes the result to S3 as CSV, as Athena does.
+ *  - Statements that return no rows, such as SHOW TABLES, fail in the runtime,
+ *    so the editor lists databases and tables through the catalog APIs instead.
+ *  - Data scanned is always reported as 0 bytes, so the editor shows only the
+ *    run time.
+ */
+export class AwsQueryAdapter implements CloudServiceAdapter {
+    readonly cloud = 'aws' as const
+    readonly service = 'query' as const
+
+    constructor(private readonly athena: AthenaClient) {}
+
+    schema(): ServiceSchema {
+        return awsQuerySchema()
+    }
+
+    async list(query: ResourceQuery = {}): Promise<CloudResource[]> {
+        const found: WorkGroupSummary[] = []
+        let next: string | undefined
+        do {
+            const res = await this.athena.send(new ListWorkGroupsCommand({MaxResults: 50, ...(next ? {NextToken: next} : {})}))
+            found.push(...(res.WorkGroups ?? []))
+            next = res.NextToken
+        } while (next)
+
+        const search = query.search?.trim().toLowerCase()
+        return found.map(toResource).filter((workGroup) => !search
+            || workGroup.name.toLowerCase().includes(search)
+            || String(workGroup.metadata.description ?? '').toLowerCase().includes(search))
+    }
+
+    async get(id: string): Promise<CloudResource | null> {
+        try {
+            const workGroup = (await this.athena.send(new GetWorkGroupCommand({WorkGroup: id}))).WorkGroup
+            return workGroup ? toResource(workGroup) : null
+        } catch (error) {
+            if (errorName(error) === 'InvalidRequestException') return null
+            throw error
+        }
+    }
+
+    async create(input: CreateResourceInput): Promise<CloudResource> {
+        const values = input.values
+        const name = text(values.name)
+        if (!new RegExp(WORKGROUP_NAME_PATTERN).test(name)) throw new ValidationError('name must be up to 128 letters, numbers, dots, dashes or underscores')
+        if (name === PRIMARY_WORKGROUP) throw new ValidationError('Every account already has the primary workgroup')
+        const outputLocation = text(values.outputLocation)
+        if (outputLocation && !S3_URI.test(outputLocation)) throw new ValidationError('outputLocation must be an S3 URI such as s3://my-bucket/athena-results/')
+        const description = text(values.description)
+
+        await this.athena.send(new CreateWorkGroupCommand({
+            Name: name,
+            ...(description ? {Description: description} : {}),
+            Configuration: {
+                ...(outputLocation ? {ResultConfiguration: {OutputLocation: outputLocation.endsWith('/') ? outputLocation : `${outputLocation}/`}} : {}),
+                EnforceWorkGroupConfiguration: values.enforce === 'true',
+            },
+        }))
+        const created = await this.get(name)
+        if (!created) throw new RuntimeError(`Athena did not return the new workgroup ${name}`)
+        return created
+    }
+
+    async delete(id: string): Promise<void> {
+        if (id === PRIMARY_WORKGROUP) throw new ValidationError('The primary workgroup cannot be deleted')
+        await this.athena.send(new DeleteWorkGroupCommand({WorkGroup: id, RecursiveDeleteOption: true}))
+    }
+
+    async startQuery(workGroup: string, input: QueryInput): Promise<QueryExecutionSummary> {
+        const sql = typeof input.sql === 'string' ? input.sql.trim() : ''
+        if (!sql) throw new ValidationError('Enter a query to run')
+        if (sql.length > MAX_QUERY_LENGTH) throw new ValidationError(`A query can be at most ${MAX_QUERY_LENGTH} characters`)
+        const database = text(input.database)
+
+        const started = await this.athena.send(new StartQueryExecutionCommand({
+            QueryString: sql,
+            WorkGroup: workGroup,
+            ...(database ? {QueryExecutionContext: {Catalog: DATA_CATALOG, Database: database}} : {}),
+        }))
+        if (!started.QueryExecutionId) throw new RuntimeError('Athena did not return a query id')
+        return (await this.execution(workGroup, started.QueryExecutionId))
+    }
+
+    async getQueryResult(workGroup: string, queryId: string): Promise<QueryResult> {
+        const execution = await this.execution(workGroup, queryId)
+        if (execution.state !== 'SUCCEEDED' || !execution.outputLocation) return {execution, columns: [], rows: [], truncated: false}
+
+        const pages: GetQueryResultsCommandOutput[] = []
+        let next: string | undefined
+        let rowCount = 0
+        do {
+            const page = await this.athena.send(new GetQueryResultsCommand({QueryExecutionId: queryId, MaxResults: 1000, ...(next ? {NextToken: next} : {})}))
+            pages.push(page)
+            rowCount += page.ResultSet?.Rows?.length ?? 0
+            next = page.NextToken
+        } while (next && rowCount <= QUERY_RESULT_ROW_LIMIT)
+
+        const columnInfo = pages[0]?.ResultSet?.ResultSetMetadata?.ColumnInfo ?? []
+        const raw = pages.flatMap((page) => page.ResultSet?.Rows ?? []).map((row) => (row.Data ?? []).map((cell) => cell.VarCharValue ?? null))
+        const header = raw[0] ?? []
+        const columns = columnInfo.length > 0
+            ? columnInfo.map((column) => ({name: column.Label ?? column.Name ?? '', type: column.Type ?? null}))
+            : header.map((name) => ({name: name ?? '', type: null}))
+        // Athena repeats the column names as the first row of a SELECT's results.
+        const body = raw.length > 0 && header.length === columns.length && header.every((name, index) => name === columns[index].name) ? raw.slice(1) : raw
+        return {execution, columns, rows: body.slice(0, QUERY_RESULT_ROW_LIMIT), truncated: body.length > QUERY_RESULT_ROW_LIMIT || Boolean(next)}
+    }
+
+    async stopQuery(workGroup: string, queryId: string): Promise<void> {
+        await this.execution(workGroup, queryId)
+        await this.athena.send(new StopQueryExecutionCommand({QueryExecutionId: queryId}))
+    }
+
+    async listQueries(workGroup: string): Promise<QueryExecutionSummary[]> {
+        const ids = (await this.athena.send(new ListQueryExecutionsCommand({WorkGroup: workGroup, MaxResults: QUERY_HISTORY_LIMIT}))).QueryExecutionIds ?? []
+        const executions = await Promise.all(ids.slice(0, QUERY_HISTORY_LIMIT).map(async (id) => {
+            const res = await this.athena.send(new GetQueryExecutionCommand({QueryExecutionId: id}))
+            return res.QueryExecution ? toExecution(res.QueryExecution) : null
+        }))
+        return executions
+            .filter((execution): execution is QueryExecutionSummary => execution !== null && (execution.workGroup ?? PRIMARY_WORKGROUP) === workGroup)
+            .sort((a, b) => (b.submittedAt ?? '').localeCompare(a.submittedAt ?? ''))
+    }
+
+    async describeQueryCatalog(database?: string): Promise<QueryCatalog> {
+        const databases: string[] = []
+        let next: string | undefined
+        do {
+            const res = await this.athena.send(new ListDatabasesCommand({CatalogName: DATA_CATALOG, MaxResults: 50, ...(next ? {NextToken: next} : {})}))
+            databases.push(...(res.DatabaseList ?? []).map((entry) => entry.Name ?? '').filter(Boolean))
+            next = res.NextToken
+        } while (next)
+        databases.sort()
+
+        const chosen = database && databases.includes(database) ? database : databases[0] ?? null
+        if (!chosen) return {databases, database: null, tables: []}
+
+        const tables: TableMetadata[] = []
+        let tableToken: string | undefined
+        do {
+            const res: ListTableMetadataCommandOutput = await this.athena.send(new ListTableMetadataCommand({CatalogName: DATA_CATALOG, DatabaseName: chosen, MaxResults: 50, ...(tableToken ? {NextToken: tableToken} : {})}))
+            tables.push(...(res.TableMetadataList ?? []))
+            tableToken = res.NextToken
+        } while (tableToken)
+        return {
+            databases,
+            database: chosen,
+            tables: tables.map((table) => ({
+                name: table.Name ?? '',
+                columns: [...(table.Columns ?? []), ...(table.PartitionKeys ?? [])].map((column) => ({name: column.Name ?? '', type: column.Type ?? ''})),
+            })).sort((a, b) => a.name.localeCompare(b.name)),
+        }
+    }
+
+    /** A query, refused unless it ran in this workgroup, so one workgroup's page never shows another's. */
+    private async execution(workGroup: string, queryId: string): Promise<QueryExecutionSummary> {
+        let execution: QueryExecution | undefined
+        try {
+            execution = (await this.athena.send(new GetQueryExecutionCommand({QueryExecutionId: queryId}))).QueryExecution
+        } catch (error) {
+            if (errorName(error) === 'InvalidRequestException') throw new NotFoundError(`Query ${queryId} not found`)
+            throw error
+        }
+        if (!execution || (execution.WorkGroup ?? PRIMARY_WORKGROUP) !== workGroup) throw new NotFoundError(`Query ${queryId} is not in the ${workGroup} workgroup`)
+        return toExecution(execution)
+    }
+}
+
+function toResource(workGroup: WorkGroup | WorkGroupSummary): CloudResource {
+    const name = workGroup.Name ?? ''
+    const detail = 'Configuration' in workGroup ? workGroup : undefined
+    const configuration = detail?.Configuration
+    return {
+        id: name,
+        name,
+        cloud: 'aws',
+        service: 'query',
+        type: 'athenaWorkGroup',
+        region: null,
+        createdAt: workGroup.CreationTime ? workGroup.CreationTime.toISOString() : null,
+        status: workGroup.State ?? null,
+        metadata: {
+            description: workGroup.Description || null,
+            ...(detail ? {
+                outputLocation: configuration?.ResultConfiguration?.OutputLocation ?? null,
+                enforceConfiguration: configuration?.EnforceWorkGroupConfiguration === true,
+                engineVersion: configuration?.EngineVersion?.EffectiveEngineVersion ?? configuration?.EngineVersion?.SelectedEngineVersion ?? null,
+            } : {}),
+        },
+    }
+}
+
+function toExecution(execution: QueryExecution): QueryExecutionSummary {
+    const status = execution.Status
+    return {
+        id: execution.QueryExecutionId ?? '',
+        sql: execution.Query ?? '',
+        database: execution.QueryExecutionContext?.Database ?? null,
+        workGroup: execution.WorkGroup ?? null,
+        state: status?.State ?? 'QUEUED',
+        stateReason: status?.StateChangeReason ?? status?.AthenaError?.ErrorMessage ?? null,
+        statementType: execution.StatementType ?? null,
+        submittedAt: status?.SubmissionDateTime ? status.SubmissionDateTime.toISOString() : null,
+        completedAt: status?.CompletionDateTime ? status.CompletionDateTime.toISOString() : null,
+        runtimeMs: execution.Statistics?.TotalExecutionTimeInMillis ?? execution.Statistics?.EngineExecutionTimeInMillis ?? null,
+        dataScannedBytes: execution.Statistics?.DataScannedInBytes ?? null,
+        outputLocation: execution.ResultConfiguration?.OutputLocation ?? null,
+    }
+}
+
+function text(value: unknown): string {
+    return typeof value === 'string' ? value.trim() : ''
+}
+
+function errorName(error: unknown): string | undefined {
+    return typeof error === 'object' && error !== null ? (error as {name?: string}).name : undefined
+}

packages/api/src/aws.ts

@@ -39,6 +39,7 @@ import { ACMClient } from "@aws-sdk/client-acm";
 import { PipesClient } from "@aws-sdk/client-pipes";
 import { EFSClient } from "@aws-sdk/client-efs";
 import { GlueClient } from "@aws-sdk/client-glue";
+import { AthenaClient } from "@aws-sdk/client-athena";
 
 const endpoint = process.env.FLOCI_ENDPOINT;
 const region = process.env.AWS_REGION || "us-east-1";
@@ -109,6 +110,7 @@ export type AwsClients = {
   pipes: PipesClient;
   efs: EFSClient;
   glue: GlueClient;
+  athena: AthenaClient;
 };
 
 export type AwsClientName = keyof AwsClients;
@@ -163,6 +165,7 @@ function buildClients(accountId: string): AwsClients {
     pipes: new PipesClient(base),
     efs: new EFSClient(base),
     glue: new GlueClient(base),
+    athena: new AthenaClient(base),
   };
 }
 

packages/api/src/cloud-spi/querySchema.ts

@@ -0,0 +1,80 @@
+import type {CloudProvider, FieldSchema, ServiceSchema, TableColumnSchema} from './types'
+
+/** CreateWorkGroup's name rule. */
+export const WORKGROUP_NAME_PATTERN = '^[a-zA-Z0-9._-]{1,128}$'
+/** The workgroup every account has, which Athena does not let you delete. */
+export const PRIMARY_WORKGROUP = 'primary'
+/** Rows the editor shows for one query; the full result stays in the CSV file in S3. */
+export const QUERY_RESULT_ROW_LIMIT = 1000
+/** Recent queries the history shows. */
+export const QUERY_HISTORY_LIMIT = 25
+
+const workGroupColumns: TableColumnSchema[] = [
+    {name: 'name', label: 'Name'},
+    {name: 'status', label: 'State', format: 'badge'},
+    {name: 'description', label: 'Description', path: 'metadata.description', emptyText: '—'},
+    {name: 'createdAt', label: 'Created', format: 'datetime', emptyText: '—'},
+]
+
+const workGroupFilters: FieldSchema[] = [{name: 'search', label: 'Search', type: 'text', required: false}]
+
+export function awsQuerySchema(): ServiceSchema {
+    return {
+        cloud: 'aws',
+        service: 'query',
+        displayName: 'Athena workgroups',
+        fields: [
+            {
+                name: 'name',
+                label: 'Name',
+                type: 'text',
+                required: true,
+                validation: {pattern: WORKGROUP_NAME_PATTERN, message: 'Use up to 128 letters, numbers, dots, dashes and underscores'},
+            },
+            {name: 'description', label: 'Description', type: 'text', required: false, validation: {maxLength: 1024}},
+            {
+                name: 'outputLocation',
+                label: 'Query result location',
+                type: 'text',
+                required: false,
+                span: true,
+                description: 'Where each query writes its results as a CSV file, such as s3://my-bucket/athena-results/. Leave empty to use TheCloud\'s default results bucket.',
+                validation: {pattern: '^s3://[a-z0-9.-]{3,63}(/.*)?$', message: 'Use an S3 URI such as s3://my-bucket/athena-results/'},
+            },
+            {
+                name: 'enforce',
+                label: 'Override client-side settings',
+                type: 'select',
+                required: false,
+                defaultValue: 'false',
+                description: 'When on, queries always use this workgroup\'s result location, even if a client asks for another.',
+                options: [
+                    {label: 'Off', value: 'false'},
+                    {label: 'On', value: 'true'},
+                ],
+            },
+        ],
+        actions: ['list', 'create', 'delete', 'inspect'],
+        capabilities: {
+            resourceActions: [
+                {name: 'list', label: 'List workgroups', enabled: true, status: 'available', runtimeRequired: true},
+                {name: 'create', label: 'Create workgroup', enabled: true, status: 'available', runtimeRequired: true},
+                {name: 'delete', label: 'Delete workgroup', enabled: true, status: 'available', runtimeRequired: true},
+                {name: 'inspect', label: 'Inspect workgroup', enabled: true, status: 'available', runtimeRequired: true},
+            ],
+            queryActions: [
+                {name: 'run', label: 'Run query', enabled: true, status: 'available', runtimeRequired: true},
+                {name: 'results', label: 'Get query results', enabled: true, status: 'available', runtimeRequired: true},
+                {name: 'stop', label: 'Cancel query', enabled: true, status: 'available', runtimeRequired: true},
+                {name: 'history', label: 'Recent queries', enabled: true, status: 'available', runtimeRequired: true},
+                {name: 'catalog', label: 'Browse databases and tables', enabled: true, status: 'available', runtimeRequired: true},
+            ],
+        },
+        filters: workGroupFilters,
+        columns: workGroupColumns,
+    }
+}
+
+export function querySchemaFor(cloud: CloudProvider): ServiceSchema | null {
+    return cloud === 'aws' ? awsQuerySchema() : null
+}

packages/api/src/cloud-spi/serviceCatalog.ts

@@ -229,6 +229,13 @@ export const SERVICE_CATALOG = {
         group: 'Analytics',
         order: 20,
     },
+    query: {
+        displayName: 'Query',
+        displayNameByCloud: {aws: 'Athena'},
+        iconKey: 'query',
+        group: 'Analytics',
+        order: 21,
+    },
     identity: {displayName: 'Identity', iconKey: 'iam', group: 'Security', order: 5},
     apigateway: {displayName: 'API Gateway', iconKey: 'apigateway', group: 'Integration', order: 10},
     email: {

packages/api/src/cloud-spi/types.ts

@@ -188,6 +188,7 @@ export type UserPoolActionName =
 export type DistributionActionName = 'setEnabled' | 'createInvalidation'
 export type AutoScalingActionName = 'setCapacity' | 'terminateInstance'
 export type CertificateActionName = 'download' | 'export' | 'revoke'
+export type QueryActionName = 'run' | 'results' | 'stop' | 'history' | 'catalog'
 export type DataCatalogActionName = 'createTable' | 'deleteTable'
 export type FileSystemActionName = 'createMountTarget' | 'deleteMountTarget' | 'createAccessPoint' | 'deleteAccessPoint' | 'attachFunction' | 'detachFunction'
 export type MonitoringActionName = 'listMetrics' | 'getMetricData' | 'alarmHistory' | 'setAlarmState' | 'setAlarmActions'
@@ -253,6 +254,7 @@ export interface ServiceSchema {
         certificateActions?: CapabilitySchema<CertificateActionName>[]
         fileSystemActions?: CapabilitySchema<FileSystemActionName>[]
         dataCatalogActions?: CapabilitySchema<DataCatalogActionName>[]
+        queryActions?: CapabilitySchema<QueryActionName>[]
         monitoringActions?: CapabilitySchema<MonitoringActionName>[]
         /** API Gateway v2 (HTTP and WebSocket APIs): what the routes, stages and security panel can do. */
         httpApiActions?: CapabilitySchema<HttpApiActionName>[]
@@ -560,6 +562,43 @@ export interface AccessPointInput {
     permissions: string
 }
 
+export interface QueryInput {
+    sql: string
+    /** The Glue database unqualified table names resolve in. */
+    database?: string
+}
+
+export interface QueryExecutionSummary {
+    id: string
+    sql: string
+    database: string | null
+    workGroup: string | null
+    /** QUEUED, RUNNING, SUCCEEDED, FAILED or CANCELLED. */
+    state: string
+    stateReason: string | null
+    statementType: string | null
+    submittedAt: string | null
+    completedAt: string | null
+    runtimeMs: number | null
+    dataScannedBytes: number | null
+    /** The S3 object holding the full result as CSV. */
+    outputLocation: string | null
+}
+
+export interface QueryResult {
+    execution: QueryExecutionSummary
+    columns: Array<{name: string; type: string | null}>
+    rows: Array<Array<string | null>>
+    /** More rows exist than the console returns; the full result is in the output file. */
+    truncated: boolean
+}
+
+export interface QueryCatalog {
+    databases: string[]
+    database: string | null
+    tables: Array<{name: string; columns: Array<{name: string; type: string}>}>
+}
+
 export interface CatalogColumnInput {
     name: string
     type: string
@@ -1255,6 +1294,13 @@ export interface CloudServiceAdapter {
     /** With `replace`, the group launches a new instance in its place; otherwise desired capacity drops by one. */
     terminateAutoScalingInstance?(groupName: string, instanceId: string, replace: boolean): Promise<void>
     getCertificatePem?(certificateId: string): Promise<CertificatePem>
+    startQuery?(workGroup: string, input: QueryInput): Promise<QueryExecutionSummary>
+    /** The query's state, and its first rows once it has succeeded. */
+    getQueryResult?(workGroup: string, queryId: string): Promise<QueryResult>
+    stopQuery?(workGroup: string, queryId: string): Promise<void>
+    listQueries?(workGroup: string): Promise<QueryExecutionSummary[]>
+    /** The databases a query can use and, for the one named, its tables. */
+    describeQueryCatalog?(database?: string): Promise<QueryCatalog>
     createCatalogTable?(databaseName: string, input: CatalogTableInput): Promise<CloudResource>
     deleteCatalogTable?(databaseName: string, tableName: string): Promise<CloudResource>
     createMountTarget?(fileSystemId: string, subnetId: string): Promise<CloudResource>

packages/api/src/cloudProxy.test.ts

@@ -2,7 +2,7 @@ import {describe, expect, test} from 'bun:test'
 import {createCloudAdapterRegistry} from './cloudProxy'
 import {checkChildCapabilities} from './cloud-spi/childCapabilities'
 import {isServiceType} from './cloud-spi/serviceCatalog'
-import type {AutoScalingActionName, CloudProvider, CloudServiceAdapter, CloudServiceType, CertificateActionName, DatabaseActionName, DataCatalogActionName, DistributionActionName, FileSystemActionName, HttpApiActionName, KubernetesActionName, MonitoringActionName, ResourceActionName, UserPoolActionName} from './cloud-spi/types'
+import type {AutoScalingActionName, CloudProvider, CloudServiceAdapter, CloudServiceType, CertificateActionName, DatabaseActionName, DataCatalogActionName, DistributionActionName, FileSystemActionName, HttpApiActionName, QueryActionName, KubernetesActionName, MonitoringActionName, ResourceActionName, UserPoolActionName} from './cloud-spi/types'
 
 /**
  * Guards the schema-to-implementation contract for every registered adapter.
@@ -81,6 +81,14 @@ const METHOD_FOR_CERTIFICATE_ACTION: Record<CertificateActionName, keyof CloudSe
     revoke: 'revokeCertificate',
 }
 
+const METHOD_FOR_QUERY_ACTION: Record<QueryActionName, keyof CloudServiceAdapter> = {
+    run: 'startQuery',
+    results: 'getQueryResult',
+    stop: 'stopQuery',
+    history: 'listQueries',
+    catalog: 'describeQueryCatalog',
+}
+
 const METHOD_FOR_DATA_CATALOG_ACTION: Record<DataCatalogActionName, keyof CloudServiceAdapter> = {
     createTable: 'createCatalogTable',
     deleteTable: 'deleteCatalogTable',
@@ -231,6 +239,15 @@ describe('registered adapters honour their schema', () => {
                 ).toBe('function')
             }
 
+            const queryClaims = (adapter.schema().capabilities?.queryActions ?? []).filter((capability) => capability.status === 'available')
+            for (const capability of queryClaims) {
+                const method = METHOD_FOR_QUERY_ACTION[capability.name]
+                expect(
+                    typeof adapter[method],
+                    `${label} advertises ${capability.name} as available but has no ${String(method)}()`,
+                ).toBe('function')
+            }
+
             const dataCatalogClaims = (adapter.schema().capabilities?.dataCatalogActions ?? []).filter((capability) => capability.status === 'available')
             for (const capability of dataCatalogClaims) {
                 const method = METHOD_FOR_DATA_CATALOG_ACTION[capability.name]
@@ -274,6 +291,7 @@ describe('registered adapters honour their schema', () => {
                 ...(adapter.schema().capabilities?.autoScalingActions ?? []),
                 ...(adapter.schema().capabilities?.fileSystemActions ?? []),
                 ...(adapter.schema().capabilities?.dataCatalogActions ?? []),
+                ...(adapter.schema().capabilities?.queryActions ?? []),
                 ...(adapter.schema().capabilities?.certificateActions ?? []),
                 ...(adapter.schema().capabilities?.monitoringActions ?? []),
                 ...(adapter.schema().capabilities?.httpApiActions ?? []),

packages/api/src/cloudProxy.ts

@@ -55,6 +55,7 @@ import {AwsCertificatesAdapter} from './adapter-aws/AwsCertificatesAdapter'
 import {AwsPipesAdapter} from './adapter-aws/AwsPipesAdapter'
 import {AwsFileSystemsAdapter} from './adapter-aws/AwsFileSystemsAdapter'
 import {AwsDataCatalogAdapter} from './adapter-aws/AwsDataCatalogAdapter'
+import {AwsQueryAdapter} from './adapter-aws/AwsQueryAdapter'
 import {AwsMonitoringAdapter} from './adapter-aws/AwsMonitoringAdapter'
 import {awsClientsForAccount, resolveAccountId} from './aws'
 import {createEc2Service} from './services/ec2'
@@ -113,6 +114,7 @@ export function createCloudAdapterRegistry(accountId?: string | null): CloudAdap
         new AwsPipesAdapter(clients.pipes),
         new AwsFileSystemsAdapter(clients.efs, clients.lambda, clients.ec2),
         new AwsDataCatalogAdapter(clients.glue),
+        new AwsQueryAdapter(clients.athena),
         new AwsMonitoringAdapter(clients.cloudwatch),
         new AzureStorageAdapter(),
         new AzureServiceBusAdapter(),

packages/api/src/routes/clouds.test.ts

@@ -21,6 +21,7 @@ import {awsCdnSchema} from '../cloud-spi/cdnSchema'
 import {awsAutoScalingSchema} from '../cloud-spi/autoScalingSchema'
 import {awsFileSystemsSchema} from '../cloud-spi/fileSystemsSchema'
 import {awsDataCatalogSchema} from '../cloud-spi/dataCatalogSchema'
+import {awsQuerySchema} from '../cloud-spi/querySchema'
 import {awsCertificatesSchema} from '../cloud-spi/certificatesSchema'
 import {awsMonitoringSchema} from '../cloud-spi/monitoringSchema'
 import {awsAppConfigSchema} from '../cloud-spi/appConfigSchema'
@@ -877,6 +878,28 @@ describe('cloud schema routes', () => {
         expect(calls).toEqual([['capacity', 'web-asg', {desiredCapacity: 3}], ['terminate', 'web-asg', 'i-abc', true]])
     })
 
+    test('runs, reads, lists and cancels queries through the Athena adapter', async () => {
+        const calls: unknown[] = []
+        const execution = {id: 'q1', sql: 'SELECT 1', database: 'shop', workGroup: 'analysts', state: 'SUCCEEDED', stateReason: null, statementType: 'DML', submittedAt: null, completedAt: null, runtimeMs: 5, dataScannedBytes: 0, outputLocation: 's3://r/q1.csv'}
+        const app = appWithRoutes([mockAdapter('aws', {
+            service: 'query',
+            schema: awsQuerySchema,
+            startQuery: async (id, input) => { calls.push(['start', id, input.sql, input.database]); return execution },
+            getQueryResult: async (id, queryId) => { calls.push(['result', id, queryId]); return {execution, columns: [{name: '_col0', type: 'integer'}], rows: [['1']], truncated: false} },
+            stopQuery: async (id, queryId) => { calls.push(['stop', id, queryId]) },
+            listQueries: async (id) => { calls.push(['list', id]); return [execution] },
+            describeQueryCatalog: async (database) => { calls.push(['catalog', database]); return {databases: ['shop'], database: 'shop', tables: []} },
+        })])
+        const base = '/api/clouds/aws/services/query/resources/analysts/queries'
+
+        expect((await app.request(base, {method: 'POST', headers: {'content-type': 'application/json'}, body: JSON.stringify({sql: 'SELECT 1', database: 'shop'})})).status).toBe(201)
+        expect((await (await app.request(`${base}/q1`)).json()).rows).toEqual([['1']])
+        expect((await app.request(base)).status).toBe(200)
+        expect((await app.request(`${base}/q1/stop`, {method: 'POST'})).status).toBe(200)
+        expect((await (await app.request('/api/clouds/aws/services/query/catalog?database=shop')).json()).databases).toEqual(['shop'])
+        expect(calls).toEqual([['start', 'analysts', 'SELECT 1', 'shop'], ['result', 'analysts', 'q1'], ['list', 'analysts'], ['stop', 'analysts', 'q1'], ['catalog', 'shop']])
+    })
+
     test('creates and deletes catalog tables through the Glue adapter', async () => {
         const calls: unknown[] = []
         const database = {id: 'shop', name: 'shop', cloud: 'aws' as const, service: 'datacatalog' as const, type: 'glueDatabase', region: null, createdAt: null, metadata: {}}

packages/api/src/routes/clouds.ts

@@ -5,6 +5,7 @@ import type {
     AutoScalingCapacityInput,
     AccessPointInput,
     CatalogTableInput,
+    QueryInput,
     FileSystemAttachmentInput,
     CertificateRevocationReason,
     CloudProvider,
@@ -557,6 +558,44 @@ export function createCloudRoutes(injectedService?: CloudProxyService) {
         })
     })
 
+    app.get('/:cloud/services/query/catalog', async (c) => {
+        const cloud = c.req.param('cloud') as CloudProvider
+        if (!isCloudProvider(cloud)) return c.json({error: 'Unknown cloud'}, 404)
+
+        return withRuntime(c, async () => c.json(await svc(c).describeQueryCatalog(cloud, c.req.query('database') || undefined)))
+    })
+
+    app.get('/:cloud/services/query/resources/:id/queries', async (c) => {
+        const cloud = c.req.param('cloud') as CloudProvider
+        if (!isCloudProvider(cloud)) return c.json({error: 'Unknown cloud'}, 404)
+
+        return withRuntime(c, async () => c.json(await svc(c).listQueries(cloud, c.req.param('id'))))
+    })
+
+    app.post('/:cloud/services/query/resources/:id/queries', async (c) => {
+        const cloud = c.req.param('cloud') as CloudProvider
+        if (!isCloudProvider(cloud)) return c.json({error: 'Unknown cloud'}, 404)
+
+        return withRuntime(c, async () => c.json(await svc(c).startQuery(cloud, c.req.param('id'), await c.req.json<QueryInput>()), 201))
+    })
+
+    app.get('/:cloud/services/query/resources/:id/queries/:queryId', async (c) => {
+        const cloud = c.req.param('cloud') as CloudProvider
+        if (!isCloudProvider(cloud)) return c.json({error: 'Unknown cloud'}, 404)
+
+        return withRuntime(c, async () => c.json(await svc(c).getQueryResult(cloud, c.req.param('id'), c.req.param('queryId'))))
+    })
+
+    app.post('/:cloud/services/query/resources/:id/queries/:queryId/stop', async (c) => {
+        const cloud = c.req.param('cloud') as CloudProvider
+        if (!isCloudProvider(cloud)) return c.json({error: 'Unknown cloud'}, 404)
+
+        return withRuntime(c, async () => {
+            await svc(c).stopQuery(cloud, c.req.param('id'), c.req.param('queryId'))
+            return c.json({ok: true})
+        })
+    })
+
     app.post('/:cloud/services/datacatalog/resources/:id/tables', async (c) => {
         const cloud = c.req.param('cloud') as CloudProvider
         if (!isCloudProvider(cloud)) return c.json({error: 'Unknown cloud'}, 404)

packages/api/src/service/CloudProxyService.ts

@@ -96,6 +96,10 @@ import type {
     AutoScalingCapacityInput,
     AccessPointInput,
     CatalogTableInput,
+    QueryCatalog,
+    QueryExecutionSummary,
+    QueryInput,
+    QueryResult,
     FileSystemAttachmentInput,
     CertificatePem,
     CertificateRevocationReason,
@@ -967,6 +971,36 @@ export class CloudProxyService {
         return adapter.revokeCertificate(certificateId, reason)
     }
 
+    async startQuery(cloud: CloudProvider, workGroup: string, input: QueryInput): Promise<QueryExecutionSummary> {
+        const adapter = this.requireAdapter(cloud, 'query')
+        if (!adapter.startQuery) throw new NotSupportedError(`Running queries is not supported for ${cloud}/query`)
+        return adapter.startQuery(workGroup, input)
+    }
+
+    async getQueryResult(cloud: CloudProvider, workGroup: string, queryId: string): Promise<QueryResult> {
+        const adapter = this.requireAdapter(cloud, 'query')
+        if (!adapter.getQueryResult) throw new NotSupportedError(`Query results are not supported for ${cloud}/query`)
+        return adapter.getQueryResult(workGroup, queryId)
+    }
+
+    async stopQuery(cloud: CloudProvider, workGroup: string, queryId: string): Promise<void> {
+        const adapter = this.requireAdapter(cloud, 'query')
+        if (!adapter.stopQuery) throw new NotSupportedError(`Cancelling queries is not supported for ${cloud}/query`)
+        return adapter.stopQuery(workGroup, queryId)
+    }
+
+    async listQueries(cloud: CloudProvider, workGroup: string): Promise<QueryExecutionSummary[]> {
+        const adapter = this.requireAdapter(cloud, 'query')
+        if (!adapter.listQueries) throw new NotSupportedError(`Query history is not supported for ${cloud}/query`)
+        return adapter.listQueries(workGroup)
+    }
+
+    async describeQueryCatalog(cloud: CloudProvider, database?: string): Promise<QueryCatalog> {
+        const adapter = this.requireAdapter(cloud, 'query')
+        if (!adapter.describeQueryCatalog) throw new NotSupportedError(`Browsing the catalog is not supported for ${cloud}/query`)
+        return adapter.describeQueryCatalog(database)
+    }
+
     async createCatalogTable(cloud: CloudProvider, databaseName: string, input: CatalogTableInput): Promise<CloudResource> {
         const adapter = this.requireAdapter(cloud, 'datacatalog')
         if (!adapter.createCatalogTable) throw new NotSupportedError(`Creating tables is not supported for ${cloud}/datacatalog`)