documentation/manual/ja/module_specs/Zend_Search_Lucene-IndexCreation.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20854 -->
   4 <sect1 id="zend.search.lucene.index-creation">
   5     <title>インデックスの構築</title>
   6
   7     <sect2 id="zend.search.lucene.index-creation.creating">
   8         <title>新しいインデックスの作成</title>
   9
  10         <para>
  11             インデックスの作成機能および更新機能は、
  12             <classname>Zend_Search_Lucene</classname> モジュールと Java Lucene で実装されています。
  13             これらのいずれかの機能を使用して作成したインデックスについて、
  14             <classname>Zend_Search_Lucene</classname> により検索できます。
  15         </para>
  16
  17         <para>
  18             以下の PHP コードでは、<classname>Zend_Search_Lucene</classname> のインデックス作成
  19             API を用いてファイルをインデックス化する例を示します。
  20         </para>
  21
  22         <programlisting language="php"><![CDATA[
  23 // インデックスを作成します
  24 $index = Zend_Search_Lucene::create('/data/my-index');
  25
  26 $doc = new Zend_Search_Lucene_Document();
  27
  28 // ドキュメントの URL を、検索結果の ID として保存します。
  29 $doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
  30
  31 // ドキュメントの内容をインデックス化します。
  32 $doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $docContent));
  33
  34 // ドキュメントをインデックスに追加します。
  35 $index->addDocument($doc);
  36 ]]></programlisting>
  37
  38         <para>
  39             新しく追加されたドキュメントは、
  40             すぐにインデックスから取得できるようになります。
  41         </para>
  42     </sect2>
  43
  44     <sect2 id="zend.search.lucene.index-creation.updating">
  45         <title>インデックスの更新</title>
  46
  47         <para>
  48             既存のインデックスを更新する際にも同じ手順を使用します。ただひとつの違いは、
  49             create() メソッドではなく open() メソッドをコールするということです。
  50         </para>
  51
  52         <programlisting language="php"><![CDATA[
  53 // 既存のインデックスをオープンします。
  54 $index = Zend_Search_Lucene::open('/data/my-index');
  55
  56 $doc = new Zend_Search_Lucene_Document();
  57 // ドキュメントの URL を、検索結果の ID として保存します。
  58 $doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
  59 // ドキュメントの内容をインデックス化します。
  60 $doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
  61                                                   $docContent));
  62
  63 // ドキュメントをインデックスに追加します。
  64 $index->addDocument($doc);
  65 ]]></programlisting>
  66     </sect2>
  67
  68     <sect2 id="zend.search.lucene.index-creation.document-updating">
  69         <title>ドキュメントの更新</title>
  70
  71         <para>
  72             Lucene インデックスファイルは、ドキュメントの更新をサポートしていません。
  73             更新するためには、いったん削除した上で改めて追加する必要があります。
  74         </para>
  75
  76         <para>
  77             そのためには、インデックス内部のドキュメント ID を使用して
  78             <methodname>Zend_Search_Lucene::delete()</methodname> メソッドをコールします。
  79             この ID は、クエリでヒットした内容から 'id' プロパティで取得できます。
  80         </para>
  81
  82         <programlisting language="php"><![CDATA[
  83 $removePath = ...;
  84 $hits = $index->find('path:' . $removePath);
  85 foreach ($hits as $hit) {
  86     $index->delete($hit->id);
  87 }
  88 ]]></programlisting>
  89     </sect2>
  90
  91     <sect2 id="zend.search.lucene.index-creation.counting">
  92         <title>インデックスの大きさの取得</title>
  93
  94         <para>
  95             <classname>Zend_Search_Lucene</classname> のインデックスの大きさを知るには、二通りの方法があります。
  96         </para>
  97
  98         <para>
  99              <methodname>Zend_Search_Lucene::maxDoc()</methodname> は、
 100              最大のドキュメント番号にひとつ足した値を返します。
 101              これは、削除されたドキュメントを含む、インデックス内のドキュメントの総数を表します。
 102              そこで、このメソッドのシノニムとして <methodname>Zend_Search_Lucene::count()</methodname>
 103              を用意しました。
 104         </para>
 105
 106         <para>
 107              <methodname>Zend_Search_Lucene::numDocs()</methodname> は、削除されていないドキュメントの総数を返します。
 108         </para>
 109
 110         <programlisting language="php"><![CDATA[
 111 $indexSize = $index->count();
 112 $documents = $index->numDocs();
 113 ]]></programlisting>
 114
 115         <para>
 116             <methodname>Zend_Search_Lucene::isDeleted($id)</methodname>
 117             メソッドで、そのドキュメントが削除されているかどうかを調べます。
 118         </para>
 119
 120         <programlisting language="php"><![CDATA[
 121 for ($count = 0; $count < $index->maxDoc(); $count++) {
 122     if ($index->isDeleted($count)) {
 123         echo "ドキュメント #$id は削除されました。\n";
 124     }
 125 }
 126 ]]></programlisting>
 127
 128         <para>
 129             インデックスの最適化を行うと、削除されたドキュメントを取り除き、
 130             ドキュメントの ID を前のほうに詰め込みます。
 131             つまり、内部でのドキュメント ID は変わる可能性があります。
 132         </para>
 133     </sect2>
 134
 135     <sect2 id="zend.search.lucene.index-creation.optimization">
 136         <title>インデックスの最適化</title>
 137
 138         <para>
 139             Lucene のインデックスは、セグメントから構成されます。
 140             各セグメントはデータの一部分を表し、それぞれ完全に独立しています。
 141         </para>
 142         <para>
 143             Lucene インデックスセグメントのファイルは、その性質上更新することはできません。
 144             セグメントを更新するには、セグメント全体を再構成する必要があります
 145             (Lucene インデックスファイルのフォーマットについての詳細は、
 146             <ulink url="http://lucene.apache.org/java/2_3_0/fileformats.html">http://lucene.apache.org/java/2_3_0/fileformats.html</ulink>
 147             を参照ください)
 148             <footnote><para>現在サポートしている Lucene インデックスファイルフォーマットのバージョンは v2.3 (Zend Framework 1.6 以降) です</para></footnote>。
 149             このことより、新しいドキュメントをインデックスに追加する際には、
 150             新しいセグメントを作成することになります。
 151         </para>
 152         <para>
 153             セグメントの数が増えるとインデックスの効率が下がります。
 154             しかし、インデックスの最適化によってこれを修復できます。
 155             最適化により、複数のセグメントに分かれているデータがひとつにまとめられます。
 156             この処理も、セグメントを更新することはありません。まず大きなセグメントを新しく作成し、
 157             これまでいくつものセグメントに分かれていたデータをひとまとめにしてそこに格納し、
 158             その後でセグメント一覧 ('segments' ファイル) を更新します。
 159         </para>
 160
 161         <para>
 162             インデックス全体の最適化を行うには、<methodname>Zend_Search_Lucene::optimize()</methodname>
 163             をコールします。これは、すべてのインデックスセグメントを新しいひとつのセグメントにまとめます。
 164         </para>
 165         <programlisting language="php"><![CDATA[
 166 // 既存のインデックスをオープンします
 167 $index = Zend_Search_Lucene::open('/data/my-index');
 168
 169 // インデックスを最適化します
 170 $index->optimize();
 171 ]]></programlisting>
 172
 173         <para>
 174             自動的なインデックス最適化により、インデックスの一貫性を保ちます。
 175         </para>
 176         <para>
 177             自動的な最適化は、いくつかのインデックスオプションにもとづいて段階的に進められます。
 178             まず非常に小さなセグメントが少し大きめのセグメントに統合され、
 179             さらにそれがもう少し大きな別のセグメントに統合され、... といった具合です。
 180         </para>
 181
 182         <sect3 id="zend.search.lucene.index-creation.optimization.maxbuffereddocs">
 183             <title>自動最適化オプション MaxBufferedDocs</title>
 184             <para>
 185                 <emphasis>MaxBufferedDocs</emphasis> は、メモリ内に溜め込まれたドキュメントを
 186                 新しいセグメントに書き出す際の最小ドキュメント数です。
 187             </para>
 188             <para>
 189                 <emphasis>MaxBufferedDocs</emphasis> の値の取得や設定は、<code>$index->getMaxBufferedDocs()</code>
 190                 あるいは <code>$index->setMaxBufferedDocs($maxBufferedDocs)</code> のコールによって行います。
 191             </para>
 192             <para>
 193                 デフォルト値は 10 です。
 194             </para>
 195         </sect3>
 196
 197         <sect3 id="zend.search.lucene.index-creation.optimization.maxmergedocs">
 198             <title>自動最適化オプション MaxMergeDocs</title>
 199             <para>
 200                 <emphasis>MaxMergeDocs</emphasis> は、addDocument()
 201                 によってまとめられる最大のドキュメント数です。小さな値
 202                 (例えば 10.000 未満) は、対話的にインデックスを作成していく際に有効です。
 203                 これにより、インデックス化の際の処理の中断時間を数秒に抑えられます。
 204                 大きな値は、バッチ処理の際に有効です。これにより、検索をより高速に行えるようになります。
 205             </para>
 206             <para>
 207                 <emphasis>MaxMergeDocs</emphasis> の値の取得や設定は、<code>$index->getMaxMergeDocs()</code>
 208                 あるいは <code>$index->setMaxMergeDocs($maxMergeDocs)</code> のコールによって行います。
 209             </para>
 210             <para>
 211                 デフォルト値は PHP_INT_MAX です。
 212             </para>
 213         </sect3>
 214
 215         <sect3 id="zend.search.lucene.index-creation.optimization.mergefactor">
 216             <title>自動最適化オプション MergeFactor</title>
 217             <para>
 218                 <emphasis>MergeFactor</emphasis> は、addDocument() でセグメントをまとめる頻度を指定します。
 219                 小さな値を指定すると、インデックス作成の際に使用する <acronym>RAM</acronym> の量を抑えられます。
 220                 また最適化されていないインデックスへの検索が高速になります。しかし、
 221                 インデックス作成の速度は遅くなります。大きな値を指定すると、インデックス作成の際の
 222                 <acronym>RAM</acronym> の使用量が多くなります。また最適化されていないインデックスへの検索速度が落ちます。
 223                 しかしインデックスの作成は高速に行えます。大きな値 (&gt; 10)
 224                 はバッチ的なインデックス作成の際に有効で、小さな値 (&lt; 10)
 225                 は対話的なインデックス保守の際に有効です。
 226             </para>
 227             <para>
 228                 <emphasis>MergeFactor</emphasis>
 229                 は、自動最適化が行われる平均セグメント数にほぼ等しくなります。
 230                 あまり大きな値を指定すると、新しいセグメントにまとめる前に
 231                 セグメント数が多くなってしまいます。これは
 232                 "failed to open stream: Too many open files"
 233                 というエラーの原因となります。制限は、システムに依存します。
 234             </para>
 235             <para>
 236                 <emphasis>MergeFactor</emphasis> の値の取得や設定は、<code>$index->getMergeFactor()</code>
 237                 あるいは <code>$index->setMergeFactor($mergeFactor)</code> のコールによって行います。
 238             </para>
 239             <para>
 240                 デフォルト値は 10 です。
 241             </para>
 242             <para>
 243                 Lucene Java および Luke (Lucene Index Toolbox - <ulink url="http://www.getopt.org/luke/">http://www.getopt.org/luke/</ulink>)
 244                 を使用してインデックスを最適化することもできます。
 245                 Luke の最新リリース (v0.8) は Lucene v2.3 をベースにしており、
 246                 現在の <classname>Zend_Search_Lucene</classname> コンポーネントの実装 (Zend Framework 1.6) と互換性があります。
 247                 古いのバージョンの <classname>Zend_Search_Lucene</classname> の実装を使う場合は、
 248                 それと互換性のある別のバージョンの Java Lucene ツールを使う必要があります。
 249                 <itemizedlist>
 250                     <listitem>
 251                         <para>Zend Framework 1.5 - Java Lucene 2.1 (Luke tool v0.7.1 - <ulink url="http://www.getopt.org/luke/luke-0.7.1/"/>)</para>
 252                     </listitem>
 253                     <listitem>
 254                         <para>Zend Framework 1.0 - Java Lucene 1.4 - 2.1 (Luke tool v0.6 - <ulink url="http://www.getopt.org/luke/luke-0.6/"/>)</para>
 255                     </listitem>
 256                 </itemizedlist>
 257             </para>
 258         </sect3>
 259     </sect2>
 260
 261     <sect2 id="zend.search.lucene.index-creation.permissions">
 262         <title>パーミッション</title>
 263
 264         <para>
 265             インデックスファイルは、デフォルトでは全員が読み書き可能となっています。
 266         </para>
 267
 268         <para>
 269             この設定を上書きするには
 270             <methodname>Zend_Search_Lucene_Storage_Directory_Filesystem::setDefaultFilePermissions()</methodname>
 271             メソッドを使用します。
 272         </para>
 273
 274         <programlisting language="php"><![CDATA[
 275 // 現在のデフォルトのファイルパーミッションを取得します
 276 $currentPermissions =
 277     Zend_Search_Lucene_Storage_Directory_Filesystem::getDefaultFilePermissions();
 278
 279 // 現在のユーザとグループに対してのみ読み書きアクセス権限を付与します
 280 Zend_Search_Lucene_Storage_Directory_Filesystem::setDefaultFilePermissions(0660);
 281 ]]></programlisting>
 282     </sect2>
 283
 284     <sect2 id="zend.search.lucene.index-creation.limitations">
 285         <title>制限事項</title>
 286
 287         <sect3 id="zend.search.lucene.index-creation.limitations.index-size">
 288             <title>インデックスの大きさ</title>
 289             <para>
 290                 インデックスの大きさは、
 291                 32 ビットプラットフォームでは最大 2GB までとなります。
 292             </para>
 293
 294             <para>
 295                 64 ビットプラットフォームを使用すれば、
 296                 もっと大きなインデックスを扱えます。
 297             </para>
 298         </sect3>
 299
 300         <sect3 id="zend.search.lucene.index-creation.limitations.filesystems">
 301             <title>サポートするファイルシステム</title>
 302             <para>
 303                 <classname>Zend_Search_Lucene</classname> は、
 304                 検索処理やインデックス更新、インデックスの最適化を処理する際に
 305                 <methodname>flock()</methodname> を使用しています。
 306             </para>
 307
 308             <para>
 309                 PHP の <ulink url="http://www.php.net/manual/ja/function.flock.php">マニュアル</ulink>
 310                 によると、
 311                 "<methodname>flock()</methodname> は NFS 及び他の多くのネットワークファイルシステムでは動作しません"
 312                 とのことです。
 313             </para>
 314
 315             <para>
 316                 ネットワークファイルシステムは、<classname>Zend_Search_Lucene</classname> では使用しないでください。
 317             </para>
 318         </sect3>
 319     </sect2>
 320 </sect1>
 321
 322 <!--
 323 vim:se ts=4 sw=4 et:
 324 -->