------------------------
Ludia 0.8.0 ユーザガイド
------------------------

Ludiaについて
=============

概要
----

LudiaはPostgreSQLに高速な全文検索機能を提供します。
全文検索エンジンSennaを利用し、データベース内のテキスト情報を高速検索します。
Ludiaは以下のような特徴をもっています。

PostgreSQLインデックス機能への統合
    PostgreSQLのインデックスアクセスメソッドとして実装されているため、
    B-treeインデックスなど他の種類のインデックスと同じように、
    あるいは他の種類のインデックスと組み合わせて使うことができます。
    検索は追加定義の「@@」演算子を用いて行います。
    また、テーブルにレコードの追加、更新、削除を行った際は、
    インデックス側の情報も自動的に更新されます。
  
スコアを利用したクエリ文
    全文検索エンジンの検索スコア(検索内容との合致度)をクエリ中で取得し、
    フィルタ条件やソート条件として使用することができます。
  

ライセンス
----------

LudiaはOSS（オープンソースソフトウェア）です。
あなたは、Free Software Foundationが公表した
GNU Lesser General Public Licenseのバージョン2.1が定める条項に従って、
本プログラムを再頒布または変更することができます。
頒布にあたっては、
市場性及び特定目的適合性についての暗黙の保証を含めて、
いかなる保障も行いません。
詳細は GNU LESSER GENERAL PUBLIC LICENSE Version 2.1 をお読みください。


制限事項
--------

- 複数列インデックスとしては使用できません。

- 一意性インデックスの機能は提供しません。

- VACUUMには完全に対応していません。
  無効なTIDのチェックは行われますが、インデックスのサイズは減少しません。

- REINDEXには対応していません。
  インデックスの再構築は、
  インデックスファイルの削除、インデックスのDROP、インデックスの再作成、
  という手順で行ってください。


動作環境
--------

以下の環境で動作確認をしています。

:OS: RedHat Enterprise Linux AS[ES] 4
:DBMS:  PostgreSQL 8.1.4
:Senna: 0.8.1
:MeCab: 0.93


連絡先
------

株式会社NTTデータ 基盤システム事業本部
オープンソース開発センタ 技術開発担当
E-mail: osdquery@nttdata.co.jp 




使い方
======

インデックスアクセスメソッドの登録
----------------------------------

Ludiaを使用するデータベースに対してインデックスアクセスメソッドを登録します。
ソースアーカイブに含まれている pgsenna2.sql をpsqlから実行してください。::

  $ psql -f ./pgsenna2.sql testdb


インデックスの作成
------------------

ここでは、例として以下のようなテーブルを利用します。::

  CREATE TABLE table1 (col1 text, col2 varchar(128));
  INSERT INTO table1 VALUES ('すもももももももものうち', 'あの壺はよいものだ');
  INSERT INTO table1 VALUES ('ももから生まれた桃太郎', 'あの壷はよいものだ');

全文検索インデックスはCREATE INDEX 文を利用して作成します。::

  CREATE INDEX index1 ON table1 USING fulltext(col1);

インデックスアクセスメソッド名には

- fulltext : 形態素解析
- fulltextb : 2-gram

の2種類があり、どちらを指定するかによって分かち書き方式が変わります。
fulltext を利用する場合は MeCab がインストールされている必要があります。

ここで、Ludiaがインデックス対象とできるのはtext型のみです。
char型などの列に対してインデックスを作成したい場合には、キャストしてください。::

  CREATE INDEX index2 ON table1 USING fulltextb((col2::text));


検索の実行
----------

Ludiaのインデックスを用いた検索を行う場合には @@ 演算子を使用します。
@@ 演算子の右辺にはSennaの検索クエリを指定してください。
Sennaのクエリの書式については、以下のURLを参照してください。
http://qwik.jp/senna/query.html
::

  SELECT * FROM table1 WHERE col1 @@ 'もも';
             col1           |        col2
  --------------------------+--------------------
   すもももももももものうち | あの壺はよいものだ
   ももから生まれた桃太郎   | あの壷はよいものだ
  (2 rows)

また、この検索における検索スコアを取得するためには、
pgs2getscore関数を利用します。
pgs2getscore関数は2つの引数をとります。
1番目の引数には検索対象となった行のTIDを、
2番目の引数にはインデックス名を指定してください。::

  SELECT col1, pgs2getscore(table1.ctid, 'index1') FROM table1 WHERE col1 @@ 'もも';
             col1           | pgs2getscore
  --------------------------+--------------
   すもももももももものうち |           10
   ももから生まれた桃太郎   |            5


インデックスの削除
------------------

PostgreSQLのインデックスリレーションファイルは、
Ludiaのインデックスファイルは以下の5つから構成されます。
(テーブル空間を使用している場合は、テーブル空間定義時に指定した場所に置かれます。)

1.  PGDATA/base/データベースのOID/インデックスのファイルノード番号
2.  PGDATA/base/データベースのOID/インデックスのファイルノード番号.SEN 
3.  PGDATA/base/データベースのOID/インデックスのファイルノード番号.SEN.i 
4.  PGDATA/base/データベースのOID/インデックスのファイルノード番号.SEN.i.c 
5.  PGDATA/base/データベースのOID/インデックスのファイルノード番号.SEN.l 

1 はPostgreSQLのインデックスリレーションファイル、
2〜5はSennaのインデックスファイルです。
2〜5のファイルは手作業で削除する必要があります。

参考として、インデックスのファイルノード番号は以下のようなクエリで取得できます。::

  SELECT relfilenode FROM pg_class WHERE relname = 'index1';

また、データベースのOIDは以下のようなクエリで取得できます。::

  SELECT oid FROM pg_database WHERE datname = 'dbname';

1のファイルについては、DROP INDEXを実行することで削除されます。::

  DROP INDEX index1;
