html/pg_bigm-1-2.html

   1 <html>
   2 <head>
   3 <title>pg_bigm 1.2 ドキュメント</title>
   4
   5 <link rel="stylesheet" type="text/css" href="style.css">
   6 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   7 </head>
   8
   9 <body>
  10   <div id="navigation">
  11     <ul>
  12       <li><a href="index.html">ホーム</a></li>
  13       <li><a href="http://osdn.jp/projects/pgbigm/releases/?package_id=13634">ダウンロード</a></li>
  14       <li><a href="index.html#document">ドキュメント</a></li>
  15       <li><a href="index.html#community">コミュニティ</a></li>
  16       <li><a href="index.html#development">開発</a></li>
  17       <li><a href="pg_bigm_en-1-2.html">English</a></li>
  18     </ul>
  19   </div>
  20
  21 <h1 id="pg_bigm">ドキュメント (リリース1.2)</h1>
  22
  23 <div class="index">
  24 <ol>
  25 <li><a href="#description">概要</a></li>
  26 <li><a href="#pg_trgm">pg_trgmとの違い</a></li>
  27 <li><a href="#requirement">動作確認環境</a></li>
  28 <li><a href="#install">インストール</a></li>
  29 <li><a href="#uninstall">アンインストール</a></li>
  30 <li><a href="#fulltext_search">全文検索機能</a></li>
  31 <li><a href="#functions">提供関数</a></li>
  32 <li><a href="#parametares">パラメータ</a></li>
  33 <li><a href="#limitations">制約</a></li>
  34 <li><a href="#release_notes">リリースノート</a></li>
  35 </ol>
  36 </div>
  37
  38 <h2 id="description">概要</h2>
  39 <p>pg_bigm(ピージーバイグラム)は、<a href="http://www.postgresql.org/">PostgreSQL</a>上で全文検索機能を提供するモジュールです。このモジュールを使うことで、ユーザは全文検索用のインデックスを作成でき、高速に文字列検索を行えるようになります。このモジュールは、2-gram(バイグラム)と呼ばれる方法で、文字列から全文検索用のインデックスを作成します。</p>
  40 <p><a href="http://osdn.jp/projects/pgbigm/">pg_bigmプロジェクト</a>では以下の1つのモジュールを提供します。</p>
  41
  42 <table>
  43 <thead>
  44 <tr>
  45 <th>モジュール名</th><th>概要</th><th>ソースアーカイブファイル名</th>
  46 </tr>
  47 </thead>
  48 <tbody>
  49 <tr><td>pg_bigm</td>
  50   <td nowrap>PostgreSQL上で全文検索機能を提供するモジュール</td>
  51   <td>pg_bigm-x.y-YYYYMMDD.tar.gz</td></tr>
  52 </tbody>
  53 </table>
  54
  55 <p>
  56 ソースアーカイブファイル名のx.yとYYYYMMDDの部分は、それぞれ、そのファイルのバージョン番号とリリース年月日です。
  57 例えば、2013年11月22日リリースのバージョン1.1のファイルでは、x.yは1.1、YYYYMMDDは20131122です。
  58 </p>
  59 <p>pg_bigmのライセンスは<a href="http://opensource.org/licenses/postgresql">The PostgreSQL License</a>(BSDに似たライセンス)です。</p>
  60
  61 <h2 id="pg_trgm">pg_trgmとの違い</h2>
  62 <p>PostgreSQLには、<a href="http://www.postgresql.jp/document/current/html/pgtrgm.html">pg_trgm</a>という3-gram(トライグラム)の全文検索モジュールがcontribに付属されています。 pg_bigmは、pg_trgmをベースに開発されています。 pg_trgmとpg_bigmでは、機能や特徴に以下の違いがあります。</p>
  63
  64 <table>
  65 <thead>
  66 <tr>
  67 <th>機能や特徴</th><th>pg_trgm</th><th>pg_bigm</th>
  68 </tr>
  69 </thead>
  70 <tbody>
  71 <tr><td>全文検索インデックスの作成方法</td>
  72   <td nowrap>3-gram</td>
  73   <td>2-gram</td></tr>
  74 <tr><td>利用できるインデックスの種類</td>
  75   <td nowrap>GINとGiST</td>
  76   <td>GINのみ</td></tr>
  77 <tr><td>利用できるテキスト検索演算子</td>
  78   <td nowrap>LIKE (~~)、ILIKE (~~*)、~、~*</td>
  79   <td>LIKEのみ</td></tr>
  80 <tr><td>日本語検索</td>
  81   <td nowrap>未対応(*1)</td>
  82   <td>対応済</td></tr>
  83 <tr><td>検索キーワード1～2文字での検索</td>
  84   <td nowrap>低速<br>(検索時に全文検索インデックスを使えない(*2))</td>
  85   <td>高速<br>(検索時に全文検索インデックスを使える)</td></tr>
  86 <tr><td>類似文字列の検索</td>
  87   <td nowrap>対応済</td>
  88   <td>対応済(バージョン1.1以降)</td></tr>
  89 <tr><td>インデックス作成が可能な列の最大サイズ</td>
  90   <td nowrap>238,609,291Byte (約228MB)</td>
  91   <td nowrap>107,374,180 Bytes (約102MB)</td></tr>
  92 </tbody>
  93 </table>
  94
  95 <ul>
  96 <li>(*1) ソースコード内の<a href="http://lets.postgresql.jp/documents/technical/text-processing/3#contains">マクロ変数を変更することで日本語検索に対応</a>できます。しかし、日本語検索の性能はpg_bigmに比べて低速です。</li>
  97 <li>(*2) 全文検索インデックスを使える場合もありますが、その場合はフルインデックススキャンが走るため検索性能は非常に低くなります。</li>
  98 </ul>
  99
 100 <p>pg_bigmのバージョン1.1以降では、pg_trgmとpg_bigmを同じデータベース内で共存させることが可能です。しかし、バージョン1.0では共存できないため、pg_bigmを登録するデータベースには、pg_trgmを同時に登録しないでください。</p>
 101
 102 <h2 id="requirement">動作確認環境</h2>
 103 <p>pg_bigmは、以下の環境で動作確認をしています。</p>
 104 <table>
 105 <thead>
 106 <tr>
 107 <th>カテゴリ</th><th>モジュール名</th>
 108 </tr>
 109 </thead>
 110 <tbody>
 111 <tr>
 112   <td>OS</td>
 113   <td nowrap>Linux, Mac OS X</td>
 114 </tr>
 115 <tr>
 116   <td>DBMS</td>
 117   <td nowrap>PostgreSQL 9.1, 9.2, 9.3, 9.4</td>
 118 </tr>
 119 </tbody>
 120 </table>
 121
 122 <p>pg_bigmは、PostgreSQL9.1以降に対応しています。9.0以前には未対応です。</p>
 123
 124 <h2 id="install">インストール</h2>
 125
 126 <h3 id="pg_install">PostgreSQLのインストール</h3>
 127 <p><a href="http://www.postgresql.org/">PostgreSQLのオフィシャルサイト</a>からPostgreSQLのソースアーカイブファイルpostgresql-X.Y.Z.tar.gz(X.Y.Zは実際のバージョン番号に置き換えてください)をダウンロードし、ビルドとインストールを行います。</p>
 128 <pre>
 129 $ tar zxf postgresql-X.Y.Z.tar.gz
 130 $ cd postgresql-X.Y.Z
 131 $ ./configure --prefix=/opt/pgsql-X.Y.Z
 132 $ make
 133 $ su
 134 # make install
 135 # exit</pre>
 136 <ul>
 137 <li>--prefix : インストール先ディレクトリを指定します。このオプション指定は必須ではありません。未指定時のインストール先は/usr/local/pgsqlです。</li>
 138 </ul>
 139 <p>RPMからPostgreSQLをインストールしてもpg_bigmは利用可能です。 この場合、postgresql-develパッケージをインストールしなければならないことに注意してください。</p>
 140
 141 <h3 id="bigm_install">pg_bigmのインストール</h3>
 142 <p><a href="http://osdn.jp/projects/pgbigm/releases/?package_id=13634">ここ</a>からpg_bigmのソースアーカイブファイルをダウンロードし、ビルドとインストールを行います。</p>
 143 <pre>
 144 $ tar zxf pg_bigm-x.y-YYYYMMDD.tar.gz
 145 $ cd pg_bigm-x.y-YYYYMMDD
 146 $ make USE_PGXS=1 PG_CONFIG=/opt/pgsql-X.Y.Z/bin/pg_config
 147 $ su
 148 # make USE_PGXS=1 PG_CONFIG=/opt/pgsql-X.Y.Z/bin/pg_config install
 149 # exit
 150 </pre>
 151 <ul>
 152 <li>USE_PGXS : PostgreSQL関連モジュールをコンパイルするときのオマジナイです。USE_PGXS=1の指定が必須です。</li>
 153 <li>PG_CONFIG : <a href="http://www.postgresql.jp/document/current/html/app-pgconfig.html">pg_config</a>コマンド(PostgreSQLインストール先のbinディレクトリに存在)のパスを指定します。pg_configにPATHが通っているのであれば、このオプション指定は不要です。</li>
 154 </ul>
 155
 156 <h3 id="bigm_register">pg_bigmの登録</h3>
 157 <p>データベースクラスタの作成後、postgresql.confを編集、PostgreSQLを起動し、pg_bigmをデータベースに登録します。</p>
 158 <pre>
 159 $ initdb -D $PGDATA --locale=C --encoding=UTF8
 160
 161 $ vi $PGDATA/postgresql.conf
 162 shared_preload_libraries = 'pg_bigm'
 163
 164 $ pg_ctl -D $PGDATA start
 165 $ psql -d &lt;データベース名&gt;
 166 =# CREATE EXTENSION pg_bigm;
 167 =# \dx pg_bigm
 168                     List of installed extensions
 169   Name   | Version | Schema |              Description
 170 ---------+---------+--------+---------------------------------------
 171  pg_bigm | 1.1     | public | text index searching based on bigrams
 172 (1 row)
 173 </pre>
 174
 175 <ul>
 176 <li>$PGDATAは、データベースクラスタのパスを決めて、そのパスで置き換えてください。</li>
 177 <li>pg_bigmは、PostgreSQLで利用できるすべてのエンコーディングとロケールをサポートしています。</li>
 178 <li>postgresql.confで、<a href="http://www.postgresql.jp/document/current/html/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a>または<a href="http://www.postgresql.jp/document/current/html/runtime-config-client.html#GUC-SESSION-PRELOAD-LIBRARIES">session_preload_libraries</a>(PostgreSQL9.4以降で利用可能)に'pg_bigm'を設定して、pg_bigmの共有ライブラリをサーバにプリロードしなければなりません。
 179   <ul>
 180     <li>PostgreSQL9.1では、<a href="http://www.postgresql.jp/document/9.1/html/runtime-config-custom.html#GUC-CUSTOM-VARIABLE-CLASSES">custom_variable_classes</a>も'pg_bigm'に設定しなければなりません。</li>
 181   </ul>
 182 </li>
 183 <li>pg_bigmの登録には、<a href="http://www.postgresql.jp/document/current/html/sql-createextension.html">CREATE EXTENSION</a>を使います。 CREATE EXTENSIONはデータベース単位でモジュールを登録するため、pg_bigmを利用したいデータベースすべてにおいて登録が必要です。</li>
 184 </ul>
 185 <p>pg_bigmのインストールは以上で終わりです。</p>
 186
 187
 188 <h2 id="uninstall">アンインストール</h2>
 189
 190 <h3 id="bigm_uninstall">pg_bigmの削除</h3>
 191 <p>pg_bigmについて、データベースからの登録解除とアンインストールを行います。</p>
 192 <pre>
 193 $ psql -d &lt;データベース名&gt;
 194 =# DROP EXTENSION pg_bigm CASCADE;
 195 =# \q
 196
 197 $ pg_ctl -D $PGDATA stop
 198 $ su
 199
 200 # cd &lt;pg_bigmのソースディレクトリ&gt;
 201 # make USE_PGXS=1 PG_CONFIG=/opt/pgsql-X.Y.Z/bin/pg_config uninstall
 202 # exit
 203 </pre>
 204
 205 <ul>
 206 <li>pg_bigmを登録したすべてのデータベースで登録解除する必要があります。</li>
 207 <li>pg_bigmに依存するDBオブジェクト(例えば、pg_bigmを使った全文検索インデックス)を削除する必要があるため、<a href="http://www.postgresql.jp/document/current/html/sql-dropextension.html">DROP EXTENSION</a>にはCASCADEを指定します。</li>
 208 </ul>
 209
 210 <h3 id="delete_conf">postgresql.confの設定削除</h3>
 211 <p>postgresql.confの以下の設定を削除します</p>
 212 <ul>
 213 <li>shared_preload_librariesまたはsession_preload_libraries</li>
 214 <li>custom_variable_classes (PostgreSQL9.1のみ)</li>
 215 <li>pg_bigm.* (pg_bigm.から名前が始まるパラメータ)</li>
 216 </ul>
 217
 218 <h2 id="fulltext_search">全文検索機能</h2>
 219
 220 <h3 id="create_index">インデックスの作成</h3>
 221 <p>GINインデックスを利用して全文検索用のインデックスを作成します。</p>
 222 <p>以下の実行例では、PostgreSQL関連ツールの名前と説明を管理するテーブルpg_toolsを作成し、4件データを投入します。その後、ツールの説明に対して全文検索用のインデックスを作成します。</p>
 223
 224 <pre>
 225 =# CREATE TABLE pg_tools (tool text, description text);
 226
 227 =# INSERT INTO pg_tools VALUES ('pg_hint_plan', 'PostgreSQLでHINT句を使えるようにするツール');
 228 =# INSERT INTO pg_tools VALUES ('pg_dbms_stats', 'PostgreSQLの統計情報を固定化するツール');
 229 =# INSERT INTO pg_tools VALUES ('pg_bigm', 'PostgreSQLで2-gramの全文検索を使えるようにするツール');
 230 =# INSERT INTO pg_tools VALUES ('pg_trgm', 'PostgreSQLで3-gramの全文検索を使えるようにするツール');
 231
 232 =# CREATE INDEX pg_tools_idx ON pg_tools USING gin (description gin_bigm_ops);
 233 </pre>
 234
 235 <ul>
 236 <li>インデックスメソッドにはginの指定が必須です。 pg_bigmでは、pg_trgmとは異なりインデックス作成にGiSTを使えません。</li>
 237 <li>演算子クラスにはgin_bigm_opsの指定が必須です。</li>
 238 </ul>
 239
 240 <p>また、以下の実行例のように、全文検索用のマルチカラムインデックスを作成したり、作成時にGINインデックスのパラメータを指定することもできます。</p>
 241
 242 <pre>
 243 =# CREATE INDEX pg_tools_multi_idx ON pg_tools USING gin (tool gin_bigm_ops, description gin_bigm_ops) WITH (FASTUPDATE = off);
 244 </pre>
 245
 246 <h3 id="do_fulltext_search">全文検索の実行</h3>
 247 <p>pg_bigmでは、LIKE演算子の中間一致検索により全文検索を行います。</p>
 248 <pre>
 249 =# SELECT * FROM pg_tools WHERE description LIKE '%全文検索%';
 250   tool   |                     description
 251 ---------+------------------------------------------------------
 252  pg_bigm | PostgreSQLで2-gramの全文検索を使えるようにするツール
 253  pg_trgm | PostgreSQLで3-gramの全文検索を使えるようにするツール
 254 (2 rows)
 255 </pre>
 256 <ul>
 257 <li>検索文字列は<a href="#likequery">likequery</a>に記載されているとおり、全文検索用に変換されなければなりません。</li>
 258 </ul>
 259
 260 <h3 id="similarity_search">類似度検索の実行</h3>
 261 <p>pg_bigmでは、=% 演算子を使って類似度検索を行います。</p>
 262 <p>以下の実行例では、文字列「bigm」に似た文字列のtool列を検索しています。この類似度検索も、全文検索と同様にインデックスにより高速に実行されます。文字列どうしが似ているかどうかは、それら文字列の類似度が<a href="#similarity_limit">pg_bigm.similarity_limit</a>の設定値以上かどうかで判断されます。この実行例では、文字列「bigm」との類似度が0.2以上だった「pg_bigm」と「pg_trgm」のtool列だけが検索結果となります。</p>
 263 <pre>
 264 =# SET pg_bigm.similarity_limit TO 0.2;
 265
 266 =# SELECT tool FROM pg_tools WHERE tool =% 'bigm';
 267   tool
 268 ---------
 269  pg_bigm
 270  pg_trgm
 271 (2 rows)
 272 </pre>
 273 <p>
 274 類似度の計算方法や注意点については、類似度を計算する関数<a href="#bigm_similarity">bigm_similarity</a>を参照してください。
 275 </p>
 276
 277 <h2 id="functions">提供関数</h2>
 278 <h3 id="likequery">likequery</h3>
 279 <p>likequeryは、全文検索できるように、検索文字列(引数1)をLIKE演算子のパターンに変換する関数です。</p>
 280 <ul>
 281 <li>引数1(text) - 検索文字列</li>
 282 <li>戻り値(text) - 全文検索用に、引数1をLIKE演算子のパターンに変換した文字列</li>
 283 </ul>
 284
 285 <p>引数1がNULLの場合、戻り値はNULLです。</p>
 286
 287 <p>変換は、具体的には以下を行います。</p>
 288 <ul>
 289 <li>検索文字列の先頭と末尾に%(半角パーセント)を追加</li>
 290 <li>検索文字列内の%(半角パーセント)、_(半角アンダースコア)、\(半角バックスラッシュ)を\(半角バックスラッシュ)でエスケープ</li>
 291 </ul>
 292
 293 <p>pg_bigmでは、LIKE演算子の中間一致検索により全文検索を行います。このため、上記のとおり検索文字列を変換して、LIKE演算子に渡す必要があります。この変換は、通常、クライアントアプリケーション側で実装しなければなりません。しかし、likequeryを利用することで、その実装の手間を省くことができます。</p>
 294
 295 <pre>
 296 =# SELECT likequery('pg_bigmは検索性能を200%向上させました。');
 297                   likequery
 298 ---------------------------------------------
 299  %pg\_bigmは検索性能を200\%向上させました。%
 300 (1 row)
 301 </pre>
 302
 303 <p>「全文検索の実行」の実行例の検索SQLは、likequeryを使うことで、以下のように書き換えられます。</p>
 304 <pre>
 305 =# SELECT * FROM pg_tools WHERE description LIKE likequery('全文検索');
 306   tool   |                     description
 307 ---------+------------------------------------------------------
 308  pg_bigm | PostgreSQLで2-gramの全文検索を使えるようにするツール
 309  pg_trgm | PostgreSQLで3-gramの全文検索を使えるようにするツール
 310 (2 rows)
 311 </pre>
 312
 313 <h3 id="show_bigm">show_bigm</h3>
 314 <p>show_bigmは、文字列(引数1)のすべての2-gram文字列を配列として表示する関数です。</p>
 315
 316 <ul>
 317 <li>引数1(text) - 文字列</li>
 318 <li>戻り値(text[]) - 引数1のすべての2-gram文字列から構成される配列</li>
 319 </ul>
 320
 321 <p>2-gram文字列とは、文字列の先頭と末尾に空白文字を追加した上で、文字列を1文字ずつずらしながら、2文字単位で抽出した文字列のことです。例えば、文字列「ABC」の2-gram文字列は、「(空白)A」「AB」「BC」「C(空白)」の4つになります。</p>
 322
 323 <pre>
 324 =#  SELECT show_bigm('PostgreSQLの全文検索');
 325                             show_bigm
 326 -----------------------------------------------------------------
 327  {の全,全文,文検,検索,"索 "," P",Lの,Po,QL,SQ,eS,gr,os,re,st,tg}
 328 (1 row)
 329 </pre>
 330
 331 <h3 id="bigm_similarity">bigm_similarity</h3>
 332 <p>bigm_similarityは、文字列(引数1)と文字列(引数2)の類似度(文字列がどの程度似ているかを示す数値)を返却する関数です。</p>
 333
 334 <ul>
 335 <li>引数1(text) - 文字列</li>
 336 <li>引数2(text) - 文字列</li>
 337 <li>戻り値(real) - 引数1と引数2の文字列の類似度</li>
 338 </ul>
 339
 340 <p>
 341 この関数は、各文字列の2-gram文字列から一致するものの個数を数えることで類似度を計算します。
 342 類似度は0(2つの文字列にまったく類似性がないことを示す)から1(2つの文字列が同一であることを示す)までの範囲です。
 343 </p>
 344
 345 <pre>
 346 =# SELECT bigm_similarity('PostgreSQLの全文検索', 'postgresの検索');
 347  bigm_similarity
 348 -----------------
 349           0.4375
 350 (1 row)
 351 </pre>
 352
 353 <p>
 354 類似度計算に使われる2-gram文字列は、文字列の先頭と末尾に空白文字が追加された上で作成されることに注意してください。
 355 このため、例えば、文字列「B」は文字列「ABC」に含まれますが、下記のとおり一致する2-gram文字列がないため類似度は0になります。
 356 一方、文字列「A」は、下記のとおり一致する2-gram文字列があるため類似度は0より大きくなります。
 357 これは、pg_trgmのsimilarity関数と基本的に同じ挙動です。
 358
 359 <ul>
 360 <li>文字列「ABC」の2-gram文字列は「(空白)A」「AB」「BC」「C(空白)」</li>
 361 <li>文字列「A」の2-gram文字列は「(空白)A」「A(空白)」</li>
 362 <li>文字列「B」の2-gram文字列は「(空白)B」「B(空白)」</li>
 363 </ul>
 364 </p>
 365
 366 <pre>
 367 =# SELECT bigm_similarity('ABC', 'A');
 368  bigm_similarity
 369 -----------------
 370             0.25
 371 (1 row)
 372
 373 =# SELECT bigm_similarity('ABC', 'B');
 374  bigm_similarity
 375 -----------------
 376                0
 377 (1 row)
 378 </pre>
 379
 380 <p>
 381 bigm_similarityは、英字の大文字と小文字を区別することに注意してください。
 382 一方、pg_trgmのsimilarity関数は、英字の大文字と小文字を区別しません。
 383 例えば、「ABC」と「abc」の類似度は、pg_trgmのsimilarity関数では1ですが、bigm_similarityでは0です。
 384 </p>
 385
 386 <pre>
 387 =# SELECT similarity('ABC', 'abc');
 388  similarity
 389 ------------
 390           1
 391 (1 row)
 392
 393 =# SELECT bigm_similarity('ABC', 'abc');
 394  bigm_similarity
 395 -----------------
 396                0
 397 (1 row)
 398 </pre>
 399
 400 <h3 id="pg_gin_pending_stats">pg_gin_pending_stats</h3>
 401 <p>pg_gin_pending_statsは、GINインデックス(引数1)の待機リストに含まれているデータのページ数とタプル数を返却する関数です。</p>
 402
 403 <ul>
 404 <li>引数1(regclass) - GINインデックスの名前もしくはOID</li>
 405 <li>戻り値1(integer) - GINインデックス(引数1)の待機リストに含まれているデータのページ数</li>
 406 <li>戻り値2(bigint) - GINインデックス(引数1)の待機リストに含まれているデータのタプル数</li>
 407 </ul>
 408
 409 <p>
 410 FASTUPDATEオプション無効で作成されたGINインデックスが引数1の場合、そのGINインデックスは待機リストを持たないため、戻り値1と2は0となることに注意してください。
 411 GINインデックスの待機リストとFASTUPDATEオプションの詳細は、<a href="http://www.postgresql.jp/document/current/html/gin-implementation.html#GIN-FAST-UPDATE">GIN高速更新手法</a>を参照してください。
 412 </p>
 413
 414 <pre>
 415 =# SELECT * FROM pg_gin_pending_stats('pg_tools_idx');
 416  pages | tuples
 417 -------+--------
 418      1 |      4
 419 (1 row)
 420 </pre>
 421
 422 <h3 id="pg_gin_pending_cleanup">pg_gin_pending_cleanup</h3>
 423 <p>pg_gin_pending_cleanupは、待機リストからGINインデックス(引数1)にデータを一括移動することで、待機リストを整理する関数です。</p>
 424
 425 <ul>
 426 <li>引数1(regclass) - GINインデックスの名前もしくはOID</li>
 427 <li>引数2(boolean) - <a href="http://www.postgresql.jp/document/current/html/runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST">VACUUM遅延</a>を使うか?(デフォルト値はFALSE)</li>
 428 <li>戻り値1(integer) - 待機リストからGINインデックスに一括移動されたデータのページ数</li>
 429 </ul>
 430
 431 <p>
 432 FASTUPDATEオプション無効で作成されたGINインデックスが引数1の場合、そのGINインデックスは待機リストを持たないため、待機リストの整理は発生せず、戻り値1は0となることに注意してください。
 433 GINインデックスの待機リストとFASTUPDATEオプションの詳細は、<a href="http://www.postgresql.jp/document/current/html/gin-implementation.html#GIN-FAST-UPDATE">GIN高速更新手法</a>を参照してください。
 434 </p>
 435 <p>
 436 引数2がTRUEの場合、この関数は、VACUUM遅延を使って待機リストの整理による負荷を平滑化します。
 437 引数2がFALSEもしくは未指定の場合は、この関数は全速力で待機リストを整理します。
 438 </p>
 439 <p>
 440 この関数を実行するには、GINインデックスの所有者もしくはスーパーユーザでなければなりません。
 441 この関数はリカバリ中には実行できません。
 442 </p>
 443
 444 <pre>
 445 =# SELECT pg_gin_pending_cleanup('pg_tools_idx');
 446  pg_gin_pending_cleanup
 447 ------------------------
 448                       1
 449 (1 row)
 450 </pre>
 451
 452 <h2 id="parametares">パラメータ</h2>
 453 <h3 id="last_update">pg_bigm.last_update</h3>
 454 <p>pg_bigm.last_updateは、pg_bigmモジュールの最終更新日付を報告するパラメータです。このパラメータは読み取り専用です。 postgresql.confやSET文で設定値を変更することはできません。</p>
 455 <pre>
 456 =# SHOW pg_bigm.last_update;
 457  pg_bigm.last_update
 458 ---------------------
 459  2013.11.22
 460 (1 row)
 461 </pre>
 462
 463 <h3 id="enable_recheck">pg_bigm.enable_recheck</h3>
 464 <p>pg_bigm.enable_recheckは、全文検索の内部処理であるRecheckを行うかどうか指定するパラメータです。デフォルト値はonで、Recheckを行います。このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。全文検索において正しい検索結果を得るには、このパラメータは有効化されていなければなりません。</p>
 465
 466 <p>pg_bigmを使った全文検索では、内部的には以下2つの処理で検索結果が取得されます。</p>
 467
 468 <ul>
 469 <li>全文検索インデックスからの検索結果候補の取得</li>
 470 <li>検索結果候補からの正しい検索結果の選択</li>
 471 </ul>
 472
 473 <p>この後者の処理がRecheckと呼ばれます。全文検索インデックスからの検索結果の取得では、必ずしも正しい結果ばかりが得られるとは限りません。誤った結果が含まれる可能性があります。この誤った結果を取り除くのがRecheckになります。</p>
 474
 475 <p>例えば、テーブルに「ここは東京都」「東京と京都に行く」の2つの文字列が格納されている状況を想像してください。検索文字列「東京都」で検索した場合、正しい結果は「ここは東京都」です。しかし、全文検索インデックスからの結果取得では、「東京と京都に行く」も結果候補として取得できてしまいます。これは、検索文字列の2-gram文字列である「東京」と「京都」が「東京と京都に行く」に含まれているためです。 Recheckは、結果候補それぞれについて検索文字列「東京都」が含まれるのか再チェックを行い、正しい結果だけを選択します。</p>
 476
 477 <p>このRecheckによる検索結果の絞り込みの様子は、EXPLAIN ANALYZEの結果から確認できます。</p>
 478
 479 <pre>
 480 =# CREATE TABLE tbl (doc text);
 481 =# INSERT INTO tbl VALUES('ここは東京都');
 482 =# INSERT INTO tbl VALUES('東京と京都に行く');
 483 =# CREATE INDEX tbl_idx ON tbl USING gin (doc gin_bigm_ops);
 484 =# SET enable_seqscan TO off;
 485 =# EXPLAIN ANALYZE SELECT * FROM tbl WHERE doc LIKE likequery('東京都');
 486                                                    QUERY PLAN
 487 -----------------------------------------------------------------------------------------------------------------
 488  Bitmap Heap Scan on tbl  (cost=12.00..16.01 rows=1 width=32) (actual time=0.022..0.023 rows=1 loops=1)
 489    Recheck Cond: (doc ~~ '%東京都%'::text)
 490    -&gt;  Bitmap Index Scan on tbl_idx  (cost=0.00..12.00 rows=1 width=0) (actual time=0.015..0.015 rows=2 loops=1)
 491          Index Cond: (doc ~~ '%東京都%'::text)
 492  Total runtime: 0.059 ms
 493 (5 rows)
 494 </pre>
 495
 496 <p>Bitmap Index Scanのrowsは2となっており、全文検索インデックスからは2件結果を取得しています。 Recheck実行後のBitmap Heap Scanのrowsは1となっており、2件の結果候補から1件に絞り込まれた様子を確認できます。</p>
 497
 498 <p>pg_bigm.enable_recheckを無効化することで、Recheckをスキップさせ、全文検索インデックスから取得した結果候補をそのまま最終的な検索結果とすることができます。以下の実行例では、このパラメータの無効化により、誤った検索結果の「東京と京都に行く」を得られています。</p>
 499
 500 <pre>
 501 =# SELECT * FROM tbl WHERE doc LIKE likequery('東京都');
 502      doc
 503 --------------
 504  ここは東京都
 505 (1 row)
 506
 507 =# SET pg_bigm.enable_recheck TO off;
 508 =# SELECT * FROM tbl WHERE doc LIKE likequery('東京都');
 509        doc
 510 ------------------
 511  ここは東京都
 512  東京と京都に行く
 513 (2 rows)
 514 </pre>
 515
 516 <p>このパラメータは、正しい検索結果を得る必要がある運用時には必ずonに設定されていなければなりません。一方、Recheckのオーバーヘッドを評価するなど、デバッグ時にoffに設定しても構いません。</p>
 517
 518 <h3 id="gin_key_limit">pg_bigm.gin_key_limit</h3>
 519 <p>pg_bigm.gin_key_limitは、検索文字列の2-gram文字列のうち最大で何個を全文検索インデックスの検索に使うか指定するパラメータです。設定値が0(デフォルト値)の場合は、検索文字列のすべての2-gram文字列をインデックス検索に使います。このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。</p>
 520
 521 <p>pg_bigmの全文検索では、基本的に、検索文字列のすべての2-gram文字列を使ってGINインデックスを検索します。ただし、現在のGINインデックスの実装では、検索に使う2-gram文字列の個数が多いほどインデックス検索の負荷は高くなります。このため、検索文字列の文字数が多く、2-gram文字列の個数が多くなりやすいシステムでは、検索性能は劣化しやすいです。 pg_bigm.gin_key_limitによりGINインデックスの検索に使う2-gram文字列の最大数を制限することで、この性能問題を解決できます。</p>
 522
 523 <p>ただし、インデックス検索に使う2-gram文字列の個数が減ると、インデックスから取得した検索結果候補にはより多くの誤った結果が含まれることになります。このため、Recheckの負荷が高まり、逆に、より性能劣化する可能性もあるため注意が必要です。</p>
 524
 525 <h3 id="similarity_limit">pg_bigm.similarity_limit</h3>
 526 <p>pg_bigm.similarity_limitは、類似度検索の閾値を指定するパラメータです。類似度検索では、検索条件の文字列との類似度がこの閾値以上の行が検索結果となります。設定値は0以上1以下の小数点数で、デフォルト値は0.3です。このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。</p>
 527
 528 <h2 id="limitations">制約</h2>
 529 <h3 id="indexed_column_size">インデックス作成が可能な列の最大サイズ</h3>
 530
 531 <p>pg_bigmでは、列サイズが107,374,180Byte (約102MB)を越える列へインデックスを作成できません。制限を越える大きさのデータを挿入するとエラーを起こします。</p>
 532
 533 <pre>
 534 =# CREATE TABLE t1 (description text);
 535 =# CREATE INDEX t1_idx ON t1 USING gin (description gin_bigm_ops);
 536 =# INSERT INTO t1 SELECT repeat('A', 107374181);
 537 ERROR:  out of memory
 538 </pre>
 539
 540 <p>この制約はpg_trgmにも存在しますが、pg_trgmでは最大238,609,291Byte (約228MB)までインデックスの作成が可能です。</p>
 541
 542 <h2 id="release_notes">リリースノート</h2>
 543 <ul>
 544 <li><a href="release-1-2.html">バージョン1.2</a></li>
 545 <li><a href="release-1-1.html">バージョン1.1</a></li>
 546 <li><a href="release-1-0.html">バージョン1.0</a></li>
 547 </ul>
 548
 549 <hr>
 550 <div align="right">Copyright (c) 2012-2015, NTT DATA Corporation</div>
 551
 552 </body>
 553 </html>
 554