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。
验证连接¶
一次性 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
和执行槽位释放,再通过同一个执行器运行另一条查询: