# 规划器也在估算 > 读取规划器使用的统计信息，找出出错的估算，并用 ANALYZE、扩展统计信息或更好的查询修复它，而不是依赖提示。 --- LLMS 索引： [llms.txt](/llms.txt) --- 下面是一条查询某个账户内某个项目的 85 个事件的语句： ```sql select * from events where account_id = 696 and project_id = 4242; ``` 规划器预计会得到一行： ```text Bitmap Heap Scan on events (cost=28.78..32.80 rows=1 width=112) (actual time=0.250..0.696 rows=85.00 loops=1) ``` 估算差了 85 倍，但没有任何东西坏了。这张表一分钟前才做过分析，规划器使用的每个数字都是正确的。它做了一个不适用于这份数据的假设；除非你告诉它实际情况，否则它会一直这样假设下去。 大多数糟糕的计划都从这样的差距开始。规划器不了解你的数据。它根据一份很小的数据摘要进行估算，而且通常估得不错。弄清它知道什么、又假设了什么之后，“规划器怎么这么蠢”就会变成一个可以指出并修复的具体估算错误。 ## 规划器是代价计算器 {#the-planner-is-a-cost-calculator} Postgres 不会尝试执行各种计划来看看哪个最快。它会列出候选方案（扫描每张表的所有方式、所有连接方法和连接顺序），用公式为每个方案计算代价，然后运行代价最低的那个。一个计划的代价取决于两件事：每一步会产生**多少行**，这来自统计信息；每个工作单位的**代价是多少**，这来自少数几个设置。 行数估得准，哪怕代价估得粗糙，通常也能得到好计划。行数估错了，单靠调整代价无法弥补。所以本章讨论的是估算。规划器如何把这些估算变成扫描、连接和连接顺序的选择，见[代价最低的计划胜出](/21-plans/#basics-chapter-21)。 ### 每个代价都相对于一次顺序页读取 {#every-price-is-relative-to-one-sequential-page} 代价是以一个数为基准的任意单位：顺序读取一个 8 KB 页的代价是 `seq_page_cost = 1.0`。其他一切都相对于它计算代价： | 参数 | 默认值 | 它计算的代价 | |---|---|---| | `seq_page_cost` | 1.0 | 顺序扫描时读取一个页 | | `random_page_cost` | 4.0 | 无序获取一个页（索引扫描） | | `cpu_tuple_cost` | 0.01 | 处理一行 | | `cpu_index_tuple_cost` | 0.005 | 处理一个索引项 | | `cpu_operator_cost` | 0.0025 | 计算一个运算符或函数调用 | **Table 20-1.** 每个代价都相对于一次顺序页读取 一次顺序扫描的代价，是页数乘以 `seq_page_cost`，加上行数乘以 `cpu_tuple_cost`，再加上每行每个过滤条件对应的一个 `cpu_operator_cost`（[精确到分](/19-explain/#cost-is-a-guess-in-made-up-units)）。公式本身不是难点。注意其中大部分项目都乘以什么：行数。真正的工作量就在这里。 `random_page_cost` 是一个比值，不是测量值。默认值 4.0 源自旋转磁盘；使用 SSD 的系统通常设为 1.1 到 2（[random_page_cost 假定使用旋转磁盘](/30-configuration/#random_page_cost-assumes-spinning-disks)）。而 `effective_cache_size` 根本不是代价：它告诉规划器可能有多少数据已经缓存在内存中（[effective_cache_size 是提示，不是内存](/05-buffers/#effective_cache_size-is-a-hint-not-memory)）。 > [!WARNING] 先调整估算，再调整代价 > > 计划看起来不对时，人们的本能反应是不断微调 `random_page_cost`，直到计划翻转。若把它设为全服务器范围，这样做只是通过让规划器以另一种方式误判其他每条查询来修好一条查询，其中一些查询还会翻到足以拖垮服务器的计划。先修正估算。只有为了描述硬件特性，才应一次性为整台服务器调整代价参数。 ## pg_stats 是规划器看到的全部信息 {#pg_stats-is-the-planners-entire-picture} 行数估算来自 `ANALYZE` 保存的统计信息，而 `pg_stats` 视图会按每列一行显示这些信息。对于 `events` 来说（`ANALYZE` 会随机抽样，所以你看到的末位数字会不同）： ```text attname | null_frac | avg_width | n_distinct | correlation ------------+-----------+-----------+------------+---------------- account_id | 0 | 8 | 1000 | 0.0029704524 created_at | 0 | 8 | -1 | 1 id | 0 | 8 | -1 | 1 kind | 0 | 6 | 5 | 0.25737208 payload | 0 | 66 | 40687 | -0.0014929087 project_id | 0 | 8 | 19979 | -0.00024722528 user_id | 0 | 8 | 19979 | -0.00069223094 ``` 这就是规划器看到的一张两百万行表的全部信息： - **`null_frac`**：空值所占的比例。（在 `projects` 中，`archived_at` 的空值比例为 0.80445，因此 `archived_at is null` 的估算值是 80.4%。） - **`avg_width`**：每个值的平均字节数，用来估算哈希和排序的大小。 - **`n_distinct`**：不同值的数量。正数表示数量（`kind` 有 5 个）；负数表示行数的比例，`-1` 表示每个值都唯一。 - **`most_common_vals`** 和 **`most_common_freqs`**：高频值列表（MCV 列表），也就是出现频率最高的值及其出现频率。 - **`histogram_bounds`**：其他值，被切分成 100 个行数大致相等的桶。 - **`correlation`**：物理行顺序与列值顺序的接近程度，范围从 -1 到 1。它会影响索引扫描的代价（[相关性会影响索引扫描的代价](/21-plans/#correlation-prices-the-index-scan)）。 下面是 `kind` 的高频值列表： ```text -[ RECORD 1 ]-----+------------------------------------------------- most_common_vals | {build,deploy,login,comment,alert} most_common_freqs | {0.3713,0.25146666,0.12726666,0.12716667,0.1228} ``` 因此，`where kind = 'deploy'` 的估算值是 `rows=502927`：即这张表 1,999,974 行的 0.25146666 倍。高频值列表中的值使用它自己的频率；其他值则平均分摊剩余部分。范围条件会统计直方图桶：`created_at` 上 2026 年 9 月 1 日所在的一周估计有 36,613 行，实际为 38,356 行。 > [!DETAILS]- 深入阅读：手算规划器的算术 > > 每个行数估算都是一个基于 `pg_stats` 的公式，你可以自行核对。以 `events.account_id` 为例（有 1,000 个不同值；这次抽样恰好把六个稍微更繁忙的账户放进了高频值列表，它们的频率之和为 0.0091666665）： > > ```text > equality, value in the MCV list (account 393): > 0.0015666666 x 2,000,034 = 3,133.4 -> rows=3133 > > equality, any other value (account 42): > selectivity = (1 - sum(MCV freqs) - null_frac) > / (n_distinct - number of MCVs) > = (1 - 0.0091666665) / (1000 - 6) = 0.00099681 > 0.00099681 x 2,000,034 = 1,993.7 -> rows=1994 > ``` > > 第二个公式解释了为什么数据倾斜的列会带来问题。如果几百个中等规模的租户各自占有 0.5% 的行数，100 个 MCV 槽位就容不下它们，剩下的每个租户都会被估算为约 2,000 行，而不是 10,000 行。提高统计目标（见下一节）可以让大租户各自拥有一个条目。 > > 范围条件会找到两端所在的直方图桶，并假设桶内的值均匀分布。对于 `created_at >= '2026-04-01' and created_at < '2026-04-08'`： > > ```text > frac(2026-04-01) = (48 + 0.4176) / 100 = 0.484176 > frac(2026-04-08) = (50 + 0.3391) / 100 = 0.503391 > rows = (0.503391 - 0.484176) x 2,000,021 = 38,430 > ``` > > 规划器给出的结果是 38,431（差异来自我们的四舍五入），实际数量是 38,356。没有更好信息时，`=` 连接会把两个输入相乘，再除以较大的 `n_distinct`：events 与 173 个企业账户连接时，估算值为 2,000,000 x 173 / 1,000 = 346,000。它假设企业账户产生的事件数处于平均水平，这和下面的独立性假设相同。 > > > [!EXAMPLE]- 动手验证 · lab `19-planner` > > > > ```sql > > select lab.prove('equality on a non-MCV value: (1 - sum(freqs) - null_frac) / (n_distinct - #MCVs)', > > abs(lab.est_rows(format('select * from events where account_id = %s', > > (select min(g) from generate_series(1, 1000) g where g <> all (mcv)))) > > - round((1 - (select sum(f) from unnest(freqs) f) - null_frac) > > / (n_distinct - cardinality(mcv)) * reltuples)) <= 1) > > from s; > > > > select lab.prove('a one-week range: rows = (frac(b) - frac(a)) x reltuples, from the histogram', > > abs(lab.est_rows(format('select * from events where created_at >= %L and created_at < %L', > > current_setting('plans.week_a'), current_setting('plans.week_b'))) > > - (hist_frac(current_setting('plans.week_b')::timestamptz) > > - hist_frac(current_setting('plans.week_a')::timestamptz)) > > * (select reltuples from pg_class where relname = 'events')) > > < 2); > > ``` > > > > [完整实验脚本](https://www.flagon.io/books/eight-kilobytes/lab/19-planner.sql) > > `pg_stats` 还会提供 `most_common_elems` 和 `elem_count_histogram`，用于数组和 `tsvector` 列；对范围类型，还会提供范围直方图：其他数据形态也是同样的思路。 ## ANALYZE 读取样本，而不是整张表 {#analyze-reads-a-sample-not-the-table} `ANALYZE` 会抽取 `300 x default_statistics_target` 行作为样本。默认目标是 100，因此样本有 30,000 行： ```text INFO: "events": scanned 30000 of 35173 pages, containing 1705877 live rows and 17 dead rows; 30000 rows in sample, 2000027 estimated total rows ``` 统计目标还会把 MCV 列表和直方图分别限制为最多 100 个条目：对大多数列来说足够，但对拥有大量不同值且数据倾斜的列来说太少。如果 `account_id` 有很长的大租户尾部，100 个 MCV 槽位容不下它们，其余值就只能采用平均估算。应按列提高统计目标，而不是全局提高： ```sql alter table events alter column account_id set statistics 1000; analyze events; ``` 现在，`ANALYZE` 会为一个 300,000 行的样本读取全部 35,173 个页，1,000 个账户也都会各自得到一个 MCV 条目。代价是 `ANALYZE` 变慢（在我们的机器上约 2 秒，而不是 0.2 秒），规划也会略微变慢。只有在估算确实有明显错误的地方才使用 500 到 1000，通常是租户 ID 和状态列。如果 `ANALYZE` 持续把 `n_distinct` 估错，可以用 `alter table ... alter column ... set (n_distinct = 20000)` 把它固定下来。 ### 自动清理的分析会漏掉三类变化 {#three-kinds-of-change-slip-past-autovacuums-analyze} [自动清理](/43-glossary/#autovacuum)会在大约 `autovacuum_analyze_threshold + autovacuum_analyze_scale_factor x reltuples` 行发生变化后分析一张表：默认是 50 加上 10%，因此两百万行的表要等到 200,050 行发生变化。以下三种情况会漏过去： - **批量加载。** 规划器使用的是加载前的统计信息，或者根本没有统计信息。每次批量加载或大型回填结束时都运行 `ANALYZE`（[在开门前清理并分析](/27-loading/#vacuum-and-analyze-before-you-open-the-doors)）。 - **不断增长的时间范围。** `ANALYZE` 上次运行是在昨天，而你查询的是“最近一小时”，直方图的末端还没有覆盖新行。Postgres 对有索引的列会部分补偿，但只追加数据的大表需要更低的表级 `autovacuum_analyze_scale_factor`（[大表不该使用默认值](/10-vacuum/#the-defaults-are-wrong-for-big-tables)）。 - **临时表。** 自动清理永远不会处理临时表。在把它和其他表连接之前，先对它运行分析。 PostgreSQL 18 的 `pg_upgrade` 会保留规划器统计信息，消除了过去升级后“要等分析完成才恢复正常速度”的窗口。但它不会保留本章后面讨论的扩展统计信息，因此应随后运行 `vacuumdb --all --analyze-only --missing-stats-only`（18 中新增），只重建这些统计信息。 ## 规划器假设各列彼此独立 {#the-planner-assumes-your-columns-are-independent} 回到开头的查询。规划器从 `pg_stats` 知道两件事：`account_id = 696` 大约匹配 1,000 个值中的 1 个，`project_id = 4242` 大约匹配 20,000 个值中的 1 个。要把它们合并，它会相乘： ```text 2,000,000 x (1 / 1,000) x (1 / 20,000) = 0.1 -> rounded up to 1 row ``` 只有在项目不能告诉你任何账户信息时，相乘才是正确的。但一个项目恰好属于一个账户，所以第二个过滤条件什么也不会排除。正确答案是“约 100 行”。两个列各有一个单列索引时，计划会显示这一点： ```text Bitmap Heap Scan on events (... rows=1 ...) (actual ... rows=85.00 loops=1) -> BitmapAnd (... rows=1 ...) (actual ... rows=0.00 loops=1) -> Bitmap Index Scan on events_project_id_idx (... rows=100 ...) (actual ... rows=85.00 loops=1) -> Bitmap Index Scan on events_account_id_idx (... rows=1990 ...) (actual ... rows=1961.00 loops=1) ``` （`BitmapAnd` 总是报告 0 行：它会合并位图，但从不统计行数。）每个叶节点的估算都很准：项目是 100 对实际 85，账户是 1,990 对实际 1,961。只有合并结果错了。**叶节点正确、组合错误：这就是列相关性的特征。** 这条查询无论怎样都很快。但这个 1 行的估算会传给它上面的每个节点：如果再和其他东西连接，它就会选择[嵌套循环](/43-glossary/#nested-loop)，对 1 行来说很好，对 10,000 行来说却很痛苦。列相关性无处不在：租户和项目、城市和邮政编码、`status` 和 `completed_at`。连接也会继承这个假设。多余的 `and p.account_id = e.account_id` 会让连接估算再除以 1,000（[代价最低的计划胜出](/21-plans/#basics-chapter-21)一开头就展示了这种情况）。 ### 扩展统计信息联合测量多列 {#extended-statistics-measure-columns-together} 让 `ANALYZE` 联合测量这些列： ```sql create statistics events_account_project (dependencies, ndistinct) on account_id, project_id from events; analyze events; ``` ```text -[ RECORD 1 ]---+------------------------ statistics_name | events_account_project attnames | {account_id,project_id} n_distinct | {"2, 3": 19959} dependencies | {"3 => 2": 1.000000} ``` 这就是 `pg_stats_ext`，在 psql 中用 `\x` 可以让它每行显示一列。把 `dependencies` 读作：“第 3 列（`project_id`）以 1.0 的程度决定第 2 列（`account_id`）”：项目每次都能告诉你账户。`n_distinct` 表示这对列有 19,959 种组合，而不是 1,000 x 20,000 种。再次运行开头的查询，估算值为 `rows=100`，实际为 85。 扩展统计信息分为三种，分别对应一种相关性： | 类型 | 修复的问题 | 用于 | |---|---|---| | `dependencies` | 一个列决定另一个列时的等值过滤 | 租户 + 项目、邮政编码 + 城市 | | `ndistinct` | 多列 `GROUP BY` 和 `DISTINCT` 的分组数量 | 相关键上的汇总 | | `mcv` | 部分相关组合上的过滤 | 状态 + 类型、套餐 + 区域 | **Table 20-2.** 扩展统计信息联合测量多列 省略类型列表就会得到全部三种。它们开销很小，但应在发现估算错误的地方添加，而不是为每一对列都添加。 > [!DETAILS]- 深入阅读：ndistinct 和 mcv 统计信息的实测修复效果 > > > [!EXAMPLE]- 动手验证 · lab `19-planner` > > > > ```sql > > select lab.prove( > > 'before extended statistics: estimated 1 row, actual 85', > > (select (p -> 'Plan' ->> 'Plan Rows')::numeric = 1 > > and (p -> 'Plan' ->> 'Actual Rows')::numeric = 85 > > from lab.plan($$ select * from events where account_id = 696 and project_id = 4242 $$) p)); > > > > select lab.prove( > > 'after extended statistics: estimated about 100 rows, actual 85', > > (select (p -> 'Plan' ->> 'Plan Rows')::numeric between 60 and 140 > > and (p -> 'Plan' ->> 'Actual Rows')::numeric = 85 > > from lab.plan($$ select * from events where account_id = 696 and project_id = 4242 $$) p)); > > ``` > > > > [完整实验脚本](https://www.flagon.io/books/eight-kilobytes/lab/19-planner.sql) > > **`ndistinct`** 会修复分组数量。在有它之前，`select account_id, project_id, count(*) from events group by 1, 2` 的计划如下： > > ```text > HashAggregate (cost=188301.60..209833.36 rows=200005 width=24) > (actual time=289.762..290.971 rows=20000.00 loops=1) > Planned Partitions: 4 Batches: 1 Memory Usage: 3097kB > ``` > > 由于不知道有多少对组合，规划器把输入的 10%（200,005 个组）当作估算值，并为它预计会溢出 `work_mem` 的哈希表规划了 4 个磁盘分区。之后：`rows=19959`，没有计划中的溢写，代价只有三分之一。运行时间几乎没变，因为哈希表原本就能放进内存；但在更大的查询中，把分组数量高估 10 倍会让聚合改用排序，或使上方第三层的连接选择错误的一侧来建立哈希表。 > > **`mcv`** 处理部分相关的情况，也就是一列只在大多数情况下能预测另一列。在一份 `events` 的副本中，`status` 在 95% 的告警中为 `failed`，其他类型的事件则只有 5% 为此状态；单独相乘会在两个方向上都估错：失败告警估计为 42,822（实际 237,213，低估 5.5 倍），失败构建估计为 123,067（实际 37,336，高估 3.3 倍）。执行 `create statistics event_outcomes_kind_status (mcv) on kind, status from event_outcomes` 后，两者的估算误差都落在 10% 以内。存储的列表说明了原因： > > ```text > values | frequency | base_frequency > ------------------+-----------------------+---------------------- > {alert,failed} | 0.11763333333333334 | 0.020256466666666667 > ... > ``` > > `frequency` 是样本看到的频率；`base_frequency` 是按每列频率相乘后预测的频率。两者相差接近 6 倍时，独立性假设就严重错误。 > > > [!EXAMPLE]- 动手验证 · lab `19-planner` > > > > ```sql > > select lab.prove( > > 'before extended statistics: GROUP BY over both columns is estimated at about 200,000 groups, actual 20,000', > > (select (p -> 'Plan' ->> 'Plan Rows')::numeric between 150000 and 250000 > > and (p -> 'Plan' ->> 'Actual Rows')::numeric = 20000 > > from lab.plan($$ select account_id, project_id, count(*) from events group by 1, 2 $$) p)); > > > > select lab.prove( > > 'after extended statistics: the GROUP BY estimate is within 10% of the 20,000 actual groups', > > (select (p -> 'Plan' ->> 'Plan Rows')::numeric between 18000 and 22000 > > from lab.plan($$ select account_id, project_id, count(*) from events group by 1, 2 $$) p)); > > > > select lab.prove( > > 'before MCV statistics: failed alerts are underestimated more than 4x', > > (select (n ->> 'Actual Rows')::numeric / (n ->> 'Plan Rows')::numeric > 4 > > from lab.plan($$ select count(*) from event_outcomes > > where kind = 'alert' and status = 'failed' $$) p, > > lab.find_node(p -> 'Plan', 'Seq Scan') n)); > > > > create statistics event_outcomes_kind_status (mcv) on kind, status from event_outcomes; > > analyze event_outcomes; > > > > select lab.prove( > > 'after MCV statistics: both estimates land close to the actual counts', > > (select bool_and((n ->> 'Plan Rows')::numeric / (n ->> 'Actual Rows')::numeric between 0.8 and 1.25) > > from (values ('alert'), ('build')) k(kind), > > lab.plan(format($$ select count(*) from event_outcomes > > where kind = %L and status = 'failed' $$, k.kind)) p, > > lab.find_node(p -> 'Plan', 'Seq Scan') n)); > > ``` > > > > [完整实验脚本](https://www.flagon.io/books/eight-kilobytes/lab/19-planner.sql) > [!TIP] 如何寻找候选列 > > 在估算出错的节点上，如果它同时过滤同一张表的两列或更多列，而每列单独的估算都没问题，那就是存在列相关性：只对这几列创建统计信息，运行分析，再次检查。 ## 函数会隐藏你的统计信息 {#functions-hide-your-statistics} 统计信息按列保存。把一列包在函数里，规划器就没有可查的信息，只能退回到源代码中的常量：等值条件使用整张表的 0.5%，范围条件使用 33%。 ```text Seq Scan on events (cost=0.00..65173.71 rows=10000 width=111) Filter: ((payload ->> 'status'::text) = 'failed'::text) ``` 10,000 行是两百万行的 0.5%；实际数量为 500,420，是估算值的 50 倍。`lower(kind) = 'deploy'` 得到相同的 10,000 行（实际为 499,992），而 `(payload->>'duration_ms')::int > 4000` 会得到固定的三分之一，即 666,682 行（实际为 400,064）。这些数字和你的数据根本无关。 > [!DETAILS]- 深入阅读：证明回退常量 > > 这些常量是规划器 [selfuncs.h](https://github.com/postgres/postgres/blob/master/src/include/utils/selfuncs.h) 中的 `DEFAULT_EQ_SEL`（0.005）和 `DEFAULT_INEQ_SEL`（三分之一），旁边还有几个用于 `like`、范围和布尔值的常量。计划的代价也能暴露这个表达式：65,173.71 是普通扫描的 60,173，再加上每行一个 `cpu_operator_cost`，用于执行 `->>` 调用本身。 > > > [!EXAMPLE]- 动手验证 · lab `19-planner` > > > > ```sql > > select lab.prove( > > 'an expression compared with = is estimated at 0.5% of the table', > > (select bool_and(abs((lab.estimate(q) ->> 'Plan Rows')::numeric > > - 0.005 * (select reltuples from pg_class where relname = 'events')) < 10) > > from (values ($$ select * from events where payload ->> 'status' = 'failed' $$), > > ($$ select * from events where lower(kind) = 'deploy' $$)) v(q))); > > > > select lab.prove( > > 'an expression compared with > is estimated at one third of the table', > > abs((lab.estimate($$ select * from events where (payload ->> 'duration_ms')::int > 4000 $$) > > ->> 'Plan Rows')::numeric > > - (select reltuples / 3 from pg_class where relname = 'events')) < 10); > > ``` > > > > [完整实验脚本](https://www.flagon.io/books/eight-kilobytes/lab/19-planner.sql) 你可以用两种方式给规划器提供真实数字。一种是**表达式索引**：`ANALYZE` 会像对待一列一样，收集每个已索引表达式的统计信息。另一种是**表达式统计信息**（PostgreSQL 14+），它收集相同的统计信息，却不需要在每次写入时维护索引： ```sql create statistics events_status_stats on (payload ->> 'status') from events; analyze events; ``` 现在，第一个查询的估算值是 500,670 行，实际为 500,420 行。[比较估计行数和实际行数](/19-explain/#compare-estimated-and-actual-rows)展示了这个修复如何把糟糕的嵌套循环变成哈希连接。（如果一个 jsonb 字段需要统计信息，应问问它是不是应该成为真正的列。） ### FROM 中的函数默认估算为 1,000 行 {#a-function-in-from-is-guessed-at-1000-rows} 除非规划器能够看穿函数内部，否则 `FROM` 中的函数就是一个黑盒，估算为 1,000 行： ```text Function Scan on recent_projects_plpgsql (cost=0.25..10.25 rows=1000 width=72) ``` 这是一个返回某个账户最近项目的 PL/pgSQL 函数。若它是单语句的 `language sql` 函数，规划器会把函数体内联进去，统计信息也一并可见：`Seq Scan on projects` 的估算值为 1 行。无法内联时，应声明一个符合实际的估算值：`alter function recent_projects_plpgsql(bigint) rows 5`。什么会阻止内联，以及易变性向规划器作出什么保证，见[易变性是给规划器的承诺](/24-functions/#volatility-is-a-promise-to-the-planner)。 > [!DETAILS]- 深入阅读：函数的两个版本 > > ```sql > create function recent_projects_plpgsql(acct bigint) returns setof projects > language plpgsql stable as $$ > begin > return query > select * from projects > where account_id = acct and created_at > now() - interval '30 days'; > end > $$; > > create function recent_projects(acct bigint) returns setof projects > language sql stable as $$ > select * from projects > where account_id = acct and created_at > now() - interval '30 days' > $$; > ``` > > ```text > Seq Scan on projects (cost=0.00..591.00 rows=1 width=53) > Filter: ((account_id = '42'::bigint) AND (created_at > (now() - ...))) > ``` > > 这就是 `explain select * from recent_projects(42)` 的结果：函数体被内联了。像 `generate_series` 这样的内置函数带有支持函数，当参数是常量时可以计算出实际数量（结果为 `rows=50`，对应 `generate_series(1, 50)`）。`COST` 以 `cpu_operator_cost` 为单位计算一次调用的代价；在 `WHERE` 子句中，规划器会先计算代价更低的条件。 ## 预备语句运行五次后切换计划 {#prepared-statements-switch-plans-after-five-runs} 大多数驱动和 ORM 都使用预备语句：解析一次，执行多次。前五次执行都会获得一个**定制计划**，根据实际值构建。从第六次开始，Postgres 还会构建一个参数未知的**通用计划**；如果它看起来不比定制计划的平均代价更高，Postgres 就会永久切换到通用计划并停止规划。对于每秒执行数千次的短查询，这样省下的规划开销确实可观。 危险在于数据倾斜：通用计划看不到具体值，只能按平均值规划。设想 `latest($1)`，它查询某种类型最新的 10 个事件；`events (kind)` 和 `events (created_at)` 上都有索引，而一种罕见的新类型 `incident` 有 20 行，且都来自十个月前。定制计划会随值适配：查询 `incident` 时，通过 `kind` 索引取出 20 行再排序（23 个页）；查询 `build` 时，反向遍历 `created_at` 索引，找到 10 行后停止（5 个页）。 像应用一样再执行几次，第六次执行就会切换到通用计划。此时有人打开 incident 事件页面： ```text Limit (cost=0.43..2.73 rows=10 width=16) (actual time=284.639..291.002 rows=10.00 loops=1) Buffers: shared hit=4691 read=29845 written=7425 -> Index Scan Backward using events_created_at_idx on events (cost=0.43..92124.34 rows=399999 width=16) (actual time=284.638..290.994 rows=10.00 loops=1) Filter: (kind = $1) Rows Removed by Filter: 1698631 ``` 通用计划假定 `kind = $1` 匹配整张表的五分之一（即 1 除以 `n_distinct`），因此它认为反向遍历 `created_at` 几乎立刻就能找到 10 行。实际上，它遍历了 170 万行和 34,536 个页，才找到十个月前的 incident；定制计划只访问了 23 个页：两者相差 1,500 倍，完全由计划缓存造成。 `Filter: (kind = $1)` 中使用 `$1` 而不是字面值，就是识别通用计划的方法。 `plan_cache_mode` 控制这一行为：`auto`（默认值）、`force_custom_plan` 或 `force_generic_plan`。对于数据倾斜列上的查询，可以按角色、函数或会话设置 `force_custom_plan`；规划只需几分之一毫秒，属于便宜的保险措施，它能让 incident 事件查询回到 23 个页。高频且分布均匀的查找则保持 `auto`。PL/pgSQL 在函数内部也会以同样方式缓存计划（[PL/pgSQL 按会话缓存计划](/24-functions/#plpgsql-caches-plans-per-session)）。 > [!WARNING] 只在生产环境变慢的查询 > > 在 psql 中粘贴执行很快，从应用中执行却很慢？先怀疑通用计划。psql 发送的是字面值，所以总会得到定制计划；你的驱动发送的是参数。用 `PREPARE` 和六次 `EXECUTE` 重现它，或者在会话中执行 `set plan_cache_mode = force_generic_plan`。在 PostgreSQL 16+ 中，`explain (generic_plan)` 会接收原样带有 `$1` 占位符的查询，直接显示通用计划。 > [!DETAILS]- 深入阅读：实验设置，以及通用计划为何猜成五分之一 > > ```sql > prepare latest(text) as > select id, created_at from events > where kind = $1 > order by created_at desc > limit 10; > > insert into events (account_id, project_id, user_id, kind, payload, created_at) > select p.account_id, p.id, p.owner_id, 'incident', '{"status": "failed"}', > timestamptz '2026-10-06' - interval '300 days' - g * interval '1 day' > from generate_series(1, 20) g > join projects p on p.id = g * 100; > > create index events_kind_idx on events (kind); > create index events_created_at_idx on events (created_at); > vacuum analyze events; > ``` > > 30,000 行的样本通常会漏掉全部 20 个 incident，因此统计信息会记录 5 种类型（如果样本碰巧抽到一个，则记录 6 种），通用计划把 `kind = $1` 的代价按整张表的五分之一计算：`rows=399999`。下面列出两个定制计划，供参考： > > ```text > -- execute latest('incident') > Limit (cost=8.46..8.46 rows=1 width=16) (actual ... rows=10.00 loops=1) > Buffers: shared hit=20 read=3 > -> Sort (cost=8.46..8.46 rows=1 width=16) (actual ... rows=10.00 loops=1) > -> Index Scan using events_kind_idx on events > (cost=0.43..8.45 rows=1 ...) (actual ... rows=20.00 loops=1) > > -- execute latest('build') > Limit (cost=0.43..1.66 rows=10 width=16) (actual ... rows=10.00 loops=1) > Buffers: shared hit=3 read=2 > -> Index Scan Backward using events_created_at_idx on events > (cost=0.43..92124.34 rows=745065 ...) (actual ... rows=10.00 loops=1) > Rows Removed by Filter: 19 > ``` > > （`generic_plans` 和 `custom_plans` 这两列从 PostgreSQL 14 起才出现在 `pg_prepared_statements` 中。） > > > [!EXAMPLE]- 动手验证 · lab `19-planner` > > > > ```sql > > select lab.prove( > > 'after five executions: five custom plans, no generic plan yet', > > (select (generic_plans, custom_plans) = (0::bigint, 5::bigint) > > from pg_prepared_statements where name = 'latest')); > > > > select lab.prove( > > 'the sixth execution switches to the generic plan', > > (select (generic_plans, custom_plans) = (1::bigint, 5::bigint) > > from pg_prepared_statements where name = 'latest')); > > > > select lab.prove( > > 'the generic plan for incident filters on $1 and reads over 30,000 pages', > > (select lab.find_node(p -> 'Plan', 'Index Scan') ->> 'Filter' = '(kind = $1)' > > and (p -> 'Plan' ->> 'Shared Hit Blocks')::int + (p -> 'Plan' ->> 'Shared Read Blocks')::int > 30000 > > from lab.plan($$ execute latest('incident') $$) p)); > > > > set plan_cache_mode = force_custom_plan; > > > > select lab.prove( > > 'force_custom_plan brings incident back to the kind index and a few dozen pages', > > (select lab.find_node(p -> 'Plan', 'Index Scan') ->> 'Index Name' = 'events_kind_idx' > > and (p -> 'Plan' ->> 'Shared Hit Blocks')::int + (p -> 'Plan' ->> 'Shared Read Blocks')::int < 50 > > from lab.plan($$ execute latest('incident') $$) p)); > > ``` > > > > [完整实验脚本](https://www.flagon.io/books/eight-kilobytes/lab/19-planner.sql) ## 提示会冻结计划；应该修复估算 {#a-hint-freezes-a-plan-fix-the-estimate-instead} Postgres 没有内置的优化器提示：没有 `/*+ INDEX(...) */`，也没有 `FORCE INDEX`（[Postgres 修复估算，而不是接受提示](/11-not-mysql/#postgres-fixes-estimates-instead-of-taking-hints)）。这是有意为之，而且我们认为这样是对的。提示会冻结一个在写下它的那天还正确的计划；随着数据变化，这个计划会悄悄腐化，并掩盖真正的问题：估算错误。 本章介绍的都是替代做法：找到估算出错的节点（[慢查询的方法](/19-explain/#a-method-for-slow-queries)），然后用批量加载后的新统计信息、更好的统计信息、一个[可使用索引的](/22-queries/#keep-the-indexed-column-bare)查询，或更好的索引，修正规划器掌握的信息。给定规划器当时掌握的信息，糟糕的计划往往已经是它能找到的最佳方案。下一章最后会介绍查看规划器拒绝的计划的工具，以及在你确实需要提示的夜晚可以使用的扩展。 ## 本章要点 {#the-short-version} - 错误的行数估算导致大多数糟糕的计划。先修估算，再动代价设置。 - `pg_stats` 是规划器看到的列的全部信息。估算看起来不对时，读取它。 - 对数据倾斜的租户 ID，按列把统计目标提高到 500 到 1000；批量加载后自己运行 `ANALYZE`。 - 规划器把列当作彼此独立来相乘。对于相关列，`create statistics` 把估算从 1 行修正到了 100 行，而实际是 85 行。 - 列上的表达式会得到固定的估算值（等值条件为 0.5%，范围条件为 33%）。为它们创建表达式索引或表达式统计信息。 - 预备语句运行五次后切换到通用计划。数据倾斜时，代价会相差 1,500 倍；把 `plan_cache_mode = force_custom_plan` 限定在角色或函数范围内即可修复。 - Postgres 没有提示。修复估算、统计信息、索引或查询。 ## 延伸阅读 {#further-reading} - [Statistics Used by the Planner](https://www.postgresql.org/docs/18/planner-stats.html)，PostgreSQL 文档。介绍 `ANALYZE` 收集的内容，包括扩展统计信息；配合 [How the Planner Uses Statistics](https://www.postgresql.org/docs/18/planner-stats-details.html) 阅读行数估算算术的完整示例。 - [CREATE STATISTICS](https://www.postgresql.org/docs/18/sql-createstatistics.html)，PostgreSQL 文档。介绍每种扩展统计信息及表达式形式。 - [Query Planning settings](https://www.postgresql.org/docs/18/runtime-config-query.html)，PostgreSQL 文档。介绍代价常量和 `plan_cache_mode`。 - [PREPARE: notes on custom and generic plans](https://www.postgresql.org/docs/18/sql-prepare.html#SQL-PREPARE-NOTES)，PostgreSQL 文档。说明预备语句何时在定制计划和通用计划之间切换的确切规则。 - [How Good Are Query Optimizers, Really?](https://www.vldb.org/pvldb/vol9/p204-leis.pdf)，Leis 等，PVLDB 2015。使用 PostgreSQL 的证据表明，糟糕的基数估算，而不是代价模型，导致了大多数糟糕的计划。 - [OptimizerHintsDiscussion](https://wiki.postgresql.org/wiki/OptimizerHintsDiscussion)，PostgreSQL Wiki。介绍该项目将提示排除在核心之外的理由。