跳转至

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 验收

维护者的 fixture 回归由私有仓库 datus-db-testkit 负责。Athena 环境实现准备隔离数据,由 testkit 中的 Rust runner 回放共享指标与 select 用例, 最后清理本轮资源。每周云端回归使用同一流程。连接 profile 和 AWS 测试配置也在 testkit 维护;Dosi 不再包含 Athena seed 或环境构建脚本。

本地配置好 testkit 和 adapter 工作区后,可以运行:

../datus-db-testkit/.venv/bin/python -m datus_db_testkit.development \
  --root ../datus-db-testkit --dosi-source . \
  --adapters-source ../datus-db-adapters --engine athena

产品层的真实 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