Amazon Athena 连接器¶

Dosi 使用独立的 athena 方言，通过 AWS Athena API 执行 SQL。需要 SQL engine v3 Workgroup。exec-athena 已包含在完整、精简连接器构建和 Python wheel 中。

除法和 AVG（含窗口平均值）会将输入提升为 DOUBLE，与 DuckDB 参考语义对齐，避免 Athena 按 DECIMAL 输入的小数位数舍入占比和均值，例如两位小数的 30 / 180 被算成 0.17。这些运算返回近似浮点结果。

连接配置¶

原生 Dosi 和 Python datus-athena 使用相同的数据源字段。独立配置使用 datasources:；Datus agent.yml 则将其放在 services: 下。

datasources:
  lake:
    type: athena
    aws:
      region: us-east-1
      profile: analytics
    workgroup: analytics
    catalog: AwsDataCatalog
    database: sales
    query_timeout_seconds: 600
    result_timeout_seconds: 60
    cancel_timeout_seconds: 10
    max_rows: 10000
    max_result_bytes: 16777216

模型的 dataset source 可以写 catalog.database.table、database.table，或由配置中的 database 解析的表名。Athena 没有额外的 schema 层。

参数¶

字段	默认值	含义
`aws.region`	SDK 配置	AWS 区域。
`aws.profile`	SDK 默认凭据链	命名 profile，支持可刷新的 AssumeRole、credential process 等。
`aws.ca_bundle`	SDK 信任根	可选 PEM CA 包，保持证书和主机名校验。
`workgroup`	`primary`	启用的 SQL engine v3 Workgroup。
`catalog`	`AwsDataCatalog`	查询 catalog。
`database`	未设置	未限定表名的默认 database。
`output_location`	未设置	可选 S3 结果前缀，服从 Workgroup 策略。
`timeout_seconds`	`30`	单次 SDK 操作及其重试的预算。
`query_timeout_seconds`	`600`	提交和查询状态轮询预算。
`result_timeout_seconds`	`60`	获取全部结果页的预算。
`cancel_timeout_seconds`	`10`	额外的恢复、取消预算；零表示禁用清理调用。
`poll_interval_seconds`	`1`	状态轮询间隔。
`max_rows`	`10000`	完整结果的最大行数。
`max_result_bytes`	`16777216`	单元格 UTF-8 内容的最大字节数。
`page_size`	`1000`	每个 API 页的行数，范围 1–1000。

兼容平铺的 region、profile_name、ca_bundle；与嵌套配置冲突时直接报错。数据源保存身份选择配置，凭据始终由 SDK provider 获取和刷新。

结果与取消¶

客户 S3 结果和 Athena managed results 都通过 GetQueryResults 获取。 Workgroup 强制配置优先，managed results 可以省略 output_location。结果加密在 Workgroup 配置。

Python、Server 的外层期限同样约束执行。超时会发出取消信号，之后最多使用 cancel_timeout_seconds 的额外清理时间。提交响应不确定时保留原幂等 token 尝试恢复查询 ID。AWS 不可达时，恢复和取消可能无法确认。

JSON 结果和执行错误中的 execution_info 为每条 SQL 保留查询 ID、状态、扫描量、耗时、引擎版本及取消状态。cancellation_requested 表示尝试取消， cancellation_confirmed 需要确认 CANCELLED 终态。 Arrow schema 的 dosi.execution_info 保存相同数组。

结果超过预算时明确失败。超出共享数值表示精度的精确数值保留为十进制文本。行数限制约束返回数据；扫描量上限应配置在 Workgroup。

验证连接¶

dosi query --model model.yaml --metrics revenue --execute --connection lake

一次性 AWS 验收¶

使用 scripts/aws/athena_environment.py create <run-dir> 创建独立的 S3 桶、Glue database、S3/managed results 两个 Workgroup 和限定权限的测试角色。每查询扫描上限为 10 MiB，不创建 EC2 实例或预置计算容量。populate 为每个场景创建 <database>_<场景命名空间> Glue 数据库并上传微型 Parquet 数据，保持原始表名、模型、种子和 DuckDB 期望结果不变；destroy 终止残留查询、删除资源并记录实时删除核查结果。命令使用 AWS CLI 的身份。

完整验收先执行 DuckDB，再执行 Athena；加载或查询失败也会自动回收资源：

uv pip install -r scripts/aws/requirements-athena.txt
cargo build -p dosi-testkit --features exec-athena
python scripts/aws/athena_environment.py run target/athena-acceptance
cargo run -p dosi-testkit -- accept-reports --report target/athena-acceptance/athena.json

运行目录保存两个引擎的 Row/Arrow 回执、数据清单、查询历史及 cleanup-audit.json。进程异常中断后可再次运行 destroy <run-dir> 回收。每周任务复用此流程，使用 --ignore-seals 重跑全部用例。需要配置专用的 DOSI_TEST_ATHENA_AWS_ROLE_ARN 仓库变量，对应的 OIDC 角色须允许管理模板内的一次性资源及场景 Glue 数据库；缺少配置时看板明确记录未执行。不要复用 EC2 runner 角色，也不要将此权限提供给 PR 工作流。

现有 testkit 读取 DOSI_TEST_ATHENA_DATABASE、DOSI_TEST_ATHENA_WORKGROUP 和可选的 DOSI_TEST_ATHENA_CATALOG。准备好独立数据后才设置 DOSI_TEST_ATHENA_FIXTURES_READY=1。testkit 在基础数据库名后附加场景命名空间；执行回执直接对应原始 fixture，无需改写或运行 bootstrap。真实 API 测试需要显式启用：

cargo test -p dosi-exec --no-default-features --features exec-athena \
  --test athena_live -- --ignored

MCP 验收测试会在真实查询进入 RUNNING 后发送协议取消通知，确认 CANCELLED 和执行槽位释放，再通过同一个执行器运行另一条查询：

cargo test -p dosi-server --features exec-athena \
  --test athena_mcp_live -- --ignored --nocapture