3 <title>ludia_funcs ドキュメント</title>
5 <link rel="stylesheet" type="text/css" href="style.css">
6 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
12 <li><a href="index.html">ホーム</a></li>
13 <li><a href="http://sourceforge.jp/projects/ludiafuncs/releases/">ダウンロード</a></li>
14 <li><a href="ludia_funcs.html">ドキュメント</a></li>
15 <li><a href="index.html#community">コミュニティ</a></li>
16 <li><a href="index.html#development">開発</a></li>
20 <h1 id="ludia_funcs">ludia_funcs ドキュメント</h1>
24 <li><a href="#description">概要</a></li>
25 <li><a href="#requirement">動作確認環境</a></li>
26 <li><a href="#install">インストール</a></li>
27 <li><a href="#uninstall">アンインストール</a></li>
28 <li><a href="#functions">提供関数</a></li>
29 <li><a href="#parametares">パラメータ</a></li>
33 <h2 id="description">概要</h2>
34 <p>ludia_funcs(ルディア・ファンクス)は、文字列の正規化関数とスニペット作成関数を提供するモジュールです。それらの関数は全文検索モジュール<a href="http://ludia.sourceforge.jp/moin.cgi/">Ludia</a>が提供していたものと同じです。 ludia_funcsは、それらの関数を<a href="http://www.postgresql.org/">PostgreSQL</a>9.1以降で利用可能にしています。</p>
35 <p><a href="http://sourceforge.jp/projects/ludiafuncs/">ludia_funcsプロジェクト</a>では以下2つのモジュールを提供します。</p>
40 <th>モジュール名</th><th>概要</th><th>ソースアーカイブファイル名</th>
44 <tr><td>ludia_funcs</td>
45 <td nowrap>文字列の正規化関数とスニペット作成関数を提供するモジュール</td>
46 <td>ludia_funcs-YYYYMMDD.tar.gz</td></tr>
47 <tr><td>senna-1.1.2-fast</td>
48 <td nowrap>組み込み型全文検索エンジン<a href="http://qwik.jp/senna/FrontPageJ.html">Senna</a>の性能改善版</td>
49 <td>senna-1.1.2-fast-YYYYMMDD.tar.gz</td></tr>
53 <p>ソースアーカイブファイル名のYYYYMMDDの部分は、実際にはそのファイルがリリースされた年月日になります。例えば、2013年4月5日リリースのファイルでは、YYYYMMDDは20130405です。</p>
55 <p>各提供モジュールのライセンスはLGPLv2.1です。</p>
57 <p>ludia_funcsは、提供モジュールの一つである性能改善版のSennaと組み合わせて使いうことで、Ludia同様に文字列の正規化やスニペット作成を行います。</p>
59 <p>ludia_funcsは、様々な形式のファイルからテキストを抽出する関数も提供します。この関数を利用するには、商用ソフトウェアの<a href="http://www.antenna.co.jp/axx/">TextPorter</a>を別途購入する必要があります。 (TextPorter Ver.5 Copyright(c) 1999- Antenna House, Inc.)</p>
60 <h2 id="requirement">動作確認環境</h2>
61 <p>ludia_funcsは、以下の環境で動作確認しています。</p>
66 <th>カテゴリ</th><th>モジュール名</th>
72 <td nowrap>Red Hat Enterprise Linux 6.1 x86_64</td>
76 <td nowrap>PostgresSQL9.1</td>
80 <td nowrap>senna-1.1.2-fast</td>
85 <p>ludia_funcsは、PostgreSQL9.1のみに対応しています。 9.0以前には未対応です。 9.2以降には対応していると思われますが、動作確認していません。</p>
87 <p>ludia_funcsは、オリジナルのSenna1.1.2以降とも組み合わせ可能だと思われますが、動作確認していません。 senna-1.1.2-fastを使う場合、ludia_funcsの登録先のデータベースでは、エンコーディングはUTF-8でなければなりません。</p>
90 <h2 id="install">インストール</h2>
92 <h3 id="pg_install">PostgreSQLのインストール</h3>
93 <p><a href="http://www.postgresql.org/">PostgreSQLのオフィシャルサイト</a>からバージョン9.1.X(バージョン番号の下一桁Xは、実際の数字に置き換えてください)のソースアーカイブファイル(postgresql-9.1.X.tar.gz)をダウンロードし、ビルドとインストールを行います。</p>
95 $ tar zxf postgresql-9.1.X.tar.gz
97 $ ./configure --prefix=/opt/pgsql-9.1.X
103 <li>--prefix : インストール先ディレクトリを指定します。未指定時のインストール先は/usr/local/pgsqlです。このオプション指定は必須ではありません。</li>
105 <p>上記手順ではソースコードからPostgreSQLをインストールしています。しかし、RPMなどの他の手順でPostgreSQLをインストールしてもludia_funcsは利用可能です。 RPMインストールのPostgreSQLでludia_funcsを利用するには、postgresql-develパッケージをインストールしなければならないことに注意してください。</p>
108 <h3 id="senna_install">Sennaのインストール</h3>
109 <p><a href="http://sourceforge.jp/projects/ludiafuncs/releases/">ここ</a>からsenna-1.1.2-fastのソースアーカイブファイルをダウンロードし、ビルドとインストールを行います。 Sennaのmakeには長時間かかることに注意してください。</p>
111 $ tar zxf senna-1.1.2-fast-YYYYMMDD.tar.gz
112 $ cd senna-1.1.2-fast-YYYYMMDD
113 $ ./configure --prefix=/opt/senna-1.1.2-fast --without-mecab
120 <li>--prefix : インストール先ディレクトリを指定します。未指定時のインストール先は/usr/localです。このオプション指定は必須ではありません。</li>
121 <li>--without-mecab : <a href="https://code.google.com/p/mecab/">mecab</a>モジュールを使用しないことを指定します。このオプション指定は必須です。</li>
124 <h3 id="ludia_funcs_install">ludia_funcsのインストール</h3>
125 <p><a href="http://sourceforge.jp/projects/ludiafuncs/releases/">ここ</a>からludia_funcsのソースアーカイブファイルをダウンロードし、ビルドとインストールを行います。</p>
127 $ tar zxf ludia_funcs-YYYYMMDD.tar.gz
128 $ cd ludia_funcs-YYYYMMDD
129 $ make USE_PGXS=1 PG_CONFIG=/opt/pgsql-9.1.X/bin/pg_config SENNA_CFG=/opt/senna-1.1.2-fast/bin/senna-cfg
131 # make USE_PGXS=1 PG_CONFIG=/opt/pgsql-9.1.X/bin/pg_config SENNA_CFG=/opt/senna-1.1.2-fast/bin/senna-cfg install
135 <li>USE_PGXS : PostgreSQL関連モジュールをコンパイルするときのオマジナイです。1の指定が必須です。</li>
136 <li>PG_CONFIG : pg_configコマンド(PostgreSQLインストール先のbinディレクトリに存在)のパスを指定します。pg_configにPATHが通っているのであれば、このオプション指定は不要です。</li>
137 <li>SENNA_CFG : senna-cfgコマンド(Sennaインストール先のbinディレクトリに存在)のパスを指定します。senna-cfgにPATHが通っているのであれば、このオプション指定は不要です。</li>
140 <h3 id="ludia_funcs_register">ludia_funcsの登録</h3>
141 <p>データベースクラスタの作成後、postgresql.confを編集、PostgreSQLを起動し、ludia_funcsをデータベースに登録します。</p>
143 $ initdb -D $PGDATA --locale=C --encoding=UTF8
145 $ vi $PGDATA/postgresql.conf
146 shared_preload_libraries = 'ludia_funcs'
147 custom_variable_classes = 'ludia_funcs'
149 $ pg_ctl -D $PGDATA start
150 $ psql -d <データベース名>
151 =# CREATE EXTENSION ludia_funcs;
153 List of installed extensions
154 Name | Version | Schema | Description
155 -------------+---------+--------+-----------------
156 ludia_funcs | 1.0 | public | ludia functions
161 <li>$PGDATAは、データベースクラスタのパスを決めて、そのパスで置き換えてください。</li>
162 <li>senna-1.1.2-fastを使う場合、ludia_funcsの登録先のデータベースでは、エンコーディングはUTF-8でなければなりません。</li>
163 <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>にludia_funcsを設定するのは必須です。
165 <li>PostgreSQL9.2以降ではcustom_variable_classesは存在しません。設定が必要なのはshared_preload_librariesだけです。</li>
168 <li>ludia_funcsの登録には、<a href="http://www.postgresql.jp/document/current/html/sql-createextension.html">CREATE EXTENSION</a>を使います。 CREATE EXTENSIONはデータベース単位でモジュールを登録するため、ludia_funcsを利用したいデータベースすべてにおいて登録が必要です。</li>
171 <p>ludia_funcsのインストールは以上で終わりです。</p>
173 <h2 id="uninstall">アンインストール</h2>
174 <h3 id="delete_ludia_funcs">ludia_funcsの削除</h3>
175 <p>ludia_funcsについて、データベースからの登録解除とアンインストールを行います。</p>
177 $ psql -d <データベース名>
178 =# DROP EXTENSION ludia_funcs CASCADE;
181 $ pg_ctl -D $PGDATA stop
184 # cd <ludia_funcsのソースディレクトリ>
185 # make USE_PGXS=1 PG_CONFIG=/opt/pgsql-9.1.X/bin/pg_config SENNA_CFG=/opt/senna-1.1.2-fast/bin/senna-cfg uninstall
189 <li>ludia_funcsを登録したすべてのデータベースで登録解除する必要があります。</li>
190 <li>ludia_funcsに依存するDBオブジェクトを削除する必要があるため、<a href="http://www.postgresql.jp/document/current/html/sql-dropextension.html">DROP EXTENSION</a>にはCASCADEを指定します。</li>
193 <h3 id="delete_conf">postgresql.confの設定削除</h3>
194 <p>postgresql.confの以下の設定を削除します。</p>
196 <li>shared_preload_libraries</li>
197 <li>custom_variable_classes</li>
198 <li>ludia_funcs.* (ludia_funcs.から名前が始まるパラメータ)</li>
201 <h3 id="senna_uninstall">Sennaのアンインストール</h3>
202 <p>senna-1.1.2-fastのソースディレクトリでアンインストールを行います。</p>
205 # cd <senna-1.1.2-fastのソースディレクトリ>
210 <h2 id="functions">提供関数</h2>
212 <h3 id="pgs2norm">pgs2norm</h3>
213 <p>pgs2normは、文字列正規化ルール(NFKCの正規化形式)に則って、文字列(引数1)を正規化する関数です。</p>
215 <li>引数1(text) - 正規化する文字列</li>
216 <li>戻り値(text) - 引数1を正規化した文字列</li>
219 <p>引数1がNULLの場合、戻り値はNULLです。</p>
221 <p>NFKCの正規化では、例えば、以下のように文字列を変換します。</p>
226 <li>アイウエオ → アイウエオ</li>
231 <li>ABCDE → abcde</li>
236 <li>AbCdE123 → abcde123</li>
241 <li>㌢㍻㊨⑤Ⅷ㈲ → センチ平成右5viii(有)</li>
248 =# SELECT pgs2norm('いロハAbCd12③Ⅳ㈱');
250 ---------------------
255 <p>pgs2normは、引数と戻り値の文字列をメモリ上にキャッシュします。そして、pgs2normの次回実行時に引数の文字列がキャッシュされているものと同じであれば、正規化処理を行わず、キャッシュされている戻り値を直接返却することで、処理を高速化します。 pgs2normは、引数と戻り値をキャッシュする際、前回までのキャッシュを破棄します。つまり、キャッシュできる引数と戻り値は直前実行分の一組だけです。キャッシュはセッション単位で行われます。他セッションのキャッシュを、別セッションから実行されたpgs2normで使うことはできません。 pgs2normのキャッシュサイズの上限は、パラメータ<a href="#norm_cache_limit">ludia_funcs.norm_cache_limit</a>で指定できます。</p>
257 <h3 id="pgs2snippet1">pgs2snippet1</h3>
258 <p>pgs2snippet1は、文字列(引数8)からキーワード(引数7)のスニペット(KWIC)を作成する関数です。</p>
260 <li>引数1(integer) - スニペット作成時に正規化するかどうか(する: 1、しない: 0)</li>
261 <li>引数2(integer) - 作成するスニペットの最大長(バイト単位で指定)</li>
262 <li>引数3(integer) - 作成するスニペットの数の上限</li>
263 <li>引数4(text) - スニペット作成時にキーワードの前に付ける文字列</li>
264 <li>引数5(text) - スニペット作成時にキーワードの後ろに付ける文字列</li>
265 <li>引数6(integer) - HTMLの特殊文字をエスケープするかどうか(する: -1、しない: 0)</li>
266 <li>引数7(text) - スニペット作成に使うキーワード</li>
267 <li>引数8(text) - スニペットの作成元となる文字列</li>
268 <li>戻り値(text) - キーワード(引数7)を使って文字列(引数8)から作成したスニペット文字列</li>
271 <p>NULLの引数がある場合、戻り値はNULLです。</p>
275 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, 'PostgreSQL', '最近、PostgreSQLの利用者が増えています。');
277 ----------------------------
282 <p>pgs2snippet1では、キーワード(引数7)に複数の文字列を指定できます。複数指定するには、各文字列を"(半角ダブルクォート)で囲み、それらを+(半角プラス)でつなげます。</p>
286 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '"PostgreSQL"+"HINT"', 'pg_hint_planは、PostgreSQLでHINT句を使えるようにするツールです。');
288 -------------------------------------
289 ★hint★_planは、★PostgreSQL★で★HINT★
293 <li>この実行例では、正規化を行う指定(引数1が1)になっているため、キーワードHINTは、小文字のhintにもマッチします。</li>
295 <p>キーワード内の"と\は、pgs2snippet1ではメタ文字("は検索文字列の区切り文字、\はエスケープ文字)として解釈されます。 "と\を文字そのものとして解釈させるには、それらを\でエスケープしなければなりません。</p>
299 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '"\"2-gram\""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
301 -------------------------------
302 ostgreSQLで★"2-gram"★の全文検
306 <p>このエスケープ処理は、<a href="#escape_snippet_keyword">ludia_funcs.escape_snippet_keyword</a>を有効にすることでpgs2snippet1に任せることもできます。</p>
308 <h3 id="pgs2seninfo">pgs2seninfo</h3>
309 <p>pgs2seninfoは、ludia_funcsが利用しているSennaのバージョン情報を表示する関数です。</p>
311 <li>戻り値1(text) - 利用しているSennaのバージョン番号</li>
312 <li>戻り値2(text) - 利用しているSennaのconfigureオプション</li>
317 =# SELECT * FROM pgs2seninfo();
318 version | configure_options
319 ---------------------------------+-------------------------------------------------
320 1.1.2 (last update: 2013.04.05) | '--without-mecab' '--prefix=/senna-1.1.2-fast/'
323 <h2 id="parametares">パラメータ</h2>
324 <h3 id="last_update">ludia_funcs.lastupdate</h3>
325 <p>ludia_funcs.last_updateは、ludia_funcsモジュールの最終更新日付を報告するパラメータです。このパラメータは読み取り専用です。 postgresql.confやSET文で設定値を変更することはできません。</p>
329 =# SHOW ludia_funcs.last_update ;
330 ludia_funcs.last_update
331 -------------------------
336 <h3 id="norm_cache_limit">ludia_funcs.norm_cache_limit</h3>
337 <p>ludia_funcs.norm_cache_limitは、<a href="#pgs2norm">pgs2norm</a>が確保するキャッシュの上限サイズを指定するパラメータです。設定値はkB単位で指定します。設定値の範囲は -1 ~ 2TB-1B です。設定値-1(デフォルト値)は、キャッシュサイズ上限としてパラメータwork_memの設定値を使うことを意味します。設定値0は、キャッシュサイズの上限がない(常にキャッシュする)ことを意味します。このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。</p>
339 <h3 id="escape_snippet_keyword">ludia_funcs.escape_snippet_keyword</h3>
340 <p>ludia_funcs.escape_snippet_keywordは、<a href="#pgs2snippet1">pgs2snippet1</a>のキーワード(引数7)内の"(半角ダブルクォート)と\(半角バックスラッシュ)をエスケープするかどうか指定するパラメータです。デフォルト値はoffで、エスケープしません。</p>
342 <p>キーワード内の"と\は、pgs2snippet1ではメタ文字("は検索文字列の区切り文字、\はエスケープ文字)として解釈されます。 "と\を文字そのものとして解釈させるには、それらを\でエスケープしなければなりません。このパラメータを有効にすると、pgs2snippet1は、文字として解釈させたい"と\を自動的にエスケープします。このようなエスケープ処理をクライアントアプリケーション側で実装済の場合は、このパラメータは無効で構いません。</p>
344 <p>このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。</p>
346 <p><a href="#pgs2snippet1">pgs2snippet1</a>に記述されている最後の実行例のSQLは、escape_snippet_keywordを使うことで、以下のように書き換えられます。</p>
350 =# SHOW ludia_funcs.escape_snippet_keyword ;
351 ludia_funcs.escape_snippet_keyword
352 ------------------------------------
356 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '""2-gram""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
362 =# SET ludia_funcs.escape_snippet_keyword TO on;
364 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '""2-gram""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
366 -------------------------------
367 ostgreSQLで★"2-gram"★の全文検
371 <li>キーワード内の先頭と末尾の"は必ずメタ文字(検索文字列の区切り文字)として解釈されます。</li>
375 <div align="right">Copyright (c) 2012-2013, NTT DATA Corporation</div>