Senna_Index クラス

class Senna_Index

Senna_Indexクラスは、検索インデックス（索引）を表現するクラスです。インデックスの更新や検索を実行する場合は、このクラスを使用します。

クラス概要
クラス定数
コンストラクタ
- __construct($path [, $key_size [, $flags [, $initial_n_segments [, $encoding]]]])
メソッド
- クラスメソッド
  - create($path [, $key_size [, $flags [, $initial_n_segments [, $encoding]]]])
  - open($path)
  - remove($path)
  - rename($old_name, $new_name)
- インスタンスメソッド
  - getEncoding()
  - getFlags()
  - getInitialSegments()
  - getKeySize()
  - getPath()
  - query($query [, $max_exprs])
  - upd($key, $old_value, $new_value)
  - update($key, $section, $old_value, $new_value)

クラス概要

<?php
$index = new Senna_Index('/path/to/index');

// インデックスの更新
$index->upd('document001', NULL, '全文検索は楽しい');
$index->upd('document002', NULL, '全文検索は難しい');
$index->upd('document003', NULL, '楽しいけど難しい');
$index->update('document004', 1, NULL, '組み込み型全文検索エンジンSenna');
$index->update('document004', 2, NULL, 'PHPバインディング');
$index->update('document004', 2, 'PHPバインディング', 'php_sennaでオリジナル検索エンジンを作ろう');

// 検索
$records = $index->query('楽しい 検索 OR php_senna');

// インデックスの作成、オープン、リネーム、削除
$index = Senna_Index::create('/path/to/index');
$index = Senna_Index::open('/path/to/index');
Senna_Index::rename('/path/to/old', '/path/to/new');
Senna_Index::remove('/path/to/index');

クラス定数

Tokenizer関連

インデックス生成時に指定するフラグです。複数のフラグを組み合わせて指定する場合は、論理 OR (|) 演算子で連結します。特定のフラグが指定されているか調べる場合は、論理 AND (&) 演算子でテストしてください。

NORMALIZE (integer)
- 英文字の大文字/小文字、全角文字/半角文字を正規化します。
SPLIT_ALPHA (integer)
- 英文字列を文字要素に分割します。
SPLIT_DIGIT (integer)
- 数字を文字要素に分割します。
SPLIT_SYMBOL (integer)
- 記号を文字要素に分割します。
MORPH_ANALYSE (integer)
- 形態素解析を使用します。デフォルトの動作です。
NGRAM (integer)
- 形態素解析ではなく、N-gramを使用します。
DELIMITED (integer)
- 形態素解析ではなく、空白で単語を区切ります。
ENABLE_SUFFIX_SEARCH (integer)
- 後方一致検索を有効にします。
DISABLE_SUFFIX_SEARCH (integer)
- 後方一致検索を無効にします。
WITH_VGRAM (integer)
- V-gramを使います。トークンは可変長になります。
WITH_VACUUM (integer)

文書ID長関連

VARIABLE_KEY_SIZE (integer)
- 文書IDを可変長文字列として扱います。
MAX_KEY_SIZE (integer)
- 扱うことができる文書IDの最大長です(Senna-1.0.9では8KB)。

バッファ関連

DEFAULT_INITIAL_N_SEGMENTS (integer)
- デフォルトで確保する初期バッファサイズです(Senna-1.0.9では約130MB)。

クエリー関連

DEFAULT_MAX_N_EXPRS (integer)
- クエリー発行時の最大演算子数のデフォルト値(32)です。

コンストラクタ

public void __construct(
    string $path [, int $key_size [, int $flags [, int $initial_n_segments [, int $encoding]]]])

指定されたパスでインデックスを作成します。パスは*.SENファイルの拡張子「.SEN」を含めずに指定してください。

パスにインデックスファイルが存在していればそれを開き、そうでなければ新規作成します。インデックスファイルが存在していた場合は、パス以外の引数を無視します。

1つのインデックスに対して、4つのファイルを作成します（フラグにSenna_Index::WITH_VGRAMを指定した場合は5つ）。各ファイルの詳細はSennaのインデックスファイルを参照してください。

初期バッファサイズinitial_n_segmentsは、実メモリサイズを越えない範囲で大きいほど更新処理が高速になります。

形態素解析を使う場合は、MeCabの辞書のエンコーディングと同じエンコーディングを指定してください。異なるエンコーディングを指定すると検索がうまくいかない場合があります。

パラメータ
- path - インデックスファイル名
- key_size - 文書ID長（バイト数）。デフォルトはSenna_Index::VARIABLE_KEY_SIZE（可変長文字列）です。
- flags - フラグを組み合わせて指定します。デフォルトはSenna_Index::NORMALIZEです。
- initial_n_segments - 初期バッファサイズ。デフォルトはSenna_Index::DEFAULT_INITIAL_N_SEGMENTSです。
- encoding - 文字コードを指定します。デフォルトは、Senna::ENC_DEFAULTです。
例外
- UnexpectedValueException - 以下の場合
  - pathが空文字
  - (key_size < 0)または(Senna_Index::MAX_KEY_SIZE < key_size)
  - initial_n_segmentsが負の値
  - encodingが未対応の文字コード
- SennaException - インデックスファイルの作成やオープンに失敗した場合

メソッド

create

public static Senna_Index create(
    string $path [, int $key_size [, int $flags [, int $initial_n_segments [, int $encoding]]]])

指定されたパスに新しいインデックスファイルを作成し、Senna_Indexオブジェクトを返します。パスは*.SENファイルの拡張子「.SEN」を含めずに指定してください。

インデックスファイルが既に存在していた場合は、空のインデックスファイルとして初期化します。

初期バッファサイズinitial_n_segmentsは、実メモリサイズを越えない範囲で大きいほど更新処理が高速になります。

パラメータ
- path - インデックスファイル名
- key_size - 文書ID長（バイト数）。デフォルトはSenna_Index::VARIABLE_KEY_SIZE（可変長文字列）です。
- flags - フラグを組み合わせて指定します。デフォルトはSenna_Index::NORMALIZEです。
- initial_n_segments - 初期バッファサイズ。デフォルトはSenna_Index::DEFAULT_INITIAL_N_SEGMENTSです。
- encoding - 文字コードを指定します。デフォルトは、Senna::ENC_DEFAULTです。
戻り値
- 新しく作成したSenna_Indexオブジェクト
例外
- UnexpectedValueException - 以下の場合
  - pathが空文字
  - (key_size < 0)または(Senna_Index::MAX_KEY_SIZE < key_size)
  - initial_n_segmentsが負の値
  - encodingが未対応の文字コード
- SennaException - インデックスファイルの作成に失敗した場合

open

public static Senna_Index create(string $path)

指定されたパスのインデックスファイルを開き、Senna_Indexオブジェクトを返します。パスは*.SENファイルの拡張子「.SEN」を含めずに指定してください。

パラメータ
- path - インデックスファイル名
戻り値
- Senna_Indexオブジェクト
例外
- UnexpectedValueException - パスが空文字の場合
- SennaException - インデックスファイルのオープンに失敗した場合

rename

public static void rename(string $old_name, string $new_name)

インデックスファイルのファイル名を変更します。それぞれのパスは*.SENファイルの拡張子「.SEN」を含めずに指定してください。

パラメータ
- old_name - 変更前の名前
- new_name - 変更後の名前
例外
- UnexpectedValueException - old_nameもしくはnew_nameが空文字の場合
- SennaException - ファイル名の変更に失敗した場合

remove

public static void remove(string $path)

インデックスファイルを削除します。パスは*.SENファイルの拡張子「.SEN」を含めずに指定してください。

Senna-1.1.0より前のバージョンを使用している場合、V-gram用ファイルに関連するバグ[Senna-dev 694]を回避するために、パスが空文字でなければ常に成功とみなします。実際の成否にかかわらずSennaExceptionは投げません。

パラメータ
- path - 削除するインデックスファイル名
例外
- UnexpectedValueException - pathが空文字の場合
- SennaException - 削除に失敗した場合（Senna-1.1.0以降）

upd

public Senna_Index upd(string $key, string $old_value, string $new_value)

このインデックス内の、指定された文書の内容を更新します。

新規文書を追加する場合、old_valueは空文字（またはNULL）を指定してください。
文書を削除する場合、new_valueは空文字（またはNULL）を指定してください。
old_valueとnew_valueが共に空の場合、何もしません。
存在しない文書IDを削除しようとすると更新に失敗し、例外を投げます。

文書を更新する場合は、前回登録した内容をold_valueに設定する必要があります。これはSennaが文書の内容を保持しない仕様のためです（参考：[Senna-dev 112]）。

このメソッドはオブジェクト自身を返します。これにより、メソッドを連続して呼ぶことができます。例えば次のような書き方が可能です。

<?php
$i = new Senna_Index('/path/to/index');
$i->
  upd('key001', NULL, 'document1')->
  upd('key002', NULL, 'document2')->
  upd('key003', NULL, 'document3');

$i->upd('key001', 'document1', NULL)
  ->upd('key002', 'document2', NULL)
  ->upd('key003', 'document3', NULL);

パラメータ
- key - 更新する文書ID
- old_value - 更新前の文書の内容
- new_value - 更新後の文書の内容
戻り値
- オブジェクト自身(Senna_Index)
例外
- UnexpectedValueException - keyが空文字の場合
- SennaException - 更新に失敗した場合

update

public Senna_Index update(string $key, int $section, string $old_value, string $new_value)

このインデックス内の、指定された文書のsection番目の段落を更新します。

新規文書の場合、old_valueは空文字（またはNULL）を指定してください。
文書を削除する場合、new_valueは空文字（またはNULL）を指定してください。
old_valueとnew_valueが共に空の場合は何もしません。
存在しない文書IDを削除しようとすると更新に失敗し、例外を投げます。

upd()と同様、文書を更新する場合は前回登録した内容をold_valueに設定する必要があります。

upd()と違い、このメソッドは1つの文書を複数の論理的な「段落」に分けて扱います。論理的なセクションに分けて登録しておくことで、検索の際に特定の段落のみを対象としたり（例：タイトル検索）、キーワードが特定の段落（要約セクションなど）でヒットした場合にスコアを上げる（または下げる）、というような制御が可能になります。

段落番号は連続していなくても更新可能です。例えば、2, 4, 5番目を使い1, 3番目の段落は未使用にしておく、ということも可能です。

このメソッドはオブジェクト自身を返します。これにより、メソッドを連続して呼ぶことができます。例えば以下のような書き方が可能です。

<?php
$i = new Senna_Index('/path/to/index');
$i->
  update('key001', 1, NULL, 'document1')->
  update('key002', 1, NULL, 'document2')->
  update('key002', 7, NULL, 'document2');

$i->update('key001', 1, 'document1', NULL)
  ->update('key002', 1, 'document2', NULL)
  ->update('key002', 7, 'document2', NULL);

パラメータ
- key - 更新する文書ID
- section - 更新する段落番号。1以上の値
- old_value - 更新前の文書の内容
- new_value - 更新後の文書の内容
戻り値
- オブジェクト自身(Senna_Index)
例外
- UnexpectedValueException - keyが空文字の場合、またはsectionが1未満の場合
- SennaException - 更新に失敗した場合

query

public Senna_Records query(string $query [, int $max_exprs])

指定された条件でこのインデックス内を検索し、検索結果を返します。

クエリーの書式はSennaのクエリー書式を参考にしてください。演算子を省略した場合は、+（AND演算子）が指定されたものとして扱います。通常の検索エンジンでの検索クエリーと同じ使用感です。

最大max_exprs個までの演算子（キーワード）をクエリー文字列に含めることができます。max_exprs個を超えたものは無視します。

パラメータ
- query - 検索クエリー文字列
- max_exprs - クエリー内で使用する演算子の上限。デフォルトはSenna_Index::DEFAULT_MAX_N_EXPRSです。
戻り値
- 指定されたクエリーでの検索結果
例外
- UnexpectedValueException - queryが空文字の場合、またはmax_exprsが1未満の場合
- SennaException - 検索に失敗した場合
関連項目
- Senna_Records