SAP HANA 连接器¶

Dosi 使用 hana dialect 生成 SAP HANA Database SQL，通过 SAP 官方 HDBODBC 客户端执行。Rust ODBC 封装来自社区；数据库客户端及协议实现来自 SAP。 Dosi 不需要 Java、JDBC 桥接或 Python SDK。

指标和明细查询会为最终输出别名添加双引号，确保结果列名（包括大小写）与语义绑定一致。内部 CTE 别名及物理标识符保持 HANA 原有的解析规则。Datus compose 派生指标支持使用标准 NULLIF 表达式。

安装客户端¶

在运行 Dosi 的机器上安装 SAP HANA Client ODBC 包。客户端的系统和 CPU 架构必须与 Dosi 可执行文件或 Python 进程一致。 SAP 提供 Linux x86-64、macOS ARM64 和 macOS x86-64 包；在 ARM64 Mac 上使用 Intel Python 时，需要 Intel 客户端。数据库服务器可以部署在其他机器上。

通过 odbc_driver 或环境变量 DOSI_HANA_ODBC_DRIVER 指定客户端库的绝对路径： Linux 为 libodbcHDB.so，macOS 为 libodbcHDB.dylib，也可以使用已注册的 HDBODBC 驱动名。Unix 构建中包含 ODBC 管理器；SAP 客户端单独安装，首次连接 HANA 时才加载。离线 SQL 编译及其他数据库连接器不依赖 SAP 安装。

连接配置¶

datasources:
  hana:
    type: hana
    host: hana.internal
    port: 39041
    username: ANALYTICS_READER
    password: ${HANA_PASSWORD}
    database: HXE
    schema: ANALYTICS
    odbc_driver: /opt/sap/hdbclient/libodbcHDB.so
    encrypt: true
    ssl_validate_certificate: true
    ssl_trust_store: /etc/dosi/hana-ca.pem
    ssl_host_name_in_certificate: hana.internal

配置同样适用于 Datus agent.yml 和 Python 的运行时 connections 映射。 database 是连接的 tenant，不进入 SQL 命名空间；对象只使用 schema.table。未限定对象使用配置的 schema，未配置时使用登录用户的默认 schema。带双引号的标识符保留大小写。

配置项	默认值	含义
`port`	`39041`	tenant 的 SQL 端口，HANA Cloud 通常需要显式设置为 `443`。
`database`	未设置	可选 tenant 连接目标，不是 SQL catalog。
`schema`	用户默认值	会话 schema；user-store 认证时必填。
`userkey`	未设置	SAP `hdbuserstore` key，与用户名、密码互斥。
`odbc_driver`	环境变量 / `HDBODBC`	SAP 驱动绝对路径或已注册的驱动名。
`encrypt`	`true`	启用加密连接。
`ssl_validate_certificate`	`true`	校验服务器证书。
`ssl_trust_store`	客户端默认值	CA 信任库路径，传给 SAP 客户端。
`ssl_host_name_in_certificate`	连接主机名	预期证书主机名，连接隧道时可以显式指定。
`communication_timeout_seconds`	`60`	登录和通信超时。
`timeout_seconds`	`30`	ODBC 语句超时。
`max_result_rows`	`10000`	结果行数上限。
`max_result_bytes`	`16777216`	列名及单元格 UTF-8 字节预算，NULL 按一个字节计。

超时和预算必须为正数。超过预算直接报错并丢弃结果，不返回截断答案。 LOB 按有限大小分块读取；二进制值返回小写十六进制文本；超过 f64 精确表示范围的精确数值保留文本，近似数值保持数值类型。时间戳保留有效小数精度。

TLS 和证书校验默认开启。自签名测试环境需要提供 CA；连接失败后不会自动关闭 TLS 或证书校验重试。

SAP secure user store¶

在 Dosi 运行机器上，以相同 OS 用户通过 SAP hdbuserstore 创建 key，然后去掉 username、password，改为：

datasources:
  hana:
    type: hana
    userkey: ANALYTICS_READONLY
    schema: ANALYTICS
    odbc_driver: /opt/sap/hdbclient/libodbcHDB.so
    encrypt: true
    ssl_validate_certificate: true

使用 SAP ODBC 的 serverNode=@KEY 约定，endpoint 和凭据来自 secure store。 Dosi 不负责创建、复制或轮换生产环境的 store。hdbuserstore 工具位于完整 SAP HANA Client 中，参见 SAP 文档。

SQL 和功能边界¶

支持原生模型表达式、指标、普通分组、过滤、排序、limit、明细查询，以及复用现有的行结果到 Arrow 转换。日期表达式可以使用已验证的 HANA 原生函数，例如 ADD_DAYS、ADD_MONTHS、DAYS_BETWEEN、SECONDS_BETWEEN、TO_DATE、 TO_VARCHAR，模型表达式标记为 HANA。

通用模型支持日、周、月、季度、年粒度、D-FORMAT 时间解析、日历偏移，以及基于这些能力的时间比较。周从周一开始。unit-first DATEDIFF 支持日、时、分、秒的边界计数；原生 DAYS_BETWEEN 仍按完整经过天数计算。通用平均值和统计输入使用 HANA 浮点十进制（TO_DECIMAL，至多 34 位有效数字），避免无条件转为二进制 DOUBLE；显式浮点转换保留所请求的类型。这不保证任意 DECIMAL(38,s) 输入的聚合都无损。

统计窗口、CUME_DIST、NTH_VALUE 使用原生函数。协方差窗口用相同窗口帧上的相关系数和标准差计算，任一参数为 NULL 的行从配对中排除。累计 RANGE 使用 HANA 隐式的有序窗口，保留相同排序值的 peers；其他显式 RANGE 边界明确拒绝。

生成阶段不支持的能力在发送查询前返回 dialect_unsupported_feature 或现有的 dialect_unsupported_window_function。通用表达式在执行前完成转换，不在执行失败后更换 dialect 重试。标记为 HANA 的原生函数保留其自身语义。

每次执行使用独立连接。批量执行在一个连接上按分号拆分普通 DDL/DML，使用自动提交，不保证原子性，也不解析 SQLScript 块；需要块执行时，应通过底层执行 API 一次发送完整语句。

错误和构建¶

执行错误区分配置、认证、连接、超时、驱动、SQL 拒绝。公开诊断保留 SQLSTATE 和 SAP 错误码，不回显驱动原始 SQL 或连接文本。缺少客户端会返回带安装提示的配置错误。离线编译、dry run 成功不代表真实连接已验证。

源码构建使用 exec-hana、exec-all-lean 或 exec-all。从该源码构建的 Python wheel 通过 exec-all 包含 HANA executor；已发布旧版本需要等待新版本发布，仅安装 SAP 客户端不会为旧 wheel 增加 HANA dialect。