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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20854 -->
<!-- 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>
            O aumento do número de segmentos reduz a qualidade do índice, mas uma otimização do
            índice resolverá o problema. Essencialmente, a otimização mescla vários segmentos em um
            novo. Além disso, este processo não atualiza os segmentos. Ele gera um novo grande
            segmento e atualiza a lista de segmentos (arquivo 'segments').
        </para>

        <para>
            A otimização completa do índice pode ser feita chamando o método
            <methodname>Zend_Search_Lucene::optimize()</methodname>. Ele funde todos os segmentos de
            índice em um novo segmento:
        </para>

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

// Otimiza o índice
$index->optimize();
]]></programlisting>

        <para>
            A otimização automática do índice é realizada para manter os índices em um estado
            consistente.
        </para>

        <para>
            A otimização automática é um processo iterativo controlado por várias opções de índice.
            Ele funde segmentos muito pequenos para obter outros maiores, então mescla esses
            segmentos em segmentos ainda maiores e assim por diante.
        </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:
-->