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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20854 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.search.lucene.index-creation">
   5     <title>Créer des index</title>
   6
   7     <sect2 id="zend.search.lucene.index-creation.creating">
   8         <title>Créer un nouvel index</title>
   9
  10         <para>
  11             La création et la mise à jour des index sont implémentées dans le composant
  12             <classname>Zend_Search_Lucene</classname>, ainsi que dans le projet Java Lucene. Vous
  13             pouvez utiliser l'une ou l'autre de ces options pour créer des index dans lesquels
  14             <classname>Zend_Search_Lucene</classname> pourra chercher.
  15         </para>
  16
  17         <para>
  18             Le listing ci-dessous donne un exemple d'indexation d'un fichier en utilisant
  19             l'API d'indexation de <classname>Zend_Search_Lucene</classname> :
  20         </para>
  21
  22         <programlisting language="php"><![CDATA[
  23 // Création de l'index
  24 $index = Zend_Search_Lucene::create('/data/my-index');
  25
  26 $doc = new Zend_Search_Lucene_Document();
  27
  28 // Stockage de l'URL du document afin de pouvoir l'identifier dans les résultats de recherche
  29 $doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
  30
  31 // Indexation des contenus du document
  32 $doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $docContent));
  33
  34 // Ajout du document à l'index
  35 $index->addDocument($doc);
  36 ]]></programlisting>
  37
  38         <para>
  39             Les documents nouvellement ajoutés sont immédiatement recherchables dans
  40             l'index.
  41         </para>
  42     </sect2>
  43
  44     <sect2 id="zend.search.lucene.index-creation.updating">
  45         <title>Mettre à jour un index</title>
  46
  47         <para>
  48             La même procédure est utilisée pour mettre à jour un index existant. La seule
  49             différence est l'appel de la méthode open() à la place de <methodname>create()</methodname>.
  50         </para>
  51
  52         <programlisting language="php"><![CDATA[
  53 // Ouverture d'un index existant
  54 $index = Zend_Search_Lucene::open('/data/my-index');
  55
  56 $doc = new Zend_Search_Lucene_Document();
  57 // Stockage de l'URL du document afin de pouvoir l'identifier dans les résultats de recherche
  58 $doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
  59 // Indexation des contenus du document
  60 $doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
  61                                                   $docContent));
  62
  63 // Ajout du document à l'index
  64 $index->addDocument($doc);
  65 ]]></programlisting>
  66     </sect2>
  67
  68     <sect2 id="zend.search.lucene.index-creation.document-updating">
  69         <title>Mise à jour de Documents</title>
  70
  71         <para>
  72             Le format de fichier d'un index Lucene ne permet pas la mise à jour d'un document.
  73             Les documents doivent être supprimés puis réinsérés dans l'index afin d'être mis à jour
  74             efficacement.
  75         </para>
  76
  77         <para>
  78             La méthode <methodname>Zend_Search_Lucene::delete()</methodname> utilise un
  79             identifiant interne de document. Cet identifiant peut être récupéré dans une requête en
  80             demandant la propriété 'id' :
  81         </para>
  82
  83         <programlisting language="php"><![CDATA[
  84 $removePath = ...;
  85 $hits = $index->find('path:' . $removePath);
  86 foreach ($hits as $hit) {
  87     $index->delete($hit->id);
  88 }
  89 ]]></programlisting>
  90     </sect2>
  91
  92     <sect2 id="zend.search.lucene.index-creation.counting">
  93         <title>Récupération de la taille de l'index</title>
  94
  95         <para>
  96             Il existe deux méthodes pour récupérer la taille d'un index dans
  97             <classname>Zend_Search_Lucene</classname>.
  98         </para>
  99
 100         <para>
 101             La méthode <methodname>Zend_Search_Lucene::maxDoc()</methodname> retourne un de plus
 102             que le plus grand nombre possible de documents. Il s'agit en fait du nombre total de
 103             documents dans l'index, y compris les documents supprimés. Cette méthode a une méthode
 104             synonyme : <methodname>Zend_Search_Lucene::count()</methodname>.
 105         </para>
 106
 107         <para>
 108             La méthode <methodname>Zend_Search_Lucene::numDocs()</methodname> retourne le nombre
 109             total de documents non supprimés.
 110         </para>
 111
 112         <programlisting language="php"><![CDATA[
 113 $indexSize = $index->count();
 114 $documents = $index->numDocs();
 115 ]]></programlisting>
 116
 117         <para>
 118             La méthode <methodname>Zend_Search_Lucene::isDeleted($id)</methodname> peut être
 119             utilisée pour vérifier si un document a été supprimé.
 120         </para>
 121
 122         <programlisting language="php"><![CDATA[
 123 for ($count = 0; $count < $index->maxDoc(); $count++) {
 124     if ($index->isDeleted($count)) {
 125         echo "Le document #$id a été supprimé.\n";
 126     }
 127 }
 128 ]]></programlisting>
 129
 130         <para>
 131             L'optimisation d'index retire les documents supprimés et resserre les identifiants
 132             de documents dans un intervalle plus petit. Ainsi, un identifiant interne de document
 133             peut être modifié durant l'optimisation de l'index.
 134         </para>
 135     </sect2>
 136
 137     <sect2 id="zend.search.lucene.index-creation.optimization">
 138         <title>Optimisation d'index</title>
 139
 140         <para>
 141             Un index Lucene est composé de plusieurs segments. Chaque segment est un ensemble
 142             de données complètement indépendant des autres.
 143         </para>
 144
 145         <para>
 146             Les fichiers de segment d'index Lucene ne peuvent pas être mis à jour
 147             conceptuellement. Une mise à jour de segment requiert une réorganisation complète de
 148             tous les segments. Consultez les formats de fichiers d'index pour plus de détails
 149             (<ulink
 150                 url="http://lucene.apache.org/java/2_3_0/fileformats.html">http://lucene.apache.org/java/2_3_0/fileformats.html</ulink>)
 151             <footnote>
 152                 <para>
 153                     Le format de fichier d'index supporté actuellement est la version 2.3
 154                     (depuis Zend Framework 1.6).
 155                 </para>
 156             </footnote>Les nouveaux documents sont ajoutés à l'index en créant de nouveaux
 157             segments.
 158         </para>
 159
 160         <para>
 161             L'augmentation du nombre de segments réduit la qualité de l'index, mais
 162             l'optimisation de l'index remédie à ce problème. L'optimisation a pour principale
 163             activité de fusionner plusieurs segments en un seul. Ce processus ne met pas à jour les
 164             segments. Il génère un nouveau segment plus gros et met à jour la liste des segments
 165             ('segments' file).
 166         </para>
 167
 168         <para>
 169             L'optimisation complète de l'index peut être déclenchée en appelant la méthode
 170             <methodname>Zend_Search_Lucene::optimize()</methodname>. Elle va fusionner tous les
 171             segments de l'index en un seul nouveau segment :
 172         </para>
 173
 174         <programlisting language="php"><![CDATA[
 175 // Ouverture d'un index existant.
 176 $index = Zend_Search_Lucene::open('/data/my-index');
 177
 178 // Optimisation de l'index.
 179 $index->optimize();
 180 ]]></programlisting>
 181
 182         <para>
 183             L'optimisation automatique de l'index est lancée pour garder les index dans un
 184             état cohérent.
 185         </para>
 186
 187         <para>
 188             L'optimisation automatique est un processus itératif géré par plusieurs options
 189             d'index. Il s'agit de fusionner les très petits segments pour obtenir de plus gros
 190             segments, puis de fusionner ces segments obtenus vers des segments encore plus gros et
 191             ainsi de suite.
 192         </para>
 193
 194         <sect3 id="zend.search.lucene.index-creation.optimization.maxbuffereddocs">
 195             <title>Option d'optimisation automatique
 196             <emphasis>MaxBufferedDocs</emphasis></title>
 197
 198             <para>
 199                 <emphasis>MaxBufferedDocs</emphasis> correspond au nombre minimum de documents
 200                 requis avant que les documents présents en mémoire dans le buffer soit écris dans un
 201                 nouveau segment.
 202             </para>
 203
 204             <para>
 205                 <emphasis>MaxBufferedDocs</emphasis> peut être récupéré ou défini en appelant
 206                 <code>$index-&gt;getMaxBufferedDocs()</code> ou
 207                 <code>$index-&gt;setMaxBufferedDocs($maxBufferedDocs)</code>.
 208             </para>
 209
 210             <para>Sa valeur par défaut est 10.</para>
 211         </sect3>
 212
 213         <sect3 id="zend.search.lucene.index-creation.optimization.maxmergedocs">
 214             <title>Option d'optimisation automatique <emphasis>MaxMergeDocs</emphasis></title>
 215
 216             <para>
 217                 <emphasis>MaxMergeDocs</emphasis> correspond à un nombre maximal de documents
 218                 fusionnés via <methodname>addDocument()</methodname>. Des petites valeurs (p. ex., moins de
 219                 10'000) sont préférables pour de l'indexation interactive, du fait que cela limite
 220                 les pauses durant l'indexation à quelques secondes. Des valeurs plus grandes sont
 221                 meilleures pour les indexations en tâches planifiées (batch) et des recherches plus
 222                 rapides.
 223             </para>
 224
 225             <para>
 226                 <emphasis>MaxMergeDocs</emphasis> peut être récupéré ou défini en appelant
 227                 <code>$index-&gt;getMaxMergeDocs()</code> ou
 228                 <code>$index-&gt;setMaxMergeDocs($maxMergeDocs)</code>.
 229             </para>
 230
 231             <para>Sa valeur par défaut est PHP_INT_MAX.</para>
 232         </sect3>
 233
 234         <sect3 id="zend.search.lucene.index-creation.optimization.mergefactor">
 235             <title>Option d'optimisation automatique <emphasis>MergeFactor</emphasis></title>
 236
 237             <para>
 238                 <emphasis>MergeFactor</emphasis> détermine à quelle fréquence les segments
 239                 d'index sont fusionnés par <methodname>addDocument()</methodname>. Avec des petites valeurs, on
 240                 utilise moins de <acronym>RAM</acronym> durant l'indexation et les recherche sur des index non
 241                 optimisés sont plus rapides, mais la vitesse d'indexation est plus lente. Avec des
 242                 valeurs plus grandes, on utilise plus de <acronym>RAM</acronym> durant l'indexation, et tandis que les
 243                 recherches sur les index non optimisés sont plus lentes, l'indexation est plus
 244                 rapide. Au final, les grandes valeurs (&gt; 10) sont préférables pour les
 245                 indexations planifiées (batch), et les valeurs plus petites (&lt; 10) pour les index
 246                 qui sont maintenus de manière interactives.
 247             </para>
 248
 249             <para>
 250                 L'option <emphasis>MergeFactor</emphasis> constitue une bonne estimation pour
 251                 le nombre moyen de segments fusionnés par une passe d'auto-optimisation. Des valeurs
 252                 trop grandes produisent un nombre trop important de segments car ils ne sont pas
 253                 fusionnés. Cela peut causer l'erreur "failed to open stream: Too many open files".
 254                 Cette limitation est dépendante du système.
 255             </para>
 256
 257             <para>
 258                 <emphasis>MergeFactor</emphasis> peut être récupéré ou défini par les méthodes
 259                 <code>$index-&gt;getMergeFactor()</code> ou
 260                 <code>$index-&gt;setMergeFactor($mergeFactor)</code>.
 261             </para>
 262
 263             <para>Sa valeur par défaut est 10.</para>
 264
 265             <para>
 266                 Lucene Java et Luke (Lucene Index Toolbox - <ulink
 267                 url="http://www.getopt.org/luke/">http://www.getopt.org/luke/</ulink>) peuvent aussi
 268                 être utilisés pour optimiser un index. La dernière version de Luke (v0.8) est basée
 269                 sur Lucene v2.3 et est compatible avec l'implémentation courante du composant
 270                 <classname>Zend_Search_Lucene</classname> (ZF 1.6). Les versions précédentes de
 271                 <classname>Zend_Search_Lucene</classname> nécessitent d'autres versions des outils
 272                 de Java Lucene : <itemizedlist>
 273                         <listitem>
 274                         <para>
 275                             ZF 1.5 - Java Lucene 2.1 (Luke tool v0.7.1 - <ulink
 276                             url="http://www.getopt.org/luke/luke-0.7.1/"></ulink>)
 277                         </para>
 278                     </listitem>
 279
 280                     <listitem>
 281                         <para>
 282                             ZF 1.0 - Java Lucene 1.4 - 2.1 (Luke tool v0.6 - <ulink
 283                             url="http://www.getopt.org/luke/luke-0.6/"></ulink>)
 284                         </para>
 285                     </listitem>
 286                     </itemizedlist>
 287                 </para>
 288         </sect3>
 289     </sect2>
 290
 291     <sect2 id="zend.search.lucene.index-creation.permissions">
 292         <title>Permissions</title>
 293
 294         <para>
 295             Par défaut, les fichiers d'index sont disponibles en lecture et écriture par tout
 296             le monde.
 297         </para>
 298
 299         <para>
 300             Il est possible de surcharger ce comportement grâce à la méthode
 301             <methodname>Zend_Search_Lucene_Storage_Directory_Filesystem::setDefaultFilePermissions()</methodname>
 302             :
 303         </para>
 304
 305         <programlisting language="php"><![CDATA[
 306 // Récupération des permissions par défaut
 307 $currentPermissions =
 308     Zend_Search_Lucene_Storage_Directory_Filesystem::getDefaultFilePermissions();
 309
 310 // Donne la permission lecture-écriture uniquement à l'utilisateur et au groupe courant.
 311 Zend_Search_Lucene_Storage_Directory_Filesystem::setDefaultFilePermissions(0660);
 312 ]]></programlisting>
 313     </sect2>
 314
 315     <sect2 id="zend.search.lucene.index-creation.limitations">
 316         <title>Limitations</title>
 317
 318         <sect3 id="zend.search.lucene.index-creation.limitations.index-size">
 319             <title>Taille de l'index</title>
 320
 321             <para>La taille de l'index est limité à 2GB sur les plate-formes 32 bits.</para>
 322
 323             <para>Utilisez des plate-formes 64 bits pour des index plus gros.</para>
 324         </sect3>
 325
 326         <sect3 id="zend.search.lucene.index-creation.limitations.filesystems">
 327             <title>Systèmes de fichiers supportés</title>
 328
 329             <para>
 330                 <classname>Zend_Search_Lucene</classname> utilise <methodname>flock()</methodname> pour
 331                 fournir des recherches concurrentes, la mise à jour des index et
 332                 l'optimisation.
 333             </para>
 334
 335             <para>
 336                 Selon la <ulink
 337                 url="http://www.php.net/manual/en/function.flock.php">documentation</ulink> <acronym>PHP</acronym>,
 338                 "<methodname>flock()</methodname> ne fonctionnera pas sur NFS et plusieurs autres systèmes de
 339                 fichiers en réseaux".
 340             </para>
 341
 342             <para>
 343                 N'utilisez pas de systèmes de fichiers en réseaux avec
 344                 <classname>Zend_Search_Lucene</classname>.
 345             </para>
 346         </sect3>
 347     </sect2>
 348 </sect1>
 349 <!--
 350 vim:se ts=4 sw=4 et:
 351 -->