首先，必须设法加载 pg_plan_advice 模块。可以通过把 pg_plan_advice 加入 shared_preload_libraries 并重启服务器来在整个系统范围内加载它； 也可以把它加入 session_preload_libraries 并启动一个新会话； 或者使用 LOAD 命令把它加载到单个会话中。

一旦加载了 pg_plan_advice 模块， EXPLAIN 就会支持 PLAN_ADVICE 选项。可以用这个选项查看所选计划对应的计划建议字符串。例如：

EXPLAIN (COSTS OFF, PLAN_ADVICE)
        SELECT * FROM join_fact f JOIN join_dim d ON f.dim_id = d.id;
             QUERY PLAN
------------------------------------
 Hash Join
   Hash Cond: (f.dim_id = d.id)
   ->  Seq Scan on join_fact f
   ->  Hash
         ->  Seq Scan on join_dim d
 Generated Plan Advice:
   JOIN_ORDER(f d)
   HASH_JOIN(d)
   SEQ_SCAN(f d)
   NO_GATHER(f d)

在这个例子中，用户并没有指定任何建议；相反，允许规划器自行做出它认为最优的决定，然后把这些决定整理成一条建议字符串。JOIN_ORDER(f d) 表示 f 应该是驱动表，并且首先与 d 连接。HASH_JOIN(d) 表示 d 应该出现在哈希连接的内侧。SEQ_SCAN(f d) 表示 f 和 d 都应该通过顺序扫描访问。NO_GATHER(f d) 表示 f 和 d 都不应出现在 Gather 或 Gather Merge 节点下方。有关计划建议迷你语言的更多细节，请参阅下面的 建议目标 和 建议标签。

一旦你为某个查询得到了一条建议字符串，就可以用它来控制该查询的规划方式。做法是将 pg_plan_advice.advice 设置为你选定的建议字符串。这个字符串既可以是系统生成的，也可以是你自己编写的。编写自己的建议字符串的一种好办法，是取系统生成的字符串，然后只保留你希望强制执行的那些元素。在上面的例子中，pg_plan_advice 会为连接顺序、连接方法、扫描方法以及并行度的使用输出建议，但你可能只想控制连接顺序：

SET pg_plan_advice.advice = 'JOIN_ORDER(f d)';
EXPLAIN (COSTS OFF)
        SELECT * FROM join_fact f JOIN join_dim d ON f.dim_id = d.id;
             QUERY PLAN
------------------------------------
 Hash Join
   Hash Cond: (f.dim_id = d.id)
   ->  Seq Scan on join_fact f
   ->  Hash
         ->  Seq Scan on join_dim d
 Supplied Plan Advice:
   JOIN_ORDER(f d) /* matched */

由于 EXPLAIN 并未指定 PLAN_ADVICE 选项，所以不会为该计划生成建议字符串。不过，提供的计划建议仍会显示出来，这样查看 EXPLAIN 输出的人就能知道该计划受到了计划建议的影响。如果不希望显示提供的计划建议，可以把 pg_plan_advice.always_explain_supplied_advice = false。对于每一条提供的建议，输出都会显示 建议反馈，表明该建议是否成功应用到查询中。在这个例子中，反馈显示为 /* matched */，表示 f 和 d 在查询中都找到了，而且生成的查询计划符合所指定的建议。

计划建议是以命令式方式编写的，也就是说，它指定应该做什么。不过在实现层面上，pg_plan_advice 的工作方式是告诉核心规划器什么不应该做。换句话说，它是通过约束规划器的选择来工作的，而不是替换规划器。因此，无论你提供什么建议，你得到的都只会是核心规划器本来就会为相关查询考虑的计划。如果你试图通过提供一条建议字符串来强行得到你认为正确的计划，而规划器仍然无法生成所需计划，这意味着要么你的建议字符串有 bug，要么核心规划器根本没有把该计划视为可行。这通常有两个原因。第一，规划器可能认为你试图强制的计划在语义上不正确，也就是会产生错误结果，因此没有考虑它。第二，规划器可能因为除代价之外的原因拒绝了你希望生成的计划。例如，给定一个非常简单的查询，比如 SELECT * FROM some_table，查询规划器会在进行任何代价计算之前就判断这里使用索引毫无价值。即使你设置了 enable_seqscan = false，也无法强迫它在这个查询中使用索引；同样，也不能通过计划建议强迫它这样做。

指定计划建议不应导致规划器失败。不过，如果你指定了要求某些不可能之事的计划建议，EXPLAIN 输出中可能会有一些计划节点被标记为 Disabled: true。在某些情况下，这样的计划与完全没有提供建议时得到的计划基本相同，但在另一些情况下，它们可能糟得多。例如：

SET pg_plan_advice.advice = 'JOIN_ORDER(x f d)';
EXPLAIN (COSTS OFF)
        SELECT * FROM join_fact f JOIN join_dim d ON f.dim_id = d.id;
                     QUERY PLAN
----------------------------------------------------
 Nested Loop
   Disabled: true
   ->  Seq Scan on join_fact f
   ->  Index Scan using join_dim_pkey on join_dim d
         Index Cond: (id = f.dim_id)
 Supplied Plan Advice:
   JOIN_ORDER(x f d) /* partially matched */

由于 f 和 d 都不是 JOIN_ORDER() 规格中的第一个表，规划器会禁用它们之间的所有直接连接，认为应该先与 x 连接。由于规划不允许失败，最终还是会选出一个被禁用的两关系计划，但这里得到的是一个 Nested Loop，而不是前面那个未指定任何建议时选出的 Hash Join。这种情况可以通过多种不同方式发生；一旦发生，得到的计划通常会比完全没有指定建议时更差。因此，最好验证你指定的建议确实适用于它所对应的查询，而且结果符合预期。

建议目标用于唯一标识某个特定查询中涉及的某个关系的某个实例。在前面展示的简单例子中，建议目标就是关系别名。不过，当使用子查询、表分区，或者同一个关系别名在同一子查询中出现不止一次时，就需要更复杂的语法（例如 (foo JOIN bar ON foo.a = bar.a) x JOIN foo ON x.b = foo.b）。这三种情况还可以同时出现：一个关系可以被引用多次，可以是分区表，也可以位于子查询内部。

因此，关系标识符的一般语法是：

alias_name#occurrence_number/partition_schema.partition_name@plan_name

除了 alias_name 之外，其余所有组成部分都是可选的，只在必要时才出现。某个组成部分省略时，前面的标点也必须同时省略。对于给定子查询中的某个关系首次出现，系统生成的建议会省略出现次数编号，但如果愿意，也可以写成 #1。分区模式和分区名只用于分区表的子项。在系统生成的建议中，pg_plan_advice 总是同时包含两者，但模式可以省略。计划名对顶层计划会省略，而对任何子计划都必须写出。

仅凭查看查询，并不总是容易确定正确的建议目标。比如，如果规划器把一个子查询拉升到父查询级别，那么其中的所有内容都会变成父查询级别的一部分，并使用父查询的子计划名（如果已拉升到顶层，则不使用子计划名）。此外，正确的子查询名有时也并不明显。例如，当两个查询通过 UNION 或 INTERSECT 之类的操作组合时，SQL 语法里不会给子查询指定名字；相反，系统会为每个分支分配一个生成的名字。发现正确建议目标的最简单方法是使用 EXPLAIN (PLAN_ADVICE) 并检查生成的建议。

建议标签用于指定查询某一部分应强制遵循的特定行为，例如某个特定的连接顺序或连接方法。所有建议标签都以 建议目标 作为参数，而且其中很多都允许使用建议目标列表，而这些列表在某些情况下可以嵌套多层。建议标签有好几类，每一类控制查询规划的一个不同方面。

SEQ_SCAN(target [ ... ])
TID_SCAN(target [ ... ])
INDEX_SCAN(target index_name [ ... ])
INDEX_ONLY_SCAN(target index_name [ ... ])
FOREIGN_JOIN((target [ ... ]) [ ... ])
BITMAP_HEAP_SCAN(target [ ... ])
DO_NOT_SCAN(target [ ... ])

JOIN_ORDER(join_order_item [ ... ])

其中 join_order_item 为：

advice_target |
( join_order_item [ ... ] ) |
{ join_order_item [ ... ] }

Join
  ->  Join
        -> Scan on a
        -> Join
             -> Scan on b
             -> Scan on c
  ->  Scan on d

join_method_name(join_method_item [ ... ])

其中 join_method_name 为：

{ MERGE_JOIN_MATERIALIZE | MERGE_JOIN_PLAIN | NESTED_LOOP_MATERIALIZE | NESTED_LOOP_MEMOIZE | NESTED_LOOP_PLAIN | HASH_JOIN }

而 join_method_item 为：

{ advice_target |
( advice_target [ ... ] ) }

PARTITIONWISE(partitionwise_item [ ... ])

其中 partitionwise_item 为：

{ advice_target |
( advice_target [ ... ] ) }

SEMIJOIN_UNIQUE(sj_unique_item [ ... ])
SEMIJOIN_NON_UNIQUE(sj_unique_item [ ... ])

其中 sj_unique_item 为：

{ advice_target |
( advice_target [ ... ] ) }

GATHER(gather_item [ ... ])
GATHER_MERGE(gather_item [ ... ])
NO_GATHER(advice_target [ ... ])

其中 gather_item 为：

{ advice_target |
( advice_target [ ... ] ) }

 Finalize Aggregate
   ->  Gather
         ->  Partial Aggregate
               ->  Parallel Seq Scan on outer_example
                     Filter: (something = (hashed SubPlan any_1).col1)
                     SubPlan any_1
                       ->  Seq Scan on inner_example
                             Filter: (something_else > 100)

 Aggregate
   ->  Seq Scan on outer_example
         Filter: (something = (hashed SubPlan any_1).col1)
         SubPlan any_1
           ->  Gather
                 -> Parallel Seq Scan on inner_example
                      Filter: (something_else > 100)

EXPLAIN 会通过在每一条提供的建议上附加注释的形式，反馈所提供的建议是否成功应用到了查询中。例如：

SET pg_plan_advice.advice = 'hash_join(f g) join_order(f g) index_scan(f no_such_index)';
EXPLAIN (COSTS OFF)
    SELECT * FROM jo_fact f
    LEFT JOIN jo_dim1 d1 ON f.dim1_id = d1.id
    LEFT JOIN jo_dim2 d2 ON f.dim2_id = d2.id
    WHERE val1 = 1 AND val2 = 1;
                            QUERY PLAN
-------------------------------------------------------------------
 Hash Join
   Hash Cond: ((d1.id = f.dim1_id) AND (d2.id = f.dim2_id))
   ->  Nested Loop
         ->  Seq Scan on jo_dim2 d2
               Filter: (val2 = 1)
         ->  Materialize
               ->  Seq Scan on jo_dim1 d1
                     Filter: (val1 = 1)
   ->  Hash
         ->  Seq Scan on jo_fact f
 Supplied Plan Advice:
   INDEX_SCAN(f no_such_index) /* matched, inapplicable, failed */
   HASH_JOIN(f) /* matched */
   HASH_JOIN(g) /* not matched */
   JOIN_ORDER(f g) /* partially matched */

对于这个查询，f 是一个有效的建议目标，但 g 不是。因此，把 f 放到哈希连接内侧的请求会标记为 matched，而把 g 放到哈希连接内侧的请求会标记为 not matched。JOIN_ORDER 建议标签涉及一个有效目标和一个无效目标，因此会标记为 partially matched。请注意，HASH_JOIN(f g) 实际上是对两个逻辑上彼此独立的行为的请求，所以在反馈中它会被拆分成 HASH_JOIN(f) 和 HASH_JOIN(g)。相比之下，JOIN_ORDER(f g) 是单个请求，因此会原样显示。

建议反馈可以包含以下任意一种状态：

所有建议都应且只能被标记为 matched、partially matched 或 not matched 中的一种。

目前还不能通过计划建议来控制规划器在聚合方面的任何行为。这既包括聚合是通过排序还是通过哈希来计算，也包括是否使用诸如 急切聚合 或 分区式聚合 之类的策略。

目前也还不能通过计划建议来控制规划器在 UNION 或 INTERSECT 等集合操作方面的任何行为。

如上面 工作原理 所述，计划建议只能影响规划器从它认为可行的计划中选择哪一个。它永远不能强迫规划器选择一个它一开始就拒绝考虑的计划。

Robert Haas <rhaas@postgresql.org>