html/ludia_funcs.html

   1 <html>
   2 <head>
   3 <title>Ludia functions ドキュメント</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://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>
  17     </ul>
  18   </div>
  19
  20 <h1 id="ludia_funcs">ドキュメント</h1>
  21
  22 <div class="index">
  23 <ol>
  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 </ol>
  31 </div>
  32
  33 <h2 id="description">概要</h2>
  34 <p>Ludia functionsは、文字列の正規化関数とスニペット作成関数を提供するモジュールです。それらの関数は全文検索モジュール<a href="http://ludia.sourceforge.jp/moin.cgi/">Ludia</a>が提供していたものと同じです。 Ludia functionsは、それらの関数を<a href="http://www.postgresql.org/">PostgreSQL</a>9.1以降で利用可能にしています。</p>
  35 <p><a href="http://sourceforge.jp/projects/ludiafuncs/">Ludia functionsプロジェクト</a>では以下2つのモジュールを提供します。</p>
  36
  37 <table>
  38 <thead>
  39 <tr>
  40 <th>モジュール名</th><th>概要</th><th>ソースアーカイブファイル名</th>
  41 </tr>
  42 </thead>
  43 <tbody>
  44 <tr><td>Ludia functions</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>
  50 </tbody>
  51 </table>
  52
  53 <p>ソースアーカイブファイル名のYYYYMMDDの部分は、実際にはそのファイルがリリースされた年月日になります。例えば、2013年4月5日リリースのファイルでは、YYYYMMDDは20130405です。</p>
  54
  55 <p>各提供モジュールのライセンスはLGPLv2.1です。</p>
  56
  57 <p>Ludia functionsは、提供モジュールの一つである性能改善版のSennaと組み合わせて使いうことで、Ludia同様に文字列の正規化やスニペット作成を行います。</p>
  58
  59 <p>Ludia functionsは、様々な形式のファイルからテキストを抽出する関数も提供します。この関数を利用するには、商用ソフトウェアの<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 functionsは、以下の環境で動作確認しています。</p>
  62
  63 <table>
  64 <thead>
  65 <tr>
  66 <th>カテゴリ</th><th>モジュール名</th>
  67 </tr>
  68 </thead>
  69 <tbody>
  70 <tr>
  71   <td>OS</td>
  72   <td nowrap>Red Hat Enterprise Linux 6.1 x86_64</td>
  73 </tr>
  74 <tr>
  75   <td>DMBMS</td>
  76   <td nowrap>PostgresSQL9.1</td>
  77 </tr>
  78 <tr>
  79   <td>Senna</td>
  80   <td nowrap>senna-1.1.2-fast</td>
  81 </tr>
  82 </tbody>
  83 </table>
  84
  85 <p>Ludia functionsは、PostgreSQL9.1のみに対応しています。 9.0以前には未対応です。 9.2以降には対応していると思われますが、動作確認していません。</p>
  86
  87 <p>Ludia functionsは、オリジナルのSenna1.1.2以降とも組み合わせ可能だと思われますが、動作確認していません。 senna-1.1.2-fastを使う場合、Ludia functionsの登録先のデータベースでは、エンコーディングはUTF-8でなければなりません。</p>
  88
  89
  90 <h2 id="install">インストール</h2>
  91
  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>
  94 <pre>
  95 $ tar zxf postgresql-9.1.X.tar.gz
  96 $ cd postgresql-9.1.X
  97 $ ./configure --prefix=/opt/pgsql-9.1.X
  98 $ make
  99 $ su
 100 # make install
 101 # exit</pre>
 102 <ul>
 103 <li>--prefix : インストール先ディレクトリを指定します。未指定時のインストール先は/usr/local/pgsqlです。このオプション指定は必須ではありません。</li>
 104 </ul>
 105 <p>上記手順ではソースコードからPostgreSQLをインストールしています。しかし、RPMなどの他の手順でPostgreSQLをインストールしてもLudia functionsは利用可能です。 RPMインストールのPostgreSQLでLudia functionsを利用するには、postgresql-develパッケージをインストールしなければならないことに注意してください。</p>
 106
 107
 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>
 110 <pre>
 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
 114 $ make
 115 $ su
 116 # make install
 117 # exit
 118 </pre>
 119 <ul>
 120 <li>--prefix : インストール先ディレクトリを指定します。未指定時のインストール先は/usr/localです。このオプション指定は必須ではありません。</li>
 121 <li>--without-mecab : <a href="https://code.google.com/p/mecab/">mecab</a>モジュールを使用しないことを指定します。このオプション指定は必須です。</li>
 122 </ul>
 123
 124 <h3 id="ludia_funcs_install">Ludia functionsのインストール</h3>
 125 <p><a href="http://sourceforge.jp/projects/ludiafuncs/releases/">ここ</a>からLudia functionsのソースアーカイブファイルをダウンロードし、ビルドとインストールを行います。</p>
 126 <pre>
 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
 130 $ su
 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
 132 # exit
 133 </pre>
 134 <ul>
 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>
 138 </ul>
 139
 140 <h3 id="ludia_funcs_register">Ludia functionsの登録</h3>
 141 <p>データベースクラスタの作成後、postgresql.confを編集、PostgreSQLを起動し、Ludia functionsをデータベースに登録します。</p>
 142 <pre>
 143 $ initdb -D $PGDATA --locale=C --encoding=UTF8
 144
 145 $ vi $PGDATA/postgresql.conf
 146 shared_preload_libraries = 'ludia_funcs'
 147 custom_variable_classes = 'ludia_funcs'
 148
 149 $ pg_ctl -D $PGDATA start
 150 $ psql -d &lt;データベース名&gt;
 151 =# CREATE EXTENSION ludia_funcs;
 152 =# \dx ludia_funcs
 153            List of installed extensions
 154     Name     | Version | Schema |   Description
 155 -------------+---------+--------+-----------------
 156  ludia_funcs | 1.0     | public | ludia functions
 157 (1 row)
 158 </pre>
 159
 160 <ul>
 161 <li>$PGDATAは、データベースクラスタのパスを決めて、そのパスで置き換えてください。</li>
 162 <li>senna-1.1.2-fastを使う場合、Ludia functionsの登録先のデータベースでは、エンコーディングは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を設定するのは必須です。
 164   <ul>
 165     <li>PostgreSQL9.2以降ではcustom_variable_classesは存在しません。設定が必要なのはshared_preload_librariesだけです。</li>
 166   </ul>
 167 </li>
 168 <li>Ludia functionsの登録には、<a href="http://www.postgresql.jp/document/current/html/sql-createextension.html">CREATE EXTENSION</a>を使います。 CREATE EXTENSIONはデータベース単位でモジュールを登録するため、Ludia functionsを利用したいデータベースすべてにおいて登録が必要です。</li>
 169 </ul>
 170
 171 <p>Ludia functionsのインストールは以上で終わりです。</p>
 172
 173 <h2 id="uninstall">アンインストール</h2>
 174 <h3 id="delete_ludia_funcs">Ludia functionsの削除</h3>
 175 <p>Ludia functionsについて、データベースからの登録解除とアンインストールを行います。</p>
 176 <pre>
 177 $ psql -d &lt;データベース名&gt;
 178 =# DROP EXTENSION ludia_funcs CASCADE;
 179 =# \q
 180
 181 $ pg_ctl -D $PGDATA stop
 182 $ su
 183
 184 # cd &lt;ludia_funcsのソースディレクトリ&gt;
 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
 186 # exit
 187 </pre>
 188 <ul>
 189 <li>Ludia functionsを登録したすべてのデータベースで登録解除する必要があります。</li>
 190 <li>Ludia functionsに依存するDBオブジェクトを削除する必要があるため、<a href="http://www.postgresql.jp/document/current/html/sql-dropextension.html">DROP EXTENSION</a>にはCASCADEを指定します。</li>
 191 </ul>
 192
 193 <h3 id="delete_conf">postgresql.confの設定削除</h3>
 194 <p>postgresql.confの以下の設定を削除します。</p>
 195 <ul>
 196 <li>shared_preload_libraries</li>
 197 <li>custom_variable_classes</li>
 198 <li>ludia_funcs.* (ludia_funcs.から名前が始まるパラメータ)</li>
 199 </ul>
 200
 201 <h3 id="senna_uninstall">Sennaのアンインストール</h3>
 202 <p>senna-1.1.2-fastのソースディレクトリでアンインストールを行います。</p>
 203 <pre>
 204 $ su
 205 # cd &lt;senna-1.1.2-fastのソースディレクトリ&gt;
 206 # make uninstall
 207 # exit
 208 </pre>
 209
 210 <h2 id="functions">提供関数</h2>
 211
 212 <h3 id="pgs2norm">pgs2norm</h3>
 213 <p>pgs2normは、文字列正規化ルール(NFKCの正規化形式)に則って、文字列(引数1)を正規化する関数です。</p>
 214 <ul>
 215 <li>引数1(text) - 正規化する文字列</li>
 216 <li>戻り値(text) - 引数1を正規化した文字列</li>
 217 </ul>
 218
 219 <p>引数1がNULLの場合、戻り値はNULLです。</p>
 220
 221 <p>NFKCの正規化では、例えば、以下のように文字列を変換します。</p>
 222 <ul>
 223
 224     <li>半角カタカナを全角カタカナに変換
 225     <ul>
 226         <li>ｱｲｳｴｵ → アイウエオ</li>
 227     </ul>
 228     </li>
 229     <li>大文字英字を小文字英字に変換
 230     <ul>
 231         <li>ABCDE → abcde</li>
 232     </ul>
 233     </li>
 234     <li>全角英数字を半角英数字に変換
 235     <ul>
 236         <li>ＡｂＣｄＥ１２３ → abcde123</li>
 237     </ul>
 238     </li>
 239     <li>環境依存文字を変換
 240     <ul>
 241         <li>㌢㍻㊨⑤Ⅷ㈲ → センチ平成右5viii(有)</li>
 242     </ul>
 243     </li>
 244 </ul>
 245
 246 <p>実行例</p>
 247 <pre>
 248 =# SELECT pgs2norm('いロﾊAbＣｄ1２③Ⅳ㈱');
 249       pgs2norm
 250 ---------------------
 251  いロハabcd123iv(株)
 252 (1 row)
 253 </pre>
 254
 255 <p>pgs2normは、引数と戻り値の文字列をメモリ上にキャッシュします。そして、pgs2normの次回実行時に引数の文字列がキャッシュされているものと同じであれば、正規化処理を行わず、キャッシュされている戻り値を直接返却することで、処理を高速化します。 pgs2normは、引数と戻り値をキャッシュする際、前回までのキャッシュを破棄します。つまり、キャッシュできる引数と戻り値は直前実行分の一組だけです。キャッシュはセッション単位で行われます。他セッションのキャッシュを、別セッションから実行されたpgs2normで使うことはできません。 pgs2normのキャッシュサイズの上限は、パラメータ<a href="#norm_cache_limit">ludia_funcs.norm_cache_limit</a>で指定できます。</p>
 256
 257 <h3 id="pgs2snippet1">pgs2snippet1</h3>
 258 <p>pgs2snippet1は、文字列(引数8)からキーワード(引数7)のスニペット(KWIC)を作成する関数です。</p>
 259 <ul>
 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>
 269 </ul>
 270
 271 <p>NULLの引数がある場合、戻り値はNULLです。</p>
 272
 273 <p>実行例</p>
 274 <pre>
 275 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, 'PostgreSQL', '最近、PostgreSQLの利用者が増えています。');
 276         pgs2snippet1
 277 ----------------------------
 278  最近、★PostgreSQL★の利用者
 279 (1 row)
 280 </pre>
 281
 282 <p>pgs2snippet1では、キーワード(引数7)に複数の文字列を指定できます。複数指定するには、各文字列を"(半角ダブルクォート)で囲み、それらを+(半角プラス)でつなげます。</p>
 283
 284 <p>実行例</p>
 285 <pre>
 286 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '"PostgreSQL"+"HINT"', 'pg_hint_planは、PostgreSQLでHINT句を使えるようにするツールです。');
 287             pgs2snippet1
 288 -------------------------------------
 289  ★hint★_planは、★PostgreSQL★で★HINT★
 290 (1 row)
 291 </pre>
 292 <ul>
 293 <li>この実行例では、正規化を行う指定(引数1が1)になっているため、キーワードHINTは、小文字のhintにもマッチします。</li>
 294 </ul>
 295 <p>キーワード内の"と\は、pgs2snippet1ではメタ文字("は検索文字列の区切り文字、\はエスケープ文字)として解釈されます。 "と\を文字そのものとして解釈させるには、それらを\でエスケープしなければなりません。</p>
 296
 297 <p>実行例</p>
 298 <pre>
 299 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '"\"2-gram\""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
 300          pgs2snippet1
 301 -------------------------------
 302  ostgreSQLで★"2-gram"★の全文検
 303 (1 row)
 304 </pre>
 305
 306 <p>このエスケープ処理は、<a href="#escape_snippet_keyword">ludia_funcs.escape_snippet_keyword</a>を有効にすることでpgs2snippet1に任せることもできます。</p>
 307
 308 <h3 id="pgs2seninfo">pgs2seninfo</h3>
 309 <p>pgs2seninfoは、Ludia functionsが利用しているSennaのバージョン情報を表示する関数です。</p>
 310 <ul>
 311     <li>戻り値1(text) - 利用しているSennaのバージョン番号</li>
 312     <li>戻り値2(text) - 利用しているSennaのconfigureオプション</li>
 313 </ul>
 314
 315 <p>実行例</p>
 316 <pre>
 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/'
 321 </pre>
 322
 323 <h2 id="parametares">パラメータ</h2>
 324 <h3 id="last_update">ludia_funcs.lastupdate</h3>
 325 <p>ludia_funcs.last_updateは、Ludia functionsモジュールの最終更新日付を報告するパラメータです。このパラメータは読み取り専用です。 postgresql.confやSET文で設定値を変更することはできません。</p>
 326
 327 <p>実行例</p>
 328 <pre>
 329 =# SHOW ludia_funcs.last_update ;
 330  ludia_funcs.last_update
 331 -------------------------
 332  2013.04.05
 333 (1 row)
 334 </pre>
 335
 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>
 338
 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>
 341
 342 <p>キーワード内の"と\は、pgs2snippet1ではメタ文字("は検索文字列の区切り文字、\はエスケープ文字)として解釈されます。 "と\を文字そのものとして解釈させるには、それらを\でエスケープしなければなりません。このパラメータを有効にすると、pgs2snippet1は、文字として解釈させたい"と\を自動的にエスケープします。このようなエスケープ処理をクライアントアプリケーション側で実装済の場合は、このパラメータは無効で構いません。</p>
 343
 344 <p>このパラメータは、postgresql.confとSET文(スーパーユーザに限らずどのユーザからでも)で設定値を変更できます。</p>
 345
 346 <p><a href="#pgs2snippet1">pgs2snippet1</a>に記述されている最後の実行例のSQLは、escape_snippet_keywordを使うことで、以下のように書き換えられます。</p>
 347
 348 <p>実行例</p>
 349 <pre>
 350 =# SHOW ludia_funcs.escape_snippet_keyword ;
 351  ludia_funcs.escape_snippet_keyword
 352 ------------------------------------
 353  off
 354 (1 row)
 355
 356 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '""2-gram""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
 357  pgs2snippet1
 358 --------------
 359  (null)
 360 (1 row)
 361
 362 =# SET ludia_funcs.escape_snippet_keyword TO on;
 363
 364 =# SELECT pgs2snippet1(1, 32, 1, '★', '★', 0, '""2-gram""', 'pg_bigmは、PostgreSQLで"2-gram"の全文検索を使えるようにするツールです。');
 365          pgs2snippet1
 366 -------------------------------
 367  ostgreSQLで★"2-gram"★の全文検
 368 (1 row)
 369 </pre>
 370 <ul>
 371     <li>キーワード内の先頭と末尾の"は必ずメタ文字(検索文字列の区切り文字)として解釈されます。</li>
 372 </ul>
 373
 374 <hr>
 375 <div align="right">Copyright (c) 2012-2015, NTT DATA Corporation</div>
 376
 377 </body>
 378 </html>