repo_zf1/documentation/manual/ja/module_specs/Zend_Search_Lucene-BestPractice.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.search.lucene.best-practice">
    <title>ベストプラクティス</title>

    <sect2 id="zend.search.lucene.best-practice.field-names">
        <title>フィールド名</title>

        <para>
            <classname>Zend_Search_Lucene</classname> では、フィールド名に関する制限は特にありません。
        </para>

        <para>
            しかし、できれば '<emphasis>id</emphasis>'
            および '<emphasis>score</emphasis>' という名前は使用を控えるようにしましょう。
            これらを使用すると、<classname>QueryHit</classname>
            のプロパティ名と区別しにくくなります。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Search_QueryHit</classname> のプロパティ
            <property>id</property> と <property>score</property> はそれぞれ、Lucene
            ドキュメントが内部で使用する ID、検索結果の
            <link linkend="zend.search.lucene.searching.results-scoring">スコア</link>
            を表します。もしドキュメントでこれらと同じ名前のフィールドを使っているのなら、
            そのフィールドにアクセスするには <methodname>getDocument()</methodname>
            メソッドを使う必要があります。
        </para>

        <programlisting language="php"><![CDATA[
$hits = $index->find($query);

foreach ($hits as $hit) {
    // 'title' フィールドを取得します
    $title = $hit->title;

    // 'contents' フィールドを取得します
    $contents = $hit->contents;

    // Lucene ドキュメントの内部 ID を取得します
    $id = $hit->id;

    // 検索結果のスコアを取得します
    $score = $hit->score;

    // 'id' フィールドを取得します
    $docId = $hit->getDocument()->id;

    // 'score' フィールドを取得します
    $docId = $hit->getDocument()->score;

    // 'title' フィールドもこの方法で取得できます
    $title = $hit->getDocument()->title;
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.search.lucene.best-practice.indexing-performance">
        <title>インデックス作成のパフォーマンス</title>

        <para>
            インデックス作成のパフォーマンスは、
            リソースの消費量と所要時間、
            そしてインデックスの品質との兼ね合いで決まります。
        </para>

        <para>
            インデックスの品質とは、要するにインデックスセグメントの数のことです。
        </para>

        <para>
            各インデックスセグメントはデータ部とは独立しています。
            つまり、インデックスに含まれるセグメントが多くなればなるほど
            検索に要するメモリと時間は増加します。
        </para>

        <para>
            インデックスの最適化を行うと、
            複数のセグメントをまとめて新しいひとつのセグメントを作成します。
            完全に最適化されたインデックスは、セグメントひとつだけで構成されます。
        </para>

        <para>
            インデックスの最適化を行うには <methodname>optimize()</methodname> メソッドを使用します。
        </para>

        <programlisting language="php"><![CDATA[
$index = Zend_Search_Lucene::open($indexPath);

$index->optimize();
]]></programlisting>

        <para>
            インデックスの最適化はデータストリーム上で行われるので、
            それほどメモリは消費しません。ただ、CPU
            リソースをかなり消費し、時間もかかります。
        </para>

        <para>
            Lucene のインデックスセグメントは、その性質上
            更新はできません (更新するには、
            セグメントファイルを新たに作りなおす必要があります)。
            したがって、新しいドキュメントがインデックスに追加されるたびに
            新しいセグメントが作成されることになります。
            その結果、インデックスの品質は下がっていきます。
        </para>

        <para>
            セグメントが作成されるたびにインデックスの自動最適化が行われ、
            一部のセグメントは自動的にマージされます。
        </para>

        <para>
            自動最適化の設定は、次の 3 つのオプションで変更できます
            (<link linkend="zend.search.lucene.index-creation.optimization">インデックスの最適化</link>
            を参照ください)。
            <itemizedlist>
                <listitem>
                    <para><emphasis>MaxBufferedDocs</emphasis>
                          は、メモリ内のバッファに保持されるドキュメントの最大数です。
                          この数を超えると、新しいセグメントを作成して
                          ハードディスクに書き込みます。</para>
                </listitem>
                <listitem>
                    <para><emphasis>MaxMergeDocs</emphasis>
                          は、自動最適化によって新しいセグメントへのマージを行う基準となる
                          ドキュメント数です。</para>
                </listitem>
                <listitem>
                    <para><emphasis>MergeFactor</emphasis>
                          は、自動最適化を行う頻度を指定します。</para>
                </listitem>
            </itemizedlist>
            <note>
                <para>
                    これらのオプションはすべて <classname>Zend_Search_Lucene</classname>
                    オブジェクトのプロパティであり、インデックスのプロパティではありません。
                    したがって、この設定は現在使用中の
                    <classname>Zend_Search_Lucene</classname> オブジェクトに対してのみ働くようになり、
                    スクリプトによって設定は異なります。
                </para>
            </note>
        </para>

        <para>
            <emphasis>MaxBufferedDocs</emphasis> は、
            スクリプトを一回実行するたびにひとつのドキュメントしか扱わない場合は
            何の影響も及ぼしません。
            逆に、バッチ処理の場合にはこの設定が非常に重要になります。
            値を大きくするとインデックス作成の速度が上がりますが、
            同時に大量のメモリを消費するようになります。
        </para>

        <para>
            <emphasis>MaxBufferedDocs</emphasis>
            パラメータの値として最適なものを計算する公式はありません。
            これはドキュメントのサイズや解析器、使用できるメモリ量などに依存するからです。
        </para>

        <para>
            最適な設定値を取得するには、
            扱うであろうドキュメントの中で最もサイズが大きいものを用いて
            何度かテストをしてみましょう
            <footnote>
              <para>
                <methodname>memory_get_usage()</methodname>
                や <methodname>memory_get_peak_usage()</methodname>
                で、メモリの使用量を確認します。
              </para>
            </footnote>。
            使用可能なメモリのうち半分を超えない程度のメモリ消費量に抑えておくことをお勧めします。
        </para>

        <para>
            <emphasis>MaxMergeDocs</emphasis> はセグメントの大きさ
            (これはドキュメントの大きさによって決まります) を制限します。
            これにより、自動最適化の時間を短縮できます。
            つまり、<methodname>addDocument()</methodname> メソッドが
            ある時間以上は実行されなくなります。
            これは、対話的なアプリケーションで重要になります。
        </para>

        <para>
            <emphasis>MaxMergeDocs</emphasis> の設定値を小さくすると、
            バッチ処理のパフォーマンスもあがります。
            インデックスの自動最適化は対話的な処理であり、
            ひとつひとつ順を追って実行していきます。
            小さなセグメントたちがひとつの大きなセグメントにまとめられ、
            さらにまたそれが他のセグメントとまとまってより大きなセグメントになり、
            といった具合です。インデックスの最適化を完全に行うと、
            処理が非常に効率的になります。
        </para>

        <para>
            セグメントのサイズを小さくするとインデックスの品質が下がり、
            大量のセグメントができあがってしまいます。場合によっては、OS
            の制限に引っかかって "オープンしているファイルが多すぎる"
            というエラーが発生するかもしれません
            <footnote>
              <para>
                <classname>Zend_Search_Lucene</classname> は、セグメントファイルをずっとオープンしたままにしておきます。
                これによって検索の効率を上げています。
              </para>
            </footnote>。
        </para>

        <para>
            したがって、バックグラウンドでのインデックスの最適化は対話モードで行い、
            バッチ処理用の <emphasis>MaxMergeDocs</emphasis>
            はあまり小さくしすぎないようにしなければなりません。
        </para>

        <para>
            <emphasis>MergeFactor</emphasis> は自動最適化の頻度に影響を及ぼします。
            値を小さくすると、最適化されていないインデックスの品質が上がります。
            値を大きくするとインデックス作成の策度が上がりますが、
            セグメントの数も増えます。何度も言いますが、これは
            "オープンしているファイルが多すぎる" エラーの原因となりえます。
        </para>

        <para>
            <emphasis>MergeFactor</emphasis> は、以下の条件を満たす大きさで
            インデックスセグメントをグループ化します。
            <orderedlist>
                <listitem><para><emphasis>MaxBufferedDocs</emphasis> 以下</para></listitem>
                <listitem><para><emphasis>MaxBufferedDocs</emphasis> より大きいが
                                <emphasis>MaxBufferedDocs</emphasis>*<emphasis>MergeFactor</emphasis> を超えない</para></listitem>
                <listitem><para><emphasis>MaxBufferedDocs</emphasis>*<emphasis>MergeFactor</emphasis> より大きいが
                <emphasis>MaxBufferedDocs</emphasis>*<emphasis>MergeFactor</emphasis>*<emphasis>MergeFactor</emphasis> を超えない</para></listitem>
                <listitem><para>...</para></listitem>
            </orderedlist>
        </para>

        <para>
            Zend_Search_Lucene は、<methodname>addDocument()</methodname>
            をコールするたびにセグメントの状況を調べ、
            いくつかのセグメントをまとめて次のグループの新しいセグメントに移動できるかどうかを確認します。
            できる場合はマージを行います。
        </para>

        <para>
            つまり、N 個のグループからなるインデックスには <emphasis>MaxBufferedDocs</emphasis> + (N-1)*<emphasis>MergeFactor</emphasis>
            のセグメントが含まれ、少なくとも
            <emphasis>MaxBufferedDocs</emphasis>*<emphasis>MergeFactor</emphasis><superscript>(N-1)</superscript>
            のドキュメントが存在することになります。
        </para>

        <para>
            この式で、インデックス内のセグメントの概数を求めることができます。
        </para>
        <para>
            <emphasis>NumberOfSegments</emphasis> &lt;= <emphasis>MaxBufferedDocs</emphasis> + <emphasis>MergeFactor</emphasis>*log
            <subscript><emphasis>MergeFactor</emphasis></subscript> (<emphasis>NumberOfDocuments</emphasis>/<emphasis>MaxBufferedDocs</emphasis>)
        </para>

        <para>
            <emphasis>MaxBufferedDocs</emphasis> は、使用できるメモリ量によって決まります。
            MergeFactor を適切に設定することで、セグメントの数を調整できます。
        </para>

        <para>
            バッチ処理においては、<emphasis>MergeFactor</emphasis>
            パラメータを調整するほうが <emphasis>MaxMergeDocs</emphasis>
            を調整するよりも効率的です。しかし、微調整はできず大雑把なものとなります。
            そこで、まず上の公式をもとに <emphasis>MergeFactor</emphasis> を調整し、
            それから <emphasis>MaxMergeDocs</emphasis> を微調整してパフォーマンスを最適化しましょう。
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.best-practice.shutting-down">
        <title>インデックスの終了時処理</title>

        <para>
            <classname>Zend_Search_Lucene</classname> オブジェクトは、
            終了時にちょっとした作業を行います。
            これは、インデックスにドキュメントが追加されたけれども
            新しいセグメントに書き込まれていないという場合に行われます。
        </para>

        <para>
            また、場合によっては自動最適化も行います。
        </para>

        <para>
            インデックスオブジェクトは、自分自身および QueryHit
            オブジェクトがすべてスコープ外に出た時点で自動的に終了処理を行います。
        </para>

        <para>
            インデックスオブジェクトがグローバル変数に格納されている場合は、
            スクリプトの終了時に破棄されます
            <footnote>
              <para>
                インデックスや QueryHit オブジェクトが複合データ型から参照されている場合にもこれは起こりえます。
                たとえば、循環参照を含むオブジェクトはスクリプトの終了時まで破棄されません。
              </para>
            </footnote>。
        </para>

        <para>
            <acronym>PHP</acronym> の例外処理もここで終了します。
        </para>

        <para>
            これは通常のインデックス終了処理を妨げることはありませんが、
            何かエラーが発生した際に正しいエラー情報を取得できなくなる可能性があります。
        </para>

        <para>
            この問題を回避する方法はふたつあります。
        </para>

        <para>
            まずは、強制的にスコープ外に出す方法です。
        </para>

        <programlisting language="php"><![CDATA[
$index = Zend_Search_Lucene::open($indexPath);

...

unset($index);]]></programlisting>

        <para>
            そしてもうひとつは、スクリプトの終了前にコミット操作を行うことです。
        </para>

        <programlisting language="php"><![CDATA[
$index = Zend_Search_Lucene::open($indexPath);

$index->commit();
]]></programlisting>

        <para>
            これについては、このドキュメントの
            "<link linkend="zend.search.lucene.advanced.static">応用: 静的プロパティとしてのインデックスの使用</link>"
            でも説明しています。
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.best-practice.unique-id">
        <title>一意な ID によるドキュメントの取得</title>

        <para>
            ドキュメントの一意な ID、たとえば URL やパス、データベース上の ID
            などをインデックスに保存しておくとよいでしょう。
        </para>

        <para>
            <classname>Zend_Search_Lucene</classname> には <methodname>termDocs()</methodname>
            というメソッドがあり、指定した単語を含むドキュメントを取得できます。
        </para>

        <para>
            これは <methodname>find()</methodname> メソッドよりも効率的です。
        </para>

        <programlisting language="php"><![CDATA[
// find() メソッドでクエリ文字列を指定してドキュメントを取得
$query = $idFieldName . ':' . $docId;
$hits  = $index->find($query);
foreach ($hits as $hit) {
    $title    = $hit->title;
    $contents = $hit->contents;
    ...
}
...

// find() メソッドでクエリ API を使用してドキュメントを取得
$term = new Zend_Search_Lucene_Index_Term($docId, $idFieldName);
$query = new Zend_Search_Lucene_Search_Query_Term($term);
$hits  = $index->find($query);
foreach ($hits as $hit) {
    $title    = $hit->title;
    $contents = $hit->contents;
    ...
}

...

// termDocs() メソッドでドキュメントを取得
$term = new Zend_Search_Lucene_Index_Term($docId, $idFieldName);
$docIds  = $index->termDocs($term);
foreach ($docIds as $id) {
    $doc = $index->getDocument($id);
    $title    = $doc->title;
    $contents = $doc->contents;
    ...
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.search.lucene.best-practice.memory-usage">
        <title>メモリの使用法</title>

        <para>
            <classname>Zend_Search_Lucene</classname> は、比較的メモリを消費するモジュールです。
        </para>

        <para>
            各種の情報をキャッシュしたり、検索やインデックス作成の速度を上げたりするために、メモリを使用しています。
        </para>

        <para>
            メモリに関する挙動は、モードによって異なります。
        </para>

        <para>
            単語辞書のインデックスは、検索時にメモリに読み込まれます。
            これは、実際の辞書に登録されている単語が 128件
            <footnote><para>
                Lucene のファイルフォーマットでは、この件数を変更することもできます。しかし
                <classname>Zend_Search_Lucene</classname> の <acronym>API</acronym> ではそれをサポートしていません。
                別の Lucene 実装を使用してインデックスをサポートすれば、
                この値を変更することも可能です。
            </para></footnote>
            に達するごとに作成されます。
        </para>

        <para>
            したがって、単語の数が増えれば増えるほどメモリの消費量も増加します。
            トークン化していないフレーズをフィールドの値として使用したり、
            テキスト以外の情報を大量にインデックスとして使用したりすると、
            単語の数が増えることになります。
        </para>

        <para>
            最適化されていないインデックスは、複数のセグメントで構成されます。
            これも、メモリ消費量の増加の要因となります。
            各セグメントは独立しているので、それぞれ独自に単語辞書と辞書インデックスを持っています。
            ひとつのインデックスの中に <emphasis>N</emphasis> 個のセグメントがあったとすると、
            メモリの消費量は最悪で <emphasis>N</emphasis> 倍になってしまいます。
            インデックスの最適化を行ない、セグメントをひとつにまとめましょう。
        </para>

        <para>
            インデックスは、検索処理とドキュメントのバッファリングに同じメモリを使用します。
            このメモリの使用量は、パラメータ <emphasis>MaxBufferedDocs</emphasis>
            で指定します。
        </para>

        <para>
            インデックスの最適化 (完全最適化、部分最適化の両方)
            はストリーム上で行なわれるので、あまりメモリを消費しません。
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.best-practice.encoding">
        <title>エンコーディング</title>

        <para>
            <classname>Zend_Search_Lucene</classname> は、内部で UTF-8 文字列を使用しています。
            したがって、Zend_Search_Lucene が返す文字列は、すべて UTF-8
            でエンコードされています。
        </para>

        <para>
            単なる <acronym>ASCII</acronym> データのみを扱うのであればエンコーディングを気にする必要はありません。
            しかしそれ以外の場合は要注意です。
        </para>

        <para>
            間違ったエンコーディングを使用すると、
            エンコーディングの変換時にエラーが発生したりデータを失ってしまったりする可能性があります。
        </para>

        <para>
            <classname>Zend_Search_Lucene</classname> は、ドキュメントやクエリのエンコーディングとしてさまざまなものに対応しています。
        </para>

        <para>
            フィールドを作成するメソッドで、エンコーディングをオプションのパラメータによって指定できます。
        </para>

        <programlisting language="php"><![CDATA[
$doc = new Zend_Search_Lucene_Document();
$doc->addField(Zend_Search_Lucene_Field::Text('title',
                                              $title,
                                              'iso-8859-1'));
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
                                                  $contents,
                                                  'utf-8'));
]]></programlisting>

        <para>
            エンコーディングの指定をはっきりさせるという意味で、これが最も良い方法です。
        </para>

        <para>
            このエンコーディング指定を省略すると、現在のロケールをもとに判断を行ないます。
            ロケールの指定時に、言語だけでなく文字セットも指定できます。
        </para>

        <programlisting language="php"><![CDATA[
setlocale(LC_ALL, 'fr_FR');
...

setlocale(LC_ALL, 'de_DE.iso-8859-1');
...

setlocale(LC_ALL, 'ja_JP.UTF-8');
...
]]></programlisting>

        <para>
            クエリ文字列のエンコーディングも、同じ方式で指定します。
        </para>

        <para>
            エンコーディングを何らかの方法で指定しなかった場合は、
            現在のロケールにもとづいて判断を行ないます。
        </para>

        <para>
            検索の前にクエリのパースを行なう場合、
            エンコーディングはオプションのパラメータとして指定できます。
        </para>

        <programlisting language="php"><![CDATA[
$query =
    Zend_Search_Lucene_Search_QueryParser::parse($queryStr, 'iso-8859-5');
$hits = $index->find($query);
...
]]></programlisting>

        <para>
            デフォルトのエンコーディングを指定するには <methodname>setDefaultEncoding()</methodname>
            メソッドを使用します。
        </para>

        <programlisting language="php"><![CDATA[
Zend_Search_Lucene_Search_QueryParser::setDefaultEncoding('iso-8859-1');
$hits = $index->find($queryStr);
...
]]></programlisting>

        <para>
            空の文字列は、'現在のロケール' を意味します。
        </para>

        <para>
            正しいエンコーディングを指定すれば、解析器はそれを正しく処理できます。
            実際の挙動は、使用する解析器によって異なります。詳細は
            <link linkend="zend.search.lucene.charset">文字セット</link>
            についての説明を参照ください。
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.best-practice.maintenance">
        <title>インデックスの保守</title>

        <para>
            まずはっきりさせておくべきなのは、<classname>Zend_Search_Lucene</classname> やその他の
            Lucene 実装は決して "データベース" ではないということです。
        </para>

        <para>
            つまり、データを保存するものとして使用してはいけません。
            通常のデータベース管理システムのように、バックアップ/リストア
            やジャーナル処理、ログの記録、トランザクションといった機能は持っていません。
        </para>

        <para>
            しかし、<classname>Zend_Search_Lucene</classname> はインデックスの一貫性を保持するための機能は持っています。
        </para>

        <para>
            インデックスのバックアップ/リストアは、オフラインでインデックスフォルダをコピーすることで行ないます。
        </para>

        <para>
            何らかの理由でインデックスが壊れてしまった場合は、
            インデックスをリストアするか再構築しなければなりません。
        </para>

        <para>
            そこで、大きなインデックスは、どこかに手動でバックアップしておき、
            何かあったときに手動で復元できるようにしておきましょう。
            そうすれば、障害からの復旧にかかる時間が短縮できます。
        </para>

    </sect2>
</sect1>