• R/O
  • HTTP
  • SSH
  • HTTPS

pg_hint_plan: Commit

firtst release


Commit MetaInfo

Revisionf348aa33e27dcc953330755428fa1395ce820dc9 (tree)
Time2019-01-17 15:20:53
AuthorKyotaro Horiguchi <horiguchi.kyotaro@lab....>
CommiterKyotaro Horiguchi

Log Message

Fix documentation.

The documentation contains some stale description or missing
items. Fix it.

Change Summary

Incremental Difference

--- a/doc/hint_list-ja.html
+++ b/doc/hint_list-ja.html
@@ -36,13 +36,12 @@
3636 継承関係の親テーブルとそのテーブルのインデックスを指定した場合は、子テーブルに対してそのインデックスと同様の定義のインデックスを選択します。</td></tr>
3737 <tr><td nowrap>IndexOnlyScan(テーブル[ インデックス...])</td>
3838 <td>指定したテーブルについて、Index Only ScanとIndex Scanのうちコストが最小となるスキャン方式を選択します。インデックスも指定した場合は、指定したインデックスの中でIndex Only ScanとIndex Scanのうちコストが最小となるスキャン方式を選択します。ただし、インデックスが存在しない場合や指定したインデックスがWHERE句やJOIN条件などに関連しない場合はSeq Scanを選択します。また、これらの場合以外にも、インデックスが持つ値だけでなくテーブルの値も必要な場合はIndex Scanを選択します。<br>
39-継承関係の親テーブルとそのテーブルのインデックスを指定した場合は、子テーブルに対してそのインデックスと同様の定義のインデックスを選択します。
40-PostgreSQL 9.2以降で動作します。</td></tr>
39+継承関係の親テーブルとそのテーブルのインデックスを指定した場合は、子テーブルに対してそのインデックスと同様の定義のインデックスを選択します。</td></tr>
4140 <tr><td nowrap>BitmapScan(テーブル[ インデックス...])</td>
4241 <td>指定したテーブルについて、Bitmap Scanを選択します。インデックスも指定した場合は、指定したインデックスの中でコストが最小となるインデックスを選択します。ただし、インデックスが存在しない場合や指定したインデックスがWHERE句やJOIN条件などに関連しない場合はSeq Scanを選択します。<br>
4342 継承関係の親テーブルとそのテーブルのインデックスを指定した場合は、子テーブルに対してそのインデックスと同様の定義のインデックスを選択します。</td></tr>
4443 <tr><td nowrap>IndexScanRegexp(テーブル[ POSIX正規表現...])</br>IndexOnlyScanRegexp(テーブル[ POSIX正規表現...])</br>BitmapScanRegexp(テーブル[ POSIX正規表現...])</td>
45- <td>テーブルのみを指定した場合のスキャン方式の選択基準は、Regexpの付かないスキャン方式のヒントと同じです。<a href="http://www.postgresql.jp/document/current/html/functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX正規表現</a>も指定した場合は、指定したPOSIX正規表現パターンに一致するインデックスの中でコストが最小となるスキャン方式を選択します。指定したテーブルが継承テーブルの場合は、子テーブルについても同じ基準で、使用するインデックスとスキャン方式を選択します。IndexOnlyScanRegexpヒントはPostgreSQL 9.2以降で動作します。</td></tr>
44+ <td>テーブルのみを指定した場合のスキャン方式の選択基準は、Regexpの付かないスキャン方式のヒントと同じです。<a href="http://www.postgresql.jp/document/current/html/functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX正規表現</a>も指定した場合は、指定したPOSIX正規表現パターンに一致するインデックスの中でコストが最小となるスキャン方式を選択します。指定したテーブルが継承テーブルの場合は、子テーブルについても同じ基準で、使用するインデックスとスキャン方式を選択します。</td></tr>
4645 <tr><td nowrap>NoSeqScan(テーブル)</td>
4746 <td>指定したテーブルについて、Seq Scan以外でコストが最小となるスキャン方式を選択します。ただし、他のスキャン方式を選択できない場合は、Seq Scanを選択します。</td></tr>
4847 <tr><td nowrap>NoTidScan(テーブル)</td>
@@ -50,7 +49,7 @@ PostgreSQL 9.2以降で動作します。</td></tr>
5049 <tr><td nowrap>NoIndexScan(テーブル)</td>
5150 <td>指定したテーブルについて、Index ScanとIndex Only Scanを除いたスキャン方式の中でコストが最小となるスキャン方式を選択します。</td></tr>
5251 <tr><td nowrap>NoIndexOnlyScan(テーブル)</td>
53- <td>指定したテーブルについて、Index Only Scan以外でコストが最小となるスキャン方式を選択します。PostgreSQL 9.2以降で動作します。</td></tr>
52+ <td>指定したテーブルについて、Index Only Scan以外でコストが最小となるスキャン方式を選択します。</td></tr>
5453 <tr><td nowrap>NoBitmapScan(テーブル)</td>
5554 <td>指定したテーブルについて、Bitmap Scan以外でコストが最小となるスキャン方式を選択します。</td></tr>
5655
--- a/doc/hint_list.html
+++ b/doc/hint_list.html
@@ -34,7 +34,7 @@
3434 <tr><td nowrap>IndexScan(table[ index...])</td>
3535 <td>Forces index scan on the table. Restricts to specified indexes if any. </td></tr>
3636 <tr><td nowrap>IndexOnlyScan(table[ index...])</td>
37- <td>Forces index only scan on the table. Rstricts to specfied indexes if any. Index scan may be used if index only scan is not available. Available for PostgreSQL 9.2 and later.</td></tr>
37+ <td>Forces index only scan on the table. Restricts to specfied indexes if any. Index scan may be used if index only scan is not available.</td></tr>
3838 <tr><td nowrap>BitmapScan(table[ index...])</td>
3939 <td>Forces bitmap scan on the table. Restoricts to specfied indexes if any.</td></tr>
4040 <tr><td nowrap>NoSeqScan(table)</td>
@@ -42,10 +42,9 @@
4242 <tr><td nowrap>NoTidScan(table)</td>
4343 <td>Forces not to do TID scan on the table. </td></tr>
4444 <tr><td nowrap>NoIndexScan(table)</td>
45- <td>Forces not to do index scan and index only scan (For PostgreSQL
46- 9.2 and later) on the table. </td></tr>
45+ <td>Forces not to do index scan and index only scan on the table. </td></tr>
4746 <tr><td nowrap>NoIndexOnlyScan(table)</td>
48- <td>Forces not to do index only scan on the table. Available for PostgreSQL 9.2 and later.</td></tr>
47+ <td>Forces not to do index only scan on the table.</td></tr>
4948 <tr><td nowrap>NoBitmapScan(table)</td>
5049 <td>Forces not to do bitmap scan on the table. </td></tr>
5150
--- a/doc/pg_hint_plan-ja.html
+++ b/doc/pg_hint_plan-ja.html
@@ -326,27 +326,12 @@ postgres-# ORDER BY a.aid;
326326 <tr><td>pg_hint_plan.enable_hint_table</td>
327327 <td>ヒントをテーブルで指定する機能を有効または無効にします。</td><td>off</td></tr>
328328 <tr><td>pg_hint_plan.debug_print</td>
329- <td>指定したヒントが実行計画生成にどのように影響したかを出力します。メッセージはLOGメッセージレベルで出力されますので、デフォルトではサーバログに出力され、クライアントには渡されません。</td><td>off</td></tr>
329+ <td>指定したヒントが実行計画生成にどのように影響したかを出力します。off、on、detailed、verbose が指定可能です。メッセージはLOGメッセージレベルで出力されますので、デフォルトではサーバログに出力され、クライアントには渡されません。</td><td>off</td></tr>
330330 <tr><td>pg_hint_plan.parse_messages</td>
331331 <td>指定したヒントを解釈できなかった場合に、どのメッセージ階層でログを出力するかを指定します。有効な値は、debug5、debug4、debug3、debug2、debug1、log、info、notice、warning、またはerrorです。fatalとpanicは指定できません。</td><td>info</td></tr>
332332
333333 </tbody>
334334 </table>
335-<p>
336-PostgreSQL 9.1の環境でこれらのパラメータをpostgresql.confファイルで設定するには、<a href="http://www.postgresql.jp/document/9.1/html/runtime-config-custom.html#GUC-CUSTOM-VARIABLE-CLASSES">custom_variable_classes</a>にpg_hint_planを加える必要があります。
337-典型的な使用例は以下のようになります。
338-</p>
339-<pre>
340-# postgresql.conf
341-shared_preload_libraries = 'pg_hint_plan'
342-
343-custom_variable_classes = 'pg_hint_plan' # 9.2以降は廃止されたため記述不要
344-pg_hint_plan.parse_messages = 'debug2'
345-</pre>
346-<p>
347-PostgreSQL 9.2以降ではcustom_variable_classesは廃止されているため、pg_hint_planのGUCパラメータを標準のGUCパラメータと同様に記述することができます。
348-</p>
349-
350335 <h2 id="install">インストール</h2>
351336 <p>pg_hint_planのインストール方法について説明します。</p>
352337
@@ -493,7 +478,9 @@ postgres$# END;
493478 postgres$# $$ LANGUAGE plpgsql;
494479 </pre>
495480 </dd>
496-<dt>オブジェクト名の引用符付け</dt>
481+<dt>ヒント句内のオブジェクト名の文字ケース</dt>
482+<dd>PostgreSQL は引用符で囲われないオブジェクト名を文字ケースを無視して扱いますが、pg_hint_plan は指定されたオブジェクト名の文字ケースはそのまま PostgreSQL の内部表現と比較します。つまり、ヒント句で TBL と指定した場合、データベース上で "TBL" と定義したもののみと合致し, TBL, tbl, Tbl など引用符で囲われないオブジェクト名とは合致しません。</dd>
483+<dt>ヒント句内のオブジェクト名の引用符付け</dt>
497484 <dd>ヒントに記述するオブジェクト名や別名が括弧((、)のいずれか)、二重引用符(")、空白(スペース、タブ、改行のいずれか)を含む場合は、通常のSQL文で使う場合と同じように二重引用符(")で囲んでください。二重引用符を含むオブジェクト名は、全体を二重引用符で括ったうえで、内部に含む二重引用符を二重引用符でエスケープしてください(例: 「quoted"table"name」→「"quoted""table""name"」)。</dd>
498485 <dt>同一名称テーブルの区別</dt>
499486 <dd>スキーマ違いや同一テーブルの複数回使用などでクエリ中に同一名称のテーブルが複数回出現する場合は、テーブルに別名をつけてそれぞれのテーブルを区別してください。以下の例の1つ目のSQL文では、HashJoin(t1 t1)をヒントに指定したとき、ヒント句対象のオブジェクトが特定できずにエラーになっています。2つ目のSQL文では、各テーブルにptやstという別名をつけているため、実行計画作成時にヒントで指定した通りにHash Joinを選択しています。</p>
@@ -626,14 +613,13 @@ postgres=# WHERE aid IN (SELECT bid FROM pgbench_accounts a2 LIMIT 10);
626613
627614 postgres=#
628615 </pre>
629-一つのクエリで上記のような副問い合わせを複数使用している場合は、「ANY_subquery」と指定しても対象を特定できないため、ヒント句はエラーとなり無視されます。</br>
630-</dd>
631-<dt>IndexOnlyScanヒント句の指定(PostgreSQL 9.2以降)</dt>
632-<dd>ヒント句の対象となるテーブルにIndex Only Scanが可能なインデックスとIndex Only Scanが不可能なインデックスが存在する場合、Index Only Scanが可能なインデックスをテーブルと併せてIndexOnlyScanヒント句に指定しないとIndex Scanが選択されることがあります。</dd>
633-<dt>NoIndexScanヒント句の注意点(PostgreSQL 9.2以降)</dt>
634-<dd>PostgreSQL 9.2以降でNoIndexScanヒント句を指定した場合は、Index ScanだけでなくIndex Only Scanも選択されません。</dd>
635-</dl>
616+<dt>IndexOnlyScanヒント</dt>
617+<dd>ヒント句の対象となるテーブルにIndex Only Scanが可能なインデックスとIndex Only Scanが不可能なインデックスが同時に存在する場合、Index Only Scanが可能なインデックスをテーブルに対してIndexOnlyScanヒント句を追加で指定しないとIndex Scanが選択されることがあります。</dd>
636618
619+<dt>NoIndexScanヒント</dt>
620+<dd>NoIndexScanヒント句を指定した場合は、Index ScanだけでなくIndex Only Scanも選択されません。</dd>
621+</dl>
622+</dd>
637623 <h3>ヒント指定エラーの扱い</h3>
638624 <dt>構文エラー</dt>
639625 <dd>ヒント句の記述に構文上の誤りがあった場合、pg_hint_planは誤った記述より前のヒント句のみ有効とし、誤った記述以降のヒント句を無視してクエリを実行します。誤りの内容はpg_hint_plan.parse_messagesで指定したレベルでサーバログに記録されます。
@@ -674,15 +660,15 @@ postgres=#
674660 </dd>
675661 <dt>ECPGにおける制限</dt>
676662 <dd>ECPGで実装したアプリケーションから発行するクエリにヒントをコメントで指定した場合、実行計画を制御できません。これは、CプリプロセッサがCコードに変換するタイミングで、全てのブロックコメントを取り除いてしまうためです。ただし、C言語文字列に格納したクエリをEXECUTEコマンドで実行する動的SQLの場合は、コメントでヒントを指定しても実行計画を制御できます。</dd>
677-<dt>ヒントによるフィンガープリントの変化</dt>
678-<dd>SQLコメントでヒントを指定した場合、SQL文フィンガープリントベースのクエリキャッシュなどでは、ヒントが異なれば別のSQL文として扱われます。pg_stat_statementも9.1では別クエリとして集計しますが、9.2ではクエリ集約機能によりコメントが除去されるので、コメントで指定したヒントのみが異なるクエリは同じクエリとして扱われます。</dd>
663+<dt>ヒントの pg_stat_statements への影響</dt>
664+<dd>SQLコメントでヒントを指定した場合、pg_stat_statements では、コメントで指定したヒントのみが異なるクエリは同じクエリとして扱われます。</dd>
679665
680666 </dl>
681667
682668 <h2 id="requirement">動作環境</h2>
683669 <dl>
684670 <dt>PostgreSQL</dt>
685- <dd>バージョン 9.4</dd>
671+ <dd>バージョン 9.4-11</dd>
686672 <dt>動作確認済みOS</dt>
687673 <dd>RHEL 7.5</dd>
688674 </dl>
--- a/doc/pg_hint_plan.html
+++ b/doc/pg_hint_plan.html
@@ -108,16 +108,14 @@ postgres=# </pre>
108108 <tbody>
109109 <tr><td>pg_hint_plan.enable_hint</td>
110110 <td>Enbles or disables the function of pg_hint_plan.</td><td>on</td></tr>
111+<tr><td>pg_hint_plan.enable_hint_table</td>
112+ <td>Enbles or disables table-based hinting.</td><td>on</td></tr>
111113 <tr><td>pg_hint_plan.debug_print</td>
112- <td>Enables and select the verbosity of the debug output of pg_hint_plan. off, on, detailed and verbose are valid.</td><td>off</td></tr>
114+ <td>Enables and select the verbosity of the debug output of pg_hint_plan. Valid options are off, on, detailed and verbose.</td><td>off</td></tr>
113115 <tr><td>pg_hint_plan.message_level</td>
114116 <td>Specifies the message level of debug prints. error, warning, notice, info, log, debug<n> are valid and fatal and panic are inhibited.</td><td>info</td></tr>
115117 </tbody>
116118 </table>
117-<p>
118-PostgreSQL 9.1 requires a custom variable class to be defined for those GUC parameters. See <a href="http://www.postgresql.org/docs/9.1/static/runtime-config-custom.html#GUC-CUSTOM-VARIABLE-CLASSES">custom_variable_classes</a> for details.
119-</p>
120-
121119 <h2 id="install">Installation</h2>
122120 This section describes the installation steps.
123121 <h3 id="build">building binary module</h3>
@@ -213,8 +211,9 @@ postgres-# SELECT * FROM table1 t1 WHERE key = 'value';
213211 </p>
214212
215213 <h2 id="hint_syntax">Hint syntax</h2>
216-<h3>Hint comment location</h3>
217-<p>pg_hint_plan reads hints from only the first block comment, and any characters except alphabets, digits, spaces, underscores, commas and parentheses are not allowed before the comment. In the following example HashJoin(a b) and SeqScan(a) are recognized as Hint and IndexScan(a) and MergeJoin(a b) is not. </p>
214+<dl>
215+<dt>Hint comment location</dt>
216+<dd>pg_hint_plan reads hints from only the first block comment, and any characters except alphabets, digits, spaces, underscores, commas and parentheses are not allowed before the comment. In the following example HashJoin(a b) and SeqScan(a) are recognized as Hint and IndexScan(a) and MergeJoin(a b) is not.
218217 <pre>
219218 postgres=# /*+
220219 postgres*# <span class="strong">HashJoin(a b)</span>
@@ -237,13 +236,50 @@ postgres-# ORDER BY a.aid;
237236 (7 rows)
238237
239238 postgres=# </pre>
240-<h3>Escaping special chacaters in object names</h3>
241-<p>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.
242-</p>
243-<h3>Distinction among table occurrences with the same name </h3>
244-<p>Target name duplication caused by multiple occurrences of the same object or objects with the same name in different name spaces can be avoided by giving alias names for each occurrence in the target query and using them in hint phases.
239+</dd>
240+
241+<dt>Using with PL/pgSQL</dt>
242+<dd>pg_hint_plan works for queries in PL/pgSQL scripts with some restrictions.
243+<ul>
244+ <li>Hints affect only on the following kind of queires.
245+ <ul>
246+ <li>Queries that returns one row. (SELECT, INSERT, UPDATE and DELETE)</li>
247+ <li>Queries that returns multiple rows. (RETURN QUERY)</li>
248+ <li>Dynamic SQL statements. (EXECUTE)</li>
249+ <li>Cursor open. (OPEN)</li>
250+ <li>Loop over result of a query (FOR)</li>
251+ </ul>
252+
253+ <li>A hint comment have to be placed after the first word in a query
254+ as the following since preceding comments are not sent as a part
255+ of the query.</li>
256+</ul>
257+<pre>
258+postgres=# CREATE FUNCTION hints_func(integer) RETURNS integer AS $$
259+postgres$# DECLARE
260+postgres$# id integer;
261+postgres$# cnt integer;
262+postgres$# BEGIN
263+postgres$# SELECT <b><u>/*+ NoIndexScan(a) */</u></b> aid
264+postgres$# INTO id FROM pgbench_accounts a WHERE aid = $1;
265+postgres$# SELECT <b><u>/*+ SeqScan(a) */</u></b> count(*)
266+postgres$# INTO cnt FROM pgbench_accounts a;
267+postgres$# RETURN id + cnt;
268+postgres$# END;
269+postgres$# $$ LANGUAGE plpgsql;
270+</pre>
271+</dd>
272+
273+<dt>Letter case in a hinted object</dt>
274+<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.
275+</dd>
276+
277+<dt>Escaping special chacaters in object names</dt>
278+<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.
279+</dd>
280+<dt>Distinction among table occurrences with the same name </dt>
281+<dd>Target name duplication caused by multiple occurrences of the same object or objects with the same name in different name spaces can be avoided by giving alias names for each occurrence in the target query and using them in hint phases.
245282 The example below, the first SQL statement results in error from using a table name appeared twice in the target query, while the second example works since each occurrence of table t1 is given a distinct alias name and specified in the HashJoin hint using it.
246-</p>
247283 <pre>
248284 postgres=# /*+ <span class="strong">HashJoin(t1 t1)</span>*/
249285 postgres-# EXPLAIN SELECT * FROM s1.t1
@@ -273,28 +309,42 @@ postgres-# JOIN public.t1 pt ON (st.id=pt.id);
273309 -> Hash (cost=34.00..34.00 rows=2400 width=4)
274310 -> Seq Scan on t1 pt (cost=0.00..34.00 rows=2400 width=4)
275311 (5 行)
312+</dd>
276313
277-postgres=#</pre>
278-</p>
279-<h2 id="restrictions">Restrictions</h2>
280-<h3>Limitations on multiple VALUES lists in FROM clauses</h3>
281-<p>All occurences of VALUES lists in FROM clauses in a query has the same name "*VALUES*" irrespective of aliases syntactically given to them or shown in explain descriptions. So it cannot be hinted at all if appeares twice or more in a target query. </p>
282-<h3>Hinting on inheritance children</h3>
283-<p>Inheritnce children cannot be hinted individually. They share the same hints on their parent.</p>
284-
285-<h3>Setting pg_hint_plan parameters by Set hints</h3>
286-<p>pg_hint_plan paramters changes the behavior of itself so some parameters doesn't work as expected.</p>
287-<ul>
288-<li>Hints to change enable_hint, enable_hint_tables are ignored, but they are reported as "used hints" in debug logs.</li>
289-<li>Setting debug_print and message_level works from midst of the processing of the target query.</li>
290-</ul>
291-
292-
293-<h2 id="technics">Technics to hint on desired targets</h2>
294-<h3>Hinting on objecects implicitly used in the target query</h3>
295-<p>Hints are effective on any objects with the target name even if they aren't aparent in the query, specifically objects in views. For that reason, you should create different views in which targetted objects have distinct aliases if you want to hint them differently from the first view.</p>
296-<p>In the following examples, the first query is assigning the same name "t1" on the two occurrences of the table1 so the hint SeqScan(t1) affects both scans. On the other hand the second assignes the different name 't3' on the one of them so the hint affects only on the rest one.</p>
297-<p>This mechanism also applies on rewritten queries by rules.</p>
314+<dt>Underlying tables of views or rules</dt>
315+<dd>Hints are not applicable on views itself, but they can affect the
316+queries within if the object names match the object names in the
317+expanded query on the view. Assigning aliases to the tables in a view
318+enables them to be manipulated from outside the view.
319+<pre>
320+<b>postgres=#</b> CREATE VIEW v1 AS SELECT * FROM <b><u>t2</u></b>;
321+<b>postgres=#</b> EXPLAIN <b>/*+ HashJoin(t1 v1) */</b>
322+ SELECT * FROM t1 JOIN v1 ON (c1.a = v1.a);
323+ QUERY PLAN
324+------------------------------------------------------------------
325+ Hash Join (cost=3.27..18181.67 rows=101 width=8)
326+ Hash Cond: (t1.a = t2.a)
327+ -> Seq Scan on t1 (cost=0.00..14427.01 rows=1000101 width=4)
328+ -> Hash (cost=2.01..2.01 rows=101 width=4)
329+ -> Seq Scan on t2 (cost=0.00..2.01 rows=101 width=4)
330+</pre>
331+</dd>
332+
333+<dt>Inheritance tables</dt>
334+<dd>Hints can point only the parent of an inheritance tables and the
335+hint affect all the inheritance. Hints simultaneously point directly
336+to children are not in effect.
337+</dd>
338+
339+<dt>Hinting on multistatements</dt>
340+<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>
341+
342+<dt>VALUES expressions</dt>
343+<dd>VALUES expressions in FROM clause are named as *VALUES* internally
344+so it is hintable if it is the only VALUES in a query. Two or more
345+VALUES expressions in a query seems distinguishable looking its
346+explain result. But in reality it is mere a cosmetic and they are not
347+distinguisable.
298348 <pre>
299349 postgres=# CREATE VIEW view1 AS SELECT * FROM table1 <span class="strong">t1</span>;
300350 CREATE TABLE
@@ -321,14 +371,15 @@ postgres=# EXPLAIN SELECT * FROM table1 <span class="strong">t3</span> JOIN view
321371 (5 rows)
322372
323373 </pre>
324-<h3>Hinting on the hinheritance children</h3>
325-<p>Hints targeted on inheritance parents automatically affect on all their own children. Child tables cannot have their own hint specified. </p>
374+</dd>
375+<dt>Hinting on the hinheritance children</dt>
376+<dd>Hints targeted on inheritance parents automatically affect on all their own children. Child tables cannot have their own hint specified. </dd>
326377
327-<h3>Scope of hints on multistatement</h3>
328-<p>One multistatement description 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. Conversely, every single statement have their own hint comments affect on them.</p>
378+<dt>Scope of hints on multistatement</dt>
379+<dd>One multistatement description 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. Conversely, every single statement have their own hint comments affect on them.</dd>
329380
330-<h3>Subqueries in some contexts</h3>
331-<p>Subqueries in the following context also can be hinted.</p>
381+<dt>Subqueries in some contexts</dt>
382+<dd>Subqueries in the following context also can be hinted.
332383 <pre>
333384 IN (SELECT ... {LIMIT | OFFSET ...} ...)
334385 = ANY (SELECT ... {LIMIT | OFFSET ...} ...)
@@ -351,49 +402,51 @@ postgres=# WHERE aid IN (SELECT bid FROM pgbench_accounts a2 LIMIT 10);
351402 -> Seq Scan on pgbench_accounts a2 (cost=0.00..2640.00 rows=100000 width=4)
352403 (6 rows)
353404 </pre>
405+</dd>
354406
355-<h3>Using IndexOnlyScan hint (PostgreSQL 9.2 and later)</h3>
356-<p>You shoud explicitly specify an index that can perform index only scan if you put IndexOnlyScan hint on a table that have other indexes that cannot perform index only scan. Or pg_hint_plan may select them. </p>
357-
358-<h3>Precaution points for NoIndexScan hint (PostgreSQL 9.2 and later)</h3>
359-<p>NoIndexScan hint involes NoIndexOnlyScan.</p>
407+<dt>Using IndexOnlyScan hint</dt>
408+<dd>You shoud explicitly specify an index that can perform index only scan if you put IndexOnlyScan hint on a table that have other indexes that cannot perform index only scan. Or pg_hint_plan may select them. </dd>
360409
410+<dt>Using NoIndexScan hint</dt>
411+<dd>NoIndexScan hint involes NoIndexOnlyScan.</dd>
412+</dl>
361413
362414 <h2 id="errors">Errors of hints</h2>
363-<p>pg_hint_plan stops parsing on any error and uses hints already parsed on the most cases. Followings are the typical errors.</p>
364-<h3>Syntax errors </h3>
365-<p>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.</p>
366-<h3>Object misspecifications</h3>
367-<p>Object misspecifications results silent ingorance of the hints. This kind of error is reported as "not used hints" in the server log by the same condtion to syntax errors.</p>
415+<dl>pg_hint_plan stops parsing on any error and uses hints already parsed on the most cases. Followings are the typical errors.
416+<dt>Syntax errors </dt>
417+<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>
418+<dt>Object misspecifications</dt>
419+<dd>Object misspecifications results silent ingorance of the hints. This kind of error is reported as "not used hints" in the server log by the same condtion to syntax errors.</dd>
368420
369-<h3>Redundant or conflicting hints</h3>
370-<p>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.</p>
421+<dt>Redundant or conflicting hints</dt>
422+<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>
371423
372-<h3>Nested comments</h3>
373-<p>Hint comment cannot include another block comment within. If pg_hint_plan finds it, differently from other erros, it stops parsing and abandans all hints already parsed. This kind of error is reported in the same manner as other errors. </p>
424+<dt>Nested comments</dt>
425+<dd>Hint comment cannot include another block comment within. If pg_hint_plan finds it, differently from other erros, it stops parsing and abandans all hints already parsed. This kind of error is reported in the same manner as other errors. </dd>
426+</dl>
374427
375428 <h2 id="func_limits">Functional limitations</h2>
376-<h3>Influences of some planner GUC parameters</h3>
377-<p>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.</p>
429+<dl>
430+<dt>Influences of some planner GUC parameters</dt>
431+<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>
378432
379-<h3>Cases that pg_hint_plan essentially cannot affect </h3>
380-<p>By the nature of pg_hint_plan, it cannot affect some cases that out of scope of the planner like following.</p>
433+<dt>Hints trying to enforce unexecutable plans </dt>
434+<dd>pg_hint_plan doesn't enforce plans that cannot be executed.</dd>
381435 <ul>
382436 <li>FULL OUTER JOIN to use nested loop</li>
383437 <li>To use indexes that does not have columns used in quals</li>
384438 <li>To do TID scans for queries without ctid conditions</li>
385439 </ul>
440+</dd>
386441
387-<h3>Queries in ECPG</h3>
388-<p>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 unmodifed. Please consider hint tables for this case.</p>
389-
390-<h3>Effects on query fingerprints</h3>
391-<p>The same queries with different commnets yields the same fingerprint by pg_stat_statements on PostgreSQL 9.2 and later, but they yield different fingerprints on 9.1 and earlier, so the same queires with different hints are summerized as separate queries on such versions.</p>
442+<dt>Queries in ECPG</dt>
443+<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 unmodifed. Please consider using hint tables in the case.</dd>
444+</dl>
392445
393446 <h2 id="requirement">Requirements</h2>
394447 <dl>
395448 <dt>PostgreSQL versions tested</dt>
396- <dd>Version 9.4</dd>
449+ <dd>Version 9.4-11</dd>
397450 <dt>OS versions tested</dt>
398451 <dd>RHEL 7.5</dd>
399452 </dl>
--- a/doc/style.css
+++ b/doc/style.css
@@ -54,6 +54,15 @@ th, td {
5454 padding: 0.2em;
5555 }
5656
57+dt {
58+ font-weight: 600;
59+ margin-top: 1em;
60+ margin-left: 1em;
61+}
62+dd {
63+ margin-top: 0.5em;
64+}
65+
5766 thead th {
5867 background: #f2f2f2;
5968 text-align: center;
Show on old repository browser