在DB2数据库运行过程中，应用程序有时会收到SQLSTATE 01003的返回码。这并不是一个导致语句失败的错误，而是一种警告性质的SQL状态。它明确指向一个现象：在执行标量聚合函数（如SUM、AVG、MAX、MIN）时，参与计算的所有值都是NULL，因此聚合结果也是NULL，数据库认为有必要提醒调用者这一情况。与SQLSTATE 02000（无数据发现）或各类以SQLCODE为负数的真正错误不同，01003允许语句成功完成，只是结果可能不符合业务预期。
一、SQLSTATE 01003的触发原理与标准语义
根据DB2的SQL标准实现，当单列聚合函数作用于一个空集或全为NULL的集合时，数据库引擎不会抛出错误，因为从关系代数角度看，聚合空集本身是合法操作，结果定义为NULL。但为了告知客户端“此处发生了空消”，DB2会设置SQLSTATE为01003，并在SQLCA或JDBC的警告链中记录。这种设计的初衷是防止开发者误以为聚合拿到了有效数值零，而实际上是没有任何有效输入。
以SUM函数为例，如果某张销售记录表中，某分区在查询时间范围内没有任何行，或者对应金额列由于ETL异常全部为NULL，那么SUM(amount)的求值路径会遍历零个非空值。DB2内部聚合器在发现计数为零时，将结果置为NULL并打上01003标记。此时若应用程序用Java的ResultSet.getBigDecimal取值，拿到的是null，同时SQLWarning不为空。理解这一点，就能区分“卖了几块钱”和“根本没有销售记录”的本质不同。
需要注意的是，01003仅针对标量聚合。如果是分组聚合（GROUP BY），每一组若全NULL则对应组结果也是NULL，但DB2通常不会对每一组单独发01003警告，而是在整体层面视实现版本而定。此外，像COUNT(*)这类函数永远返回数字，不会触发01003，因为NULL不参与计数逻辑，这也是为什么排查时常用COUNT(*)验证行数。
二、常见引发01003的业务场景与代码实例
最常见的场景是报表统计中的可选过滤条件。例如用户在前端选择了某个新开的分公司，而该系统刚上线尚未产生交易，后端SQL直接用AVG计算客单价，便会触发警告。另一种情况是左连接之后对右表列聚合，当右表无匹配时，该列在结果集中均为NULL，聚合同样给出01003。下面是一段可能引发该警告的SQL：
SELECT d.dept_name, SUM(e.salary) AS total_salary FROM department d LEFT JOIN employee e ON d.dept_id = e.dept_id WHERE d.dept_id = 999 GROUP BY d.dept_name;
上述语句中，若部门999没有员工，e.salary全为NULL，SUM求得NULL并带01003。在JDBC中，如果不处理警告，日志里会打印“SQLWarning: 01003”，但程序仍可继续。有些ORM框架会把警告当作错误抛出，这就造成了“明明有数据返回却报错”的错觉。因此阅读框架文档、确认其警告策略十分关键。
为消除不必要的警告并让结果更直观，可以用COALESCE把NULL转为0。改写如下：
SELECT d.dept_name, COALESCE(SUM(e.salary), 0) AS total_salary FROM department d LEFT JOIN employee e ON d.dept_id = e.dept_id WHERE d.dept_id = 999 GROUP BY d.dept_name;
使用COALESCE后，聚合结果不再是NULL，DB2不再标记01003。不过这也可能掩盖数据缺失的事实，所以要在业务层明确：零是否等价于无记录。如果业务要求严格区分，则应保留警告或显式用COUNT(e.emp_id)判断。
三、在应用程序中正确捕获与处理01003警告
以Java JDBC为例，执行查询后应通过Statement.getWarnings()或Connection.getWarnings()获取警告链。SQLSTATE可通过SQLWarning.getSQLState()读取，若为"01003"则按业务规则记录日志或忽略。切勿用异常捕获代替警告处理，因为01003不会进入SQLException。下面展示一段处理代码：
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT SUM(amount) FROM orders WHERE create_date < '2020-01-01'");
SQLWarning warn = stmt.getWarnings();
while (warn != null) {
if ("01003".equals(warn.getSQLState())) {
System.out.println("聚合结果为NULL，原因为全部空值");
}
warn = warn.getNextWarning();
}
if (rs.next()) {
BigDecimal sum = rs.getBigDecimal(1);
System.out.println("SUM结果: " + (sum == null ? "无有效数据" : sum));
}
rs.close();
stmt.close();
在存储过程里，也可以用DECLARE CONTINUE HANDLER FOR SQLSTATE '01003'来捕获，但更推荐在过程逻辑中主动用IF total IS NULL THEN判断，因为警告处理器主要用于异常而非提示。对于命令行用户，执行查询后输入LIST WARNINGS或查看db2 ? sqlstate 01003可看到官方说明。
从系统运维角度，如果应用频繁收到01003，往往暗示数据质量或分区策略有问题。比如某张按天分区的表，历史分区被清理后旧查询仍带入旧日期条件，便会大量触发。此时应优化查询参数或调整保留策略，而不是简单屏蔽警告。将01003视作数据健康的一个信号，比单纯写防御性SQL更有长期价值。
四、01003与其他相似状态的对比及误区澄清
不少开发者把01003和02000（无行）混为一谈。02000通常出现在游标FETCH无数据时，或SELECT INTO未找到行，而01003专指聚合消空。还有人以为只有SUM会触发，实际上AVG、STDDEV等依赖非空集合的函数都会，但MAX和MIN在全集NULL时也返回NULL并给01003，这点容易被忽略。下面的表格简要对比：
| SQLSTATE | 含义 | 是否终止语句 | 典型函数 |
|---|---|---|---|
| 01003 | 聚合消去空值 | 否 | SUM, AVG, MAX, MIN |
| 02000 | 无数据 | 否（但游标结束） | FETCH, SELECT INTO |
| 01503 | 列被截断 | 否 | 赋值给较短变量 |
澄清一个误区：有些文档说“01003表示除零”，这是错误的，除零在DB2中通常是SQLCODE -802或状态22012。01003永远关联聚合空输入。另外，在UNION或JOIN中产生的NULL不会单独触发01003，只有顶层标量聚合才会。明确这些边界，才能在排查告警时快速定位，而不是盲目修改SQL。
最后，若使用CLI或嵌入式SQL，SQLCODE为+304也可能伴随01003，表示宿主变量被赋NULL。此时应在C程序中检查指示变量，而非仅看返回码。跨语言开发中统一对01003的认知，能显著降低联调成本。
DB2SQLSTATE_01003聚合函数警告修改时间：2026-08-16 17:04:54