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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24795 -->
<sect1 id="zend.search.lucene.searching">
    <title>インデックスの検索</title>

    <sect2 id="zend.search.lucene.searching.query_building">
        <title>クエリの作成</title>

        <para>
            インデックスを検索するには二通りの方法があります。
            クエリパーサを使用して文字列からクエリを作成する方法と、
            <classname>Zend_search_Lucene</classname> <acronym>API</acronym> を使用して独自のクエリを作成する方法です。
        </para>

        <para>
        提供されているクエリパーサを使用する前に、以下の点を考慮してください。

            <orderedlist>
                <listitem>
                    <para>
                        プログラムで生成したクエリ文字列をクエリパーサに渡そうとしているなら、
                        クエリ <acronym>API</acronym> を使用してクエリを直接作成すべきです。言い換えると、
                        クエリパーサというのは人間が入力したテキストのために設計されたものであり、
                        プログラムが生成したテキストのためのものではないのです。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        トークン化されていないフィールドについては、
                        クエリパーサを使用するよりも直接クエリに追加するほうが適しています。
                        フィールドの値がアプリケーションによって生成されるのなら、
                        フィールドのクエリ条件についても自動処理で作成すべきです。
                        クエリパーサが使用している解析器は、人間が入力したテキストを
                        単語に分解するために設計されています。
                        日付やキーワードなどのプログラムが生成した値は、
                        クエリ <acronym>API</acronym> で追加しなければなりません。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        検索フォームにおいては、
                        テキストで入力された内容はクエリパーサを使用すべきでしょう。
                        その他のフィールド、例えば範囲指定やキーワードなどについては、
                        クエリ <acronym>API</acronym> に直接渡すようにしましょう。
                        限られた内容、例えばプルダウンメニューで選択するフィールドは、
                        クエリ文字列に追加すべきではありません。
                        その代わりに、TermQuery 条件として使用します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        論理クエリにより、複数のクエリをひとつにまとめることができます。
                        これは、クエリ文字列で定義されるユーザ検索に条件を追加するための最良な方法です。
                    </para>
                </listitem>
            </orderedlist>

        </para>

        <para>
            どちらの方法を使用したとしても、インデックスを検索する <acronym>API</acronym> メソッドは同じです。
        </para>

        <programlisting language="php"><![CDATA[
$index = Zend_Search_Lucene::open('/data/my_index');

$index->find($query);
]]></programlisting>

        <!-- TODO : to be translated -->
        <para>
            You can also search multiple indexes simultaneously using MultiSearcher, which operates
            using the same <acronym>API</acronym> as searching on a single index:
        </para>

        <programlisting language="php"><![CDATA[
$multi = new Zend_Search_Lucene_MultiSearcher();
$multi->addIndex(Zend_Search_Lucene::open('/data/my_index_one');
$multi->addIndex(Zend_Search_Lucene::open('/data/my_index_two');

$multi->find($query);
]]></programlisting>

        <para>
            <methodname>Zend_Search_Lucene::find()</methodname> メソッドは、
            入力の型を自動的に判別し、クエリパーサを使用して文字列から
            <classname>Zend_Search_Lucene_Search_Query</classname> オブジェクトを作成します。
        </para>

        <para>
            重要なのは、クエリパーサは標準の解析器を使用してクエリ文字列をトークン化するということです。
            インデックス化されたテキストに対するすべての変換は、クエリ文字列エントリに対しても行われます。
        </para>
        <para>
            小文字変換を行うことで大文字小文字を区別しない検索を行えるようにしたり、
            ストップワードを取り除いたりといったさまざまなことを行います。
        </para>
        <para>
            それに対して、<acronym>API</acronym> メソッドは単語の変換やフィルタリングを行いません。これは、
            コンピュータが生成したフィールドやトークン化されていないフィールドに適しています。
        </para>

        <sect3 id="zend.search.lucene.searching.query_building.parsing">
            <title>クエリのパース</title>
            <para>
                <methodname>Zend_Search_Lucene_Search_QueryParser::parse()</methodname>
                メソッドを使用してクエリ文字列をパースし、
                クエリオブジェクトに格納します。
            </para>

            <para>
                このオブジェクトをクエリ作成 <acronym>API</acronym> メソッドで使用し、
                ユーザが入力したクエリと機械が生成したクエリを結合します。
            </para>

            <para>
                実際のところ、これが
                トークン化されたいないフィールドを検索する唯一の方法となることもあります。
            </para>

            <programlisting language="php"><![CDATA[
$userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);

$pathTerm  = new Zend_Search_Lucene_Index_Term(
                     '/data/doc_dir/' . $filename, 'path'
                 );
$pathQuery = new Zend_Search_Lucene_Search_Query_Term($pathTerm);

$query = new Zend_Search_Lucene_Search_Query_Boolean();
$query->addSubquery($userQuery, true /* required */);
$query->addSubquery($pathQuery, true /* required */);

$hits = $index->find($query);
]]></programlisting>

            <para>
                <methodname>Zend_Search_Lucene_Search_QueryParser::parse()</methodname>
                メソッドはオプションのパラメータでエンコーディングを受け取ることができます。
                ここで、クエリ文字列のエンコーディングを指定します。
            </para>

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

            <para>
                エンコーディングを省略した場合は、現在のロケールを使用します。
            </para>

            <para>
                デフォルトのクエリ文字列エンコーディングを
                <methodname>Zend_Search_Lucene_Search_QueryParser::setDefaultEncoding()</methodname>
                メソッドで指定することもできます。
            </para>

            <programlisting language="php"><![CDATA[
Zend_Search_Lucene_Search_QueryParser::setDefaultEncoding('iso-8859-5');
...
$userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);
]]></programlisting>

            <para>
                <methodname>Zend_Search_Lucene_Search_QueryParser::getDefaultEncoding()</methodname>
                は、デフォルトのクエリ文字列エンコーディングを返します
                (空文字列は "現在のロケール" を表します)。
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.search.lucene.searching.results">
        <title>検索結果</title>
        <para>
            検索結果は <classname>Zend_Search_Lucene_Search_QueryHit</classname> オブジェクトの配列となります。
            各オブジェクトは、2 つのプロパティを保持しています。
            <code>$hit->id</code> がインデックス内のドキュメント番号、
            <code>$hit->score</code> が検索結果のスコアを表します。
            結果はスコア順に並べられます (スコアの高い結果が最初になります)。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Search_QueryHit</classname> オブジェクトでは、
            検索結果としてヒットした <classname>Zend_Search_Lucene_Document</classname>
            の各フィールドも公開しています。
            この例で、ヒットしたドキュメントには
            title と author の 2 つのフィールドが含まれています。
        </para>
        <programlisting language="php"><![CDATA[
$index = Zend_Search_Lucene::open('/data/my_index');

$hits = $index->find($query);

foreach ($hits as $hit) {
    echo $hit->score;
    echo $hit->title;
    echo $hit->author;
}
]]></programlisting>

        <para>
            保存されたフィールドは、常に UTF-8 エンコーディングで返されます。
        </para>

        <para>
            オプションで、
            <classname>Zend_Search_Lucene_Search_QueryHit</classname> から元の <classname>Zend_Search_Lucene_Document</classname>
            を取得できます。

            保存されたドキュメントを取得するには、
            インデックスオブジェクトの <code>getDocument()</code>
            メソッドを使用し、その <code>getFieldValue()</code>
            メソッドでフィールドの値を取得します。
        </para>
        <programlisting language="php"><![CDATA[
$index = Zend_Search_Lucene::open('/data/my_index');

$hits = $index->find($query);
foreach ($hits as $hit) {
    // ヒットした結果の Zend_Search_Lucene_Document オブジェクトを返します
    echo $document = $hit->getDocument();

    // Zend_Search_Lucene_Document から
    // Zend_Search_Lucene_Field オブジェクトを返します
    echo $document->getField('title');

    // Zend_Search_Lucene_Field オブジェクトを値を文字列で返します
    echo $document->getFieldValue('title');

    // getFieldValue() と同じです
    echo $document->title;
}
]]></programlisting>
        <para>
        <classname>Zend_Search_Lucene_Document</classname> オブジェクトで使用可能なフィールドは、
        インデックス化の際に決まります。ドキュメントのフィールドは、
        インデックス化用アプリケーション (例えば LuceneIndexCreation.jar)
        によってインデックス化、あるいはインデックス化して保存されます。
        </para>

        <para>
        ドキュメントを識別するフィールド (例では 'path')
        もインデックス化して取得できるようにしなければならないことに注意しましょう。
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.searching.results-limiting">
        <title>結果の制限</title>

        <para>
            検索処理の中でいちばん時間がかかるのが、スコアの計算です。
            検索結果の数が多い (数万件程度) 場合、これには数秒程度かかることもあります。
        </para>

        <para>
            <classname>Zend_Search_Lucene</classname> では、結果セットの件数を制限するためのメソッドとして
            <code>getResultSetLimit()</code> と
            <code>setResultSetLimit()</code> を用意しています。
        </para>

        <programlisting language="php"><![CDATA[
$currentResultSetLimit = Zend_Search_Lucene::getResultSetLimit();

Zend_Search_Lucene::setResultSetLimit($newLimit);
]]></programlisting>

        <para>
            0 (デフォルト値) は、'制限しない' という意味です。
        </para>

        <para>
            このメソッドが返す結果は、'スコアの高いほうから N 件' ではなく
            あくまで '最初の N 件'
            <footnote><para>
                しかし、返される結果はスコア順 (あるいはその他指定した順)
                で並べ替えられています。
            </para></footnote>
            です。
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.searching.results-scoring">
        <title>結果の重み付け</title>
        <para>
            <classname>Zend_Search_Lucene</classname> は、Java Lucene と同じ重み付けアルゴリズムを使用します。
            検索結果に一致したものが、デフォルトで重み順に並べ替えられます。スコアの高いものが先頭となり、
            スコアの高いもののほうが低いものよりクエリにマッチするようになります。
        </para>

        <para>
            大雑把に言うと、文書の中に検索語句が頻繁に登場するほどスコアが高くなります。
        </para>

        <para>
            検索結果のスコアを取得するには <code>score</code> プロパティを使用します。
        </para>
        <programlisting language="php"><![CDATA[
$hits = $index->find($query);

foreach ($hits as $hit) {
    echo $hit->id;
    echo $hit->score;
}
]]></programlisting>

        <para>
            重みを計算するために使用されるのが
            <classname>Zend_Search_Lucene_Search_Similarity</classname> クラスです。詳細は
            <link linkend="zend.search.lucene.extending.scoring">拡張性
            - 重み付けのアルゴリズム</link> を参照ください。
        </para>

    </sect2>

    <sect2 id="zend.search.lucene.searching.sorting">
        <title>検索結果の並べ替え</title>
        <para>
            検索結果は、デフォルトではスコアで並べ替えられます。
            これを変更するには、並べ替え用の (ひとつあるいは複数の)
            フィールドと並べ替えの形式、そして並べ替えの方向をパラメータで指定します。
        </para>

        <para>
            <code>$index->find()</code> のコール時に、オプションのパラメータを指定できます。
        </para>

        <programlisting language="php"><![CDATA[
$index->find($query [, $sortField [, $sortType [, $sortOrder]]]
                    [, $sortField2 [, $sortType [, $sortOrder]]]
             ...);
]]></programlisting>

        <para>
            <code>$sortField</code> は、結果の並べ替えを行う保存されたフィールドの名前です。
        </para>

        <para>
            <code>$sortType</code> は省略可能です。
            <code>SORT_REGULAR</code> (通常の並べ替え。デフォルト)、
            <code>SORT_NUMERIC</code> (数値として並べ替え)、
            <code>SORT_STRING</code> (文字列として並べ替え) のいずれかとなります。
        </para>

        <para>
            <code>$sortOrder</code> は省略可能です。
            <code>SORT_ASC</code> (昇順で並べ替え。デフォルト)、
            <code>SORT_DESC</code> (降順で並べ替え) のいずれかとなります。
        </para>

        <para>
            例を以下に示します。
        </para>

        <programlisting language="php"><![CDATA[
$index->find($query, 'quantity', SORT_NUMERIC, SORT_DESC);
]]></programlisting>

        <programlisting language="php"><![CDATA[
$index->find($query, 'fname', SORT_STRING, 'lname', SORT_STRING);
]]></programlisting>

        <programlisting language="php"><![CDATA[
$index->find($query, 'name', SORT_STRING, 'quantity', SORT_NUMERIC, SORT_DESC);
]]></programlisting>

        <para>
            デフォルト以外の並び順を使用する際には注意しましょう。
            並べ替えのためにはドキュメント全体をインデックスから読み込む必要があり、
            検索のパフォーマンスが著しく低下してしまいます。
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.searching.highlighting">
        <title>検索結果の強調</title>
        <para>
            <classname>Zend_Search_Lucene</classname> では、2 とおりの方法で検索結果を強調させることができます。
        </para>
        <para>
            まず最初の方法が、<classname>Zend_Search_Lucene_Document_Html</classname> クラス
            (詳細は <link linkend="zend.search.lucene.index-creation.html-documents">HTML ドキュメントの節</link>
            を参照ください) を用いて次のようにすることです。
        </para>

        <programlisting language="php"><![CDATA[
/**
 * テキストを指定した色で強調する
 *
 * @param string|array $words
 * @param string $colour
 * @return string
 */
public function highlight($words, $colour = '#66ffff');
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * テキストを、指定したビューヘルパーあるいはコールバック関数で強調する
 *
 * @param string|array $words  強調したい単語。配列あるいは文字列で指定します
 * @param callback $callback   コールバックメソッド。テキストの変換 (強調) に使用します
 * @param array    $params     コールバックのパラメータとして渡す配列
 *                             (最初の必須パラメータは、強調させる HTML 片となります)
 * @return string
 * @throws Zend_Search_Lucene_Exception
 */
public function highlightExtended($words, $callback, $params = array())
]]></programlisting>

        <para>
            強調方法をカスタマイズするには <code>highlightExtended()</code>
            メソッドにコールバックを指定して使用します。このコールバックは、ひとつ以上のパラメータを受け取ります
            <footnote><para>最初のパラメータは強調対象の <acronym>HTML</acronym> 片、
            そしてその他のパラメータはコールバックの振る舞いによって変わります。
            返り値は、強調済みの <acronym>HTML</acronym> 片となります。</para></footnote>。
            あるいは、<classname>Zend_Search_Lucene_Document_Html</classname> クラスを継承して
            <code>applyColour($stringToHighlight, $colour)</code> メソッドを再定義することもできます。
            このメソッドは、デフォルトの強調コールバックとして用いられるものです。
            <footnote>
                <para>
                    どちらの場合についても、返される <acronym>HTML</acronym> は自動的に正しい <acronym>XHTML</acronym> 形式に変換されます。
                </para>
            </footnote>
        </para>
        <para>
            <link linkend="zend.view.helpers">ビューヘルパー</link> も、ビュースクリプトのコンテキストでコールバックとして使えます。
        </para>

        <programlisting language="php"><![CDATA[
$doc->highlightExtended('word1 word2 word3...', array($this, 'myViewHelper'));
]]></programlisting>

        <para>
            強調した結果を取得するには <code>Zend_Search_Lucene_Document_Html->getHTML()</code> メソッドを使用します。
        </para>

        <note>
            <para>
                強調処理は、現在の解析器を使って行われます。つまり、解析器が理解するすべての形式の単語が強調されます。
            </para>
            <para>
                たとえば、大文字小文字を区別しない解析器を使っている場合に 'text' を強調するよう指定すると、
                'text' や 'Text' そして 'TEXT' といった単語も強調されます。
            </para>
            <para>
                同様に、語幹抽出機能を持つ解析器を使っている場合に 'indexed' を強調するよう指定すると、
                'index' や 'indexing' そして 'indices' といった単語も強調されます。
            </para>
            <para>
                一方、現在の解析器が処理をスキップするような単語
                (短い単語に対するフィルタが解析器に適用されている場合など)
                は、なにも強調されません。
            </para>
        </note>

        <para>
            もうひとつの方法は、
            <code>Zend_Search_Lucene_Search_Query->highlightMatches(string $inputHTML[, Zend_Search_Lucene_Search_Highlighter_Interface $highlighter])</code>
            メソッドを使うことです。
        </para>

        <programlisting language="php"><![CDATA[
$query = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);
$highlightedHTML = $query->highlightMatches($sourceHTML);
]]></programlisting>

        <para>
            オプションの 2 番目のパラメータは、
            デフォルトの <acronym>HTML</acronym> ドキュメントエンコーディングです。
            省略した場合は、Content-type HTTP-EQUIV meta タグを使用します。
        </para>
        <para>
            オプションの 3 番目のパラメータは、
            <classname>Zend_Search_Lucene_Search_Highlighter_Interface</classname>
            インターフェイスを実装したオブジェクトです。
        </para>

        <programlisting language="php"><![CDATA[
interface Zend_Search_Lucene_Search_Highlighter_Interface
{
    /**
     * 強調対象の文書を設定します
     *
     * @param Zend_Search_Lucene_Document_Html $document
     */
    public function setDocument(Zend_Search_Lucene_Document_Html $document);

    /**
     * 強調対象の文書を取得します
     *
     * @return Zend_Search_Lucene_Document_Html $document
     */
    public function getDocument();

    /**
     * 指定した単語を強調します (サブクエリ単位でこのメソッドが起動されます)
     *
     * @param string|array $words  強調したい単語。配列あるいは文字列で指定します
     */
    public function highlight($words);
}
]]></programlisting>

        <para>
            ここでの <classname>Zend_Search_Lucene_Document_Html</classname> オブジェクトは、
            <classname>Zend_Search_Lucene_Search_Query->highlightMatches()</classname> メソッドに渡された
            <acronym>HTML</acronym> から作成されるオブジェクトです。
        </para>
        <para>
            <code>$highlighter</code> パラメータを省略すると、
            <classname>Zend_Search_Lucene_Search_Highlighter_Default</classname>
            オブジェクトのインスタンスを作成してそれを使用します。
        </para>
        <para>
            <code>highlight()</code> メソッドはサブクエリ単位で起動されるので、
            サブクエリ単位で異なる強調処理を行うことができます。
        </para>
        <para>
            実際のところ、デフォルトの処理は定義済みの色テーブルを使用しているだけです。
            自前の強調処理を実装することもできますし、デフォルトの処理を継承して色テーブルだけを再定義することもできます。
        </para>
        <para>
            <code>Zend_Search_Lucene_Search_Query->htmlFragmentHighlightMatches()</code>
            も同じような動きをします。唯一の違いは、入力を受け取って、
            &lt;>HTML>, &lt;HEAD>, &lt;BODY> tags タグを含まない <acronym>HTML</acronym> 片を返すことです。
            それでも、返される <acronym>HTML</acronym> 片は自動的に正しい <acronym>XHTML</acronym> に変換されます.
        </para>
    </sect2>
</sect1>