<!DOCTYPE HTML PUBLIC "-//W3C//DTD html 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
+<html lang="ja">
<head>
<title>pg_hint_plan</title>
<!-- Uncoment after the tool has been hosted somewhere.
</head>
<body>
-<h1 id="pg_hint_plan">pg_hint_plan 1.0.0</h1>
+<h1 id="pg_hint_plan">pg_hint_plan 1.6</h1>
<div class="navigation">
<a href="pg_hint_plan-ja.html">pg_hint_plan</a>
</div>
<div class="index">
<ol>
-<li><a href="#name">pg_hint_planとは？</a></li>
-<li><a href="#description">機能概要</a></li>
-<li><a href="#install">インストール</a>
-<ol>
- <li><a href="#requirement">動作環境</a></li>
- <li><a href="#build">ビルド</a></li>
-</ol>
-</li>
+<li><a href="#name">名前</a></li>
+<li><a href="#synopsis">概要</a></li>
+<li><a href="#description">機能説明</a>
+<li><a href="#install">インストール</a></li>
<li><a href="#uninstall">アンインストール</a></li>
-<li><a href="#usage">使い方</a>
-<ol>
- <li><a href="#hint-load">pg_hint_planのロード</a></li>
- <li><a href="#hint-rule">ヒントの記述方法</a></li>
- <li><a href="#hint-group">ヒントのグループ</a></li>
- <li><a href="#hint-GUC">pg_hint_planのGUCパラメータ</a></li>
-</ol>
-</li>
<li><a href="#restrictions">使用上の注意と制約</a></li>
+<li><a href="#requirement">動作環境</a></li>
<li><a href="#seealso">関連項目</a></li>
-<li><a href="hint_list-ja.html">Appendix A. ヒント一覧</a></li>
+<li><a href="hint_list-ja.html">Appendix A. ヒント句一覧</a></li>
</div>
-<h2 id="name">pg_hint_planとは？</h2>
-<p>pg_hint_planは、元のSQL文を変えずに実行計画を制御するためのツールです。</p>
+<h2 id="name">名前</h2>
+<p>pg_hint_plan -- 実行計画を示すヒントをクエリに指定することで、SQL文やGUCパラメータを変えずに実行計画を制御します。</p>
-<h2 id="description">機能概要</h2>
-<p>pg_hint_planを用いると、ヒントを記述したブロックコメントをSQL文の前に加えることで、実行計画を制御することができます。</p>
+<h2 id="synopsis">概要</h2>
+<p>PostgreSQLのプランナははコストベースでのオプティマイズを行なっており、SQL文と統計情報を元に可能な実行計画のコストを見積もり、最もコストの低い実行計画を選択します。プランナは可能な限りよい実行計画を作成しようとしますが、例えばカラム間の相関関係などは考慮しないため、複雑なクエリでは常に最適なプランを選択するとは限りません。</p>
+<p>pg_hint_planを用いると、ヒントでスキャン方式や結合方式を指定することで、SQL文やGUCパラメータを変更することなく実行計画を制御することができます。</p>
-<h2 id="install">インストール</h2>
-<p>pg_hint_planのインストール方法について説明します。</p>
+<h2 id="description">機能説明</h2>
+<p>pg_hint_planの機能について説明するにあたり、まず文中で使用されている用語について説明します。</p>
+<table>
+<thead>
+<tr>
+<tr><th>用語</th><th>説明</th></tr>
+</tr></thead>
+<tbody>
+<tr><td>ヒント句</td>
+ <td>実行計画を制御するための情報です。</td></tr>
+ <tr><td>ヒント</td>
+ <td>実行計画を制御したいクエリに適用するヒント句を列挙したものです。</td></tr>
+</tbody>
+</table>
-<h3 id="requirement">動作環境</h3>
-<dl>
-<dt>PostgreSQL</dt>
- <dd>バージョン 9.1.4</dd>
-<dt>動作検証済みOS</dt>
- <dd>RHEL 6.1</dd>
-</dl>
+<h3 id="hint-rule">ヒントの指定方法</h3>
+<p>ヒントは二つの方法で指定することができます。</p>
+<ul>
+<li>コメントでの指定</li>
+<p>特殊なSQLブロックコメント内にヒントを記述します。</p>
+<li>テーブルでの指定</li>
+<p>ヒント用のテーブルにヒントを登録します。</p>
+</ul>
+<p>特定のアプリケーションではヒントをコメントで指定することができないため、「テーブルでの指定」でヒントを指定します。なお、「コメントでの指定」と異なり、アプリケーションのソースコードに手を入れずに指定するヒントを変更することができます。</p>
-<h3 id="build">ビルド</h3>
-<p>pg_hint_planをソースコードからビルドする場合、pg_hint_planのソースを展開したディレクトリでmake → make installの順に実行してください。make installはPostgreSQLをインストールしたOSユーザで実行してください。なお、pg_hint_planのビルドにはpgxsを使用するので、RPM版のPostgreSQLを使用している環境では、postgresql-devel パッケージが必要です。</p>
-<p>以下にビルドの例を示します。</p>
+<h4 id="hint-comment">コメントでの指定</h4>
+<p>指定したいヒントを、実行計画を制御したいクエリの先頭または途中のSQLブロックコメントの中に記述します。</p>
+<p>ヒント用コメントと通常のコメントを区別するために、ヒント用のブロックコメントは「<span class="bold">/*+</span>」で始めます。ヒントの対象は、カッコ内にオブジェクト名または別名で指定します。オブジェクト名は、スペース、タブ、または改行のいずれかで区切って指定します。</p>
+<p>以下の例では、HashJoinとSeqScanヒント句により、pgbench_accountsテーブルに対するSeq Scanの結果をHash Joinする実行計画が選択されています。なおかつ、Setヒント句によりこのクエリの実行計画を作成する間だけrandom_page_costが2.0に変更されています。</p>
<pre>
-$ tar xzvf pg_hint_plan-1.0.0.tar.gz
-$ cd pg_hint_plan-1.0.0
-$ make
-$ su
-# make install
+<span class="strong">postgres=#</span> EXPLAIN (VERBOSE, COSTS)
+<span class="strong">postgres-# /*+</span>
+<span class="strong">postgres*# SeqScan(a)</span>
+<span class="strong">postgres*# HashJoin(a b)</span>
+<span class="strong">postgres*# Set(random_page_cost 2.0)</span>
+<span class="strong">postgres*# */</span>
+<span class="strong">postgres-#</span> SELECT *
+<span class="strong">postgres-#</span> FROM pgbench_accounts a
+<span class="strong">postgres-#</span> JOIN pgbench_branches b
+<span class="strong">postgres-#</span> ON a.bid = b.bid
+<span class="strong">postgres-#</span> ORDER BY a.aid
+<span class="strong">postgres-#</span> LIMIT 10;
+ QUERY PLAN
+----------------------------------------------------------------------------------------------------
+ Limit (cost=6176.99..6177.01 rows=10 width=461)
+ Output: a.aid, a.bid, a.abalance, a.filler, b.bid, b.bbalance, b.filler, a.aid
+ -> Sort (cost=6176.99..6426.99 rows=100000 width=461)
+ Output: a.aid, a.bid, a.abalance, a.filler, b.bid, b.bbalance, b.filler, a.aid
+ Sort Key: a.aid
+ -> <span class="strong">Hash Join</span> (cost=1.02..4016.02 rows=100000 width=461)
+ Output: a.aid, a.bid, a.abalance, a.filler, b.bid, b.bbalance, b.filler, a.aid
+ Hash Cond: (a.bid = b.bid)
+ -> <span class="strong">Seq Scan on public.pgbench_accounts a</span> (cost=0.00..2640.00 rows=100000 width=97)
+ Output: a.aid, a.bid, a.abalance, a.filler
+ -> Hash (cost=1.01..1.01 rows=1 width=364)
+ Output: b.bid, b.bbalance, b.filler
+ -> Seq Scan on public.pgbench_branches b (cost=0.00..1.01 rows=1 width=364)
+ Output: b.bid, b.bbalance, b.filler
+(14 rows)
+
+postgres=#
</pre>
-<h2 id="uninstall">アンインストール</h2>
-<p>pg_hint_planをアンインストールするには、pg_hint_planのソースを展開したディレクトリでmake uninstallを実行してください。</p>
-<p>以下にアンインストールの例を示します。</p>
+<h4 id="hint-table">テーブルでの指定</h4>
+<p>指定したいヒントを、実行計画を制御したいクエリと併せてヒント用のテーブルに登録します。</p>
+<p>デフォルトでは無効なので、テーブルで指定したヒントは適用されません。そのため、ヒントをテーブルで指定する場合は、<a href="#hint-GUC">pg_hint_planのGUCパラメータ</a>pg_hint_plan.enable_hint_tableの設定を変更します。この機能を利用する場合にはcompute_query_idが"auto"または"on"である必要があります。</p>
+<p>ヒント用のテーブルは「<span class="bold">hint_plan.hints</span>」です。hint_plan.hintsテーブルには、以下の情報を登録します。</p>
+<table>
+<thead>
+<tr>
+<tr><th>列名</th><th>説明</th></tr>
+</tr></thead>
+<tbody>
+<tr><td>id</td>
+ <td>ユーザがヒントを識別するための番号です。連番型ですので、新しいヒントを登録するときにはこの列を指定しないでください。</td></tr>
+<tr><td>norm_query_string</td>
+ <td>実行計画を制御したいクエリを指定します。対象のクエリに定数があるときは、下記の例のように「?」に置き換えます。キーワード間の空白の数が、登録するクエリと実行するクエリで異なると別のSQL文として扱われます。</td></tr>
+<tr><td>application_name</td>
+ <td>ヒント適用対象のアプリケーション名を指定します。下記の例では「psql」から実行されたクエリのみがヒント適用対象となります。全てのアプリケーションにヒントを適用したいときは、空文字列を登録します。アプリケーション名は、セッションの「application_name」GUCパラメータと等しいか判断します。</td></tr>
+<tr><td>hints</td>
+ <td>ヒントを指定します。SQLコメント記号を除いた内容のみを登録します。</td></tr>
+</tbody>
+</table>
+<p>ヒントの登録情報を変更する場合は、変更したい登録情報のidを指定して登録情報を更新してください。</br>
+ヒントの登録を解除する場合は、解除したい登録情報のidを指定してテーブルから削除してください。</p>
+<p>以下の例では、ヒントの登録、ヒント登録情報の変更、ヒントの解除の順に、クエリの実行結果を示しています。
+</p>
<pre>
-$ cd pg_hint_plan-1.0.0
-$ su
-# make uninstall
+<span class="strong">postgres=#</span> INSERT INTO hint_plan.hints(norm_query_string, application_name, hints)
+<span class="strong">postgres-#</span> VALUES (
+<span class="strong">postgres(#</span> 'EXPLAIN (COSTS false) SELECT * FROM t1 WHERE t1.id = ?;',
+<span class="strong">postgres(#</span> '',
+<span class="strong">postgres(#</span> 'SeqScan(t1)'
+<span class="strong">postgres(#</span> );
+INSERT 0 1
+<span class="strong">postgres=#</span> UPDATE hint_plan.hints
+<span class="strong">postgres-#</span> SET hints = 'IndexScan(t1)'
+<span class="strong">postgres-#</span> WHERE id = 1;
+UPDATE 1
+<span class="strong">postgres=#</span> DELETE FROM hint_plan.hints
+<span class="strong">postgres-#</span> WHERE id = 1;
+DELETE 1
+<span class="strong">postgres=#</span>
</pre>
-
-<h2 id="usage">使い方</h2>
-<p>pg_hint_planの使い方について説明します。</p>
-
-<h3 id="hint-load">pg_hint_planのロード</h3>
-<p>pg_hint_planを使うには、以下の例のようにpg_hint_planの共有ライブラリをロードしてください。全てのセッションでpg_hint_planを有効にするには、shared_preload_libraries GUCパラメータに'pg_hint_plan'を追加してからサーバを再起動して下さい。</p>
+<p>なお、ヒントの登録や変更や解除はスーパーユーザでのみ可能です。一般ユーザでヒントの登録や変更や解除を実施したい場合は、スーパーユーザから一般ユーザにhint_plan.hintsテーブルの各権限を付与してください。</p>
+<p>以下の例では、hint_plan.hintsテーブルに対してINSERT権限を持たない一般ユーザがヒントの登録を実施しようとしたときの結果を示しています。</p>
<pre>
-postgres=# LOAD 'pg_hint_plan';
-LOAD
-postgres=# </pre>
+<span class="strong">postgres=></span> INSERT INTO hint_plan.hints(norm_query_string, application_name, hints)
+<span class="strong">postgres-></span> VALUES (
+<span class="strong">postgres(></span> 'EXPLAIN (COSTS false) SELECT * FROM t1 WHERE t1.id = ?;',
+<span class="strong">postgres(></span> '',
+<span class="strong">postgres(></span> 'SeqScan(t1)'
+<span class="strong">postgres(></span> );
+ERROR: permission denied for relation hints
+<span class="strong">postgres=></span>
+</pre>
+<p>以下の例では、テーブルに登録した「コメントでの指定」の例と同じヒントと、登録したクエリの実行結果を示しています。</p>
+<pre>
+<span class="strong">postgres=#</span> SELECT * FROM hint_plan.hints;
+ id | norm_query_string | application_name | hints
+----+----------------------------+------------------+--------------------------------------------------
+ 1 | EXPLAIN (VERBOSE, COSTS) +| psql | SeqScan(a)HashJoin(a b)Set(random_page_cost 2.0)
+ | SELECT * +| |
+ | FROM pgbench_accounts a+| |
+ | JOIN pgbench_branches b+| |
+ | ON a.bid = b.bid +| |
+ | ORDER BY a.aid +| |
+ | LIMIT ?; +| |
+ | | |
+...
+
+<span class="strong">postgres=#</span> SET pg_hint_plan.enable_hint_table TO on;
+<span class="strong">postgres=#</span> EXPLAIN (VERBOSE, COSTS)
+<span class="strong">postgres-#</span> SELECT *
+<span class="strong">postgres-#</span> FROM pgbench_accounts a
+<span class="strong">postgres-#</span> JOIN pgbench_branches b
+<span class="strong">postgres-#</span> ON a.bid = b.bid
+<span class="strong">postgres-#</span> ORDER BY a.aid
+<span class="strong">postgres-#</span> LIMIT 10;
+ QUERY PLAN
+----------------------------------------------------------------------------------------------------
+ Limit (cost=6176.99..6177.01 rows=10 width=461)
+ Output: a.aid, a.bid, a.abalance, a.filler, b.bid, b.bbalance, b.filler, a.aid
+ -> Sort (cost=6176.99..6426.99 rows=100000 width=461)
+ Output: a.aid, a.bid, a.abalance, a.filler, b.bid, b.bbalance, b.filler, a.aid
+ Sort Key: a.aid
+ -> <span class="strong">Hash Join</span> (cost=1.02..4016.02 rows=100000 width=461)
+ Output: a.aid, a.bid, a.abalance, a.filler, b.bid, b.bbalance, b.filler, a.aid
+ Hash Cond: (a.bid = b.bid)
+ -> <span class="strong">Seq Scan on public.pgbench_accounts a</span> (cost=0.00..2640.00 rows=100000 width=97)
+ Output: a.aid, a.bid, a.abalance, a.filler
+ -> Hash (cost=1.01..1.01 rows=1 width=364)
+ Output: b.bid, b.bbalance, b.filler
+ -> Seq Scan on public.pgbench_branches b (cost=0.00..1.01 rows=1 width=364)
+ Output: b.bid, b.bbalance, b.filler
+(14 rows)
-<h3 id="hint-rule">ヒントの記述方法</h3>
-<p>ヒントはクエリ文字列の先頭のブロックコメント内に記述してください。ブロックコメントをヒントとして認識させるには、ブロックコメントの開始直後にプラス（+）を指定する必要があります。ヒントの対象は、カッコ内にオブジェクト名または別名(エイリアス)で指定してください。オブジェクト名は、スペース、タブ、または改行のいずれかで区切って指定してください。</p>
+postgres=#
+</pre>
-<p>以下の例では、HashJoinとSeqScanヒントにより、pgbench_accountsテーブルに対するSeq Scanの結果をHash Joinする実行計画が選択されています。</p>
+<div class="tips">
+<span class="strong">指定方法の優先度</span>
+<p>ヒントをコメントとテーブルの両方で指定した場合、テーブルで指定したヒントが適用され、コメントで指定したヒントは無視されます。</p>
+<p>以下の例では、コメントでヒントを指定して実行計画を制御しているクエリに対して、テーブルに空文字列のヒントを登録しています。テーブルで指定したヒントが優先されるので、コメントで指定したヒントを取り消すことができます。</p>
<pre>
-postgres=# /*+
-postgres*# <span class="strong">HashJoin(a b)</span>
-postgres*# <span class="strong">SeqScan(a)</span>
-postgres*# */
-postgres-# EXPLAIN SELECT *
-postgres-# FROM pgbench_branches b
-postgres-# JOIN pgbench_accounts a ON b.bid = a.bid
-postgres-# ORDER BY a.aid;
- QUERY PLAN
----------------------------------------------------------------------------------------
- Sort (cost=31465.84..31715.84 rows=100000 width=197)
- Sort Key: a.aid
- -> <span class="strong">Hash Join</span> (cost=1.02..4016.02 rows=100000 width=197)
- Hash Cond: (a.bid = b.bid)
- -> <span class="strong">Seq Scan on pgbench_accounts a</span> (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)
+postgres=# select * from hint_plan.hints;
+ id | norm_query_string | application_name | hints
+----+--------------------------------------------+------------------+-------
+ 1 | EXPLAIN (VERBOSE, COSTS) +| psql |
+ | /*+ +| |
+ | HashJoin(a b) +| |
+ | SeqScan(a) +| |
+ | */ +| |
+ | SELECT * +| |
+ | FROM pgbench_accounts a +| |
+ | JOIN pgbench_branches b ON a.bid = b.bid+| |
+ | ORDER BY a.aid; | |
+...
-postgres=# </pre>
+postgres=# EXPLAIN (VERBOSE, COSTS)
+postgres-# /*+
+postgres*# HashJoin(a b)
+postgres*# SeqScan(a)
+postgres*# */
+postgres-# SELECT *
+postgres-# FROM pgbench_accounts a
+postgres-# JOIN pgbench_branches b ON a.bid = b.bid
+postgres-# ORDER BY a.aid;
+ QUERY PLAN
+----------------------------------------------------------------------------------------------------------------------
+ <span class="strong">Nested Loop</span> (cost=0.00..5750.47 rows=100000 width=461)
+ Output: a.aid, a.bid, a.abalance, a.filler, b.bid, b.bbalance, b.filler, a.aid
+ Join Filter: (a.bid = b.bid)
+ -> <span class="strong">Index Scan using pgbench_accounts_pkey on public.pgbench_accounts a</span> (cost=0.00..4249.45 rows=100000 width=97)
+ Output: a.aid, a.bid, a.abalance, a.filler
+ -> Materialize (cost=0.00..1.01 rows=1 width=364)
+ Output: b.bid, b.bbalance, b.filler
+ -> Seq Scan on public.pgbench_branches b (cost=0.00..1.01 rows=1 width=364)
+ Output: b.bid, b.bbalance, b.filler
+(9 rows)
+</pre>
+</div>
-<h3 id="hint-group">ヒントのグループ</h3>
-<p>pg_hint_planで使えるヒントは、スキャン方式と結合方式、結合順序、GUCパラメータの4グループに分けられます。各グループの具体的なヒントは、<a href="hint_list-ja.html">ヒント一覧</a>を参照してください。</p>
+<h3 id="hint-group">ヒント句のグループ</h3>
+<p>pg_hint_planで使えるヒント句の種類は、スキャン方式と結合方式、結合順序、見積もり件数補正、並列実行の設定、GUCパラメータの6グループです。各グループの具体的なヒント句は、<a href="hint_list-ja.html">ヒント句一覧</a>を参照してください。</p>
<h4>スキャン方式</h4>
-<p>あるオブジェクトでどのスキャン方式を選択するかを指定できるヒントのグループで、「SeqScan」や「IndexScan」などが含まれます。</p>
-<p>スキャン方式を指定できるオブジェクトは、通常のテーブル、継承テーブル、UNLOGGEDテーブル、一時テーブル、システムカタログです。スキャン方式を指定できないオブジェクトは、外部テーブル、テーブル関数、VALUESコマンド結果、CTE、VIEW、副問い合わせ結果です。</p>
-<p>特定のオブジェクトについてあるスキャン方式を選択して欲しい場合は、そのスキャン方式のヒントと、対象となるオブジェクトの名前を指定してください。逆に、特定のオブジェクトについてあるスキャン方式を選択して欲しくない場合は、Noで始まるヒントを指定してください。同じオブジェクトに対して複数のスキャン方式のヒントを指定した場合は、最後に指定したヒントが適用されます。</p>
+<p>あるオブジェクトでどのスキャン方式を選択するかを指定できるヒント句のグループです。「SeqScan」や「IndexScan」などを含みます。</p>
+<p>スキャン方式を指定できるオブジェクトは、通常のテーブル、継承テーブル、UNLOGGEDテーブル、一時テーブル、システムカタログです。スキャン方式を指定できないオブジェクトは、外部テーブル、テーブル関数、VALUESコマンド結果、CTE(共通テーブル式)、ビュー、副問い合わせ結果です。</p>
+<p>特定のオブジェクトについてあるスキャン方式を選択して欲しい場合は、そのスキャン方式のヒント句と、対象となるオブジェクトの名前を指定します。逆に、特定のオブジェクトについてあるスキャン方式を選択して欲しくない場合は、Noで始まるヒント句を指定します。同じオブジェクトに対して複数のスキャン方式のヒント句を指定した場合は、最後に指定したヒント句が適用されます。</p>
<h4>結合方式</h4>
-<p>あるオブジェクトの組み合わせでどの結合方式を選択するかを指定できるヒントのグループで、「MergeJoin」や「NestLoop」などが含まれます。</p>
-<p>結合方式を指定できるオブジェクトは、通常のテーブル、継承テーブル、UNLOGGEDテーブル、一時テーブル、外部テーブル、システムカタログ、テーブル関数、VALUESコマンド結果、CTEです。結合方式を指定できないオブジェクトは、VIEW、副問い合わせ結果です。</p>
-<p>特定のオブジェクトの組み合わせについてある結合方式を選択して欲しい場合は、その結合方式のヒントと、対象となる2つ以上のオブジェクトの名前を指定してください。逆に、特定のオブジェクトの組み合わせについてある結合方式を選択して欲しくない場合は、Noで始まるヒントを指定してください。同じオブジェクトの組み合わせに対して複数の結合方式のヒントを指定した場合は、最後に指定したヒントが適用されます。</p>
+<p>あるオブジェクトの組み合わせでどの結合方式を選択するかを指定できるヒント句のグループです。「MergeJoin」や「NestLoop」などを含みます。</p>
+<p>結合方式を指定できるオブジェクトは、通常のテーブル、継承テーブル、UNLOGGEDテーブル、一時テーブル、外部テーブル、システムカタログ、テーブル関数、VALUESコマンド結果、CTE(共通テーブル式)です。結合方式を指定できないオブジェクトは、ビュー、副問い合わせ結果です。</p>
+<p>特定のオブジェクトの組み合わせについてある結合方式を選択して欲しい場合は、その結合方式のヒント句と、対象となる2つ以上のオブジェクトの名前を指定します。逆に、特定のオブジェクトの組み合わせについてある結合方式を選択して欲しくない場合は、Noで始まるヒント句を指定します。同じオブジェクトの組み合わせに対して複数の結合方式のヒント句を指定した場合は、最後に指定したヒント句が適用されます。</p>
+
<h4>結合順序</h4>
-<p>あるオブジェクトの組み合わせでどのような順番で結合するかを指定できるヒントのグループで、「Leading」のみが含まれます。</p>
+<p>あるオブジェクトの組み合わせでどのような順番で結合するかを指定できるヒント句のグループです。「Leading」のみを含みます。</p>
<p>結合順序を指定できるオブジェクトは結合方式と同じです。</p>
-<p>先に結合して欲しいオブジェクトから順にオブジェクト名または別名を指定してください。複数の結合順序のヒントを指定した場合は、最後に指定したヒントが適用されます。</p>
+<p>先に結合して欲しいオブジェクトから順にオブジェクト名または別名を指定します。同じ問合せブロックのオブジェクトに対して複数の結合順序のヒント句を指定した場合は、最後に指定したヒント句が適用されます。 </p>
+<div class="tips">
+<p>結合対象のテーブルが3つ以上ある場合、結合方式のヒント句を指定したとしてもコスト見積もりによっては対象のテーブルが直接結合されないことがあります。対象のテーブルが直接結合されない場合は、結合順序のヒント句を併せて指定します。</p>
+<p>以下の例では、table1とtable2を直接結合する場合はNested Loopを、table1とtable2とtable3を結合する場合はMerge Joinを指定しています。また、コスト見積もりによってはtable1とtable2が直接結合されない場合を避けるため、table1とtable2を結合してからtable3を結合するようにLeadingヒント句を併用しています。</p>
+<pre>
+<span class="strong">postgres=# /*+</span>
+<span class="strong">postgres*# NestLoop(t1 t2)</span>
+<span class="strong">postgres*# MergeJoin(t1 t2 t3)</span>
+<span class="strong">postgres*# Leading(t1 t2 t3)</span>
+<span class="strong">postgres*# */</span>
+<span class="strong">postgres-#</span> SELECT * FROM table1 t1
+<span class="strong">postgres-#</span> JOIN table table2 t2 ON (t1.key = t2.key)
+<span class="strong">postgres-#</span> JOIN table table3 t3 ON (t2.key = t3.key);
+...
+</pre>
+</div>
+<h4>結合方向</h4>
+<p>上記の結合順序の指定を行なった際にはプランナの都合により結合方向(外部表/内部表もしくは駆動表/被駆動表の別)が期待とは異なるものになる場合があります。このような状況に対して結合方向を固定したい場合はもうひとつの書式を使う必要があります。</p>
+<pre>
+<span class="strong">postgres=# /*+ Leading((t1 (t2 t3))) */</span> SELECT...
+</pre>
+<p>この書式では2つの要素を丸括弧で囲ったものがネストする形になっており、一つの括弧内では1つ目の要素が外部/駆動表、2番めの要素が内部/被駆動表として結合されます。</p>
+<h4>結合の挙動制御</h4>
+<p>あるオブジェクトの組み合わせ最上位結合の挙動を制御するヒント句のグループです。「Memoize」のみを含みます。</p>
+<p>Memoizeは最上位結合のインナープランの出力結果をキャッシングして高速化を試みる挙動を制御します。</p>
+<p>以下の例では、テーブルaとテーブルbの結合のインナー側(この例ではa側)のMemoizeを禁止します。</p>
+
+<pre>
+postgres=# /*+ NoMemoize(a b) */
+EXPLAIN SELECT * FROM a, b WHERE a.val = b.val;
+ QUERY PLAN
+--------------------------------------------------------------------
+ Hash Join (cost=270.00..1412.50 rows=100000 width=16)
+ Hash Cond: (b.val = a.val)
+ -> Seq Scan on b (cost=0.00..15.00 rows=1000 width=8)
+ -> Hash (cost=145.00..145.00 rows=10000 width=8)
+ -> Seq Scan on a (cost=0.00..145.00 rows=10000 width=8)
+(5 行)
+</pre>
+
+<h4>見積もり件数補正</h4>
+<p>あるオブジェクトの結合結果の件数を補正できるヒント句のグループです。「Rows」のみを含みます。</p>
+<p>見積もり件数補正対象として指定できるオブジェクトは結合方式と同じです。補正できるのは結合結果の見積もり件数だけで、スキャンの見積もり件数を補正することはできません。</p>
+<p>以下の例では、テーブルaとテーブルbの結合結果の件数を、ヒント句で指定した値に補正しています。</p>
+<pre>
+<span class="strong">postgres=# /*+ Rows(a b #10) */</span>
+<span class="strong">postgres-#</span> EXPLAIN SELECT *
+<span class="strong">postgres-#</span> FROM pgbench_branches b
+<span class="strong">postgres-#</span> JOIN pgbench_accounts a ON b.bid = a.bid
+<span class="strong">postgres-#</span> WHERE aid < 20
+<span class="strong">postgres-#</span> ORDER BY a.aid;
+ QUERY PLAN
+--------------------------------------------------------------------------------------------------------
+ Nested Loop (cost=0.29..9.92 rows=<span class="strong">10</span> width=461)
+ Join Filter: (b.bid = a.bid)
+ -> Index Scan using pgbench_accounts_pkey on pgbench_accounts a (cost=0.29. .8.62 rows=19 width=97)
+ Index Cond: (aid < 20)
+ -> Materialize (cost=0.00..1.01 rows=1 width=364)
+ -> Seq Scan on pgbench_branches b (cost=0.00..1.01 rows=1 width=364)
+(6 行)
+</pre>
+
+<h4>並列実行の指定</h4>
+<p>スキャンの並列実行の方法を指定します。最初のパラメータは対象とするオブジェクトの指定で、2番目に指定する数だけ並列処理ワーカを起動するように指定します。
+<p>3番目のパラメータは強制の程度を指定します。 "soft" は max_parallel_workers_per_gather のみを変更して適用はプランナに任せます。"hard" は他のプランナ変数も変更するなどしてワーカ数を強制します。</p>
+<p>以下の例では、テーブル c1 とテーブル c2 の結合で各々異なるワーカ数を強制します。</p>
+<pre>
+<span class="strong">postgres=#</span> explain <span class="strong">/*+ Parallel(c1 3 hard) Parallel(c2 5 hard) */</span>
+ 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)
+ <span class="strong">Workers Planned: 3</span>
+ -> Parallel Seq Scan on <span class="strong">c1</span> (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)
+ <span class="strong">Workers Planned: 5</span>
+ -> Parallel Seq Scan on <span class="strong">c2</span> (cost=0.00..1.59 rows=59 width=4)
+</pre>
+
<h4>GUCパラメータ</h4>
-<p>そのクエリの実行計画を作成している間だけGUCパラメータを変更できるヒントのグループで、「Set」のみが含まれます。</p>
-<p>設定したいGUCパラメータとそのパラメータの値を指定してください。<a href="http://www.postgresql.org/docs/9.1/static/sql-set.html">SET</a>コマンドで指定できるGUCパラメータならば全て指定できますが、効果があるのは<a href="http://www.postgresql.org/docs/9.1/static/runtime-config-query.html">問い合わせ計画</a>のGUCパラメータのみです。同じGUCパラメータに対して複数のGUCパラメータのヒントを指定した場合は、最後に指定したヒントが適用されます。</p>
+<p>そのクエリの実行計画を作成している間だけGUCパラメータを変更できるヒント句のグループです。「Set」のみを含みます。</p>
+<p>設定したいGUCパラメータとそのパラメータの値を指定します。指定できるGUCパラメータは<a href="http://www.postgresql.jp/document/current/html/runtime-config-query.html">問い合わせ計画</a>のGUCパラメータのみです。同じGUCパラメータのヒント句を2回以上指定した場合は、最後に指定したヒント句が適用されます。</p>
+<div class="tips">
+<span class="strong">Setヒント句の制限</span>
+<p>Setヒント句に問い合わせ計画のGUCパラメータ以外を指定した場合の動作は保証できません。問い合わせ計画以外のGUCパラメータを指定した場合の例の一つとして、<a href="#hint-GUC">pg_hint_planのGUCパラメータ</a>を指定した場合の動作を、以下に示します。<p>
+<ul>
+<li>pg_hint_plan.enable_hint、pg_hint_plan.enable_hint_tableをSetヒント句の対象に指定した場合は、無効になります。なお、pg_hint_plan.debug_printをonに設定していると、そのヒント句はログ出力で「適用されたヒント句」として出力されます。</li>
+<li>pg_hint_plan.debug_printをSetヒント句の対象に指定した場合は、指定したとおりに適用されます。</li>
+<li>pg_hint_plan.parse_messagesをSetヒント句の対象に指定した場合は、構文エラーと一部のSetヒント句のエラーのメッセージはクエリ開始時の設定レベルで出力され、それ以外のメッセージはSetヒント句で指定したレベルで出力されます。</li>
+</ul>
+</div>
<h3 id="hint-GUC">pg_hint_planのGUCパラメータ</h3>
<p>pg_hint_planの動作を制御するGUCパラメータを以下に記述します。</p>
<tr><th>GUCパラメータ</th><th>説明</th><th>デフォルト値</th></tr>
</tr></thead>
<tbody>
-<tr><td>pg_hint_plan.enable</td>
+<tr><td>pg_hint_plan.enable_hint</td>
<td>pg_hint_planの機能を有効または無効にします。</td><td>on</td></tr>
-<tr><td>pg_hint_plan.debug_print</td>
- <td>pg_hint_planのデバッグ出力を有効にします。メッセージはLOGメッセージレベルで出力されますので、デフォルトではサーバログに出力され、クライアントには渡されません。</td><td>off</td></tr>
+<tr><td>pg_hint_plan.enable_hint_table</td>
+ <td>ヒントをテーブルで指定する機能を有効または無効にします。</td><td>off</td></tr>
<tr><td>pg_hint_plan.parse_messages</td>
- <td>指定したヒントを解釈できなかった場合に、どのメッセージ階層でログを出力するかを指定します。有効な値は、debug5、debug4、debug3、debug2、debug1、log、info、notice、warning、またはerrorです。fatalとpanicは指定できません。</td><td>info</td></tr>
+ <td>指定したヒントを解釈できなかった場合のログメッセージのレベルを指定します。有効な値は、debug5、debug4、debug3、debug2、debug1、log、info、notice、warning、またはerrorです。</td><td>INFO</td></tr>
+<tr><td>pg_hint_plan.debug_print</td>
+ <td>動作状況を示すログメッセージの出力を制御します。指定可能な値は off, on, verbose, detailed です。</td><td>off</td></tr>
+<tr><td>pg_hint_plan.message_level</td>
+ <td>動作ログメッセージのログレベルを指定します。有効な値は、debug5、debug4、debug3、debug2、debug1、log、info、notice、warning、またはerrorです。</td><td>LOG</td></tr>
+
</tbody>
</table>
-<p>これらのパラメータをpostgresql.confファイルに設定するには、<a href="http://www.postgresql.org/docs/9.1/static/runtime-config-custom.html#GUC-CUSTOM-VARIABLE-CLASSES">custom_variable_classes</a>に auth_delayを加える必要があります。標準的な使用例は以下のようになります。</p>
+<h2 id="install">インストール</h2>
+<p>pg_hint_planのインストール方法について説明します。</p>
+
+<h3 id="build">ビルド</h3>
+<p>pg_hint_planをソースコードからビルドする場合、pg_hint_planのソースを展開したディレクトリでmake → make installの順に実行します。make installはPostgreSQLをインストールしたOSユーザで実行します。なお、pg_hint_planのビルドにはpgxsを使用するので、RPM版のPostgreSQLを使用している環境では、postgresql-devel パッケージが必要です。</p>
+<p>以下にビルドの例を示します。</p>
<pre>
-# postgresql.conf
-shared_preload_libraries = 'pg_hint_plan'
+$ tar xzvf pg_hint_plan-1.0.0.tar.gz
+$ cd pg_hint_plan-1.0.0
+$ make
+$ su
+# make install
+</pre>
-custom_variable_classes = 'pg_hint_plan'
-pg_hint_plan.parse_messages = 'debug2'
+<h3 id="create-extension">データベースへの登録</h3>
+<p>pg_hint_planはPostgreSQLの拡張(EXTENSION)を使用しているので、pg_hint_planを利用するデータベースにスーパーユーザもしくはそのデータベースの所有者で接続してCREATE EXTENSIONコマンドを実行します。</p>
+<p>以下にデータベースへの登録の例を示します。 <i>dbname</i>は対象となるデータベース名を意味します。</p>
+<pre>
+$ psql -d <i>dbname</i> -c "CREATE EXTENSION pg_hint_plan"
+</pre>
+
+<h3 id="hint-load">pg_hint_planのロード</h3>
+<p>特定のセッションでのみpg_hint_planを使う場合は、以下の例のようにpg_hint_planの共有ライブラリをLOADコマンドでロードします。一般ユーザで利用する場合は$libdir/pluginsにもインストールする必要があるので注意してください。
+<pre>
+postgres=# LOAD 'pg_hint_plan';
+LOAD
+postgres=# </pre></p>
+<p>全てのセッションでpg_hint_planを有効にするには、shared_preload_libraries GUCパラメータに'pg_hint_plan'を追加してからサーバを再起動します。</p>
+<p>注意: pg_hint_planを<a href="#create-extension">データベースに登録</a>せずに、ロード後にSQL文を実行すると以下に示す例のようなエラーとなります。 pg_hint_planを使うときは、データベースへの登録を忘れないように注意してください。</p>
+<pre>
+postgres=# EXPLAIN SELECT * FROM pgbench_accounts a WHERE aid = 1;
+ERROR: schema "hint_plan" does not exist
+LINE 1: SELECT hints FROM hint_plan.hints WHERE norm_query_string...
+ ^
+QUERY: SELECT hints FROM hint_plan.hints WHERE norm_query_string = $1 AND ( application_name = $2 OR application_name = '' ) ORDER BY application_name DESC
+postgres=#
+</pre>
+
+<h2 id="uninstall">アンインストール</h2>
+<p>pg_hint_planをアンインストールするときは、以下の手順を実行します。 <i>dbname</i>は対象となるデータベース名を意味します。</p>
+<ol>
+<li>pg_hint_planのソースを展開したディレクトリでmake uninstallを実行します。make uninstallはPostgreSQLをインストールしたOSユーザで実行します。</li>
+<pre>
+$ cd pg_hint_plan-1.0.0
+$ su
+# make uninstall
+</pre>
+<li>pg_hint_planを登録したデータベースにスーパーユーザもしくはそのデータベースの所有者で接続して、DROP EXTENSIONコマンドおよびDROP SCHEMAコマンドを実行します。</li>
+<pre>
+$ psql -d <i>dbname</i> -c "DROP EXTENSION pg_hint_plan"
+$ psql -d <i>dbname</i> -c "DROP SCHEMA hint_plan"
</pre>
+</ol>
-<h2 id="restrictions">使用上の注意と制約</h2>
-<p>pg_hint_planを使用する際には、以下の注意と制約があります。</p>
+<h2 id="restrictions">ヒントの指定に関する詳細</h2>
+<p>以下にいくつかのトピックに関してヒントの動作について説明します。</p>
<dl>
-<dt>ヒントの記述位置</dt>
-<dd>クエリの前に複数のブロックコメントを記述する場合は、最初のブロックコメントにのみヒントを記述してください。二番目以降のブロックコメントは、ヒントと見なされず無視されます。以下の例では、HashJoin(a b)とSeqScan(a)がヒントと見なされ、IndexScan(a)とMergeJoin(a b)は無視されています。</p>
+<dt>コメント指定でのヒント記述位置と文法</dt>
+<dd>ヒントはクエリの先頭または途中に記述できます。ただし、ヒントをクエリの途中に記述する場合、ヒント用のブロックコメントより前に以下の文字<span class="strong">以外</span>が含まれると、「/*+」で始まるコメントでもヒントと見なされず無視されます。
+<ul>
+<li>空白文字（半角スペース、水平/垂直タブ、改行、フォームフィード、復帰）</li>
+<li>アルファベット（大文字/小文字）</li>
+<li>数字</li>
+<li>アンダースコア</li>
+<li>カンマ</li>
+<li>開き括弧（(）、閉じ括弧（)）</li>
+</ul>
+<p>指定したヒントが無視される例を以下に示します。</p>
+<ol>
+<li>二重引用符（"）がヒント用のブロックコメントより前に含まれている場合</li>
+<pre>
+postgres=# SELECT bid AS "BID"
+postgres-# /*+
+postgres*# SeqScan(b)
+postgres*# */
+postgres-# FROM pgbench_branches b;
+...
+</pre>
+<li>演算子（>=）がヒント用のブロックコメントより前に含まれている場合</li>
+<pre>
+postgres=# WITH avg_aid AS (
+postgres(# SELECT avg(aid) FROM pgbench_history h
+postgres(# WHERE delta >= 0
+postgres(# )
+postgres-# /*+
+postgres*# SeqScan(h)
+postgres*# */
+postgres-# SELECT * FROM avg_aid;
+...
+</pre>
+</ol>
+一つのクエリに複数のブロックコメントを記述する場合は、最初のブロックコメントにのみヒントを記述してください。二番目以降のブロックコメントは、ヒントと見なされず無視されます。以下の例では、HashJoin(a b)とSeqScan(a)がヒントと見なされ、IndexScan(a)とMergeJoin(a b)は無視されています。</p>
<pre>
postgres=# /*+
-postgres*# <span class="strong">HashJoin(a b)</span>
-postgres*# <span class="strong">SeqScan(a)</span>
+postgres*# <span class="strong">HashJoin(a b)</span>
+postgres*# <span class="strong">SeqScan(a)</span>
postgres*# */
postgres-# /*+ IndexScan(a) */
postgres-# EXPLAIN SELECT /*+ MergeJoin(a b) */ *
postgres=# </pre>
</dd>
-<dt>オブジェクト名の引用符付け</dt>
-<dd>ヒントに記述するオブジェクト名や別名が閉じ括弧（)）、二重引用符（"）、空白（スペース、タブ、改行のいずれか）を含む場合は、通常のSQL文で使う場合と同じようにダブルクォート(")で囲んでください。二重引用符を含むオブジェクト名の場合は、二重引用符で括ったうえで2つ続けて二重引用符を記述してください。</dd>
+<dt>PL/pgSQL中の個別のクエリに対するヒント</dt>
+<dd>ヒントは、PL/pgSQLブロック中の各クエリにも指定できます。ただし、以下のような制約があります。
+<ul>
+<li>指定したヒントが適用されるSQLは以下の通りです。他のSQLにヒントを指定しても適用されません。
+<ul>
+<li>1行の結果を返す問い合わせ文(SELECT/INSERT/UPDATE/DELETE)</li>
+<li>複数行の結果を返す問い合わせ文(RETURN QUERY)</li>
+<li>動的SQL文(EXECUTE)</li>
+<li>カーソルを開く文(OPEN)</li>
+<li>問い合わせの結果を用いる繰り返し文(FOR)</li>
+</ul>
+</li>
+<li>ヒントをコメントで指定する場合は、SELECTなどのSQLキーワードより後に指定してください。ただし、動的SQL文にヒントをコメントで指定しても、そのヒントは適用されません。</li>
+</ul>
+<p>以下の例では、一つ目のクエリにNoIndexScanを、二つ目のクエリにSeqScanをそれぞれ指定しています。</p>
+<pre>
+postgres=# CREATE FUNCTION hints_func(integer) RETURNS integer AS $$
+postgres$# DECLARE
+postgres$# id integer;
+postgres$# cnt integer;
+postgres$# BEGIN
+postgres$# SELECT <span class="strong">/*+ NoIndexScan(a) */</span> aid
+postgres$# INTO id FROM pgbench_accounts a WHERE aid = $1;
+postgres$# SELECT <span class="strong">/*+ SeqScan(a) */</span> count(*)
+postgres$# INTO cnt FROM pgbench_accounts a;
+postgres$# RETURN id + cnt;
+postgres$# END;
+postgres$# $$ LANGUAGE plpgsql;
+</pre>
+</dd>
+<dt>ヒント句内のオブジェクト名の文字ケース</dt>
+<dd>PostgreSQL は引用符で囲われないオブジェクト名を文字ケースを無視して扱いますが、pg_hint_plan は指定されたオブジェクト名の文字ケースはそのまま PostgreSQL の内部表現と比較します。つまり、ヒント句で TBL と指定した場合、データベース上で "TBL" と定義したもののみと合致し, TBL, tbl, Tbl など引用符で囲われないオブジェクト名とは合致しません。</dd>
+<dt>ヒント句内のオブジェクト名の引用符付け</dt>
+<dd>ヒントに記述するオブジェクト名や別名が括弧（(、)のいずれか）、二重引用符（"）、空白（スペース、タブ、改行のいずれか）を含む場合は、通常のSQL文で使う場合と同じように二重引用符(")で囲んでください。二重引用符を含むオブジェクト名は、全体を二重引用符で括ったうえで、内部に含む二重引用符を二重引用符でエスケープしてください(例: 「quoted"table"name」→「"quoted""table""name"」)。</dd>
<dt>同一名称テーブルの区別</dt>
-<dd>スキーマ違いや同一テーブルの複数回使用などでクエリ中に同一名称のテーブルが複数回出現する場合は、テーブルに別名をつけてそれぞれのテーブルを区別してください。以下の例の1つ目のSQL文では、MergeJoin(t1 t1)をヒントに指定したとき、ヒント対象のオブジェクトが特定できずにエラーになっています。2つ目のSQL文では、各テーブルにptやstという別名をつけているため、実行計画作成時にヒントで指定した通りにMerge Joinを選択しています。
-</p>
+<dd>スキーマ違いや同一テーブルの複数回使用などでクエリ中に同一名称のテーブルが複数回出現する場合は、テーブルに別名をつけてそれぞれのテーブルを区別してください。以下の例の1つ目のSQL文では、HashJoin(t1 t1)をヒントに指定したとき、ヒント句対象のオブジェクトが特定できずにエラーになっています。2つ目のSQL文では、各テーブルにptやstという別名をつけているため、実行計画作成時にヒントで指定した通りにHash Joinを選択しています。</p>
<pre>
-postgres=# /*+ <span class="strong">MergeJoin(t1 t1)</span>*/
+postgres=# /*+ <span class="strong">HashJoin(t1 t1)</span>*/
postgres-# EXPLAIN SELECT * FROM s1.t1
postgres-# JOIN public.t1 ON (s1.t1.id=public.t1.id);
-INFO: hint syntax error at or near "t1 t1)"
-<span class="strong">DETAIL: relation name "t1" is ambiguous</span>
-INFO: hint syntax error at or near "t1 t1)"
-<span class="strong">DETAIL: relation name "t1" is ambiguous</span>
- QUERY PLAN
---------------------------------------------------------------------
- Hash Join (cost=270.00..323.05 rows=1230 width=44)
- Hash Cond: (s1.t1.id = public.t1.id)
- -> Seq Scan on t1 (cost=0.00..22.30 rows=1230 width=36)
- -> Hash (cost=145.00..145.00 rows=10000 width=8)
- -> Seq Scan on t1 (cost=0.00..145.00 rows=10000 width=8)
-(5 rows)
+INFO: hint syntax error at or near "HashJoin(t1 t1)"
+<span class="strong">DETAIL: Relation name "t1" is ambiguous.</span>
+ QUERY PLAN
+------------------------------------------------------------------
+ Merge Join (cost=337.49..781.49 rows=28800 width=8)
+ Merge Cond: (s1.t1.id = public.t1.id)
+ -> Sort (cost=168.75..174.75 rows=2400 width=4)
+ Sort Key: s1.t1.id
+ -> Seq Scan on t1 (cost=0.00..34.00 rows=2400 width=4)
+ -> Sort (cost=168.75..174.75 rows=2400 width=4)
+ Sort Key: public.t1.id
+ -> Seq Scan on t1 (cost=0.00..34.00 rows=2400 width=4)
+(8 行)
-postgres=# /*+ <span class="strong">MergeJoin(pt st)</span> */
+postgres=# /*+ <span class="strong">HashJoin(pt st)</span> */
postgres-# EXPLAIN SELECT * FROM s1.t1 st
postgres-# JOIN public.t1 pt ON (st.id=pt.id);
- QUERY PLAN
-----------------------------------------------------------------------------------
- <span class="strong">Merge Join</span> (cost=0.00..421.33 rows=1230 width=44)
- Merge Cond: (st.id = pt.id)
- -> Index Scan using t1_id_idx on t1 st (cost=0.00..62.70 rows=1230 width=36)
- -> Index Scan using t1_pkey on t1 pt (cost=0.00..318.25 rows=10000 width=8)(4 rows)
+ QUERY PLAN
+---------------------------------------------------------------------
+ <span class="strong">Hash Join</span> (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)
+(5 行)
postgres=#</pre>
</p>
</dd>
-<dt>ヒントの記述誤り</dt>
-<dd>pg_hint_planでは、ヒントの記述に誤りがあった場合は、誤った記述に関する情報を出力しますがエラー終了しません。誤った記述より前のヒントのみ有効となり、誤った記述以降のヒントを無視してクエリを実行します。</dd>
-<dt>不正なヒント</dt>
-<dd>pg_hint_planでは、不正なヒントの指定があった場合は、不正なヒントに関する情報を出力しますがエラー終了しません。不正なヒントのみ無効となり、その他のヒントは有効なままでクエリを実行します。不正なヒントの例を以下に示します。
-<ul>
-<li>クエリ中に同じ名称のテーブル名または別名のテーブルがあり、それに対してヒントを指定した。</li>
-<li>結合方式のヒント、または結合順のヒントのオブジェクト名に、同じ名称を複数回指定した。</li>
-</ul>
+<dl>
+<dt>ビューおよびルールの中でアクセスされているテーブル</dt>
+<dd>ヒント句で指定した名称と一致すれば、ビュー定義や関数内クエリなどに出現するテーブルについても、ヒントを指定したクエリ内と同じようにヒント句が適用されます。このため、ヒント句の適用有無や適用するヒント句をそれぞれのテーブルで変えたい場合は、それぞれ異なる別名を指定してください。</br>
+以下の例では、ビュー定義で使われている「t1」という別名をSeqScanヒント句で指定したことで、表スキャンとビュー経由のスキャンの両方でSeq Scanが選択されています。ビュー定義で使用されている「t1」とは別の別名を実表に指定することで、個別にスキャン方式を制御できます。
+<pre>
+postgres=# CREATE VIEW view1 AS SELECT * FROM table1 <span class="strong">t1</span>;
+CREATE TABLE
+postgres=# /*+ SeqScan(<span class="strong">t1</span>) */
+postgres=# EXPLAIN SELECT * FROM table1 <span class="strong">t1</span> JOIN view1 t2 ON (t1.key = t2.key) WHERE t2.key = 1;
+ QUERY PLAN
+-----------------------------------------------------------------
+ Nested Loop (cost=0.00..358.01 rows=1 width=16)
+ -> Seq Scan on table1 <span class="strong">t1</span> (cost=0.00..179.00 rows=1 width=8)
+ Filter: (key = 1)
+ -> Seq Scan on table1 <span class="strong">t1</span> (cost=0.00..179.00 rows=1 width=8)
+ Filter: (key = 1)
+</pre>
</dd>
-<dt>影響を与えるGUCパラメータ</dt>
-<dd>geqo_threshold、from_collapse_limit、およびjoin_collapse_limitによって結合順序が決定する場合は、結合順序のヒントより優先されます。GUCパラメータより結合順序のヒントを優先するには、GUCパラメータの値を結合対象のテーブル数より大きくしてください。</dd>
-<dt>指定するヒントの種類の重複</dt>
-<dd>同じオブジェクトに対して同じグループのヒントを重複して指定した場合は、最後に指定したヒントを使用します。</dd>
-<dt>制御可能なヒントの制限</dt>
-<dd>pg_hint_planでは、PostgreSQLのプランナが候補としてあげる事ができない実行計画をヒントに指定しても、その実行計画を生成することはできません。PostgreSQLのプランナが候補としてあげる事ができない実行計画の例を以下に示します。
-<ul>
-<li>FULL OUTER JOINではNested Loopは候補パスとして扱われません。</li>
-<li>WHERE句やJOIN条件などに指定されない列のみを含むインデックスは候補パスとして扱われません。</li>
-<li>>検索条件にctidを指定しない場合はTid Scanは候補パスとして扱われません。</li>
-</ul>
+<dt>継承テーブル</dt>
+<dd>継承テーブルにスキャン方式のヒント句を指定する場合は、オブジェクト名として親テーブルの名称または別名を指定してください。全ての子テーブルに同じスキャン方式を選択します。子テーブルごとに別のスキャン方式を指定することはできません。</dd>
+
+<dt>マルチステートメント</dt>
+<dd>クエリをマルチステートメントで実行する場合は、ヒントの指定方法によって以下のように注意点が異なります。
+<dl>
+<dt>コメントでの指定</dt>
+<dd>1つ目のクエリで指定したヒントが全てのクエリで使用されます。2つ目以降のクエリに指定したヒントは無視されます。</dd>
+<dt>テーブルでの指定</dt>
+<dd>ヒントを指定したいクエリの定数部分を？に置き換えてから、全てのクエリを一つにまとめてヒント用テーブルに登録します。ただし、複数の動的クエリをマルチステートメントで実行する場合には対応していません。</dd>
+</dl>
</dd>
-<dt>PREPARE/EXECUTEに対する制限</dt>
-<dd>libpqプロトコルの拡張問い合わせプロトコルを使い、かつSQL文をPREPARE文とEXECUTE文で実行する場合は、pg_hint_planでは実行計画を制御できません。拡張問い合わせプロトコルで準備された文を使用したい場合は、各種ライブラリが用意しているプリペアド機能を使用してください。例えば、JDBCではクエリの実行に常に拡張問い合わせプロトコルが使われるため、準備した文が必要な場合はPreparedStatementを使用する必要があります。</dd>
-<dt>継承テーブルに対する制限</dt>
-<dd>継承テーブルにスキャン方式のヒントを指定する場合は、オブジェクト名として親テーブルの名称または別名を指定してください。全ての子テーブルに同じスキャン方式を選択します。子テーブルごとに別のスキャン方式を指定することはできません。</dd>
-<dt>VIEWおよびRULEに対する制限</dt>
-<dd>VIEWやRULEを定義したテーブルを複数用いるときに、各VIEW内のテーブルの別名やRULE書き換え後のクエリのテーブルの別名が重複した場合は、ヒントの対象を区別できません。区別する場合は、各VIEW内のテーブルの別名やRULE書き換え後のクエリのテーブルの別名を重複させないでください。</dd>
-<dt>マルチステートメントにおける制限</dt>
-<dd>クエリがマルチステートメントで実行される場合は、先頭のコメントで指定したヒントを全てのクエリで使用します。2つ目以降のクエリに指定したヒントは無視します。psqlコマンドで-cオプションで複数のクエリを指定した場合などにマルチステートメントで実行されます。</dd>
-<dt>RULEにおける制限</dt>
-<dd>RULEによるクエリ書き換え後によってクエリが複数になる場合は、先頭のコメントで指定したヒントを全てのクエリで使用します。</dd>
-<dt>PL/pgSQLおける制限</dt>
-<dd>PL/pgSQLでユーザ定義関数を実装する際に、関数定義内の各クエリの先頭にヒントを指定したとしても、そのヒントは無視します。ユーザ定義関数を実行するSELECTコマンドに指定したヒントを使用します。ただし、PL/pgSQLでは、関数定義内で指定したクエリがそのまま実行されるとは限らないため、ヒントを指定した場合の挙動は保証できません。</dd>
-<dt>ECPGにおける制限</dt>
-<dd>pg_hint_planでは、ECPGで実装したアプリケーションから発行するクエリは、基本的に実行計画を制御できません。これは、CプリプロセッサがCコードに変換するタイミングで、全てのコメントを取り除いてしまうためです。ECPGでも例外的に、動的SQLの先頭にヒントを指定した場合は、実行計画を制御できます。</dd>
-<dt>psqlのフェッチ件数指定</dt>
-<dd>psqlコマンドのFETCH_COUNT変数に0より大きな整数値を指定すると、pg_hint_planでは実行計画を制御できなくなります。FETCH_COUNT変数に0より大きな整数値を指定すると、ユーザが指定したクエリの先頭に「DECLARE _psql_cursor NO SCROLL CURSOR FOR」が自動的に追加されてクエリが発行されることにより、ヒントがクエリの先頭ではなくなってしまうためです。</dd>
-<dt>ヒントによる他の機能への影響</dt>
-<dd>pg_stat_statementやSQL文フィンガープリントベースのクエリキャッシュなどでは、ヒントが異なれば別のSQL文として扱われます。</dd>
-<dt>FROM句にVALUESコマンドを指定した場合の制限</dt>
-<dd>FROM句にVALUESコマンドを指定した場合は、ヒントのオブジェクト名に「*VALUES*」を指定してください。これは、VALUESの結果に別名を指定しても、内部的に「*VALUES*」に名称が置き換えられるためです。このため、複数のVALUESを指定するとヒントの対象を特定できなくなり、実行計画を制御できません。</dd>
+<dt>FROM句にVALUES式を使っている問い合わせ</dt>
+<dd>FROM句にVALUES式を使っている場合は、ヒント句のオブジェクト名に「*VALUES*」を指定することでヒントを与えることができる場合があります。 ただし複数のVALUESを使っている場合は内部的には区別がつかないためヒントを与えることはできません。
<pre>
-postgres=# /* <span class="strong">MergeJoin(a *VALUES*)</span> */
+postgres=# /*+ <span class="strong">MergeJoin(a *VALUES*)</span> */
postgres-# EXPLAIN SELECT *
postgres-# FROM pgbench_accounts a
-postgres-# JOIN (VALUES (1,1),(2,2)) v (vid, vbalance) ON a.aid = v.vid
+postgres-# JOIN (VALUES (1,1),(2,2)) <span class="strong">v</span> (vid, vbalance) ON a.aid = v.vid
postgres-# ORDER BY a.aid;
- QUERY PLAN
--------------------------------------------------------------------------------------------------------------
- Sort (cost=16.62..16.62 rows=2 width=105)
- Sort Key: a.aid
- -> <span class="strong">Nested Loop</span> (cost=0.00..16.61 rows=2 width=105)
+ QUERY PLAN
+---------------------------------------------------------------------------------------------------------------
+ <span class="strong">Merge Join</span> (cost=0.04..4497.33 rows=2 width=105)
+ Merge Cond: (a.aid = "*VALUES*".column1)
+ -> Index Scan using pgbench_accounts_pkey on pgbench_accounts a (cost=0.00..4247.26 rows=100000 width=97)
+ -> Sort (cost=0.04..0.04 rows=2 width=8)
+ Sort Key: "*VALUES*".column1
-> Values Scan on <span class="strong">"*VALUES*"</span> (cost=0.00..0.03 rows=2 width=8)
- -> Index Scan using pgbench_accounts_pkey on pgbench_accounts a (cost=0.00..8.28 rows=1 width=97)
- Index Cond: (aid = "*VALUES*".column1)
-(6 行)
+postgres=#
+</pre>
+</dd>
+</dl>
-postgres=#</pre>
+<dt>副問い合わせ結果</dt>
+<dd>以下のような形式の副問い合わせでは外側の文への併合が行われず「ANY_subquery」という名前の独立した副問合せとして残される場合があります。このような副問合せが一つしかない場合は ANY_subquery という名前でこの副問合せを特定することができます。
+<ul>
+<li>IN (SELECT ... { <span class="strong">LIMIT | OFFSET 等</span>} ... )</li>
+<li>ANY (SELECT ... { <span class="strong">LIMIT | OFFSET 等</span>} ...)</li>
+<li>SOME (SELECT ... { <span class="strong">LIMIT | OFFSET 等</span>} ...)</li>
+</ul>
+以下の例では、そのことを利用して Hash Joinを強制しています。
+<pre>
+postgres=# /*+HashJoin(a1 ANY_subquery)*/
+postgres=# EXPLAIN SELECT *
+postgres=# FROM pgbench_accounts a1
+postgres=# 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)
+(6 rows)
+
+postgres=#
+</pre>
+
+<dt>IndexOnlyScanヒント句</dt>
+<dd>IndexOnlyScanヒントで指定されているインデックスで index only scan が実行できない場合は、index scan を他のインデックスで実行する可能性があります。</dd>
+
+<dt>NoIndexScanヒントの挙動について</dt>
+<dd>NoIndexScanヒント句を指定した場合は、Index ScanだけでなくIndex Only Scanも選択されません。</dd>
+</dl>
+
+<dt>UNION に対する並列実行ヒント</dt>
+<dd>UNIONは直下のサブクエリが全て並列実行可能な場合にだけ並列実行を行います。一方ですべてのサブクエリが並列実行可能な場合は、そのうちの一つで並列実行を強制するとコスト比較の結果UNION全体が並列実行されることになります。ただし並列実行ヒントによる並列実行の禁止を行った場合はそのスキャンは並列実行不可となります。
+</dd>
+</dl>
+
+<dt>Set ヒントでの pg_hint_plan 自身の制御変数の設定</dt>
+<dd>pg_hint_plan 自身の挙動を設定する変数を Set ヒントで変更した場合は期待通りに動作しない場合があります。</dd>
+<ul>
+<li>enable_hint, enable_hint_tables の設定ヒントはログ上は「使用済み」と出ますが、実際には無視されています。</li>
+<li>debug_print と message_level の変更は処理の途中から影響を与えます。</li>
+</ul>
+</dd>
+
+<h2>ヒントのパースエラーについて</h2>
+<dt>構文エラー</dt>
+<dd>ヒント句の記述に構文上の誤りがあった場合、pg_hint_planは誤った記述より前のヒント句のみ有効とし、誤った記述以降のヒント句を無視してクエリを実行します。誤りの内容はpg_hint_plan.parse_messagesで指定したレベルでサーバログに記録されます。
+<ul>
+<li>ヒント句名を間違っている。</li>
+<li>オブジェクト指定を正しく括弧で囲っていない。</li>
+<li>オブジェクト名を空白で区切っていない。</li>
+</ul>
+</dd>
+<dt>オブジェクト指定エラー</dt>
+<dd>pg_hint_planは、ヒント句対象のオブジェクト指定に誤りがあった場合、pg_hint_planは正常に解析できたヒントのみを適用して、それ以外を無視します。誤りの内容はpg_hint_plan.parse_messagesで指定したレベルでサーバログに記録されます。
+<ul>
+</dd>
+
+<dt>重複したヒント</dt>
+<dd>同じオブジェクトに対して同じグループのヒント句を重複して指定した場合は、各グループで最後に指定したヒント句を使用します。</dd>
+<dt>ネストしたブロックコメント</dt>
+<dd>pg_hint_planでは、ヒントを指定したブロックコメントにネストしたブロックコメントを含めることができません。ネストしたブロックコメントを含めた場合は、誤った記述に関する情報を出力しますがエラー終了しません。ヒントを無視してクエリを実行します。</dd>
+<dt>メッセージの出力レベル</dt>
+<dd>ヒントに誤りがあった場合に出力されるメッセージのレベルは、基本的にはpg_hint_plan.parse_messagesに指定したレベルです。ただし、ヒント句に指定したオブジェクトの長さが識別子の最大長(デフォルトでは63バイト)を超えた際に切り詰めた場合は、NOTICEで出力します。</dd>
+
+<h2>注意事項</h2>
+<dt>プランナパラメータの影響</dt>
+<dd>FROM句の要素数が from_collapse_limit 以上または join_collapse_limit を超える場合には、結合順序のヒント句は正しく動作しません。また、FROM句の要素数が geqo_threshold 以上の場合は、結合順序のヒント句、および結合方式のヒント句は動作しません。ヒント句が使われるようにするには、これらのGUCパラメータの値を十分に大きくしてください。</dd>
+<dt>実行不能なプランを指定するヒント</dt>
+<dd>ヒントで指定した結果正しく実行できない実行計画が生成される場合は、実行可能なプランに強制的に修正します。実行不能な実行計画例を以下に示します。
+<ul>
+<li>特殊な場合を除いた FULL OUTER JOINに対する Nested Loop。</li>
+<li>WHERE句やJOIN条件などに指定していない列のみを含むインデックス。</li>
+<li>検索条件にctidを指定しない場合の Tid Scan。</li>
+</ul>
+</dd>
+<dt>ECPGにおける制限</dt>
+<dd>ECPGで実装したアプリケーションから発行するクエリにヒントをコメントで指定した場合、実行計画を制御できません。これは、CプリプロセッサがCコードに変換するタイミングで、全てのブロックコメントを取り除いてしまうためです。ただし、EXECUTEコマンドで実行する動的SQLに含まれるコメントは使用可能です。</dd>
+<dt>異なるヒントを与えた同一クエリの pg_stat_statements での扱い</dt>
+<dd>pg_stat_statements ではクエリIDの生成の際にコメントは無視されます。そのため与えているヒントが異なる同一のクエリは一つのクエリとして集計されます。</dd>
+
+</dl>
+
+<h2 id="requirement">動作環境</h2>
+pg_hint_plan14 1.6 は PostgreSQL 14 のみをサポートします。
+<dl>
+<dt>PostgreSQL</dt>
+ <dd>バージョン 14</dd>
+<dt>動作確認済みOS</dt>
+ <dd>CentOS 8.5</dd>
</dl>
<h2 id="seealso">関連項目</h2>
<h3 id="postgresql_document">PostgreSQLドキュメント</h3>
-<a href="http://www.postgresql.org/docs/9.1/static/sql-explain.html">EXPLAIN</a>
-<a href="http://www.postgresql.org/docs/9.1/static/sql-set.html">SET</a>
-<a href="http://www.postgresql.org/docs/9.1/static/runtime-config.html">サーバの設定</a>
+<a href="http://www.postgresql.jp/document/current/html/sql-explain.html">EXPLAIN</a>
+<a href="http://www.postgresql.jp/document/current/html/sql-set.html">SET</a>
+<a href="http://www.postgresql.jp/document/current/html/runtime-config.html">サーバの設定</a>
+<a href="http://www.postgresql.jp/document/current/html/parallel-plans.html">パラレルプラン</a>
<hr>
<div class="navigation">
<a href="pg_hint_plan-ja.html">pg_hint_plan</a>
</div>
-<p class="footer">Copyright (c) 2012, NIPPON TELEGRAPH AND TELEPHONE CORPORATION</p>
-
-<!--
-<script type="text/javascript">
-var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
-document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
-</script><script src="pg_statsinfo-ja_files/ga.js" type="text/javascript"></script>
-<script type="text/javascript">
-try{
-var pageTracker = _gat._getTracker("UA-10244036-6");
-pageTracker._trackPageview();
-} catch(err) {}
-</script>
--->
+<p class="footer">Copyright (c) 2012-2022, NIPPON TELEGRAPH AND TELEPHONE CORPORATION</p>
</body>
</html>
OSDN Git Service
