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

<!-- EN-Revision: 13910 -->
<sect1 id="zend.search.lucene.index-creation">
    <title>Créer des index</title>

    <sect2 id="zend.search.lucene.index-creation.creating">
        <title>Créer un nouvel index</title>

        <para>La création et la mise à jour des index sont implémentées dans le composant
        <classname>Zend_Search_Lucene</classname>, ainsi que dans le projet Java Lucene. Vous pouvez utiliser l'une ou l'autre de
        ces options pour créer des index dans lesquels <classname>Zend_Search_Lucene</classname> pourra chercher.</para>

        <para>Le listing ci-dessous donne un exemple d'indexation d'un fichier en utilisant l'API d'indexation de
        <classname>Zend_Search_Lucene</classname> :</para>

        <programlisting role="php"><![CDATA[
// Création de l'index
$index = Zend_Search_Lucene::create('/data/my-index');

$doc = new Zend_Search_Lucene_Document();

// Stockage de l'URL du document afin de pouvoir l'identifier dans les résultats de recherche
$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));

// Indexation des contenus du document
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $docContent));

// Ajout du document à l'index
$index->addDocument($doc);
]]></programlisting>

        <para>Les documents nouvellement ajoutés sont immédiatement recherchables dans l'index.</para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.updating">
        <title>Mettre à jour un index</title>

        <para>La même procédure est utilisée pour mettre à jour un index existant. La seule différence est l'appel de la
        méthode open() à la place de <code>create()</code>.</para>

        <programlisting role="php"><![CDATA[
// Ouverture d'un index existant
$index = Zend_Search_Lucene::open('/data/my-index');

$doc = new Zend_Search_Lucene_Document();
// Stockage de l'URL du document afin de pouvoir l'identifier dans les résultats de recherche
$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
// Indexation des contenus du document
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
                                                  $docContent));

// Ajout du document à l'index
$index->addDocument($doc);
]]></programlisting>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.document-updating">
        <title>Mise à jour de Documents.</title>

        <para>Le format de fichier d'un index Lucene ne permet pas la mise à jour d'un document. Les documents doivent
        être supprimés puis réinsérés dans l'index afin d'être mis à jour efficacement.</para>

        <para>La méthode <classname>Zend_Search_Lucene::delete()</classname> utilise un identifiant interne de document. Cet
        identifiant peut être récupéré dans une requête en demandant la propriété 'id' :</para>

        <programlisting role="php"><![CDATA[
$removePath = ...;
$hits = $index->find('path:' . $removePath);
foreach ($hits as $hit) {
    $index->delete($hit->id);
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.counting">
        <title>Récupération de la taille de l'index</title>

        <para>Il existe deux méthodes pour récupérer la taille d'un index dans <classname>Zend_Search_Lucene</classname>.</para>

        <para>La méthode <classname>Zend_Search_Lucene::maxDoc()</classname> retourne un de plus que le plus grand nombre possible
        de documents. Il s'agit en fait du nombre total de documents dans l'index, y compris les documents supprimés.
        Cette méthode a une méthode synonyme : <classname>Zend_Search_Lucene::count()</classname>.</para>

        <para>La méthode <classname>Zend_Search_Lucene::numDocs()</classname> retourne le nombre total de documents non
        supprimés.</para>

        <programlisting role="php"><![CDATA[
$indexSize = $index->count();
$documents = $index->numDocs();
]]></programlisting>

        <para>La méthode <classname>Zend_Search_Lucene::isDeleted($id)</classname> peut être utilisée pour vérifier si un document
        a été supprimé.</para>

        <programlisting role="php"><![CDATA[
for ($count = 0; $count < $index->maxDoc(); $count++) {
    if ($index->isDeleted($count)) {
        echo "Le document #$id a été supprimé.\n";
    }
}
]]></programlisting>

        <para>L'optimisation d'index retire les documents supprimés et resserre les identifiants de documents dans un
        intervalle plus petit. Ainsi, un identifiant interne de document peut être modifié durant l'optimisation de
        l'index.</para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.optimization">
        <title>Optimisation d'index</title>

        <para>Un index Lucene est composé de plusieurs segments. Chaque segment est un ensemble de données complètement
        indépendant des autres.</para>

        <para>Les fichiers de segment d'index Lucene ne peuvent pas être mis à jour conceptuellement. Une mise à jour de
        segment requiert une réorganisation complète de tous les segments. Consultez les formats de fichiers d'index
        pour plus de détails (<ulink
        url="http://lucene.apache.org/java/docs/fileformats.html">http://lucene.apache.org/java/docs/fileformats.html</ulink>)
        <footnote>
                <para>Le format de fichier d'index supporté actuellement est la version 2.3 (depuis Zend Framework
                1.6).</para>
            </footnote>Les nouveaux documents sont ajoutés à l'index en créant de nouveaux segments.</para>

        <para>L'augmentation du nombre de segments réduit la qualité de l'index, mais l'optimisation de l'index remédie
        à ce problème. L'optimisation a pour principale activité de fusionner plusieurs segments en un seul. Ce
        processus ne met pas à jour les segments. Il génère un nouveau segment plus gros et met à jour la liste des
        segments ('segments' file).</para>

        <para>L'optimisation complète de l'index peut être déclenchée en appelant la méthode
        <classname>Zend_Search_Lucene::optimize()</classname>. Elle va fusionner tous les segments de l'index en un seul nouveau
        segment :</para>

        <programlisting role="php"><![CDATA[
// Ouverture d'un index existant.
$index = Zend_Search_Lucene::open('/data/my-index');

// Optimisation de l'index.
$index->optimize();
]]></programlisting>

        <para>L'optimisation automatique de l'index est lancée pour garder les index dans un état cohérent.</para>

        <para>L'optimisation automatique est un processus itératif géré par plusieurs options d'index. Il s'agit de
        fusionner les très petits segments pour obtenir de plus gros segments, puis de fusionner ces segments obtenus
        vers des segments encore plus gros et ainsi de suite.</para>

        <sect3 id="zend.search.lucene.index-creation.optimization.maxbuffereddocs">
            <title>Option d'optimisation automatique <emphasis>MaxBufferedDocs</emphasis></title>

            <para><emphasis>MaxBufferedDocs</emphasis> correspond au nombre minimum de documents requis avant que les
            documents présents en mémoire dans le buffer soit écris dans un nouveau segment.</para>

            <para><emphasis>MaxBufferedDocs</emphasis> peut être récupéré ou défini en appelant
            <code>$index-&gt;getMaxBufferedDocs()</code> ou
            <code>$index-&gt;setMaxBufferedDocs($maxBufferedDocs)</code>.</para>

            <para>Sa valeur par défaut est 10.</para>
        </sect3>

        <sect3 id="zend.search.lucene.index-creation.optimization.maxmergedocs">
            <title>Option d'optimisation automatique <emphasis>MaxMergeDocs</emphasis></title>

            <para><emphasis>MaxMergeDocs</emphasis> correspond à un nombre maximal de documents fusionnés via
            <code>addDocument()</code>. Des petites valeurs (p. ex., moins de 10'000) sont préférables pour de
            l'indexation interactive, du fait que cela limite les pauses durant l'indexation à quelques secondes. Des
            valeurs plus grandes sont meilleures pour les indexations en tâches planifiées (batch) et des recherches
            plus rapides.</para>

            <para><emphasis>MaxMergeDocs</emphasis> peut être récupéré ou défini en appelant
            <code>$index-&gt;getMaxMergeDocs()</code> ou <code>$index-&gt;setMaxMergeDocs($maxMergeDocs)</code>.</para>

            <para>Sa valeur par défaut est PHP_INT_MAX.</para>
        </sect3>

        <sect3 id="zend.search.lucene.index-creation.optimization.mergefactor">
            <title>Option d'optimisation automatique <emphasis>MergeFactor</emphasis></title>

            <para><emphasis>MergeFactor</emphasis> détermine à quelle fréquence les segments d'index sont fusionnés par
            <code>addDocument()</code>. Avec des petites valeurs, on utilise moins de RAM durant l'indexation et les
            recherche sur des index non optimisés sont plus rapides, mais la vitesse d'indexation est plus lente. Avec
            des valeurs plus grandes, on utilise plus de RAM durant l'indexation, et tandis que les recherches sur les
            index non optimisés sont plus lentes, l'indexation est plus rapide. Au final, les grandes valeurs (&gt; 10)
            sont préférables pour les indexations planifiées (batch), et les valeurs plus petites (&lt; 10) pour les
            index qui sont maintenus de manière interactives.</para>

            <para>L'option <emphasis>MergeFactor</emphasis> constitue une bonne estimation pour le nombre moyen de
            segments fusionnés par une passe d'auto-optimisation. Des valeurs trop grandes produisent un nombre trop
            important de segments car ils ne sont pas fusionnés. Cela peut causer l'erreur "failed to open stream: Too
            many open files". Cette limitation est dépendante du système.</para>

            <para><emphasis>MergeFactor</emphasis> peut être récupéré ou défini par les méthodes
            <code>$index-&gt;getMergeFactor()</code> ou <code>$index-&gt;setMergeFactor($mergeFactor)</code>.</para>

            <para>Sa valeur par défaut est 10.</para>

            <para>Lucene Java et Luke (Lucene Index Toolbox - <ulink
            url="http://www.getopt.org/luke/">http://www.getopt.org/luke/</ulink>) peuvent aussi être utilisés pour
            optimiser un index. La dernière version de Luke (v0.8) est basée sur Lucene v2.3 et est compatible avec
            l'implémentation courante du composant <classname>Zend_Search_Lucene</classname> (ZF 1.6). Les versions précédentes de
            <classname>Zend_Search_Lucene</classname> nécessitent d'autres versions des outils de Java Lucene : <itemizedlist>
                    <listitem>
                        <para>ZF 1.5 - Java Lucene 2.1 (Luke tool v0.7.1 - <ulink
                        url="http://www.getopt.org/luke/luke-0.7.1/"></ulink>)</para>
                    </listitem>

                    <listitem>
                        <para>ZF 1.0 - Java Lucene 1.4 - 2.1 (Luke tool v0.6 - <ulink
                        url="http://www.getopt.org/luke/luke-0.6/"></ulink>)</para>
                    </listitem>
                </itemizedlist></para>
        </sect3>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.permissions">
        <title>Permissions</title>

        <para>Par défaut, les fichiers d'index sont disponibles en lecture et écriture par tout le monde.</para>

        <para>Il est possible de surcharger ce comportement grâce à la méthode
        <classname>Zend_Search_Lucene_Storage_Directory_Filesystem::setDefaultFilePermissions()</classname> :</para>

        <programlisting role="php"><![CDATA[
// Récupération des permissions par défaut
$currentPermissions =
    Zend_Search_Lucene_Storage_Directory_Filesystem::getDefaultFilePermissions();

// Donne la permission lecture-écriture uniquement à l'utilisateur et au groupe courant.
Zend_Search_Lucene_Storage_Directory_Filesystem::setDefaultFilePermissions(0660);
]]></programlisting>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.limitations">
        <title>Limitations</title>

        <sect3 id="zend.search.lucene.index-creation.limitations.index-size">
            <title>Taille de l'index</title>

            <para>La taille de l'index est limité à 2GB sur les plate-formes 32 bits.</para>

            <para>Utilisez des plate-formes 64 bits pour des index plus gros.</para>
        </sect3>

        <sect3 id="zend.search.lucene.index-creation.limitations.filesystems">
            <title>Systèmes de fichiers supportés</title>

            <para><classname>Zend_Search_Lucene</classname> utilise <code>flock()</code> pour fournir des recherches concurrentes,
            la mise à jour des index et l'optimisation.</para>

            <para>Selon la <ulink url="http://www.php.net/manual/en/function.flock.php">documentation</ulink> PHP,
            "<code>flock()</code> ne fonctionnera pas sur NFS et plusieurs autres systèmes de fichiers en
            réseaux".</para>

            <para>N'utilisez pas de systèmes de fichiers en réseaux avec <classname>Zend_Search_Lucene</classname>.</para>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->