3 <title>Ludia functions ドキュメント</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://osdn.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">ドキュメント</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>
30 <li><a href="#release_notes">リリースノート</a></li>
34 <h2 id="description">概要</h2>
35 <p>Ludia functionsは、文字列の正規化関数とスニペット作成関数を提供するモジュールです。それらの関数は全文検索モジュール<a href="https://osdn.net/projects/ludia/">Ludia</a>が提供していたものと同じです。 Ludia functionsは、それらの関数を<a href="http://www.postgresql.org/">PostgreSQL</a>9.1以降で利用可能にしています。</p>
36 <p><a href="http://osdn.jp/projects/ludiafuncs/">Ludia functionsプロジェクト</a>では以下2つのモジュールを提供します。</p>
41 <th>モジュール名</th><th>概要</th><th>ソースアーカイブファイル名</th>
45 <tr><td>Ludia functions</td>
46 <td nowrap>文字列の正規化関数とスニペット作成関数を提供するモジュール</td>
47 <td>ludia_funcs-x.y-YYYYMMDD.tar.gz</td></tr>
48 <tr><td>senna-1.1.2-fast</td>
49 <td nowrap>組み込み型全文検索エンジン<a href="http://qwik.jp/senna/FrontPageJ.html">Senna</a>の性能改善版</td>
50 <td>senna-1.1.2-fast-YYYYMMDD.tar.gz</td></tr>
54 <p>ソースアーカイブファイル名のx.yとYYYYMMDDの部分は、それぞれ、そのファイルのバージョン番号とリリース年月日です。例えば、2015年9月10日リリースのバージョン1.0のファイルでは、x.yは1.0、YYYYMMDDは20150910です。</p>
56 <p>各提供モジュールのライセンスはLGPLv2.1です。</p>
58 <p>Ludia functionsは、提供モジュールの一つである性能改善版のSennaと組み合わせて使うことで、Ludia同様に文字列の正規化やスニペット作成を行います。</p>
60 <p>Ludia functionsは、様々な形式のファイルからテキストを抽出する関数も提供します。この関数を利用するには、商用ソフトウェアの<a href="http://www.antenna.co.jp/axx/">TextPorter</a>を別途購入する必要があります。 (TextPorter Ver.5 Copyright(c) 1999- Antenna House, Inc.)</p>
61 <h2 id="requirement">動作確認環境</h2>
62 <p>Ludia functionsは、以下の環境で動作確認しています。</p>
67 <th>カテゴリ</th><th>モジュール名</th>
73 <td nowrap>Linux, Mac OS X</td>
77 <td nowrap>PostgresSQL 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 10, 11, 12, 13</td>
81 <td nowrap>senna-1.1.2-fast</td>
86 <p>Ludia functionsは、PostgreSQL9.1以降に対応しています。 9.0以前には未対応です。</p>
88 <p>Ludia functionsは、オリジナルのSenna1.1.2以降とも組み合わせ可能だと思われますが、動作確認していません。 senna-1.1.2-fastを使う場合、Ludia functionsの登録先のデータベースでは、エンコーディングはUTF-8でなければなりません。</p>
91 <h2 id="install">インストール</h2>
93 <h3 id="pg_install">PostgreSQLのインストール</h3>
94 <p><a href="http://www.postgresql.org/">PostgreSQLのオフィシャルサイト</a>からバージョンX.Y.Z(X.Y.Zは実際のバージョン数字に置き換えてください)のソースアーカイブファイル(postgresql-X.Y.Z.tar.gz)をダウンロードし、ビルドとインストールを行います。</p>
96 $ tar zxf postgresql-X.Y.Z.tar.gz
98 $ ./configure --prefix=/opt/pgsql-X.Y.Z
104 <li>--prefix : インストール先ディレクトリを指定します。未指定時のインストール先は/usr/local/pgsqlです。このオプション指定は必須ではありません。</li>
106 <p>上記手順ではソースコードからPostgreSQLをインストールしています。しかし、RPMなどの他の手順でPostgreSQLをインストールしてもLudia functionsは利用可能です。 RPMインストールのPostgreSQLでLudia functionsを利用するには、postgresql-develパッケージをインストールしなければならないことに注意してください。</p>
109 <h3 id="senna_install">Sennaのインストール</h3>
110 <p><a href="http://osdn.jp/projects/ludiafuncs/releases/">ここ</a>からsenna-1.1.2-fastのソースアーカイブファイルをダウンロードし、ビルドとインストールを行います。 Sennaのmakeには長時間かかることに注意してください。</p>
112 $ tar zxf senna-1.1.2-fast-YYYYMMDD.tar.gz
113 $ cd senna-1.1.2-fast-YYYYMMDD
114 $ ./configure --prefix=/opt/senna-1.1.2-fast --without-mecab
121 <li>--prefix : インストール先ディレクトリを指定します。未指定時のインストール先は/usr/localです。このオプション指定は必須ではありません。</li>
122 <li>--without-mecab : <a href="http://taku910.github.io/mecab/">mecab</a>モジュールを使用しないことを指定します。このオプション指定は必須です。</li>
125 <h3 id="ludia_funcs_install">Ludia functionsのインストール</h3>
126 <p><a href="http://osdn.jp/projects/ludiafuncs/releases/">ここ</a>からLudia functionsのソースアーカイブファイルをダウンロードし、ビルドとインストールを行います。</p>
128 $ tar zxf ludia_funcs-x.y-YYYYMMDD.tar.gz
129 $ cd ludia_funcs-x.y-YYYYMMDD
130 $ make USE_PGXS=1 PG_CONFIG=/opt/pgsql-X.Y.Z/bin/pg_config SENNA_CFG=/opt/senna-1.1.2-fast/bin/senna-cfg
132 # make USE_PGXS=1 PG_CONFIG=/opt/pgsql-X.Y.Z/bin/pg_config SENNA_CFG=/opt/senna-1.1.2-fast/bin/senna-cfg install
136 <li>USE_PGXS : PostgreSQL関連モジュールをコンパイルするときのオマジナイです。1の指定が必須です。</li>
137 <li>PG_CONFIG : pg_configコマンド(PostgreSQLインストール先のbinディレクトリに存在)のパスを指定します。pg_configにPATHが通っているのであれば、このオプション指定は不要です。</li>
138 <li>SENNA_CFG : senna-cfgコマンド(Sennaインストール先のbinディレクトリに存在)のパスを指定します。senna-cfgにPATHが通っているのであれば、このオプション指定は不要です。</li>
141 <h3 id="ludia_funcs_register">Ludia functionsの登録</h3>
142 <p>データベースクラスタの作成後、postgresql.confを編集、PostgreSQLを起動し、Ludia functionsをデータベースに登録します。</p>
144 $ initdb -D $PGDATA --locale=C --encoding=UTF8
146 $ vi $PGDATA/postgresql.conf
147 shared_preload_libraries = 'ludia_funcs'
148 custom_variable_classes = 'ludia_funcs'
150 $ pg_ctl -D $PGDATA start
151 $ psql -d <データベース名>
152 =# CREATE EXTENSION ludia_funcs;
154 List of installed extensions
155 Name | Version | Schema | Description
156 -------------+---------+--------+-----------------
157 ludia_funcs | 1.0 | public | ludia functions
162 <li>$PGDATAは、データベースクラスタのパスを決めて、そのパスで置き換えてください。</li>
163 <li>senna-1.1.2-fastを使う場合、Ludia functionsの登録先のデータベースでは、エンコーディングはUTF-8でなければなりません。</li>
164 <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を設定するのは必須です。
166 <li>PostgreSQL9.2以降ではcustom_variable_classesは存在しません。設定が必要なのはshared_preload_librariesだけです。</li>
169 <li>Ludia functionsの登録には、<a href="http://www.postgresql.jp/document/current/html/sql-createextension.html">CREATE EXTENSION</a>を使います。 CREATE EXTENSIONはデータベース単位でモジュールを登録するため、Ludia functionsを利用したいデータベースすべてにおいて登録が必要です。</li>
172 <p>Ludia functionsのインストールは以上で終わりです。</p>
174 <h2 id="uninstall">アンインストール</h2>
175 <h3 id="delete_ludia_funcs">Ludia functionsの削除</h3>
176 <p>Ludia functionsについて、データベースからの登録解除とアンインストールを行います。</p>
178 $ psql -d <データベース名>
179 =# DROP EXTENSION ludia_funcs CASCADE;
182 $ pg_ctl -D $PGDATA stop
185 # cd <ludia_funcsのソースディレクトリ>
186 # make USE_PGXS=1 PG_CONFIG=/opt/pgsql-X.Y.Z/bin/pg_config SENNA_CFG=/opt/senna-1.1.2-fast/bin/senna-cfg uninstall
190 <li>Ludia functionsを登録したすべてのデータベースで登録解除する必要があります。</li>
191 <li>Ludia functionsに依存するDBオブジェクトを削除する必要があるため、<a href="http://www.postgresql.jp/document/current/html/sql-dropextension.html">DROP EXTENSION</a>にはCASCADEを指定します。</li>
194 <h3 id="delete_conf">postgresql.confの設定削除</h3>
195 <p>postgresql.confの以下の設定を削除します。</p>
197 <li>shared_preload_libraries</li>
198 <li>custom_variable_classes</li>
199 <li>ludia_funcs.* (ludia_funcs.から名前が始まるパラメータ)</li>
202 <h3 id="senna_uninstall">Sennaのアンインストール</h3>
203 <p>senna-1.1.2-fastのソースディレクトリでアンインストールを行います。</p>
206 # cd <senna-1.1.2-fastのソースディレクトリ>
211 <h2 id="functions">提供関数</h2>
213 <h3 id="pgs2norm">pgs2norm</h3>
214 <p>pgs2normは、文字列正規化ルール(NFKCの正規化形式)に則って、文字列(引数1)を正規化する関数です。</p>
216 <li>引数1(text) - 正規化する文字列</li>
217 <li>戻り値(text) - 引数1を正規化した文字列</li>
220 <p>引数1がNULLの場合、戻り値はNULLです。</p>
222 <p>NFKCの正規化では、例えば、以下のように文字列を変換します。</p>
227 <li>アイウエオ → アイウエオ</li>
232 <li>ABCDE → abcde</li>
237 <li>AbCdE123 → abcde123</li>
242 <li>㌢㍻㊨⑤Ⅷ㈲ → センチ平成右5viii(有)</li>
249 =# SELECT pgs2norm('いロハAbCd12③Ⅳ㈱');
251 ---------------------
256 <p>pgs2normは、引数と戻り値の文字列をメモリ上にキャッシュします。そして、pgs2normの次回実行時に引数の文字列がキャッシュされているものと同じであれば、正規化処理を行わず、キャッシュされている戻り値を直接返却することで、処理を高速化します。 pgs2normは、引数と戻り値をキャッシュする際、前回までのキャッシュを破棄します。つまり、キャッシュできる引数と戻り値は直前実行分の一組だけです。キャッシュはセッション単位で行われます。他セッションのキャッシュを、別セッションから実行されたpgs2normで使うことはできません。 pgs2normのキャッシュサイズの上限は、パラメータ<a href="#norm_cache_limit">ludia_funcs.norm_cache_limit</a>で指定できます。</p>
258 <h3 id="pgs2snippet1">pgs2snippet1</h3>
259 <p>pgs2snippet1は、文字列(引数8)からキーワード(引数7)のスニペット(KWIC)を作成する関数です。</p>
261 <li>引数1(integer) - スニペット作成時に正規化するかどうか(する: 1、しない: 0)</li>
262 <li>引数2(integer) - 作成するスニペットの最大長(バイト単位で指定)</li>
263 <li>引数3(integer) - 作成するスニペットの数の上限</li>
264 <li>引数4(text) - スニペット作成時にキーワードの前に付ける文字列</li>
265 <li>引数5(text) - スニペット作成時にキーワードの後ろに付ける文字列</li>
266 <li>引数6(integer) - HTMLの特殊文字をエスケープするかどうか(する: -1、しない: 0)</li>
267 <li>引数7(text) - スニペット作成に使うキーワード</li>
268 <li>引数8(text) - スニペットの作成元となる文字列</li>
269 <li>戻り値(text) - キーワード(引数7)を使って文字列(引数8)から作成したスニペット文字列</li>
272 <p>NULLの引数がある場合、戻り値はNULLです。</p>
276 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, 'PostgreSQL', '最近、PostgreSQLの利用者が増えています。');
278 ----------------------------
283 <p>pgs2snippet1では、キーワード(引数7)に複数の文字列を指定できます。複数指定するには、各文字列を"(半角ダブルクォート)で囲み、それらを+(半角プラス)でつなげます。</p>
287 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '"PostgreSQL"+"HINT"', 'pg_hint_planは、PostgreSQLでHINT句を使えるようにするツールです。');
289 -------------------------------------
290 ★hint★_planは、★PostgreSQL★で★HINT★
294 <li>この実行例では、正規化を行う指定(引数1が1)になっているため、キーワードHINTは、小文字のhintにもマッチします。</li>
296 <p>キーワード内の"と\は、pgs2snippet1ではメタ文字("は検索文字列の区切り文字、\はエスケープ文字)として解釈されます。 "と\を文字そのものとして解釈させるには、それらを\でエスケープしなければなりません。</p>
300 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '"\"2-gram\""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
302 -------------------------------
303 ostgreSQLで★"2-gram"★の全文検
307 <p>このエスケープ処理は、<a href="#escape_snippet_keyword">ludia_funcs.escape_snippet_keyword</a>を有効にすることでpgs2snippet1に任せることもできます。</p>
309 <h3 id="pgs2seninfo">pgs2seninfo</h3>
310 <p>pgs2seninfoは、Ludia functionsが利用しているSennaのバージョン情報を表示する関数です。</p>
312 <li>戻り値1(text) - 利用しているSennaのバージョン番号</li>
313 <li>戻り値2(text) - 利用しているSennaのconfigureオプション</li>
318 =# SELECT * FROM pgs2seninfo();
319 version | configure_options
320 ---------------------------------+-------------------------------------------------
321 1.1.2 (last update: 2013.04.05) | '--without-mecab' '--prefix=/senna-1.1.2-fast/'
324 <h2 id="parametares">パラメータ</h2>
325 <h3 id="last_update">ludia_funcs.lastupdate</h3>
326 <p>ludia_funcs.last_updateは、Ludia functionsモジュールの最終更新日付を報告するパラメータです。このパラメータは読み取り専用です。 postgresql.confやSET文で設定値を変更することはできません。</p>
330 =# SHOW ludia_funcs.last_update ;
331 ludia_funcs.last_update
332 -------------------------
337 <h3 id="norm_cache_limit">ludia_funcs.norm_cache_limit</h3>
338 <p>ludia_funcs.norm_cache_limitは、<a href="#pgs2norm">pgs2norm</a>が確保するキャッシュの上限サイズを指定するパラメータです。設定値はkB単位で指定します。設定値の範囲は -1 ~ 2TB-1B です。設定値-1(デフォルト値)は、キャッシュサイズ上限としてパラメータwork_memの設定値を使うことを意味します。設定値0は、キャッシュサイズの上限がない(常にキャッシュする)ことを意味します。このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。</p>
340 <h3 id="escape_snippet_keyword">ludia_funcs.escape_snippet_keyword</h3>
341 <p>ludia_funcs.escape_snippet_keywordは、<a href="#pgs2snippet1">pgs2snippet1</a>のキーワード(引数7)内の"(半角ダブルクォート)と\(半角バックスラッシュ)をエスケープするかどうか指定するパラメータです。デフォルト値はoffで、エスケープしません。</p>
343 <p>キーワード内の"と\は、pgs2snippet1ではメタ文字("は検索文字列の区切り文字、\はエスケープ文字)として解釈されます。 "と\を文字そのものとして解釈させるには、それらを\でエスケープしなければなりません。このパラメータを有効にすると、pgs2snippet1は、文字として解釈させたい"と\を自動的にエスケープします。このようなエスケープ処理をクライアントアプリケーション側で実装済の場合は、このパラメータは無効で構いません。</p>
345 <p>このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。</p>
347 <p><a href="#pgs2snippet1">pgs2snippet1</a>に記述されている最後の実行例のSQLは、escape_snippet_keywordを使うことで、以下のように書き換えられます。</p>
351 =# SHOW ludia_funcs.escape_snippet_keyword ;
352 ludia_funcs.escape_snippet_keyword
353 ------------------------------------
357 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '""2-gram""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
363 =# SET ludia_funcs.escape_snippet_keyword TO on;
365 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '""2-gram""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
367 -------------------------------
368 ostgreSQLで★"2-gram"★の全文検
372 <li>キーワード内の先頭と末尾の"は必ずメタ文字(検索文字列の区切り文字)として解釈されます。</li>
375 <h2 id="release_notes">リリースノート</h2>
377 <li><a href="release-1-0.html">バージョン1.0</a></li>
381 <div align="right">Copyright (c) 2016-2021, ludia_funcs Development Group</div>
382 <div align="right">Copyright (c) 2012-2015, NTT DATA Corporation</div>