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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.search.lucene.overview">
    <title>概要</title>

    <sect2 id="zend.search.lucene.introduction">
        <title>導入</title>
        <para><classname>Zend_Search_Lucene</classname> は、完全に PHP 5
            で書かれている汎用的なテキスト検索エンジンです。
            インデックスをファイルシステム上に保存するためデータベースサーバを必要とせず、
            たいていの PHP ウェブサイト上で動作させることができます。
            <classname>Zend_Search_Lucene</classname> は、以下の機能をサポートしています。
            <itemizedlist>
                <listitem>
                    <para>重要度による検索 - 最もマッチした結果が最初に返されます</para>
                </listitem>
                <listitem>
                    <para>
                       さまざまな強力な検索方式: フレーズ検索、boolean 検索、ワイルドカード検索、
                       あいまい検索、範囲指定検索などなど
                    </para>
                </listitem>
                <listitem>
                    <para>指定したフィールド (例: タイトル、作者、内容) による検索</para>
                </listitem>
            </itemizedlist>

            <classname>Zend_Search_Lucene</classname> は Apache Lucene プロジェクトから派生したものです。
            現在 (ZF 1.6 以降) サポートしている Lucene インデックスフォーマットバージョンは
            1.4 - 2.3 です。
            Lucene についての詳細は
            <ulink url="http://lucene.apache.org/java/docs/"/>
            を参照ください。
        </para>
        <note>
            <title/>
            <para>
                以前の <classname>Zend_Search_Lucene</classname> の実装は Lucene 1.4 (1.9) - 2.1 インデックスフォーマットに対応しています。
            </para>
            <para>
                ZF 1.5 以降、2.1 より前のインデックスフォーマットで作成されたインデックスは
                <classname>Zend_Search_Lucene</classname> をアップグレードすると
                自動的に Lucene 2.1 フォーマットにアップグレードされるようになっています。
                いったんアップグレードされたインデックスは、
                ZF 1.0.x に含まれる Zend_Search_Lucene の実装で読み込むことができません。
            </para>
        </note>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.documents-and-fields">
        <title>Document および Field オブジェクト</title>
            <para>
                <classname>Zend_Search_Lucene</classname> は、ドキュメント単位でインデックスを作成します。
                ドキュメントは名前つきのフィールドから構成され、
                検索対象のコンテンツがフィールドの中に含まれます。
            </para>

            <para>
                ドキュメントを表すのが <classname>Zend_Search_Lucene_Document</classname>
                オブジェクトです。このオブジェクトの中には、フィールドを表す
                <classname>Zend_Search_Lucene_Field</classname> オブジェクトが含まれます。
            </para>

            <para>
                あらゆる種類の情報がインデックス化される可能性があることに注意しましょう。
                アプリケーション固有の情報やメタデータをドキュメントのフィールドに格納し、
                検索結果のドキュメントとして後で取得することができます。
            </para>

            <para>
                インデクサを制御するのは、あなたが作成するアプリケーションの役割です。
                ということは、あなたのアプリケーションからアクセス可能な、
                あらゆる内容のデータがインデックス化される可能性があるということです。
                例えばファイルシステム、データベース、HTML フォームなどが考えられます。
            </para>

            <para>
                <classname>Zend_Search_Lucene_Field</classname> クラスには、
                さまざまな性質のフィールドを作成するための静的メソッドが定義されています。
            </para>

            <programlisting role="php"><![CDATA[
$doc = new Zend_Search_Lucene_Document();

// フィールドはトークン化されませんが、インデックス化されて保存されます。
// 保存されたフィールドは、インデックスから取得することができます。
$doc->addField(Zend_Search_Lucene_Field::Keyword('doctype',
                                                 'autogenerated'));

// フィールドはトークン化もインデックス化も行われませんが、インデックスに保存されます。
$doc->addField(Zend_Search_Lucene_Field::UnIndexed('created',
                                                   time()));

// バイナリ文字列フィールドはトークン化もインデックス化も行われません。
// しかしインデックスには保存されます。
$doc->addField(Zend_Search_Lucene_Field::Binary('icon',
                                                $iconData));

// フィールドがトークン化・インデックス化されてインデックスに保存されます。
$doc->addField(Zend_Search_Lucene_Field::Text('annotation',
                                              'Document annotation text'));

// フィールドはトークン化されてインデックス化されますが、インデックスには保存されません。
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
                                                  'My document content'));
]]>
            </programlisting>

            <para>
                これらの各メソッド (<classname>Zend_Search_Lucene_Field::Binary()</classname>
                メソッドを除く) は、オプションのパラメータ
                <code>$encoding</code> を持っています。
                これで入力データのエンコーディングを指定します。
            </para>

            <para>
                エンコーディングはドキュメントによって異なるでしょうし、
                同一ドキュメント内でもフィールドによって異なることもあるでしょう。

                <programlisting role="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>
                エンコーディングパラメータを省略した場合は、
                現在のロケールが処理時に使用されます。たとえば次のようになります。
                <programlisting role="php"><![CDATA[
setlocale(LC_ALL, 'de_DE.iso-8859-1');
...
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $contents));
]]>
                </programlisting>
            </para>

            <para>
                フィールドをインデックス化したり返したりする際には、
                常に UTF-8 エンコーディングとなります。UTF-8 への変換は自動的に行われます。
            </para>

            <para>
                テキスト解析器 (<link linkend="zend.search.lucene.extending.analysis">以下を参照ください</link>)
                は、テキストをその他のエンコーディングに変換したりもします。
                実際、デフォルトの解析器はテキストを 'ASCII//TRANSLIT' エンコーディングに変換します。
                ここで注意が必要なのは、このような変換は現在のロケールに依存して行われるということです。
            </para>

            <para>
                フィールドの名前は <code>addField()</code> メソッドで自由につけることができます。
            </para>

            <para>
                Java Lucene は、検索の際にデフォルトで使用されるフィールド名として "contents" を使用します。
                <classname>Zend_Search_Lucene</classname> は、デフォルトではすべてのフィールドを検索します。
                しかし、この挙動を変更することもできます。詳細は
                <link linkend="zend.search.lucene.query-language.fields">"デフォルトの検索フィールド"</link>
                の章を参照ください。
            </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.understanding-field-types">
        <title>フィールド型について理解する</title>
        <itemizedlist>
            <listitem>
                <para>
                    <code>Keyword</code> フィールドは、保存されインデックス化されます。
                    つまり、検索した際に元の内容がそのまま返されるということです。
                    トークン化は行われません (いくつかの単語に分割されることはありません)。
                    列挙方のデータベースフィールドは、通常は <classname>Zend_Search_Lucene</classname> の
                    Keyword フィールドにうまく収まることでしょう。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>UnIndexed</code> フィールドは検索対象になりませんが、
                    検索結果としては返されます。このフィールドに設定する値としては、
                    データベースのタイムスタンプ、主キー、ファイルシステムのパス
                    およびその他の外部識別子などがあります。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>Binary</code> フィールドは、トークン化もインデックス化も行われません。
                    しかし、検索結果として取得できるように保存されます。
                    画像アイコンのようなバイナリデータをバイナリ文字列として
                    エンコードしたものなどに対して使用します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>Text</code> フィールドは、保存されインデックス化され、
                    そしてトークン化されます。検索項目として使用し、
                    かつ検索結果としても取得したいような項目、
                    例えばタイトルなどを保存するのに適しています。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>UnStored</code> フィールドはトークン化されインデックス化されます。
                    しかしインデックスには保存されません。大量のテキストなどに適しています。
                    データを保存してしまうとディスク上のインデックスのサイズが大きくなってしまうので、
                    検索はしたいが結果としてそれを表示する必要がない場合などは、
                    このフィールドを使用しましょう。<classname>Zend_Search_Lucene</classname> インデックスを
                    リレーショナルデータベースと組み合わせて使用する場合などには
                    UnStored フィールドが実用的に使用できるでしょう。
                    大きなデータフィールドの内容の検索用に UnStored フィールドに保存し、
                    結果をデータベースから取得するために、もうひとつ別の ID フィールドを使用します。
               </para>

                <table id="zend.search.lucene.index-creation.understanding-field-types.table">
                    <title>Zend_Search_Lucene_Field の型</title>
                    <tgroup cols="5">
                        <thead>
                            <row>
                                <entry>フィールド型</entry>
                                <entry>保存</entry>
                                <entry>インデックス化</entry>
                                <entry>トークン化</entry>
                                <entry>バイナリ</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>Keyword</entry>
                                <entry>Yes</entry>
                                <entry>Yes</entry>
                                <entry>No</entry>
                                <entry>No</entry>
                            </row>
                            <row>
                                <entry>UnIndexed</entry>
                                <entry>Yes</entry>
                                <entry>No</entry>
                                <entry>No</entry>
                                <entry>No</entry>
                            </row>
                            <row>
                                <entry>Binary</entry>
                                <entry>Yes</entry>
                                <entry>No</entry>
                                <entry>No</entry>
                                <entry>Yes</entry>
                            </row>
                            <row>
                                <entry>Text</entry>
                                <entry>Yes</entry>
                                <entry>Yes</entry>
                                <entry>Yes</entry>
                                <entry>No</entry>
                            </row>
                            <row>
                                <entry>UnStored</entry>
                                <entry>No</entry>
                                <entry>Yes</entry>
                                <entry>Yes</entry>
                                <entry>No</entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
           </listitem>
       </itemizedlist>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.html-documents">
        <title>HTML ドキュメント</title>
        <para>
            <classname>Zend_Search_Lucene</classname> には HTML をパースする機能もあります。
            次のようにして、HTML ファイルや文字列からドキュメントを直接作成することができます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Html::loadHTMLFile($filename);
$index->addDocument($doc);
...
$doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
$index->addDocument($doc);
]]>
            </programlisting>
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Html</classname> クラスは、
            <code>DOMDocument::loadHTML()</code> および
            <code>DOMDocument::loadHTMLFile()</code> メソッドを用いてソース HTML
            をパースしています。つまり、対象となる HTML は整形式である必要はなく、
            また XHTML である必要もありません。一方、ヘッダの "meta http-equiv"
            タグで、エンコーディングをきちんと設定しておく必要があります。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Html</classname> クラスは、
            ドキュメントのタイトル、本文そしてヘッダの meta タグの内容を認識します。
        </para>

        <para>
            'title' フィールドには /html/head/title の値が入ります。
            これはインデックスないにトークン化して保存され、検索の対象となります。
        </para>

        <para>
            'body' フィールドには body の中身が入ります。
            スクリプトやコメント、そしてタグの属性は含まれません。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Html</classname> クラスの
            <code>loadHTML()</code> および <code>loadHTMLFile()</code> メソッドには、
            オプションの二番目の引数もあります。これを true に設定すると、
            body の中身もインデックスに格納され、インデックスから取得できるようになります。
            body はトークン化とインデックス化だけが行われ、デフォルトでは保存されません。
        </para>
<!--    <para>
            <code>loadHTML()</code> メソッドおよび <code>loadHTMLFile()</code>
            メソッドの三番目のパラメータはオプションで、元の HTML ドキュメントのエンコーディングを指定します。
            省略した場合は、meta タグの contents type charset から自動的に取得します。
        </para>
        <para>
            あとからエンコーディングを取得したり上書きしたりするには
            <code>getEncoding()</code>/<code>setEncoding($encoding)</code> メソッドを使用します。
        </para>
-->

        <para>
            ドキュメントヘッダの meta タグの内容をもとに、追加のフィールドを作成します。
            フィールドの名前は 'name' 属性から取得します。そして
            'content' 属性の内容がその値となります。これはトークン化、インデックス化した上で
            保存されます。つまり、ドキュメントは meta タグの内容をもとにして
            (たとえばキーワードによって) 検索できるようになるわけです。
        </para>

        <para>
            パースされたドキュメントに、ユーザが別のフィールドを拡張することができます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
$doc->addField(Zend_Search_Lucene_Field::UnIndexed('created',
                                                   time()));
$doc->addField(Zend_Search_Lucene_Field::UnIndexed('updated',
                                                   time()));
$doc->addField(Zend_Search_Lucene_Field::Text('annotation',
                                              'Document annotation text'));
$index->addDocument($doc);
]]>
            </programlisting>
        </para>

        <para>
            作成されたドキュメントにはリンクは含まれません。しかし、
            <classname>Zend_Search_Lucene_Document_Html::getLinks()</classname> および
            <classname>Zend_Search_Lucene_Document_Html::getHeaderLinks()</classname>
            メソッドでリンクを取得することもできます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
$linksArray = $doc->getLinks();
$headerLinksArray = $doc->getHeaderLinks();
]]>
            </programlisting>
        </para>

        <para>
            ZF 1.6 以降では、<code>rel</code> 属性が
            <code>'nofollow'</code> に設定されているリンクを除外できるようになりました。
            このオプションを有効にするには
            <classname>Zend_Search_Lucene_Document_Html::setExcludeNoFollowLinks($true)</classname>
            を使用します。
        </para>
        <para>
            <classname>Zend_Search_Lucene_Document_Html::getExcludeNoFollowLinks()</classname>
            メソッドは、この "nofollow リンクを除外する"
            フラグの現在の状態を返します。
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.docx-documents">
        <title>Word 2007 ドキュメント</title>
        <para>
            <classname>Zend_Search_Lucene</classname> には Word 2007 のパース機能があります。Word 2007 ファイルから直接ドキュメントを作成することができます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Docx::loadDocxFile($filename);
$index->addDocument($doc);
]]>
            </programlisting>
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Docx</classname> クラスは、<code>ZipArchive</code> クラスと
            <code>simplexml</code> のメソッドでドキュメントをパースします。<code>ZipArchive</code> クラス (php_zip モジュール)
            が使用できない場合は、<classname>Zend_Search_Lucene_Document_Docx</classname> を Zend Framework で使用することはできません。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Docx</classname> クラスは、ドキュメントのメタデータとテキストを扱います。メタデータに含まれる内容は、ドキュメントの内容によって filename, title, subject, creator, keywords, description, lastModifiedBy, revision, modified, created などがあります。
        </para>

        <para>
            'filename' フィールドは、実際の Word 2007 ファイルのファイル名です。
        </para>

        <para>
            'title' フィールドは、実際のドキュメントのタイトルです。
        </para>

        <para>
            'subject' フィールドは、実際のドキュメントの表題です。
        </para>

        <para>
            'creator' フィールドは、実際のドキュメントの作成者です。
        </para>

        <para>
            'keywords' フィールドは、実際のドキュメントのキーワードです。
        </para>

        <para>
            'description' フィールドは、実際のドキュメントの説明です。
        </para>

        <para>
            'lastModifiedBy' フィールドは、実際のドキュメントを最後に編集したユーザ名です。
        </para>

        <para>
            'revision' フィールドは、実際のドキュメントのリビジョン番号です。
        </para>

        <para>
            'modified' フィールドは、実際のドキュメントの最終更新日時です。
        </para>

        <para>
            'created' フィールドは、実際のドキュメントの作成日時です。
        </para>

        <para>
            'body' フィールドは、Word 2007 ドキュメントの実際の本文です。ここに含まれるのは通常のテキストのみで、コメントやリビジョンは含まれません。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Docx</classname> クラスの <code>loadDocxFile()</code>
            メソッドにもオプションの 2 番目の引数があります。これを true に設定すると、
            本文もインデックスに格納されてインデックスから取得できるようになります。
            デフォルトでは、本文のトークン化とインデックスの作成は行いますがインデックスには格納されません。
        </para>

        <para>
            パースしたドキュメントに、プログラマが任意のフィールドを追加することができます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Docx::loadDocxFile($filename);
$doc->addField(Zend_Search_Lucene_Field::UnIndexed(
    'indexTime',
    time())
);
$doc->addField(Zend_Search_Lucene_Field::Text(
    'annotation',
    'Document annotation text')
);
$index->addDocument($doc);
]]>
            </programlisting>
        </para>

    </sect2>

    <sect2 id="zend.search.lucene.index-creation.pptx-documents">
        <title>Powerpoint 2007 ドキュメント</title>
        <para>
            <classname>Zend_Search_Lucene</classname> には Powerpoint 2007 のパース機能があります。Powerpoint 2007 ファイルから直接ドキュメントを作成することができます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Pptx::loadPptxFile($filename);
$index->addDocument($doc);
]]>
            </programlisting>
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Pptx</classname> クラスは、<code>ZipArchive</code> クラスと
            <code>simplexml</code> のメソッドでドキュメントをパースします。<code>ZipArchive</code> クラス (php_zip モジュール)
            が使用できない場合は、<classname>Zend_Search_Lucene_Document_Pptx</classname> を Zend Framework で使用することはできません。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Pptx</classname> クラスは、ドキュメントのメタデータとテキストを扱います。メタデータに含まれる内容は、ドキュメントの内容によって filename, title, subject, creator, keywords, description, lastModifiedBy, revision, modified, created などがあります。
        </para>

        <para>
            'filename' フィールドは、実際の Powerpoint 2007 ファイルのファイル名です。
        </para>

        <para>
            'title' フィールドは、実際のドキュメントのタイトルです。
        </para>

        <para>
            'subject' フィールドは、実際のドキュメントの表題です。
        </para>

        <para>
            'creator' フィールドは、実際のドキュメントの作成者です。
        </para>

        <para>
            'keywords' フィールドは、実際のドキュメントのキーワードです。
        </para>

        <para>
            'description' フィールドは、実際のドキュメントの説明です。
        </para>

        <para>
            'lastModifiedBy' フィールドは、実際のドキュメントを最後に編集したユーザ名です。
        </para>

        <para>
            'revision' フィールドは、実際のドキュメントのリビジョン番号です。
        </para>

        <para>
            'modified' フィールドは、実際のドキュメントの最終更新日時です。
        </para>

        <para>
            'created' フィールドは、実際のドキュメントの作成日時です。
        </para>

        <para>
            'body' フィールドは、Powerpoint 2007 ドキュメントのすべてのスライドとノートの実際の本文です。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Pptx</classname> クラスの <code>loadPptxFile()</code>
            メソッドにもオプションの 2 番目の引数があります。これを true に設定すると、
            本文もインデックスに格納されてインデックスから取得できるようになります。
            デフォルトでは、本文のトークン化とインデックスの作成は行いますがインデックスには格納されません。
        </para>

        <para>
            パースしたドキュメントに、プログラマが任意のフィールドを追加することができます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Pptx::loadPptxFile($filename);
$doc->addField(Zend_Search_Lucene_Field::UnIndexed(
    'indexTime',
    time()));
$doc->addField(Zend_Search_Lucene_Field::Text(
    'annotation',
    'Document annotation text'));
$index->addDocument($doc);
]]>
            </programlisting>
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.xlsx-documents">
        <title>Excel 2007 ドキュメント</title>
        <para>
            <classname>Zend_Search_Lucene</classname> には Excel 2007 のパース機能があります。Excel 2007 ファイルから直接ドキュメントを作成することができます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Xlsx::loadXlsxFile($filename);
$index->addDocument($doc);
]]>
            </programlisting>
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Xlsx</classname> クラスは、<code>ZipArchive</code> クラスと
            <code>simplexml</code> のメソッドでドキュメントをパースします。<code>ZipArchive</code> クラス (php_zip モジュール)
            が使用できない場合は、<classname>Zend_Search_Lucene_Document_Xlsx</classname> を Zend Framework で使用することはできません。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Xlsx</classname> クラスは、ドキュメントのメタデータとテキストを扱います。メタデータに含まれる内容は、ドキュメントの内容によって filename, title, subject, creator, keywords, description, lastModifiedBy, revision, modified, created などがあります。
        </para>

        <para>
            'filename' フィールドは、実際の Excel 2007 ファイルのファイル名です。
        </para>

        <para>
            'title' フィールドは、実際のドキュメントのタイトルです。
        </para>

        <para>
            'subject' フィールドは、実際のドキュメントの表題です。
        </para>

        <para>
            'creator' フィールドは、実際のドキュメントの作成者です。
        </para>

        <para>
            'keywords' フィールドは、実際のドキュメントのキーワードです。
        </para>

        <para>
            'description' フィールドは、実際のドキュメントの説明です。
        </para>

        <para>
            'lastModifiedBy' フィールドは、実際のドキュメントを最後に編集したユーザ名です。
        </para>

        <para>
            'revision' フィールドは、実際のドキュメントのリビジョン番号です。
        </para>

        <para>
            'modified' フィールドは、実際のドキュメントの最終更新日時です。
        </para>

        <para>
            'created' フィールドは、実際のドキュメントの作成日時です。
        </para>

        <para>
            'body' フィールドは、Excel 2007 ドキュメントのすべてのワークシートのすべてのセルの実際の内容です。
        </para>

        <para>
            <classname>Zend_Search_Lucene_Document_Xlsx</classname> クラスの <code>loadXlsxFile()</code>
            メソッドにもオプションの 2 番目の引数があります。これを true に設定すると、
            本文もインデックスに格納されてインデックスから取得できるようになります。
            デフォルトでは、本文のトークン化とインデックスの作成は行いますがインデックスには格納されません。
        </para>

        <para>
            パースしたドキュメントに、プログラマが任意のフィールドを追加することができます。
            <programlisting role="php"><![CDATA[
$doc = Zend_Search_Lucene_Document_Xlsx::loadXlsxFile($filename);
$doc->addField(Zend_Search_Lucene_Field::UnIndexed(
    'indexTime',
    time()));
$doc->addField(Zend_Search_Lucene_Field::Text(
    'annotation',
    'Document annotation text'));
$index->addDocument($doc);
]]>
            </programlisting>
        </para>
    </sect2>
</sect1>