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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<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 language="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 <methodname>create()</methodname>.
        </para>

        <programlisting language="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 <methodname>Zend_Search_Lucene::delete()</methodname> 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 language="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 <methodname>Zend_Search_Lucene::maxDoc()</methodname> 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 : <methodname>Zend_Search_Lucene::count()</methodname>.
        </para>

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

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

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

        <programlisting language="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/2_3_0/fileformats.html">http://lucene.apache.org/java/2_3_0/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
            <methodname>Zend_Search_Lucene::optimize()</methodname>. Elle va fusionner tous les
            segments de l'index en un seul nouveau segment :
        </para>

        <programlisting language="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 <methodname>addDocument()</methodname>. 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 <methodname>addDocument()</methodname>. Avec des petites valeurs, on
                utilise moins de <acronym>RAM</acronym> 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 <acronym>RAM</acronym> 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
            <methodname>Zend_Search_Lucene_Storage_Directory_Filesystem::setDefaultFilePermissions()</methodname>
            :
        </para>

        <programlisting language="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 <methodname>flock()</methodname> 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> <acronym>PHP</acronym>,
                "<methodname>flock()</methodname> 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:
-->