21000 — 基数冲突

速览 {#at-a-glance}

21000 表示操作得到的行数不符合基数契约。最常见的是标量子查询返回多行；它与 23505 不同，不要求存在唯一索引冲突。

含义 {#meaning}

把标量子查询当作表达式时，最多只能返回一行；执行器看到第二行就报告 21000，零行则产生 NULL。同一错误也用于命令级基数冲突：ON CONFLICT DO UPDATE 的多个候选行可能再次命中同一目标行，MERGE 的多个源行也可能匹配同一目标行；这些路径有各自的报文和提示。

诊断 {#diagnosis}

先保存 sqlstate、message_primary、hint 和语句上下文。根据业务键增加确定性谓词，或在确实要把多行合成一个值时使用聚合；不要随意加 LIMIT 1，否则可能静默选择任意行。对 ON CONFLICT，按仲裁索引或唯一键去重候选源行；对 MERGE，保证源到目标的匹配对每个目标至多一行。应检查实际源行和键映射，不能把它泛化成普通重复键错误。

处理 {#response}

显式事务中先回滚失败事务，再执行修正后的完整操作。ON CONFLICT 或 MERGE 的多行来源必须先确定基数；原样重放同一批数据仍会重复触发确定性的冲突。自动提交下本案例错误后连接仍为 IDLE，这不能替代外层事务或 PL/pgSQL 处理器的边界。

实测诊断 {#messages}

18.6 (Homebrew) / latest：SQLSTATE 21000；primary more than one row returned by a subquery used as an expression；status_after_error IDLE。 10.21 (Debian 10.21-1.pgdg90+1) / pg10：SQLSTATE 21000；primary more than one row returned by a subquery used as an expression；status_after_error IDLE。

代表案例 {#case}

运行器从 verify/cases/21000/snippets.json（SHA-256 6d820e94518ffca97f407956fdc2df104d47b14263d3117ff59dbc4409774dc2）读取下列片段，并为临时 schema 替换表名；完整 setup、断言与清理见 案例导出。

-- create
CREATE TABLE source_rows(id integer PRIMARY KEY);
-- seed
INSERT INTO source_rows VALUES (1), (2);
-- trigger
SELECT (SELECT id FROM source_rows ORDER BY id) AS only_id;
-- valid
SELECT (SELECT id FROM source_rows WHERE id = 1) AS only_id;

本案例对应的 SQLSTATE、诊断、事务状态和修复断言均来自上述共享 registry；结构化证据 · 案例导出。

作者证据 ID：identity, scalar-subquery, dml-conflict, runtime。选定运行记录：runtime.21000-batch1-latest-20260909.latest, runtime.21000-batch1-pg10-20260909.pg10。

版本与边界 {#versions}

锁定目录在 7.4 已观察到该条件，并在列出的 9.0–18.6 正式快照中均存在。固定源码证据确认 18.6 的标量子查询、ON CONFLICT 和 MERGE 路径；选定运行只覆盖 18.6 与 10.21 的标量子查询。

相关 {#related}

对比 23505 唯一约束冲突、23503 外键冲突 和 23000 完整性约束总类。

来源 {#sources}

• src.errcodes.18.6 (SHA-256 6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba)
• src.calls.REL_18_6 (SHA-256 9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf)
• src.nodeSubplan.18.6 (SHA-256 c356a9812691f875974c1f476efa987015ba19e70a4be833a43b692f3554dc47)
• src.nodeModifyTable.18.6 (SHA-256 0fc3cb180b3443f216142954e43d8ed5f84713d75094ce8cd2785ad8f604bd68)
• doc.syntax.18.6 (SHA-256 449b0c500fccca068d0f8a1db2a5ebb5430eb83e33f12c6cb310a01a7437b635) · 官方文档

来源

• 上游源码 doc/src/sgml/syntax.sgml 第 2232–2238 行 REL_18_6 724edf9bd 449b0c50
• 上游源码 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
• 上游源码 src/backend/executor/nodeModifyTable.c 第 2804–2809 行 REL_18_6 724edf9bd 0fc3cb18
• 上游源码 src/backend/executor/nodeSubplan.c 第 296–298 行 REL_18_6 724edf9bd c356a981
• 核验材料 raw/calls/REL_18_6.jsonl 9ee8a0e8