--- /dev/null
+<html>
+<head>
+<title>pg_bigm ドキュメント</title>
+
+<link rel="stylesheet" type="text/css" href="style.css">
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+
+<body>
+ <div id="navigation">
+ <ul>
+ <li><a href="index.html">ホーム</a></li>
+ <li><a href="http://sourceforge.jp/projects/pgbigm/releases/">ダウンロード</a></li>
+ <li><a href="pg_bigm.html">ドキュメント</a></li>
+ <li><a href="index.html#community">コミュニティ</a></li>
+ <li><a href="index.html#development">開発</a></li>
+ </ul>
+ </div>
+
+<h1 id="pg_bigm">pg_bigm ドキュメント</h1>
+
+<div class="index">
+<ol>
+<li><a href="#description">概要</a></li>
+<li><a href="#pg_trgm">pg_trgmとの違い</a></li>
+<li><a href="#requirement">動作確認環境</a></li>
+<li><a href="#install">インストール</a></li>
+<li><a href="#uninstall">アンインストール</a></li>
+<li><a href="#fulltext_search">全文検索機能</a></li>
+<li><a href="#functions">提供関数</a></li>
+<li><a href="#parametares">パラメータ</a></li>
+</ol>
+</div>
+
+<h2 id="description">概要</h2>
+<p>pg_bigm(ピージー・バイグラム)は、<a href="http://www.postgresql.org/">PostgreSQL</a>上で全文検索機能を提供するモジュールです。このモジュールを使うことで、ユーザは全文検索用のインデックスを作成でき、高速に文字列検索を行えるようになります。このモジュールは、2-gram(バイグラム)と呼ばれる方法で、文字列から全文検索用のインデックスを作成します。</p>
+<p><a href="http://sourceforge.jp/projects/pgbigm/">pg_bigmプロジェクト</a>では以下の1つのモジュールを提供します。</p>
+
+<table>
+<thead>
+<tr>
+<th>モジュール名</th><th>概要</th><th>ソースアーカイブファイル名</th>
+</tr>
+</thead>
+<tbody>
+<tr><td>pg_bigm</td>
+ <td nowrap>PostgreSQL上で全文検索機能を提供するモジュール</td>
+ <td>pg_bigm-YYYYMMDD.tar.gz</td></tr>
+</tbody>
+</table>
+
+<p>ソースアーカイブファイル名のYYYYMMDDの部分は、実際にはそのファイルがリリースされた年月日になります。例えば、2013年4月5日リリースのファイルでは、YYYYMMDDは20130405です。</p>
+<p>pg_bigmのライセンスは<a href="http://opensource.org/licenses/postgresql">The PostgreSQL License</a>(BSDに似たライセンス)です。</p>
+
+<h2 id="pg_trgm">pg_trgmとの違い</h2>
+<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>
+
+<table>
+<thead>
+<tr>
+<th>機能や特徴</th><th>pg_trgm</th><th>pg_bigm</th>
+</tr>
+</thead>
+<tbody>
+<tr><td>全文検索インデックスの作成方法</td>
+ <td nowrap>3-gram</td>
+ <td>2-gram</td></tr>
+<tr><td>利用できるインデックスの種類</td>
+ <td nowrap>GINとGiST</td>
+ <td>GINのみ</td></tr>
+<tr><td>日本語検索</td>
+ <td nowrap>未対応(*1)</td>
+ <td>対応済</td></tr>
+<tr><td>検索キーワード1～2文字での検索</td>
+ <td nowrap>低速<br>(検索時に全文検索インデックスを使えない(*2))</td>
+ <td>高速<br>(検索時に全文検索インデックスを使える)</td></tr>
+<tr><td>類似文字列の検索</td>
+ <td nowrap>対応済</td>
+ <td>未対応</td></tr>
+<tr><td>データベースのエンコーディングとロケール</td>
+ <td nowrap>制限なし</td>
+ <td>使用できるデータベースエンコーディングはUTF-8のみ。ロケールはCのみ</td></tr>
+</tbody>
+</table>
+
+<ul>
+<li>(*1) ソースコード内の<a href="http://lets.postgresql.jp/documents/technical/text-processing/3#contains">マクロ変数を変更することで日本語検索に対応</a>できます。しかし、日本語検索の性能はpg_bigmに比べて低速です。</li>
+<li>(*2) 全文検索インデックスを使える場合もありますが、その場合はフルインデックススキャンが走るため検索性能は非常に低くなります。</li>
+</ul>
+
+<p>pg_trgmとpg_bigmを同じデータベース内で共存させることはできません。 pg_bigmを登録するデータベースには、pg_trgmを同時に登録しないでください。</p>
+
+<h2 id="requirement">動作確認環境</h2>
+<p>pg_bigmは、以下の環境で動作確認をしています。</p>
+<table>
+<thead>
+<tr>
+<th>カテゴリ</th><th>モジュール名</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <td>OS</td>
+ <td nowrap>Red Hat Enterprise Linux 6.1 x86_64</td>
+</tr>
+<tr>
+ <td>DMBMS</td>
+ <td nowrap>PostgresSQL9.1</td>
+</tr>
+</tbody>
+</table>
+
+<p>pg_bigmは、PostgreSQL9.1のみに対応しています。 9.0以前には未対応です。 9.2以降には対応していると思われますが、動作確認していません。</p>
+
+<h2 id="install">インストール</h2>
+
+<h3 id="pg_install">PostgreSQLのインストール</h3>
+<p><a href="http://www.postgresql.org/">PostgreSQLのオフィシャルサイト</a>からバージョン9.1.X(バージョン番号の下一桁Xは、実際の数字に置き換えてください)のソースアーカイブファイル(postgresql-9.1.X.tar.gzをダウンロードし、ビルドとインストールを行います。</p>
+<pre>
+$ tar zxf postgresql-9.1.X.tar.gz
+$ cd postgresql-9.1.X
+$ ./configure --prefix=/opt/pgsql-9.1.X
+$ make
+$ su
+# make install
+# exit</pre>
+<ul>
+<li>--prefix : インストール先ディレクトリを指定します。未指定時のインストール先は/usr/local/pgsqlです。このオプション指定は必須ではありません。</li>
+</ul>
+<p>上記手順ではソースコードからPostgreSQLをインストールしています。しかし、RPMなどの他の手順でPostgreSQLをインストールしてもpg_bigmは利用可能です。 RPMインストールのPostgreSQLでpg_bigmを利用するには、postgresql-develパッケージをインストールしなければならないことに注意してください。</p>
+
+<h3 id="bigm_install">pg_bigmのインストール</h3>
+<p><a href="http://sourceforge.jp/projects/pgbigm/releases/">ここ</a>からpg_bigmのソースアーカイブファイルをダウンロードし、ビルドとインストールを行います。</p>
+<pre>
+$ tar zxf pg_bigm-YYYYMMDD.tar.gz
+$ cd pg_bigm-YYYYMMDD
+$ make USE_PGXS=1 PG_CONFIG=/opt/pgsql-9.1.X/bin/pg_config
+$ su
+# make USE_PGXS=1 PG_CONFIG=/opt/pgsql-9.1.X/bin/pg_config install
+# exit
+</pre>
+<ul>
+<li>USE_PGXS : PostgreSQL関連モジュールをコンパイルするときのオマジナイです。1の指定が必須です。</li>
+<li>PG_CONFIG : pg_configコマンド(PostgreSQLインストール先のbinディレクトリに存在)のパスを指定します。pg_configにPATHが通っているのであれば、このオプション指定は不要です。</li>
+</ul>
+
+<h3 id="bigm_register">pg_bigmの登録</h3>
+<p>データベースクラスタの作成後、postgresql.confを編集、PostgreSQLを起動し、pg_bigmをデータベースに登録します。</p>
+<pre>
+$ initdb -D $PGDATA --locale=C --encoding=UTF8
+
+$ vi $PGDATA/postgresql.conf
+shared_preload_libraries = 'pg_bigm'
+custom_variable_classes = 'pg_bigm'
+
+$ pg_ctl -D $PGDATA start
+$ psql -d <データベース名>
+=# CREATE EXTENSION pg_bigm;
+=# \dx pg_bigm
+ List of installed extensions
+ Name | Version | Schema | Description
+---------+---------+--------+---------------------------------------
+ pg_bigm | 1.0 | public | text index searching based on bigrams
+(1 row)
+</pre>
+
+<ul>
+<li>$PGDATAは、データベースクラスタのパスを決めて、そのパスで置き換えてください。</li>
+<li>pg_bigmの登録先のデータベースでは、エンコーディングはUTF-8、ロケールはCでなければなりません。</li>
+<li>postgresql.confで、<a href="http://www.postgresql.jp/document/current/html/runtime-config-resource.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a>とと<a href="http://www.postgresql.jp/document/9.1/html/runtime-config-custom.html#GUC-CUSTOM-VARIABLE-CLASSES">custom_variable_classes</a>にpg_bigmを設定するのは必須です。
+ <ul>
+ <li>PostgreSQL9.2以降ではcustom_variable_classesは存在しません。設定が必要なのはshared_preload_librariesだけです。</li>
+ </ul>
+</li>
+<li>pg_bigmの登録には、<a href="http://www.postgresql.jp/document/current/html/sql-createextension.html">CREATE EXTENSION</a>を使います。 CREATE EXTENSIONはデータベース単位でモジュールを登録するため、pg_bigmを利用したいデータベースすべてにおいて登録が必要です。</li>
+<li>pg_bigmとPostgreSQL付属のcontribモジュールpg_trgmを同じデータベース内で共存させることはできません。 pg_bigmを登録するデータベースには、pg_trgmを同時に登録しないでください。</li>
+</ul>
+<p>pg_bigmのインストールは以上で終わりです。</p>
+
+
+<h2 id="uninstall">アンインストール</h2>
+
+<h3 id="bigm_uninstall">pg_bigmの削除</h3>
+<p>pg_bigmについて、データベースからの登録解除とアンインストールを行います。</p>
+<pre>
+$ psql -d <データベース名>
+=# DROP EXTENSION pg_bigm CASCADE;
+=# \q
+
+$ pg_ctl -D $PGDATA stop
+$ su
+
+# cd <pg_bigmのソースディレクトリ>
+# make USE_PGXS=1 PG_CONFIG=/opt/pgsql-9.1.X/bin/pg_config uninstall
+# exit
+</pre>
+
+<ul>
+<li>pg_bigmを登録したすべてのデータベースで登録解除する必要があります。</li>
+<li>pg_bigmに依存するDBオブジェクト(例えば、pg_bigmを使った全文検索インデックス)を削除する必要があるため、<a href="http://www.postgresql.jp/document/current/html/sql-dropextension.html">DROP EXTENSION</a>にはCASCADEを指定します。</li>
+</ul>
+
+<h3 id="delete_conf">postgresql.confの設定削除</h3>
+<p>postgresql.confの以下の設定を削除します</p>
+<ul>
+<li>shared_preload_libraries</li>
+<li>custom_variable_classes</li>
+<li>pg_bigm.* (pg_bigm.から名前が始まるパラメータ)</li>
+</ul>
+
+<h2 id="fulltext_search">全文検索機能</h2>
+
+<h3 id="create_index">インデックスの作成</h3>
+<p>GINインデックスを利用して全文検索用のインデックスを作成します。</p>
+<p>以下の実行例では、PostgreSQL関連ツールの名前と説明を管理するテーブルpg_toolsを作成し、3件データを投入します。その後、ツールの説明に対して全文検索用のインデックスを作成します。</p>
+
+<pre>
+=# CREATE TABLE pg_tools (tool text, description text);
+
+=# INSERT INTO pg_tools VALUES ('pg_hint_plan', 'PostgreSQLでHINT句を使えるようにするツール');
+=# INSERT INTO pg_tools VALUES ('pg_dbms_stats', 'PostgreSQLの統計情報を固定化するツール');
+=# INSERT INTO pg_tools VALUES ('pg_bigm', 'PostgreSQLで2-gramの全文検索を使えるようにするツール');
+=# INSERT INTO pg_tools VALUES ('pg_trgm', 'PostgreSQLで3-gramの全文検索を使えるようにするツール');
+
+=# CREATE INDEX pg_tools_idx ON pg_tools USING gin (description gin_bigm_ops);
+</pre>
+
+<ul>
+<li>インデックスメソッドにはginの指定が必須です。 pg_bigmでは、pg_trgmとは異なりインデックス作成にGiSTを使えません。</li>
+<li>演算子クラスにはgin_bigm_opsの指定が必須です。</li>
+</ul>
+
+<p>また、以下の実行例のように、全文検索用のマルチカラムインデックスを作成したり、作成時にGINインデックスのパラメータを指定することもできます。</p>
+
+<pre>
+=# CREATE INDEX pg_tools_multi_idx ON pg_tools USING gin (tool gin_bigm_ops, description gin_bigm_ops) WITH (FASTUPDATE = off);
+</pre>
+
+<h3 id="do_fulltext_search">全文検索の実行</h3>
+<p>pg_bigmでは、LIKE演算子の中間一致検索により全文検索を行います。</p>
+<pre>
+=# SELECT * FROM pg_tools WHERE description LIKE '%全文検索%';
+ tool | description
+---------+------------------------------------------------------
+ pg_bigm | PostgreSQLで2-gramの全文検索を使えるようにするツール
+ pg_trgm | PostgreSQLで3-gramの全文検索を使えるようにするツール
+(2 rows)
+</pre>
+<ul>
+<li>検索文字列は<a href="#likequery">likequery</a>に記載されているとおり、全文検索用に変換されなければなりません。</li>
+</ul>
+
+<h2 id="functions">提供関数</h2>
+<h3 id="likequery">likequery</h3>
+<p>likequeryは、全文検索できるように、検索文字列(引数1)をLIKE演算子のパターンに変換する関数です。</p>
+<ul>
+<li>引数1(text) - 検索文字列</li>
+<li>戻り値(text) - 全文検索用に、引数1をLIKE演算子のパターンに変換した文字列</li>
+</ul>
+
+<p>引数1がNULLの場合、戻り値はNULLです。</p>
+
+<p>変換は、具体的には以下を行います。</p>
+<ul>
+<li>検索文字列の先頭と末尾に%(半角パーセント)を追加</li>
+<li>検索文字列内の%(半角パーセント)、_(半角アンダースコア)、\(半角バックスラッシュ)を\(半角バックスラッシュ)でエスケープ</li>
+</ul>
+
+<p>pg_bigmでは、LIKE演算子の中間一致検索により全文検索を行います。このため、上記のとおり検索文字列を変換して、LIKE演算子に渡す必要があります。この変換は、通常、クライアントアプリケーション側で実装しなければなりません。しかし、likequeryを利用することで、その実装の手間を省くことができます。</p>
+
+<p>実行例</p>
+<pre>
+=# SELECT likequery('pg_bigmは検索性能を200%向上させました。');
+ likequery
+---------------------------------------------
+ %pg\_bigmは検索性能を200\%向上させました。%
+(1 row)
+</pre>
+
+<p>「全文検索の実行」の実行例の検索SQLは、likequeryを使うことで、以下のように書き換えられます。</p>
+<pre>
+=# SELECT * FROM pg_tools WHERE description LIKE likequery('全文検索');
+ tool | description
+---------+------------------------------------------------------
+ pg_bigm | PostgreSQLで2-gramの全文検索を使えるようにするツール
+ pg_trgm | PostgreSQLで3-gramの全文検索を使えるようにするツール
+(2 rows)
+</pre>
+
+<h3 id="show_bigm">show_bigm</h3>
+<p>show_bigmは、文字列(引数1)のすべての2-gram文字列を配列として表示する関数です。</p>
+
+<ul>
+<li>引数1(text) - 文字列</li>
+<li>戻り値(text[]) - 引数1のすべての2-gram文字列から構成される配列</li>
+</ul>
+
+<p>2-gram文字列とは、文字列の先頭と末尾に空白文字を追加した上で、文字列を1文字ずつずらしながら、2文字単位で抽出した文字列のことです。例えば、文字列「ABC」の2-gram文字列は、「(空白)A」「AB」「BC」「C(空白)」の4つになります。</p>
+
+<pre>
+実行例
+
+=# SELECT show_bigm('PostgreSQLの全文検索');
+ show_bigm
+-----------------------------------------------------------------
+ {の全,全文,文検,検索,"索 "," P",Lの,Po,QL,SQ,eS,gr,os,re,st,tg}
+(1 row)
+</pre>
+
+<h3 id="pg_gin_pending_stats">pg_gin_pending_stats</h3>
+<p>pg_gin_pending_statsは、GINインデックス(引数1)の待機リストに含まれているデータのページ数とタプル数を返却する関数です。</p>
+
+<ul>
+<li>引数1(regclass) - GINインデックスの名前もしくはOID</li>
+<li>戻り値1(integer) - GINインデックス(引数1)の待機リストに含まれているデータのページ数</li>
+<li>戻り値2(bigint) - GINインデックス(引数1)の待機リストに含まれているデータのタプル数</li>
+</ul>
+
+<p>GINインデックスの待機リストの詳細は、<a href="http://www.postgresql.jp/document/current/html/gin-implementation.html#GIN-FAST-UPDATE">GIN高速更新手法</a>を参照してください。</p>
+
+<p>実行例</p>
+<pre>
+=# SELECT * FROM pg_gin_pending_stats('pg_tools_idx');
+ pages | tuples
+-------+--------
+ 1 | 4
+(1 row)
+</pre>
+
+<h2 id="parametares">パラメータ</h2>
+<h3 id="last_update">pg_bigm.last_update</h3>
+<p>pg_bigm.last_updateは、pg_bigmモジュールの最終更新日付を報告するパラメータです。このパラメータは読み取り専用です。 postgresql.confやSET文で設定値を変更することはできません。</p>
+<pre>
+実行例
+
+=# SHOW pg_bigm.last_update;
+ pg_bigm.last_update
+---------------------
+ 2013.04.05
+(1 row)
+</pre>
+
+<h3 id="enable_recheck">pg_bigm.enable_recheck</h3>
+<p>pg_bigm.enable_recheckは、全文検索の内部処理であるRecheckを行うかどうか指定するパラメータです。デフォルト値はonで、Recheckを行います。このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。全文検索において正しい検索結果を得るには、このパラメータは有効化されていなければなりません。</p>
+
+<p>pg_bigmを使った全文検索では、内部的には以下2つの処理で検索結果が取得されます。</p>
+
+<ul>
+<li>全文検索インデックスからの検索結果候補の取得</li>
+<li>検索結果候補からの正しい検索結果の選択</li>
+</ul>
+
+<p>この後者の処理がRecheckと呼ばれます。全文検索インデックスからの検索結果の取得では、必ずしも正しい結果ばかりが得られるとは限りません。誤った結果が含まれる可能性があります。この誤った結果を取り除くのがRecheckになります。</p>
+
+<p>例えば、テーブルに「ここは東京都」「東京と京都に行く」の2つの文字列が格納されている状況を想像してください。検索文字列「東京都」で検索した場合、正しい結果は「ここは東京都」です。しかし、全文検索インデックスからの結果取得では、「東京と京都に行く」も結果候補として取得できてしまいます。これは、検索文字列の2-gram文字列である「東京」と「京都」が「東京と京都に行く」に含まれているためです。 Recheckは、結果候補それぞれについて検索文字列「東京都」が含まれるのか再チェックを行い、正しい結果だけを選択します。</p>
+
+<p>このRecheckによる検索結果の絞り込みの様子は、EXPLAIN ANALYZEの結果から確認できます。</p>
+
+<pre>
+=# CREATE TABLE tbl (doc text);
+=# INSERT INTO tbl VALUES('ここは東京都');
+=# INSERT INTO tbl VALUES('東京と京都に行く');
+=# CREATE INDEX tbl_idx ON tbl USING gin (doc gin_bigm_ops);
+=# SET enable_seqscan TO off;
+=# EXPLAIN ANALYZE SELECT * FROM tbl WHERE doc LIKE likequery('東京都');
+ QUERY PLAN
+-----------------------------------------------------------------------------------------------------------------
+ Bitmap Heap Scan on tbl (cost=12.00..16.01 rows=1 width=32) (actual time=0.022..0.023 rows=1 loops=1)
+ Recheck Cond: (doc ~~ '%東京都%'::text)
+ -> 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)
+ Index Cond: (doc ~~ '%東京都%'::text)
+ Total runtime: 0.059 ms
+(5 rows)
+</pre>
+
+<p>Bitmap Index Scanのrowsは2となっており、全文検索インデックスからは2件結果を取得しています。 Recheck実行後のBitmap Heap Scanのrowsは1となっており、2件の結果候補から1件に絞り込まれた様子を確認できます。</p>
+
+<p>pg_bigm.enable_recheckを無効化することで、Recheckをスキップさせ、全文検索インデックスから取得した結果候補をそのまま最終的な検索結果とすることができます。以下の実行例では、このパラメータの無効化により、誤った検索結果の「東京と京都に行く」を得られています。</p>
+
+<pre>
+=# SELECT * FROM tbl WHERE doc LIKE likequery('東京都');
+ doc
+--------------
+ ここは東京都
+(1 row)
+
+=# SET pg_bigm.enable_recheck TO off;
+=# SELECT * FROM tbl WHERE doc LIKE likequery('東京都');
+ doc
+------------------
+ ここは東京都
+ 東京と京都に行く
+(2 rows)
+</pre>
+
+<p>このパラメータは、正しい検索結果を得る必要がある運用時には必ずonに設定されていなければなりません。一方、Recheckのオーバーヘッドを評価するなど、デバッグ時にoffに設定しても構いません。</p>
+
+<h3 id="gin_key_limit">pg_bigm.gin_key_limit</h3>
+<p>pg_bigm.gin_key_limitは、検索文字列の2-gram文字列のうち最大で何個を全文検索インデックスの検索に使うか指定するパラメータです。設定値が0(デフォルト値)の場合は、検索文字列のすべての2-gram文字列をインデックス検索に使います。このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。</p>
+
+<p>pg_bigmの全文検索では、基本的に、検索文字列のすべての2-gram文字列を使ってGINインデックスを検索します。ただし、現在のGINインデックスの実装では、検索に使う2-gram文字列の個数が多いほどインデック検索の負荷は高くなります。このため、検索文字列の文字数が多く、2-gram文字列の個数が多くなりやすいシステムでは、検索性能は劣化しやすいです。 pg_bigm.gin_key_limitによりGINインデックスの検索に使う2-gram文字列の最大数を制限することで、この性能問題を解決できます。</p>
+
+<p>ただし、インデックス検索に使う2-gram文字列の個数が減ると、インデックスから取得した検索結果候補にはより多くの誤った結果が含まれることになります。このため、Recheckの負荷が高まり、逆に、より性能劣化する可能性もあるため注意が必要です。</p>
+
+<hr>
+<div align="right">Copyright (c) 2012-2013, NTT DATA Corporation</div>
+
+</body>
+</html>
+
OSDN Git Service
