做数据分析的人迟早会遇到一个需求：把连续数值分到几个区间里——年龄分段、消费分层、响应时间分桶。Excel 里拖几下就完事了，到了 PostgreSQL 就得靠 width_bucket()。这个函数本身并不复杂，但围绕它的"轻量级灾难"反复上演：一位数据分析师朋友最近又踩了同样的坑，Kaarel Moppel 决定把经验写下来，免得后人继续在暗处摸索。
width_bucket() 到底怎么算
width_bucket() 的等宽分桶签名是：
width_bucket(operand, low, high, count)
逻辑很直白：把 [low, high) 切成 count 个等宽区间，返回 operand 落在第几个桶。桶编号从 1 开始，到 count 结束。
关键细节——很多人在这里翻车：
- 值 小于 low → 返回 0
- 值 大于等于 high → 返回 count + 1
- 区间是左闭右开
[low, high)，最后一个桶的上界是high，但high本身归入溢出桶
这意味着如果你期望"所有值都在 1 到 N 的桶里"，现实会给你两个额外的溢出桶。
最常见的三个坑
1. 溢出桶被当成正常桶
假设你想把订单金额分成 5档：0–100、100–200、…、400–500。
SELECT width_bucket(amount, 0, 500, 5) AS bucket
FROM orders;
你以为结果范围是 1–5，实际范围是 0–6。amount = 0 → 桶 0，amount = 500 → 桶 6。下游报表如果只处理 1–5，这两类记录就"消失"了——不是丢了，是被你忽略了。
2. 左闭右开的边界陷阱
amount = 100 落在桶 2（100–200），而不是桶 1（0–100）。这符合 [low, high) 的定义，但业务方往往期望"100 块归第一档"。如果你需要左闭右闭的语义，得手动调整 low 或用自定义分桶版本。
3. NULL 和负数的无声处理
operand 为 NULL 时，width_bucket() 返回 NULL，不会报错。如果 low 和 high 的顺序反了（比如 low > high），PostgreSQL 会抛异常。但如果 operand 是负数而你的 low 是 0，负数会安静地归入桶 0——你可能根本没打算让负数出现在数据里。
实操：一份可跑的分桶分析脚本
下面是一段完整的 SQL，演示如何安全地使用 width_bucket() 并处理溢出桶和边界问题。在任意 PostgreSQL 数据库中可直接运行（先建测试数据）：
-- 1. 建一张模拟订单表
CREATE TABLE orders AS
SELECT
generate_series(1, 1000) AS id,
(random() * 600 - 50)::numeric(10,2) AS amount; -- 包含负数和超出上限的值
-- 2. 等宽分桶：5档，0 到 500
SELECT
width_bucket(amount, 0, 500, 5) AS raw_bucket,
count(*)
FROM orders
GROUP BY 1
ORDER BY 1;
你会看到桶 0（负数）和桶 6（>500）都有数据。接下来做"安全版"——把溢出桶映射到边界桶，并给每个桶加上可读标签：
-- 3. 安全分桶 + 标签
SELECT
CASE
WHEN raw_bucket = 0 THEN 1
WHEN raw_bucket > 5 THEN 5
ELSE raw_bucket
END AS safe_bucket,
CASE
WHEN raw_bucket = 0 THEN '[<0) → 合入第1档'
WHEN raw_bucket > 5 THEN '[500+) → 合入第5档'
ELSE format('[%s, %s)',
(raw_bucket - 1) * 100,
raw_bucket * 100)
END AS label,
count(*) AS cnt,
round(avg(amount), 2) AS avg_amount
FROM (
SELECT
id,
amount,
width_bucket(amount, 0, 500, 5) AS raw_bucket
FROM orders
) sub
GROUP BY 1, 2
ORDER BY safe_bucket;
如果业务要求左闭右闭（100 归第一档），可以用 自定义分桶版本：
-- 4. 自定义边界分桶（左闭右闭语义）
SELECT
width_bucket(amount, ARRAY[0, 100, 200, 300, 400, 500]) AS custom_bucket,
count(*)
FROM orders
GROUP BY 1
ORDER BY 1;
注意：数组版本的桶编号从 1 开始，值小于第一个元素归 0，大于等于最后一个元素归 数组长度（这里是 6）。数组版本的分界点是每个元素本身，区间为 [array[i-1], array[i])，所以 amount = 100 归桶 2——和等宽版本一样。要让它归桶 1，把数组第一个元素设成略大于 0 的值（比如 0.01），或者干脆在业务层做映射。
用前检查清单
每次写 width_bucket() 时，过一遍这几项：
| 检查项 | 要做的事 |
|---|---|
| 溢出桶 | 明确桶 0 和桶 count+1 的数据该怎么处理：过滤、合入边界桶、还是单独展示 |
| 边界语义 | 确认业务方对"刚好等于分界点"的预期，和 [low, high) 是否一致 |
| NULL 值 | WHERE operand IS NOT NULL 或在结果中单独计数 NULL |
| 负数 / 异常值 | 如果数据里不该有负数或超大值，先过滤或用 CHECK 约束拦住 |
| low < high | 确保参数顺序正确，否则直接报错，不会静默返回错误结果 |
width_bucket() 本身是个好工具——等宽分桶一行搞定，自定义边界也不麻烦。问题不在函数，在于它返回的 0 号桶和 count+1 号桶太安静了，你不主动处理它们，它们就安静地歪掉你的报表。