doc/pg_hint_plan.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD html 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html lang="en_US">
   3 <head>
   4 <title>pg_hint_plan</title>
   5 <!-- Uncomment after the tool has been hosted somewhere.
   6 <link rel="home" title="pg_hint_plan" href="index.html">
   7 -->
   8 <link rel="stylesheet" type="text/css" href="style.css">
   9 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  10 <!--
  11 <style type="text/css">
  12 h2 { border-style:solid none none none; margin-top: 2em; }
  13 h3 { margin-top: 2em; }
  14 dt { margin-top: 0.5em; margin-bottom: 0.3em;}
  15 pre { margin: 0 2em 0 2em; padding:0.3em; border-style: solid; border-width:0.1em; border-color: #97A69F; background-color: #DEFFEF; }
  16 </style>
  17 -->
  18 </head>
  19
  20 <body>
  21 <h1 id="pg_hint_plan">pg_hint_plan 1.6</h1>
  22 <div class="navigation">
  23   <a href="pg_hint_plan.html">pg_hint_plan</a>
  24 </div>
  25 <hr>
  26
  27 <div class="index">
  28 <ol>
  29 <li><a href="#name">Name</a></li>
  30 <li><a href="#synopsis">Synopsis</a></li>
  31 <li><a href="#description">Description</a>
  32 <li><a href="#install">Installation</a></li>
  33 <li><a href="#uninstall">Uninstallation</a></li>
  34 <li><a href="#examples">Hint descriptions</a></li>
  35 <li><a href="#hint_syntax">Hint syntax</a></li>
  36 <li><a href="#restrictions">Restrictions</a></li>
  37 <li><a href="#techniques">Techniques to hint on desired targets</a></li>
  38 <li><a href="#errors">Errors of hints</a></li>
  39 <li><a href="#func_limits">Functional limitations</a></li>
  40 <li><a href="#requirement">Requirements</a></li>
  41 <li><a href="#seealso">See Also</a></li>
  42 <li><a href="hint_list.html">Appendix A. Hints list</a></li>
  43 </div>
  44
  45 <h2 id="name">Name</h2>
  46 <p>pg_hint_plan -- controls execution plan with hinting phrases in comment of special form.</p>
  47
  48 <h2 id="synopsis">Synopsis</h2>
  49 <p>PostgreSQL uses cost based optimizer, which utilizes data statistics, not static rules. The planner (optimizer) estimates costs of each possible execution plan for a SQL statement, and then the execution plan with the lowest cost is eventually executed.  The planner does its best to select the best execution plan, but it is not perfect, since it doesn't know all properties of the data, for example, correlation between columns.</p>
  50 <p>pg_hint_plan makes it possible to tweak execution plans using so-called "hints", which are simple descriptions in the SQL comment of special form.</p>
  51
  52 <h2 id="description">Description</h2>
  53
  54 <h3 id="hint-rule">Basic Usage</h3>
  55 <p>pg_hint_plan reads hinting phrases in a comment of special form given with the target SQL statement. The special form is beginning by the character sequence "/*+" and ends with "*/". Hint phrases consist of hint name and following parameters enclosed by parentheses and delimited by spaces. Each hinting phrases can be delimited by new lines for readability.</p>
  56
  57 <p>In the example below , hash join is selected as the join method and scanning pgbench_accounts by sequential scan method.</p>
  58 <pre>
  59 postgres=# /*+
  60 postgres*#    <span class="strong">HashJoin(a b)</span>
  61 postgres*#    <span class="strong">SeqScan(a)</span>
  62 postgres*#  */
  63 postgres-# EXPLAIN SELECT *
  64 postgres-#    FROM pgbench_branches b
  65 postgres-#    JOIN pgbench_accounts a ON b.bid = a.bid
  66 postgres-#   ORDER BY a.aid;
  67                                       QUERY PLAN
  68 ---------------------------------------------------------------------------------------
  69  Sort  (cost=31465.84..31715.84 rows=100000 width=197)
  70    Sort Key: a.aid
  71    ->  <span class="strong">Hash Join</span>  (cost=1.02..4016.02 rows=100000 width=197)
  72          Hash Cond: (a.bid = b.bid)
  73          ->  <span class="strong">Seq Scan on pgbench_accounts a</span>  (cost=0.00..2640.00 rows=100000 width=97)
  74          ->  Hash  (cost=1.01..1.01 rows=1 width=100)
  75                ->  Seq Scan on pgbench_branches b  (cost=0.00..1.01 rows=1 width=100)
  76 (7 rows)
  77
  78 postgres=# </pre>
  79
  80 <h2 id="examples">The hint table</h2>
  81 <p> Hints are described in a comment in a special form in the above
  82 section. This is inconvenient in the case where queries cannot be
  83 edited. In the case hints can be placed in a special table named
  84 "hint_plan.hints". This feature requires compute_query_id to be "on"
  85 or "auto". The table consists of the following columns.</p>
  86 <table>
  87 <thead>
  88 <tr>
  89 <tr><th>column</th><th>description</th></tr>
  90 </tr></thead>
  91 <tbody>
  92 <tr><td>id</td>
  93   <td>Unique number to identify a row for a hint. This column is filled automatically by sequence.</td></tr>
  94 <tr><td>norm_query_string</td>
  95   <td>A pattern matches to the query to be hinted. Constants in the query have to be replace with '?' as in the following example. White space is significant in the pattern.</td></tr>
  96 <tr><td>application_name</td>
  97   <td>The value of application_name of sessions to apply the hint. The hint in the example below applies to sessions connected from psql. An empty string means sessions of any application_name.</td></tr>
  98 <tr><td>hints</td>
  99   <td>Hint phrase. This must be a series of hints excluding surrounding comment marks.</td></tr>
 100 </tbody>
 101 </table>
 102
 103 <p>The following example shows how to operate with the hint table.</p>
 104 <pre>
 105 <span class="strong">postgres=#</span> INSERT INTO hint_plan.hints(norm_query_string, application_name, hints)
 106 <span class="strong">postgres-#</span>     VALUES (
 107 <span class="strong">postgres(#</span>         'EXPLAIN (COSTS false) SELECT * FROM t1 WHERE t1.id = ?;',
 108 <span class="strong">postgres(#</span>         '',
 109 <span class="strong">postgres(#</span>         'SeqScan(t1)'
 110 <span class="strong">postgres(#</span>     );
 111 INSERT 0 1
 112 <span class="strong">postgres=#</span> UPDATE hint_plan.hints
 113 <span class="strong">postgres-#</span>    SET hints = 'IndexScan(t1)'
 114 <span class="strong">postgres-#</span>  WHERE id = 1;
 115 UPDATE 1
 116 <span class="strong">postgres=#</span> DELETE FROM hint_plan.hints
 117 <span class="strong">postgres-#</span>  WHERE id = 1;
 118 DELETE 1
 119 <span class="strong">postgres=#</span>
 120 </pre>
 121 <p>The hint table is owned by the creator user and having the default privileges at the time of creation during CREATE EXTENSION. Table hints are prioritized then comment hits.</p>
 122
 123 <h3 id="hint-group">The types of hints</h3>
 124 <p>Hinting phrases are classified into six types based on what kind of object and how they can affect planning. Scaning methods, join methods, joining order, row number correction, parallel query and GUC setting. You will see the lists of hint phrases of each type in <a href="hint_list.html">Hint list</a>.</p>
 125
 126 <h4>Hints for scan methods </h4>
 127 <p>Scan method hints enforce specific scanning method on the target table. pg_hint_plan recognizes the target table by alias names if any. They are 'SeqScan' , 'IndexScan' and so on in this kind of hint.</p>
 128 <p>Scan hints are effective on ordinary tables, inheritance tables, UNLOGGED tables, temporary tables and  system catalogs. External(foreign) tables, table functions, VALUES clause, CTEs, views and subqueries are not affected.</p>
 129 <pre>
 130 <span class="strong">postgres=# /*+</span>
 131 <span class="strong">postgres*#     SeqScan(t1)</span>
 132 <span class="strong">postgres*#     IndexScan(t2 t2_pkey)</span>
 133 <span class="strong">postgres*#  */</span>
 134 <span class="strong">postgres-#</span> SELECT * FROM table1 t1 JOIN table table2 t2 ON (t1.key = t2.key);
 135 </pre>
 136
 137
 138 <h4>Hints for join methods</h4>
 139 <p>Join method hints enforce the join methods of the joins involving specified tables. </p>
 140 <p>This can affect on joins only on ordinary tables, inheritance tables, UNLOGGED tables, temporary tables, external (foreign) tables, system catalogs, table functions, VALUES command results and CTEs are allowed to be in the parameter list. But joins on views and sub query are not affected.</p>
 141
 142 <h4>Hint for joining order</h4>
 143 <p> This hint "Leading" enforces the order of join on two or more tables. There are two ways of enforcing. One is enforcing specific order of joining but not restricting direction at each join level. Another enforces join direction additionally. Details are seen in the <a href="hint_list.html">hint list</a> table.</p>
 144
 145 <pre>
 146 <span class="strong">postgres=# /*+</span>
 147 <span class="strong">postgres*#     NestLoop(t1 t2)</span>
 148 <span class="strong">postgres*#     MergeJoin(t1 t2 t3)</span>
 149 <span class="strong">postgres*#     Leading(t1 t2 t3)</span>
 150 <span class="strong">postgres*#  */</span>
 151 <span class="strong">postgres-#</span> SELECT * FROM table1 t1
 152 <span class="strong">postgres-#</span>     JOIN table table2 t2 ON (t1.key = t2.key)
 153 <span class="strong">postgres-#</span>     JOIN table table3 t3 ON (t2.key = t3.key);
 154 </pre>
 155
 156 <h4>Hint for restricting join behavior</h4>
 157 <p>This hint "Memoize" and "NoMemoize" allows and disallows a join to memoize the inner result. In the following example, The NoMemoize hint inhibits the topmost hash join from memoizing the result of table a.</p>
 158 <pre>
 159 postgres=# /*+ NoMemoize(a b) */
 160 EXPLAIN SELECT * FROM a, b WHERE a.val = b.val;
 161                              QUERY PLAN
 162 --------------------------------------------------------------------
 163  Hash Join  (cost=270.00..1412.50 rows=100000 width=16)
 164    Hash Cond: (b.val = a.val)
 165    ->  Seq Scan on b  (cost=0.00..15.00 rows=1000 width=8)
 166    ->  Hash  (cost=145.00..145.00 rows=10000 width=8)
 167          ->  Seq Scan on a  (cost=0.00..145.00 rows=10000 width=8)
 168 </pre>
 169
 170
 171
 172 <h4>Hint for row number correction</h4>
 173 <p>This hint "Rows" corrects row number misestimation of joins that comes from restrictions of the planner. </p>
 174
 175 <pre>
 176 <span class="strong">postgres=# /*+ Rows(a b #10) */</span> SELECT... ; Sets rows of join result to 10
 177 <span class="strong">postgres=# /*+ Rows(a b +10) */</span> SELECT... ; Increments row number by 10
 178 <span class="strong">postgres=# /*+ Rows(a b -10) */</span> SELECT... ; Subtracts 10 from the row number.
 179 <span class="strong">postgres=# /*+ Rows(a b *10) */</span> SELECT... ; Makes the number 10 times larger.
 180 </pre>
 181
 182 <h4>Hint for parallel plan</h4>
 183 <p>This hint "Parallel" enforces parallel execution configuration on
 184 scans. The third parameter specifies the strength of enforcement. "soft" means that pg_hint_plan only changes max_parallel_worker_per_gather and leave all others to planner. "hard" changes other planner parameters so as to forcibly apply the number. This can affect on ordinary tables, inheritance parents, unlogged
 185 tables and system catalogues. External tables, table functions, values clause, CTEs, views and subqueries are not affected. Internal tables of a view can be specified by its real name/alias as the target object. The following example shows that the query is enforced differently on each table.</p>
 186
 187 <pre>
 188 <span class="strong">postgres=#</span> explain <span class="strong">/*+ Parallel(c1 3 hard) Parallel(c2 5 hard) */</span>
 189        SELECT c2.a FROM c1 JOIN c2 ON (c1.a = c2.a);
 190                                   QUERY PLAN
 191 -------------------------------------------------------------------------------
 192  Hash Join  (cost=2.86..11406.38 rows=101 width=4)
 193    Hash Cond: (c1.a = c2.a)
 194    ->  Gather  (cost=0.00..7652.13 rows=1000101 width=4)
 195          <span class="strong">Workers Planned: 3</span>
 196          ->  Parallel Seq Scan on <span class="strong">c1</span>  (cost=0.00..7652.13 rows=322613 width=4)
 197    ->  Hash  (cost=1.59..1.59 rows=101 width=4)
 198          ->  Gather  (cost=0.00..1.59 rows=101 width=4)
 199                <span class="strong">Workers Planned: 5</span>
 200                ->  Parallel Seq Scan on <span class="strong">c2</span>  (cost=0.00..1.59 rows=59 width=4)
 201
 202 <span class="strong">postgres=#</span> EXPLAIN <span class="strong">/*+ Parallel(tl 5 hard) */</span> SELECT sum(a) FROM tl;
 203                                     QUERY PLAN
 204 -----------------------------------------------------------------------------------
 205  <span class="strong">Finalize Aggregate</span>  (cost=693.02..693.03 rows=1 width=8)
 206    ->  Gather  (cost=693.00..693.01 rows=5 width=8)
 207          <span class="strong">Workers Planned: 5</span>
 208          ->  <span class="strong">Partial Aggregate</span>  (cost=693.00..693.01 rows=1 width=8)
 209                ->  Parallel Seq Scan on tl  (cost=0.00..643.00 rows=20000 width=4)
 210 </pre>
 211 </dd>
 212
 213
 214 </pre>
 215
 216
 217 <h4>GUC parameters temporarily setting</h4>
 218 <p>'Set' hint changes GUC parameters just while planning. GUC parameter shown in <a href="http://www.postgresql.org/docs/current/static/runtime-config-query.html">Query Planning</a> can have the expected effects on planning unless any other hint conflicts with the planner method configuration parameters. The last one among hints on the same GUC parameter makes effect. <a href="#hint-GUC">GUC parameters for pg_hint_plan</a> are also settable by  this hint but it won't work as your expectation. See <a href="#restrictions">Restrictions</a> for details.</p>
 219 <pre>
 220 postgres=# <span class="strong">/*+ Set(random_page_cost 2.0) */</span>
 221 postgres-# SELECT * FROM table1 t1 WHERE key = 'value';
 222 ...
 223 </pre>
 224
 225 <h3 id="hint-GUC">GUC parameters for pg_hint_plan</h3>
 226 <p>GUC parameters below affect the behavior of pg_hint_planpg_hint_plan.</p>
 227 <table>
 228 <thead>
 229 <tr>
 230 <tr><th>Parameter name</th><th>description</th><th>Default</th></tr>
 231 </tr></thead>
 232 <tbody>
 233 <tr><td>pg_hint_plan.enable_hint</td>
 234   <td>True enables pg_hint_plan.</td><td>on</td></tr>
 235 <tr><td>pg_hint_plan.enable_hint_table</td>
 236   <td>True enbles hinting by table. true or false.</td><td>off</td></tr>
 237 <tr><td>pg_hint_plan.parse_messages</td>
 238   <td>Specifies the log level of hint parse error. Valid values are error, warning, notice, info, log, debug<n>.</td><td>INFO</td></tr>
 239 <tr><td>pg_hint_plan.debug_print</td>
 240   <td>Controls debug print and verbosity. Valid values are off, on, detailed and verbose.</td><td>off</td></tr>
 241 <tr><td>pg_hint_plan.message_level</td>
 242   <td>Specifies message level of debug print. Valid values are error, warning, notice, info, log, debug<n>.</td><td>INFO</td></tr>
 243 </tbody>
 244 </table>
 245 <h2 id="install">Installation</h2>
 246 This section describes the installation steps.
 247 <h3 id="build">building binary module</h3>
 248 <p>Simply run "make" in the top of the source tree, then "make install" as appropriate user. The PATH environment variable should be set properly for the target PostgreSQL for this process. </p>
 249 <pre>
 250 $ tar xzvf pg_hint_plan-1.x.x.tar.gz
 251 $ cd pg_hint_plan-1.x.x
 252 $ make
 253 $ su
 254 # make install
 255 </pre>
 256
 257 <h3 id="hint-load">Loading pg_hint_plan</h3>
 258 <p>Basically pg_hint_plan does not requires CREATE EXTENSION. Simply loading it by LOAD command will activate it and of course you can load it globally by setting shared_preload_libraries in postgresql.conf. Or you might be interested in ALTER USER SET/ALTER DATABASE SET for automatic loading for specific sessions.
 259 <pre>
 260 postgres=# LOAD 'pg_hint_plan';
 261 LOAD
 262 postgres=# </pre></p>
 263
 264 <p>Do CREATE EXTENSION and SET pg_hint_plan.enable_hint_tables TO on if you are planning to hint tables.</p>
 265
 266
 267 <h2 id="uninstall">Unistallation</h2>
 268 <p>"make uninstall" in the top directory of source tree will uninstall the installed files if you installed from the source tree and it is left available. </p>
 269
 270 <pre>
 271 $ cd pg_hint_plan-1.x.x
 272 $ su
 273 # make uninstall
 274 </pre>
 275
 276 <h2 id="hint_syntax">Details in hinting</h2>
 277 <dl>
 278 <dt>Syntax and placement</dt>
 279 <dd>pg_hint_plan reads hints from only the first block comment and any characters except alphabets, digits, spaces, underscores, commas and parentheses stops parsing immediately. In the following example HashJoin(a b) and SeqScan(a) are parsed as hints but IndexScan(a) and MergeJoin(a b) are not.
 280
 281 <pre>
 282 <span class="strong">postgres=# /*+</span>
 283 <span class="strong">postgres*#    HashJoin(a b)</span>
 284 <span class="strong">postgres*#    SeqScan(a)</span>
 285 <span class="strong">postgres*#  */</span>
 286 <span class="strong">postgres-# /*+ IndexScan(a) */</span>
 287 <span class="strong">postgres-#</span> EXPLAIN SELECT <span class="strong">/*+ MergeJoin(a b) */</span> *
 288 <span class="strong">postgres-#</span>    FROM pgbench_branches b
 289 <span class="strong">postgres-#</span>    JOIN pgbench_accounts a ON b.bid = a.bid
 290 <span class="strong">postgres-#</span>   ORDER BY a.aid;
 291                                       QUERY PLAN
 292 ---------------------------------------------------------------------------------------
 293  Sort  (cost=31465.84..31715.84 rows=100000 width=197)
 294    Sort Key: a.aid
 295    ->  <span class="strong">Hash Join</span>  (cost=1.02..4016.02 rows=100000 width=197)
 296          Hash Cond: (a.bid = b.bid)
 297          ->  <span class="strong">Seq Scan on pgbench_accounts a</span>  (cost=0.00..2640.00 rows=100000 width=97)
 298          ->  Hash  (cost=1.01..1.01 rows=1 width=100)
 299                ->  Seq Scan on pgbench_branches b  (cost=0.00..1.01 rows=1 width=100)
 300 (7 rows)
 301
 302 postgres=# </pre>
 303 </dd>
 304
 305 <dt>Using with PL/pgSQL</dt>
 306 <dd>pg_hint_plan works for queries in PL/pgSQL scripts with some restrictions.
 307 <ul>
 308  <li>Hints affect only on the following kind of queries.
 309  <ul>
 310   <li>Queries that return one row. (SELECT, INSERT, UPDATE and DELETE)</li>
 311   <li>Queries that return multiple rows. (RETURN QUERY)</li>
 312   <li>Dynamic SQL statements. (EXECUTE)</li>
 313   <li>Cursor open. (OPEN)</li>
 314   <li>Loop over results of a query (FOR)</li>
 315  </ul>
 316
 317  <li>A hint comment have to be placed after the first word in a query
 318      as the following since preceding comments are not sent as a part
 319      of the query.</li>
 320 </ul>
 321 <pre>
 322 postgres=# CREATE FUNCTION hints_func(integer) RETURNS integer AS $$
 323 postgres$# DECLARE
 324 postgres$#     id  integer;
 325 postgres$#     cnt integer;
 326 postgres$# BEGIN
 327 postgres$#     SELECT <span class="strong">/*+ NoIndexScan(a) */</span> aid
 328 postgres$#         INTO id FROM pgbench_accounts a WHERE aid = $1;
 329 postgres$#     SELECT <span class="strong">/*+ SeqScan(a) */</span> count(*)
 330 postgres$#         INTO cnt FROM pgbench_accounts a;
 331 postgres$#     RETURN id + cnt;
 332 postgres$# END;
 333 postgres$# $$ LANGUAGE plpgsql;
 334 </pre>
 335 </dd>
 336
 337 <dt>Letter case in the object names</dt>
 338 <dd>Unlike the way PostgreSQL handles object names, pg_hint_plan compares bare object names in hints against the database internal object names in case sensitive way. Therefore an object name TBL in a hint matches only "TBL" in database and does not match any unquoted names like TBL, tbl or Tbl.
 339 </dd>
 340
 341 <dt>Escaping special characters in object names</dt>
 342 <dd>The objects as the hint parameter should be enclosed by double quotes if they includes parentheses, double quotes and white spaces. The escaping rule is the same as PostgreSQL.
 343 </dd>
 344
 345 <h3>Distinction between multiple occurences of a table</h3>
 346 <dd>pg_hint_plan identifies the target object by using aliases if
 347 exists. This behavior is usable to point a specific occurence
 348 among multiple occurences of one table.
 349 <pre>
 350 <span class="strong">postgres=# /*+ HashJoin(t1 t1) */</span>
 351 <span class="strong">postgres-#</span> EXPLAIN SELECT * FROM s1.t1
 352 <span class="strong">postgres-#</span> JOIN public.t1 ON (s1.t1.id=public.t1.id);
 353 INFO:  hint syntax error at or near "HashJoin(t1 t1)"
 354 <span class="strong">DETAIL:  Relation name "t1" is ambiguous.</span>
 355 ...
 356 <span class="strong">postgres=# /*+ HashJoin(pt st) */</span>
 357 <span class="strong">postgres-#</span> EXPLAIN SELECT * FROM s1.t1 st
 358 <span class="strong">postgres-#</span> JOIN public.t1 pt ON (st.id=pt.id);
 359                              QUERY PLAN
 360 ---------------------------------------------------------------------
 361  <span class="strong">Hash Join</span>  (cost=64.00..1112.00 rows=28800 width=8)
 362    Hash Cond: (st.id = pt.id)
 363    ->  Seq Scan on t1 st  (cost=0.00..34.00 rows=2400 width=4)
 364    ->  Hash  (cost=34.00..34.00 rows=2400 width=4)
 365          ->  Seq Scan on t1 pt  (cost=0.00..34.00 rows=2400 width=4)
 366 </pre>
 367 </dd>
 368
 369 <dt>Underlying tables of views or rules</dt>
 370 <dd>Hints are not applicable on views itself, but they can affect the
 371 queries within if the object names match the object names in the
 372 expanded query on the view. Assigning aliases to the tables in a view
 373 enables them to be manipulated from outside the view.
 374 <pre>
 375 <span class="strong">postgres=#</span> CREATE VIEW v1 AS SELECT * FROM <span class="strong">t2</span>;
 376 <span class="strong">postgres=#</span> EXPLAIN <span class="strong">/*+ HashJoin(t1 v1) */</span>
 377           SELECT * FROM t1 JOIN v1 ON (c1.a = v1.a);
 378                             QUERY PLAN
 379 ------------------------------------------------------------------
 380  Hash Join  (cost=3.27..18181.67 rows=101 width=8)
 381    Hash Cond: (t1.a = t2.a)
 382    ->  Seq Scan on t1  (cost=0.00..14427.01 rows=1000101 width=4)
 383    ->  Hash  (cost=2.01..2.01 rows=101 width=4)
 384          ->  Seq Scan on t2  (cost=0.00..2.01 rows=101 width=4)
 385 </pre>
 386 </dd>
 387
 388 <dt>Inheritance tables</dt>
 389 <dd>Hints can point only the parent of an inheritance tables and the
 390 hint affect all the inheritance. Hints simultaneously point directly
 391 to children are not in effect.
 392 </dd>
 393
 394 <dt>Hinting on multistatements</dt>
 395 <dd>One multistatement can have exactly one hint comment and the hints affects all of the individual statement in the multistatement. Notice that the seemingly multistatement on the interactive interface of psql is internally a sequence of single statements so hints affects only on the statement just following.</dd>
 396
 397 <dt>VALUES expressions</dt>
 398 <dd>VALUES expressions in FROM clause are named as *VALUES* internally
 399 so it is hintable if it is the only VALUES in a query. Two or more
 400 VALUES expressions in a query seems distinguishable looking its
 401 explain result. But in reality it is mere a cosmetic and they are not
 402 distinguishable.
 403 <pre>
 404 <span class="strong">postgres=#</span> <span class="strong">/*+ MergeJoin(*VALUES*_1 *VALUES*) */</span>
 405       EXPLAIN SELECT * FROM (VALUES (1, 1), (2, 2)) v (a, b)
 406       JOIN (VALUES (1, 5), (2, 8), (3, 4)) w (a, c) ON v.a = w.a;
 407 INFO:  pg_hint_plan: hint syntax error at or near "MergeJoin(*VALUES*_1 *VALUES*) "
 408 <span class="strong">DETAIL:  Relation name "*VALUES*" is ambiguous.</span>
 409                                QUERY PLAN
 410 -------------------------------------------------------------------------
 411  Hash Join  (cost=0.05..0.12 rows=2 width=16)
 412    Hash Cond: ("*VALUES*_1".column1 = "*VALUES*".column1)
 413    ->  Values Scan on "*VALUES*_1"  (cost=0.00..0.04 rows=3 width=8)
 414    ->  Hash  (cost=0.03..0.03 rows=2 width=8)
 415          ->  Values Scan on "*VALUES*"  (cost=0.00..0.03 rows=2 width=8)
 416 </pre>
 417 </dd>
 418
 419 <h3>Subqueries</h3>
 420 <dd>
 421 <p>Subqueries in the following context occasionally can be hinted using the
 422 name "ANY_subquery".</p>
 423 <pre>
 424 IN (SELECT ... {<span class="strong">LIMIT | OFFSET</span> ...} ...)
 425 = ANY (SELECT ... {<span class="strong">LIMIT | OFFSET</span> ...} ...)
 426 = SOME (SELECT ... {<span class="strong">LIMIT | OFFSET</span> ...} ...)
 427 </pre>
 428 <p>For these syntaxes, planner internally assigns the name to the subquery when planning joins on tables including it, so join hints are applicable on such joins using the implicit name as the following.</p>
 429 <pre>
 430 <span class="strong">postgres=# /*+HashJoin(a1 ANY_subquery)*/</span>
 431 <span class="strong">postgres=#</span> EXPLAIN SELECT *
 432 <span class="strong">postgres=#</span>    FROM pgbench_accounts a1
 433 <span class="strong">postgres=#</span>   WHERE aid IN (SELECT bid FROM pgbench_accounts a2 LIMIT 10);
 434                                          QUERY PLAN
 435
 436 ---------------------------------------------------------------------------------------------
 437  <span class="strong">Hash Semi Join</span>  (cost=0.49..2903.00 rows=1 width=97)
 438    Hash Cond: (a1.aid = a2.bid)
 439    ->  Seq Scan on pgbench_accounts a1  (cost=0.00..2640.00 rows=100000 width=97)
 440    ->  Hash  (cost=0.36..0.36 rows=10 width=4)
 441          ->  Limit  (cost=0.00..0.26 rows=10 width=4)
 442                ->  Seq Scan on pgbench_accounts a2  (cost=0.00..2640.00 rows=100000 width=4)
 443 </pre>
 444 </dd>
 445
 446 <dt>Using IndexOnlyScan hint</dt>
 447 <dd>Index scan may unexpectedly performed on another index when the index specified in IndexOnlyScan hint cannot perform index only scan.</dd>
 448
 449 <dt>Behavior of NoIndexScan</dt>
 450 <dd>NoIndexScan hint involves NoIndexOnlyScan.</dd>
 451
 452 <dt>Parallel hint and UNION</dt>
 453 <dd>A UNION can run in parallel only when all underlying subqueries
 454 are parallel-safe. Conversely enforcing parallel on any of
 455 the subqueries let a parallel-executable UNION run in
 456 parallel. Meanwhile, a parallel hint with zero workers inhibits a scan
 457 from being executed in parallel.</dd>
 458
 459 <dt>Setting pg_hint_plan parameters by Set hints</dt>
 460 <dd><p>pg_hint_plan parameters change the behavior of itself so some parameters doesn't work as expected.</p>
 461 <ul>
 462 <li>Hints to change enable_hint, enable_hint_tables are ignored even though they are reported as "used hints" in debug logs.</li>
 463 <li>Setting debug_print and message_level works from midst of the processing of the target query.</li>
 464 </ul>
 465 </dd>
 466 </dl>
 467
 468 <h2 id="errors">Errors</h2>
 469 <p>pg_hint_plan stops parsing on any error and uses hints already parsed on the most cases. Followings are the typical errors.</p>
 470 <dl>
 471 <dt>Syntax errors </dt>
 472 <dd>Any syntactical errors or wrong hint names are reported as an syntax error. These errors are reported in the server log with the message level which specified by pg_hint_plan.message_level if pg_hint_plan.debug_print is on and aboves.</dd>
 473 <dt>Object misspecifications</dt>
 474 <dd>Object misspecifications results silent ingnorance of the hints. This kind of error is reported as "not used hints" in the server log by the same condition to syntax errors.</dd>
 475
 476 <dt>Redundant or conflicting hints</dt>
 477 <dd>The last hint will be active when redundant hints or hints conflicting with each other. This kind of error is reported as "duplication hints" in the server log by the same condition to syntax errors.</dd>
 478
 479 <dt>Nested comments</dt>
 480 <dd>Hint comment cannot include another block comment within. If pg_hint_plan finds it, differently from other errors, it stops parsing and abandons all hints already parsed. This kind of error is reported in the same manner as other errors. </dd>
 481
 482 <h2 id="func_limits">Functional limitations</h2>
 483 <dt>Influences of some of planner GUC parameters</dt>
 484 <dd>The planner does not try to consider joining order for FROM clause entries more than from_collapse_limit. pg_hint_plan cannot affect joining order as expected for the case.</dd>
 485
 486 <dt>Hints trying to enforce unexecutable plans </dt>
 487 <dd>Planner chooses any executable plans when the enforced plan cannot be executed.
 488 <ul>
 489 <li>FULL OUTER JOIN to use nested loop</li>
 490 <li>To use indexes that does not have columns used in quals</li>
 491 <li>To do TID scans for queries without ctid conditions</li>
 492 </ul>
 493 </dd>
 494
 495 <dt>Queries in ECPG</dt>
 496 <dd>ECPG removes comments in queries written as embedded SQLs so hints cannot be passed form those queries. The only exception is that EXECUTE command passes given string unmodified. Please consider hint tables in the case.</dd>
 497
 498 <dt>Work with pg_stat_statements</dt>
 499 <dd>pg_stat_statements generates a query id ignoring comments. As the result the identical queires with different hints are summarized as the same query.</dd>
 500
 501 <h2 id="requirement">Requirements</h2>
 502 pg_hint_plan14 1.6 requires PostgreSQL 14.
 503 <dl>
 504 <dt>PostgreSQL versions tested</dt>
 505   <dd>Version 14</dd>
 506 <dt>OS versions tested</dt>
 507   <dd>CentOS 8.5</dd>
 508 </dl>
 509
 510 <h2 id="seealso">See also</h2>
 511 <h3 id="postgresql_document">PostgreSQL documents</h3>
 512 <a href="http://www.postgresql.org/docs/current/static/sql-explain.html">EXPLAIN</a>
 513 <a href="http://www.postgresql.org/docs/current/static/sql-set.html">SET</a>
 514 <a href="http://www.postgresql.org/docs/current/static/runtime-config.html">Server Config</a>
 515 <a href="http://www.postgresql.org/docs/current/static/parallel-plans.html">Parallel Plans</a>
 516 <hr>
 517
 518 <div class="navigation">
 519   <a href="pg_hint_plan.html">pg_hint_plan</a>
 520 </div>
 521
 522 <p class="footer">Copyright (c) 2012-2022, NIPPON TELEGRAPH AND TELEPHONE CORPORATION</p>
 523 </body>
 524 </html>