pg_hint_plan читает фразы подсказок в комментарии специальной формы, заданной SQL-выражением. Подсказка может быть указана, если она начинается с последовательности "/\*+" и заканчивается "\*/". Фразы подсказок состоят из имен подсказок и параметров, заключенных в скобки и разделенных пробелами. Фразы подсказок могут использовать переводы строк для удобочитаемости.

В приведенном ниже примере в качестве метода соединения выбран хеш-соединение, при этом выполняется последовательное сканирование pgbench_accounts:

=# /*+
     HashJoin(a b)
     SeqScan(a)
    */
   EXPLAIN SELECT *
     FROM pgbench_branches b
     JOIN pgbench_accounts a ON b.bid = a.bid
     ORDER BY a.aid;
                                        QUERY PLAN
---------------------------------------------------------------------------------------
    Sort  (cost=31465.84..31715.84 rows=100000 width=197)
    Sort Key: a.aid
    ->  <b>Hash Join</b>  (cost=1.02..4016.02 rows=100000 width=197)
            Hash Cond: (a.bid = b.bid)
            ->  <b>Seq Scan on pgbench_accounts a</b>  (cost=0.00..2640.00 rows=100000 width=97)
            ->  Hash  (cost=1.01..1.01 rows=1 width=100)
                ->  Seq Scan on pgbench_branches b  (cost=0.00..1.01 rows=1 width=100)
(7 rows)

Подсказочные фразы классифицируются на несколько типов в зависимости от того, какой объект и как они могут повлиять на планировщик. См. Список подсказок для получения более подробной информации.

=# /*+
     SeqScan(t1)
     IndexScan(t2 t2_pkey)
    */
   SELECT * FROM table1 t1 JOIN table table2 t2 ON (t1.key = t2.key);

=# /*+
     NestLoop(t1 t2)
     MergeJoin(t1 t2 t3)
     Leading(t1 t2 t3)
    */
   SELECT * FROM table1 t1
     JOIN table table2 t2 ON (t1.key = t2.key)
     JOIN table table3 t3 ON (t2.key = t3.key);

=# /*+ Rows(a b #10) */ SELECT... ; Sets rows of join result to 10
=# /*+ Rows(a b +10) */ SELECT... ; Increments row number by 10
=# /*+ Rows(a b -10) */ SELECT... ; Subtracts 10 from the row number.
=# /*+ Rows(a b *10) */ SELECT... ; Makes the number 10 times larger.

=# EXPLAIN /*+ Parallel(c1 3 hard) Parallel(c2 5 hard) */
       SELECT c2.a FROM c1 JOIN c2 ON (c1.a = c2.a);
                                  QUERY PLAN
-------------------------------------------------------------------------------
 Hash Join  (cost=2.86..11406.38 rows=101 width=4)
   Hash Cond: (c1.a = c2.a)
   ->  Gather  (cost=0.00..7652.13 rows=1000101 width=4)
         Workers Planned: 3
         ->  Parallel Seq Scan on c1  (cost=0.00..7652.13 rows=322613 width=4)
   ->  Hash  (cost=1.59..1.59 rows=101 width=4)
         ->  Gather  (cost=0.00..1.59 rows=101 width=4)
               Workers Planned: 5
               ->  Parallel Seq Scan on c2  (cost=0.00..1.59 rows=59 width=4)

=# EXPLAIN /*+ Parallel(tl 5 hard) */ SELECT sum(a) FROM tl;
                                    QUERY PLAN
-----------------------------------------------------------------------------------
 Finalize Aggregate  (cost=693.02..693.03 rows=1 width=8)
   ->  Gather  (cost=693.00..693.01 rows=5 width=8)
         Workers Planned: 5
         ->  Partial Aggregate  (cost=693.00..693.01 rows=1 width=8)
               ->  Parallel Seq Scan on tl  (cost=0.00..643.00 rows=20000 width=4)

=# /*+ Set(random_page_cost 2.0) */
   SELECT * FROM table1 t1 WHERE key = 'value';
...

Следующие параметры GUC влияют на поведение pg_hint_plan:

pg_hint_plan не требует CREATE EXTENSION. Загрузка его с помощью команды LOAD активирует его, и, конечно, вы можете загрузить его глобально, установив shared_preload_libraries в postgresql.conf. Или вам может быть интересно ALTER USER SET/ALTER DATABASE SET для автоматической загрузки в определенных сессиях.

postgres=# LOAD 'pg_hint_plan';
LOAD
postgres=#

Выполните CREATE EXTENSION и SET pg_hint_plan.enable_hint_table TO on, если вы планируете использовать таблицу подсказок.

pg_hint_plan читает подсказки только из первого блочного комментария и прекращает разбор с любых символов, кроме буквенных символов, цифр, пробелов, подчеркиваний, запятых и круглых скобок. В следующем примере, HashJoin(a b) и SeqScan(a) разбираются как подсказки, но IndexScan(a) и MergeJoin(a b) не разбираются:

=# /*+
     HashJoin(a b)
     SeqScan(a)
    */
   /*+ IndexScan(a) */
   EXPLAIN SELECT /*+ MergeJoin(a b) */ *
     FROM pgbench_branches b
     JOIN pgbench_accounts a ON b.bid = a.bid
     ORDER BY a.aid;
                                      QUERY PLAN
---------------------------------------------------------------------------------------
 Sort  (cost=31465.84..31715.84 rows=100000 width=197)
   Sort Key: a.aid
   ->  Hash Join  (cost=1.02..4016.02 rows=100000 width=197)
         Hash Cond: (a.bid = b.bid)
         ->  Seq Scan on pgbench_accounts a  (cost=0.00..2640.00 rows=100000 width=97)
         ->  Hash  (cost=1.01..1.01 rows=1 width=100)
               ->  Seq Scan on pgbench_branches b  (cost=0.00..1.01 rows=1 width=100)
(7 rows)

pg_hint_plan работает для запросов в скриптах PL/pgSQL с некоторыми ограничениями.

=# CREATE FUNCTION hints_func(integer) RETURNS integer AS $$
   DECLARE
     id  integer;
     cnt integer;
   BEGIN
     SELECT /*+ NoIndexScan(a) */ aid
       INTO id FROM pgbench_accounts a WHERE aid = $1;
     SELECT /*+ SeqScan(a) */ count(*)
       INTO cnt FROM pgbench_accounts a;
     RETURN id + cnt;
   END;
   $$ LANGUAGE plpgsql;

В отличие от того, как Tantor SE обрабатывает имена объектов, pg_hint_plan сравнивает простые имена объектов в подсказках с внутренними именами объектов базы данных с учетом регистра. Поэтому имя объекта TBL в подсказке соответствует только “TBL” в базе данных и не соответствует никаким некавычным именам, таким как TBL, tbl или Tbl.

Объекты, определенные в параметре подсказки, могут использовать двойные кавычки, если они содержат скобки, двойные кавычки и пробелы. Правила экранирования такие же, как в Tantor SE.

pg_hint_plan идентифицирует целевой объект, используя псевдонимы, если они есть. Это поведение полезно для указания на конкретное вхождение среди нескольких вхождений одной таблицы.

=# /*+ HashJoin(t1 t1) */
   EXPLAIN SELECT * FROM s1.t1
     JOIN public.t1 ON (s1.t1.id=public.t1.id);
INFO:  hint syntax error at or near "HashJoin(t1 t1)"
DETAIL:  Relation name "t1" is ambiguous.
...
=# /*+ HashJoin(pt st) */
   EXPLAIN SELECT * FROM s1.t1 st
     JOIN public.t1 pt ON (st.id=pt.id);
                             QUERY PLAN
---------------------------------------------------------------------
 Hash Join  (cost=64.00..1112.00 rows=28800 width=8)
   Hash Cond: (st.id = pt.id)
   ->  Seq Scan on t1 st  (cost=0.00..34.00 rows=2400 width=4)
   ->  Hash  (cost=34.00..34.00 rows=2400 width=4)
         ->  Seq Scan on t1 pt  (cost=0.00..34.00 rows=2400 width=4)

Подсказки не применимы к представлениям, но они могут повлиять на запросы внутри представления, если имена объектов совпадают с именами в развернутом запросе на представление. Присвоение псевдонимов таблицам в представлении позволяет манипулировать ими извне представления.

=# CREATE VIEW v1 AS SELECT * FROM t2;
=# EXPLAIN /*+ HashJoin(t1 v1) */
          SELECT * FROM t1 JOIN v1 ON (c1.a = v1.a);
                            QUERY PLAN
------------------------------------------------------------------
 Hash Join  (cost=3.27..18181.67 rows=101 width=8)
   Hash Cond: (t1.a = t2.a)
   ->  Seq Scan on t1  (cost=0.00..14427.01 rows=1000101 width=4)
   ->  Hash  (cost=2.01..2.01 rows=101 width=4)
         ->  Seq Scan on t2  (cost=0.00..2.01 rows=101 width=4)

Подсказки могут указывать только на родителя дерева наследования, и подсказки влияют на все таблицы в дереве наследования. Подсказки, указывающие непосредственно на унаследованных потомков, не имеют эффекта.

Один многооператорный запрос может иметь ровно один комментарий-подсказку, и подсказка влияет на все отдельные операторы в многооператорном запросе.

VALUES выражения в FROM предложении называются как *VALUES* внутренне, они могут быть указаны, если это единственное VALUES в запросе. Два или более выражений VALUES в запросе не могут быть различены при просмотре результата EXPLAIN, что приводит к неоднозначным результатам:

=# /*+ MergeJoin(*VALUES*_1 *VALUES*) */
      EXPLAIN SELECT * FROM (VALUES (1, 1), (2, 2)) v (a, b)
      JOIN (VALUES (1, 5), (2, 8), (3, 4)) w (a, c) ON v.a = w.a;
INFO:  pg_hint_plan: hint syntax error at or near "MergeJoin(*VALUES*_1 *VALUES*) "
DETAIL:  Relation name "*VALUES*" is ambiguous.
                               QUERY PLAN
-------------------------------------------------------------------------
 Hash Join  (cost=0.05..0.12 rows=2 width=16)
   Hash Cond: ("*VALUES*_1".column1 = "*VALUES*".column1)
   ->  Values Scan on "*VALUES*_1"  (cost=0.00..0.04 rows=3 width=8)
   ->  Hash  (cost=0.03..0.03 rows=2 width=8)
         ->  Values Scan on "*VALUES*"  (cost=0.00..0.03 rows=2 width=8)

Контекст подзапросов можно иногда указать с помощью имени ANY_subquery:

IN (SELECT ... {LIMIT | OFFSET ...} ...)
= ANY (SELECT ... {LIMIT | OFFSET ...} ...)
= SOME (SELECT ... {LIMIT | OFFSET ...} ...)

Для этих синтаксисов планировщик внутренне присваивает имя подзапросу при планировании соединений с таблицами, включая его, поэтому подсказки соединения применимы к таким соединениям с использованием неявного имени. Например:

=# /*+HashJoin(a1 ANY_subquery)*/
   EXPLAIN SELECT *
     FROM pgbench_accounts a1
   WHERE aid IN (SELECT bid FROM pgbench_accounts a2 LIMIT 10);
                                         QUERY PLAN

---------------------------------------------------------------------------------------------
 Hash Semi Join  (cost=0.49..2903.00 rows=1 width=97)
   Hash Cond: (a1.aid = a2.bid)
   ->  Seq Scan on pgbench_accounts a1  (cost=0.00..2640.00 rows=100000 width=97)
   ->  Hash  (cost=0.36..0.36 rows=10 width=4)
         ->  Limit  (cost=0.00..0.26 rows=10 width=4)
               ->  Seq Scan on pgbench_accounts a2  (cost=0.00..2640.00 rows=100000 width=4)

Индексное сканирование может быть неожиданно выполнено по другому индексу, когда индекс, указанный в подсказке IndexOnlyScan, не может выполнить только индексное сканирование.

Подсказка NoIndexScan подразумевает NoIndexOnlyScan.

A UNION может выполняться параллельно только в том случае, если все подзапросы, на которых он основан, безопасны для параллельного выполнения. Таким образом, принуждение параллельного выполнения любого из подзапросов позволит параллельно выполняемому UNION выполняться параллельно. Между тем, параллельная подсказка с нулевым количеством рабочих потоков предотвращает выполнение сканирования в параллельном режиме.

pg_hint_plan параметры влияют на их собственное поведение, поэтому некоторые параметры могут не работать так, как можно было бы ожидать:

Любые синтаксические ошибки или неправильные имена подсказок сообщаются как синтаксическая ошибка. Эти ошибки сообщаются в журнале сервера с уровнем сообщения, указанным в pg_hint_plan.message_level, если pg_hint_plan.debug_print включен и выше.

Некорректные определения объектов приводят к тихому игнорированию подсказок. Этот вид ошибки сообщается как «Неиспользуемая подсказка» в журналах сервера.

Последняя подсказка рассматривается, когда определены избыточные подсказки или подсказки конфликтуют друг с другом. Этот вид ошибки сообщается как дублированные подсказки.

Подсказка: комментарии не могут быть рекурсивными. Если это обнаружено, разбор подсказок немедленно прекращается, и все уже разобранные подсказки игнорируются.

Планировщик не пытается учитывать порядок соединения для элементов предложения FROM более чем from_collapse_limit. pg_hint_plan не может повлиять на порядок соединения в этом случае.

Планировщик выбирает любые исполняемые планы, когда невозможно выполнить заданный план.

ECPG удаляет комментарии в запросах, написанных как встроенные SQL, поэтому подсказки не могут быть переданы ему. Единственное исключение — EXECUTE, который передает строку запроса на сервер как есть. В этом случае можно использовать таблицу подсказок.

Когда compute_query_id включен, PostgreSQL генерирует идентификатор запроса, игнорируя комментарии. Таким образом, запросы с различными подсказками, но написанные одинаково, могут иметь одинаковый идентификатор запроса.