doc/pg_hint_plan-ja.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD html 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <title>pg_hint_plan</title>
   5 <!-- Uncoment 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 </head>
  11
  12 <body>
  13 <h1 id="pg_hint_plan">pg_hint_plan 0.1.0</h1>
  14 <div class="navigation">
  15   <a href="pg_hint_plan-ja.html">pg_hint_plan</a>
  16 </div>
  17 <hr>
  18
  19 <div class="index">
  20 <ol>
  21 <li><a href="#name">pg_hint_planとは？</a></li>
  22 <li><a href="#description">機能概要</a></li>
  23 <li><a href="#install">インストール</a>
  24 <ol>
  25   <li><a href="#requirement">動作環境</a></li>
  26   <li><a href="#build">ビルド</a></li>
  27 </ol>
  28 </li>
  29 <li><a href="#uninstall">アンインストール</a></li>
  30 <li><a href="#usage">使い方</a>
  31 <ol>
  32   <li><a href="#hint-load">pg_hint_planのロード</a></li>
  33   <li><a href="#hint-rule">ヒントの記述方法</a></li>
  34   <li><a href="#hint-group">ヒントのグループ</a></li>
  35   <li><a href="#hint-GUC">pg_hint_planのGUCパラメータ</a></li>
  36 </ol>
  37 </li>
  38 <li><a href="#restrictions">使用上の注意と制約</a></li>
  39 <li><a href="#known-issues">既知の問題</a></li>
  40 <li><a href="#seealso">関連項目</a></li>
  41 <li><a href="hint_list-ja.html">Appendix A. ヒント一覧</a></li>
  42 </div>
  43
  44 <h2 id="name">pg_hint_planとは？</h2>
  45 <p>pg_hint_planは、元のSQL文を変えずに実行計画を制御するためのツールです。</p>
  46
  47 <h2 id="description">機能概要</h2>
  48 <p>pg_hint_planを用いると、ヒントを記述したブロックコメントをSQL文の前に加えることで、実行計画を制御することができます。</p>
  49
  50 <h2 id="install">インストール</h2>
  51 <p>pg_hint_planのインストール方法について説明します。</p>
  52
  53 <h3 id="requirement">動作環境</h3>
  54 <dl>
  55 <dt>PostgreSQL</dt>
  56   <dd>バージョン 9.1.3</dd>
  57   <dd>バージョン 9.2devel 4月2日版</dd>
  58 <dt>動作検証済みOS</dt><dd>RHEL 6.1</dd>
  59 </dl>
  60
  61 <h3 id="build">ビルド</h3>
  62 <p>pg_hint_planをソースコードからビルドする場合、pg_hint_planのソースを展開したディレクトリでmake → make installの順に実行してください。なお、pg_hint_planのビルドにはpgxsを使用するので、RPM版のPostgreSQLを使用している環境では、postgresql-devel パッケージが必要です。</p>
  63 <p>以下にビルドの例を示します。</p>
  64 <pre>
  65 $ tar xzvf pg_hint_plan-0.1.0.tar.gz
  66 $ cd pg_hint_plan-0.1.0
  67 $ make
  68 $ make install
  69 </pre>
  70
  71 <h2 id="uninstall">アンインストール</h2>
  72 <p>pg_hint_planをアンインストールするには、pg_hint_planのソースを展開したディレクトリでmake uninstallを実行してください。</p>
  73 <p>以下にアンインストールの例を示します。</p>
  74 <pre>
  75 $ cd pg_hint_plan-0.1.0
  76 $ make uninstall
  77 </pre>
  78
  79 <h2 id="usage">使い方</h2>
  80 <p>pg_hint_planの使い方について説明します。</p>
  81
  82 <h3 id="hint-load">pg_hint_planのロード</h3>
  83 <p>pg_hint_planを使うには、以下の例のようにpg_hint_planの共有ライブラリをロードしてください。全てのセッションでpg_hint_planを有効にするには、shared_preload_libraries GUCパラメータに'pg_hint_plan'を追加してからサーバを再起動して下さい。</p>
  84 <pre>
  85 postgres=# LOAD 'pg_hint_plan';
  86 LOAD
  87 postgres=# </pre>
  88
  89 <h3 id="hint-rule">ヒントの記述方法</h3>
  90 <p>ヒントはクエリの前のブロックコメント内に、スペース、タブ、または改行のいずれかで区切って記述してください。ブロックコメントをヒントとして認識させるには、ブロックコメントの開始直後に+（プラス）を指定する必要があります。ヒントの対象は、カッコ内にオブジェクト名または別名(エイリアス)で指定してください。</p>
  91
  92 <p>以下の例では、HashJoinとSeqScanヒントにより、pgbench_accountsテーブルに対するSeq Scanの結果をHash Joinする実行計画が選択されています。</p>
  93 <pre>
  94 postgres=# /*+
  95 postgres*#    <span class="strong">HashJoin(a b)</span>
  96 postgres*#    <span class="strong">SeqScan(a)</span>
  97 postgres*#  */
  98 postgres-# EXPLAIN SELECT *
  99 postgres-#    FROM pgbench_branches b
 100 postgres-#    JOIN pgbench_accounts a ON b.bid = a.bid
 101 postgres-#   ORDER BY a.aid;
 102                                       QUERY PLAN
 103 ---------------------------------------------------------------------------------------
 104  Sort  (cost=31465.84..31715.84 rows=100000 width=197)
 105    Sort Key: a.aid
 106    ->  <span class="strong">Hash Join</span>  (cost=1.02..4016.02 rows=100000 width=197)
 107          Hash Cond: (a.bid = b.bid)
 108          ->  <span class="strong">Seq Scan on pgbench_accounts a</span>  (cost=0.00..2640.00 rows=100000 width=97)
 109          ->  Hash  (cost=1.01..1.01 rows=1 width=100)
 110                ->  Seq Scan on pgbench_branches b  (cost=0.00..1.01 rows=1 width=100)
 111 (7 rows)
 112
 113 postgres=# </pre>
 114
 115 <h3 id="hint-group">ヒントのグループ</h3>
 116 <p>pg_hint_planで使えるヒントは、スキャン方式と結合方式、結合順序、GUCパラメータの4グループに分けられます。同じグループのヒントを同じオブジェクトに対して指定した場合は、最後に指定したヒントが適用されます。各グループの具体的なヒントは、<a href="hint_list-ja.html">ヒント一覧</a>を参照してください。</p>
 117
 118 <h4>スキャン方式</h4>
 119 <p>あるテーブルのスキャン方式を選択するかを指定できるヒントのグループで、「SeqScan」や「IndexScan」などが含まれます</p>
 120 <p>特定のテーブルについてあるスキャン方式を選択して欲しい場合は、そのスキャン方式のヒントと、対象となるオブジェクトの名前を指定してください。逆に、特定のテーブルについてあるスキャン方式を選択して欲しくない場合は、Noで始まるヒントを指定してください。</p>
 121
 122 <h4>結合方式</h4>
 123 <p>あるテーブル結合の組み合わせでどの結合方式を選択するかを指定できるヒントのグループで、「MergeJoin」や「NestLoop」などが含まれます。</p>
 124 <p>特定のテーブルの組み合わせについてある結合方式を選択して欲しい場合は、その結合方式のヒントと、対象となる2つ以上のテーブルの名前を指定してください。逆に、特定の結合方式を選択して欲しくない場合は、Noで始まるヒントを指定してください。</p>
 125 <h4>結合順序</h4>
 126 <p>特定のテーブル結合の組み合わせでどのような順番で結合するか指定できるヒントのグループで、現在は「Leading」のみです。</p>
 127 <p>先に結合して欲しいテーブルから順にテーブル名またはテーブル別名を指定してください。</p>
 128 <h4>GUCパラメータ</h4>
 129 <p>そのクエリの実行計画を作成している間だけGUCパラメータを変更できるヒントのグループで、現在は「Set」のみです。</p>
 130 設定したいGUCパラメータとそのパラメータの値を指定してください。ただし、指定する値に小文字とアンダースコア(_)以外の文字(大文字、数字、スペースなど)を含む場合はダブルクォート(")で囲んでください。</p>
 131
 132 <h3 id="hint-GUC">pg_hint_planのGUCパラメータ</h3>
 133 <p>pg_hint_planツールに関するGUCパラメータを以下に記述します。</p>
 134 <table>
 135 <thead>
 136 <tr>
 137 <tr><th>GUCパラメータ</th><th>説明</th><th>デフォルト値</th></tr>
 138 </tr></thead>
 139 <tbody>
 140 <tr><td>pg_hint_plan.enable</td>
 141   <td>pg_hint_planの機能を有効または無効にします。</td><td>on</td></tr>
 142 <tr><td>pg_hint_plan.debug_print</td>
 143   <td>pg_hint_planのデバッグ出力を有効にします。メッセージはLOGメッセージレベルで出力されますので、デフォルトではサーバログに出力され、クライアントには渡されません。</td><td>off</td></tr>
 144 <tr><td>pg_hint_plan.parse_messages</td>
 145   <td>指定したヒントを解釈できなかった場合に、どのメッセージ階層でログを出力するかを指定します。有効な値は、debug5、debug4、debug3、debug2、debug1、log、info、notice、warning、またはerrorです。fatalとpanicは指定できません。</td><td>info</td></tr>
 146 </tbody>
 147 </table>
 148
 149 <h2 id="restrictions">使用上の注意と制約</h2>
 150 <p>pg_hint_planを使用する際には、以下の注意と制約があります。</p>
 151 <dl>
 152 <dt>ヒントの記述位置</dt>
 153 <dd>クエリの前に複数のブロックコメントを記述する場合は、最初のブロックコメントにのみヒントを記述してください。二番目以降のブロックコメントは、ヒントと見なされず無視されます。以下の例では、HashJoin(a b)とSeqScan(a)がヒントと見なされ、IndexScan(a)とMergeJoin(a b)は無視されています。</p>
 154 <pre>
 155 postgres=# /*+
 156 postgres*#    <span class="strong">HashJoin(a b)</span>
 157 postgres*#    <span class="strong">SeqScan(a)</span>
 158 postgres*#  */
 159 postgres-# /*+ IndexScan(a) */
 160 postgres-# EXPLAIN SELECT /*+ MergeJoin(a b) */ *
 161 postgres-#    FROM pgbench_branches b
 162 postgres-#    JOIN pgbench_accounts a ON b.bid = a.bid
 163 postgres-#   ORDER BY a.aid;
 164                                       QUERY PLAN
 165 ---------------------------------------------------------------------------------------
 166  Sort  (cost=31465.84..31715.84 rows=100000 width=197)
 167    Sort Key: a.aid
 168    ->  <span class="strong">Hash Join</span>  (cost=1.02..4016.02 rows=100000 width=197)
 169          Hash Cond: (a.bid = b.bid)
 170          ->  <span class="strong">Seq Scan on pgbench_accounts a</span>  (cost=0.00..2640.00 rows=100000 width=97)
 171          ->  Hash  (cost=1.01..1.01 rows=1 width=100)
 172                ->  Seq Scan on pgbench_branches b  (cost=0.00..1.01 rows=1 width=100)
 173 (7 rows)
 174
 175 postgres=# </pre>
 176 </dd>
 177 <dt>オブジェクト名の引用</dt>
 178 <dd>ヒントに記述するオブジェクト名や別名が大文字や空白などの特殊な文字を含む場合は、通常のSQL文で使う場合と同じようにダブルクォート(")で囲んでください。</dd>
 179 <dt>同一名称テーブルの区別</dt>
 180 <dd>スキーマ違いや同一テーブルの複数回使用などでクエリ中に同一名称のテーブルが複数回出現する場合は、テーブルに別名をつけてそれぞれのテーブルを区別してください。以下の例の1つ目のSQL文では、MergeJoin(t1 t1)をヒントに指定したとき、ヒント対象のオブジェクトが特定できずにエラーになっています。2つ目のSQL文では、各テーブルにptやstという別名をつけているため、実行計画作成時にヒントで指定した通りにMerge Joinを選択しています。
 181 </p>
 182 <pre>
 183 postgres=# /*+ <span class="strong">MergeJoin(t1 t1)</span>*/
 184 postgres-# EXPLAIN SELECT * FROM s1.t1
 185 postgres-# JOIN public.t1 ON (s1.t1.id=public.t1.id);
 186 INFO:  hint syntax error at or near "t1 t1)"
 187 <span class="strong">DETAIL:  relation name "t1" is ambiguous</span>
 188 INFO:  hint syntax error at or near "t1 t1)"
 189 <span class="strong">DETAIL:  relation name "t1" is ambiguous</span>
 190                              QUERY PLAN
 191 --------------------------------------------------------------------
 192  Hash Join  (cost=270.00..323.05 rows=1230 width=44)
 193    Hash Cond: (s1.t1.id = public.t1.id)
 194    ->  Seq Scan on t1  (cost=0.00..22.30 rows=1230 width=36)
 195    ->  Hash  (cost=145.00..145.00 rows=10000 width=8)
 196          ->  Seq Scan on t1  (cost=0.00..145.00 rows=10000 width=8)
 197 (5 rows)
 198
 199 postgres=# /*+ <span class="strong">MergeJoin(pt st)</span> */
 200 postgres-# EXPLAIN SELECT * FROM s1.t1 st
 201 postgres-# JOIN public.t1 pt ON (st.id=pt.id);
 202                                     QUERY PLAN
 203 ----------------------------------------------------------------------------------
 204  <span class="strong">Merge Join</span>  (cost=0.00..421.33 rows=1230 width=44)
 205    Merge Cond: (st.id = pt.id)
 206    ->  Index Scan using t1_id_idx on t1 st  (cost=0.00..62.70 rows=1230 width=36)
 207    ->  Index Scan using t1_pkey on t1 pt  (cost=0.00..318.25 rows=10000 width=8)(4 rows)
 208
 209 postgres=#</pre>
 210 </p>
 211 </dd>
 212 <dt>ヒントの記述誤り</dt>
 213 <dd>pg_hint_planでは、ヒントの記述に誤りがあった場合は、誤った記述に関する情報を出力しますがエラー終了しません。誤った記述より前のヒントのみ有効となり、誤った記述以降のヒントを無視してクエリを実行します。</dd>
 214 <dt>指定するヒントの種類の重複</dt>
 215 <dd>同じオブジェクトに対して同じグループのヒントを重複して指定した場合は、最後に指定したヒントを使用します。</dd>
 216 <dt>PREPARE/EXECUTEに対する制限</dt>
 217 <dd>実行計画を制御したいSQL文をPREPARE文とEXECUTE文で実行する場合は、PREPARE文だけでなくEXECUTE文にも同じヒントを指定してください。これは、EXECUTE文実行時に実行計画を再作成する場合があるためです。</dd>
 218 <dt>ビューに対する制限</dt>
 219 <dd>ビューを複数用いるときに、各ビュー内のテーブルの別名が重複した場合は、ヒントの対象を区別できません。区別する場合は、各ビュー内のテーブルの別名を重複させないでください。</dd>
 220 </dl>
 221
 222 <h2 id="known-issues">既知の問題</h2>
 223 <p>pg_hint_planに関する既知の問題について説明します。</p>
 224 <dl>
 225 <dt>副問い合わせを含むSELECT文</dt>
 226 <dd id="view_limit">pg_hint_planの使用中に副問い合わせを含むSELECT文を実行すると、サーバ側で異常終了する場合があります。よって、pg_hint_planを試用しているときは、副問い合わせを含むSELECT文を実行しないでください。</dd>
 227 </dl>
 228
 229 <h2 id="seealso">関連項目</h2>
 230 <h3 id="postgresql_document">PostgreSQLドキュメント</h3>
 231 <a href="http://www.postgresql.org/docs/9.1/static/sql-explain.html">EXPLAIN</a>
 232 <hr>
 233
 234 <div class="navigation">
 235   <a href="pg_hint_plan-ja.html">pg_hint_plan</a>
 236 </div>
 237
 238 <p class="footer">Copyright (c) 2012, NIPPON TELEGRAPH AND TELEPHONE CORPORATION</p>
 239
 240 <!--
 241 <script type="text/javascript">
 242 var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
 243 document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
 244 </script><script src="pg_statsinfo-ja_files/ga.js" type="text/javascript"></script>
 245 <script type="text/javascript">
 246 try{
 247 var pageTracker = _gat._getTracker("UA-10244036-6");
 248 pageTracker._trackPageview();
 249 } catch(err) {}
 250 </script>
 251 -->
 252 </body>
 253 </html>