repo_zf1/documentation/manual/pt-br/module_specs/Zend_Search_Lucene-IndexCreation.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 18536 -->
<!-- Reviewed: no -->
<sect1 id="zend.search.lucene.index-creation">
    <title>Construindo Índices</title>

    <sect2 id="zend.search.lucene.index-creation.creating">
        <title>Criando um Novo Índice</title>

        <para>
            As funcionalidades de criação e atualização de índices são implementadas tanto no
            componente <classname>Zend_Search_Lucene</classname> como no projeto Java Lucene. Você
            pode usar qualquer uma destas opções para criar índices pesquisáveis pelo
            <classname>Zend_Search_Lucene</classname>.
        </para>

        <para>
            O código <acronym>PHP</acronym> abaixo mostra um exemplo de como indexar um arquivo
            usando a <acronym>API</acronym> de indexação do
            <classname>Zend_Search_Lucene</classname>:
        </para>

        <programlisting language="php"><![CDATA[
// Cria o índice
$index = Zend_Search_Lucene::create('/data/my-index');

$doc = new Zend_Search_Lucene_Document();

// Armazena a URL do documento para identificá-lo nos resultados da pesquisa
$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));

// Indexa os conteúdos do documento
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $docContent));

// Adiciona o documento ao índice
$index->addDocument($doc);
]]></programlisting>

        <para>
            Documentos adicionados recentemente são imediatamente pesquisáveis no índice.
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.updating">
        <title>Atualizando um Índice</title>

        <para>
            O mesmo procedimento é empregado para atualizar um índice existente. A única diferença
            é que o método open() é chamado no lugar do método create():
        </para>

        <programlisting language="php"><![CDATA[
// Abre um índice existente
$index = Zend_Search_Lucene::open('/data/my-index');

$doc = new Zend_Search_Lucene_Document();
// Armazena a URL do documento para identificá-lo no resultado da pesquisa
$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
// Indexa o conteúdo do documento
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
                                                  $docContent));

// Adiciona o documento ao índice
$index->addDocument($doc);
]]></programlisting>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.document-updating">
        <title>Atualizando os Documentos</title>

        <para>
            O formato de arquivo do índice Lucene não suporta a atualização do documento. Os
            documentos devem ser removidos e adicionados novamente ao índice para atualizá-los de
            forma eficaz.
        </para>

        <para>
            O método <methodname>Zend_Search_Lucene::delete()</methodname> funciona com uma
            identificação interna do índice do documento. Ela pode ser recuperada de uma consulta
            pela propriedade '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>Recuperando o Tamanho do Índice</title>

        <para>
            Existem dois métodos para recuperar o tamanho de um índice no
            <classname>Zend_Search_Lucene</classname>.
        </para>

        <para>
            O método <methodname>Zend_Search_Lucene::maxDoc()</methodname> retorna um número maior
            do que o maior número possível de documentos. É na verdade o número total de documentos
            no índice incluindo os documentos excluídos, por isso ele tem um sinônimo:
            <methodname>Zend_Search_Lucene::count()</methodname>.
        </para>

        <para>
            O método <methodname>Zend_Search_Lucene::numDocs()</methodname> retorna o número total
            de documentos que não foram excluídos.
        </para>

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

        <para>
            O método <methodname>Zend_Search_Lucene::isDeleted($id)</methodname> pode ser usado para
            verificar se um documento foi excluído.
        </para>

        <programlisting language="php"><![CDATA[
for ($count = 0; $count < $index->maxDoc(); $count++) {
    if ($index->isDeleted($count)) {
        echo "O documento #$id foi excluído.\n";
    }
}
]]></programlisting>

        <para>
            A otimização do índice remove os documentos excluídos e comprime as IDs dos documentos
            em um intervalo menor. Assim, uma id interna de um documento pode ser alterada durante
            a otimização do índice.
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.optimization">
        <title>Otimização do Índice</title>

        <para>
            Um índice Lucene é composto por vários segmentos. Cada segmento é um conjunto de dados
            completamente independente.
        </para>

        <para>
            Os arquivos de segmento de índice Lucene não podem ser atualizados devido ao seu
            projeto. A atualização de um segmento necessita de uma reorganização completa do
            segmento. Veja os formatos de arquivos de índice Lucene para mais detalhes
            (<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>
                    O formato de arquivo de índice Lucene atualmente suportado é a versão 2.3
                    (desde Zend Framework 1.6).
                </para>
            </footnote>.
            Novos documentos são adicionados ao índice através da criação de um novo segmento.
        </para>

        <para>
            Increasing number of segments reduces quality of the index, but index optimization restores it.
            Optimization essentially merges several segments into a new one. This process also doesn't update segments.
            It generates one new large segment and updates segment list ('segments' file).
        </para>

        <para>
            Full index optimization can be trigger by calling the <methodname>Zend_Search_Lucene::optimize()</methodname> method. It merges all
            index segments into one new segment:
        </para>

        <programlisting language="php"><![CDATA[
// Open existing index
$index = Zend_Search_Lucene::open('/data/my-index');

// Optimize index.
$index->optimize();
]]></programlisting>

        <para>
            Automatic index optimization is performed to keep indexes in a consistent state.
        </para>

        <para>
            Automatic optimization is an iterative process managed by several index options. It merges very small segments
            into larger ones, then merges these larger segments into even larger segments and so on.
        </para>

        <sect3 id="zend.search.lucene.index-creation.optimization.maxbuffereddocs">
            <title>MaxBufferedDocs auto-optimization option</title>

            <para>
                <emphasis>MaxBufferedDocs</emphasis> is a minimal number of documents required before
                the buffered in-memory documents are written into a new segment.
            </para>

            <para>
                <emphasis>MaxBufferedDocs</emphasis> can be retrieved or set by <code>$index->getMaxBufferedDocs()</code> or
                <code>$index->setMaxBufferedDocs($maxBufferedDocs)</code> calls.
            </para>

            <para>
                Default value is 10.
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.index-creation.optimization.maxmergedocs">
            <title>MaxMergeDocs auto-optimization option</title>

            <para>
                <emphasis>MaxMergeDocs</emphasis> is a largest number of documents ever merged by addDocument().
                Small values (e.g., less than 10.000) are best for interactive indexing, as this limits the length
                of pauses while indexing to a few seconds. Larger values are best for batched indexing and speedier
                searches.
            </para>

            <para>
                <emphasis>MaxMergeDocs</emphasis> can be retrieved or set by <code>$index->getMaxMergeDocs()</code> or
                <code>$index->setMaxMergeDocs($maxMergeDocs)</code> calls.
            </para>

            <para>
                Default value is PHP_INT_MAX.
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.index-creation.optimization.mergefactor">
            <title>MergeFactor auto-optimization option</title>

            <para>
                <emphasis>MergeFactor</emphasis> determines how often segment indices are merged by addDocument().
                With smaller values, less <acronym>RAM</acronym> is used while indexing, and searches on unoptimized indices are faster,
                but indexing speed is slower. With larger values, more <acronym>RAM</acronym> is used during indexing, and while searches
                on unoptimized indices are slower, indexing is faster. Thus larger values (&gt; 10) are best for batch
                index creation, and smaller values (&lt; 10) for indices that are interactively maintained.
            </para>

            <para>
                <emphasis>MergeFactor</emphasis> is a good estimation for average number of segments merged by one auto-optimization pass.
                Too large values produce large number of segments while they are not merged into new one. It may be a cause of
                "failed to open stream: Too many open files" error message. This limitation is system dependent.
            </para>

            <para>
                <emphasis>MergeFactor</emphasis> can be retrieved or set by <code>$index->getMergeFactor()</code> or
                <code>$index->setMergeFactor($mergeFactor)</code> calls.
            </para>

            <para>
                Default value is 10.
            </para>

            <para>
                Lucene Java and Luke (Lucene Index Toolbox - <ulink url="http://www.getopt.org/luke/">http://www.getopt.org/luke/</ulink>)
                can also be used to optimize an index. Latest Luke release (v0.8) is based on Lucene v2.3 and compatible with
                current implementation of <classname>Zend_Search_Lucene</classname> component (Zend Framework 1.6). Earlier versions of <classname>Zend_Search_Lucene</classname> implementations
                need another versions of Java Lucene tools to be compatible:
                <itemizedlist>
                    <listitem>
                        <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>
                    </listitem>

                    <listitem>
                        <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>
                    </listitem>
                </itemizedlist>
            </para>
        </sect3>
    </sect2>

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

        <para>
            By default, index files are available for reading and writing by everyone.
        </para>

        <para>
            It's possible to override this with the <methodname>Zend_Search_Lucene_Storage_Directory_Filesystem::setDefaultFilePermissions()</methodname> method:
        </para>

        <programlisting language="php"><![CDATA[
// Get current default file permissions
$currentPermissions =
    Zend_Search_Lucene_Storage_Directory_Filesystem::getDefaultFilePermissions();

// Give read-writing permissions only for current user and group
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>Index size</title>

            <para>
                Index size is limited by 2GB for 32-bit platforms.
            </para>

            <para>
                Use 64-bit platforms for larger indices.
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.index-creation.limitations.filesystems">
            <title>Supported Filesystems</title>

            <para>
                <classname>Zend_Search_Lucene</classname> uses <methodname>flock()</methodname> to provide concurrent searching, index updating and optimization.
            </para>

            <para>
                According to the <acronym>PHP</acronym> <ulink url="http://www.php.net/manual/en/function.flock.php">documentation</ulink>,
                "<methodname>flock()</methodname> will not work on NFS and many other networked file systems".
            </para>

            <para>
                Do not use networked file systems with <classname>Zend_Search_Lucene</classname>.
            </para>
        </sect3>
    </sect2>
</sect1>

<!--
vim:se ts=4 sw=4 et:
-->