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