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

<sect1 id="zend.search.lucene.index-creation">
    <title>Индексация<!--Building Indexes--></title>

    <sect2 id="zend.search.lucene.index-creation.creating">
        <title>Создание нового индекса<!--Creating a New Index--></title>

        <para>
            Возможности по созданию и обновлению индекса
            реализованы в модуле Zend_Search_Lucene и Java Lucene.
            Вы можете использовать обе эти возможности.
<!--
            Index creation and updating capabilities are implemented within Zend_Search_Lucene module and Java Lucene.
            You can use both of these capabilities.
-->
        </para>

        <para>
            Приведенный ниже листинг кода PHP дает пример того, как
            индексировать файл, используя программный интерфейс Zend_Search_Lucene
            для индексирования.
<!--
            The PHP code listing below provides an example of how to index a file
            using Zend_Search_Lucene indexing API:
-->
        </para>

        <programlisting language="php"><![CDATA[<?php
// Создание индекса
$index = Zend_Search_Lucene::create('/data/my-index');

$doc = new Zend_Search_Lucene_Document();

// Сохранение URL документа для того, чтобы идентифицировать его
// в результатах поиска
$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));

// Индексирование содержимого документа
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $docContent));

// Добавление документа в индекс
$index->addDocument($doc);
?>]]></programlisting>

        <para>
            Только что добавленные документы можно сразу извлекать из индекса.
<!--
            Newly added documents could be immediately retrieved from an index.
-->
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.updating">
        <title>Обновление индекса<!--Updating Index--></title>

        <para>
            Та же самая процедура используется при обновлении существующего
            индекса. Единственное отличие состоит в том, что вместо метода
            create() вызывается метод open():
<!--
            The same procedure is used to update an existing index. The only difference
            is that the open() method is called instead of the create() method:
-->
        </para>

        <programlisting language="php"><![CDATA[<?php
// Открытие существующего индекса
$index = Zend_Search_Lucene::open('/data/my-index');

$doc = new Zend_Search_Lucene_Document();
// Сохраниение URL документа для того, чтобы идентифицировать его в результатах поиска.
$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
// Индексация содержимого документа.
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $docContent));

// Добавление документа в индекс.
$index->addDocument($doc);
?>]]>   </programlisting>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.document-updating">
        <title>Обновление документов<!--Updating Documents--></title>

        <para>
            Формат файлов индекса Lucene не поддерживает обновление документов.
            Для обновления документ должен быть удален и добавлен снова.
<!--
            Lucene index file format doesn't support document updating. Document should be removed and re-added to do this.
-->
        </para>

        <para>
            Метод <code>Zend_Search_Lucene::delete()</code> оперирует с внутренним
            идентификатором индекса документа. Он может быть получен из результата
            запроса ("хит") через свойство 'id':
<!--
            <code>Zend_Search_Lucene::delete()</code> method operates with an internal index document id. It can be retrieved
            from a query hit by 'id' property:
-->
        </para>

        <programlisting language="php"><![CDATA[<?php
$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>Получение размера индекса<!--Retrieving Index size--></title>

        <para>
            В Zend_Search_Lucene есть два способа получения размера индекса.
<!--
            There are two methods to retrieve index size in Zend_Search_Lucene.
-->
        </para>

        <para>
             Метод <code>Zend_Search_Lucene::maxDoc()</code> возвращает число,
             на единицу большее, чем наибольший возможный номер документа.
             Фактически это общее количество документов в индексе, включая
             удаленные. У этого метода есть синоним -
             <code>Zend_Search_Lucene::count()</code>.
<!--
             <code>Zend_Search_Lucene::maxDoc()</code> returns one greater than the largest possible document number.
             It's actually overall number of the documents in the index including deleted documents.
             So it has a synonym: <code>Zend_Search_Lucene::count()</code>.
-->
        </para>

        <para>
             <code>Zend_Search_Lucene::numDocs()</code> возвращает общее
             количество не удаленных документов.
<!--
             <code>Zend_Search_Lucene::numDocs()</code> returns the total number of non-deleted documents.
-->
        </para>

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

        <para>
            Метод <code>Zend_Search_Lucene::isDeleted($id)</code> может
            использоваться для проверки того, был ли документ удален.
<!--
            <code>Zend_Search_Lucene::isDeleted($id)</code> method may be used to check if document is deleted.
-->
        </para>

        <programlisting language="php"><![CDATA[<?php
for ($count = 0; $count < $index->maxDoc(); $count++) {
    if ($index->isDeleted($count)) {
        echo "Document #$id is deleted.\n";
    }
}
?>]]></programlisting>

        <para>
            При оптимизации индекса производится очищение индекса от удаленных
            документов и сжатие диапазона используемых идентификаторов. Поэтому
            внутренний идентификатор документа может изменяться
<!--
            Index optimization removes deleted documents and squeezes documents' IDs. So internal document id may be changed.
-->
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.optimization">
        <title>Оптимизация индекса<!--Index optimization--></title>

        <para>
            Индекс Lucene состоит из сегментов. Каждый сегмент является
            независимой порцией данных.
<!--
            Lucene index is consist of segments. Each segment is a completely
            independent portion of data.
-->
        </para>
        <para>
            Файлы сегментов индекса Lucene по своей природе не могут обновляться.
            Обновление сегмента требует его полной реорганизации.
            За подробностями см. форматы файлов индекса
            (<ulink url="http://lucene.apache.org/java/docs/fileformats.html">http://lucene.apache.org/java/docs/fileformats.html</ulink>).
            Новые документы добавляются в индекс путем создания новых сегментов.
<!--
            Lucene index segment files can't be updated by their nature.
            A segment update needs full segment
            reorganization. See Lucene index file formats for details
            (<ulink url="http://lucene.apache.org/java/docs/fileformats.html">http://lucene.apache.org/java/docs/fileformats.html</ulink>).
            Thus new documents are added to the index by creating new segment.
-->
        </para>
        <para>
            Увеличение числа сегментов ухудшает качество индекса,
            но оптимизация индекса восстанавливает его. Оптимизация сводится к
            объединению нескольких сегментов в один. Этот процедура также не
            обновляет сегменты. Она создает новый большой сегмент, который
            содержит новый оптимизированный сегмент вместо набора старых
            сегментов и обновляет список сегментов (файл 'segments').
<!--
            Increasing number of segments reduces quality of the index,
            but index optimization restores it.
            Optimization is reduced to merging several segments into one.
            This process also doesn't update segments.
            It generates new large segment, which contains new optimized
            segment instead of the set of old segments,
            and updates segment list ('segments' file).
-->
        </para>

        <para>
            Полная оптимизация индекса может производиться через вызов метода
            <code>Zend_Search_Lucene::optimize()</code>. Он объединяет все
            сегменты индекса в один.
<!--
            Full index optimization can be invoked by <code>Zend_Search_Lucene::optimize()</code> call. It merges all
            index segments into new one:
-->
        </para>
        <programlisting language="php"><![CDATA[<?php
// Открытие существующего индекса
$index = Zend_Search_Lucene::open('/data/my-index');

// Оптимизация индекса
$index->optimize();
?>]]></programlisting>

        <para>
            Автоматическая оптимизация индекса выполняется для
            поддержания индекса в согласованном состоянии.
<!--
            Automatic index optimization is performed to keep index in a consistent state.
-->
        </para>
        <para>
            Автоматическая оптимизация является итеративным процессом,
            управление которым производится посредством нескольких опций.
            В процессе этой оптимизации очень маленькие сегменты объединяются
            в сегменты большего размера, затем эти сегменты объединяются
            в еще большие и т.д.
<!--
            Automatic optimization is an iterative process managed by several index options.
            It merges very small segments
            into larger one, then merges these larger segments into more larger and so on.
-->
        </para>

        <sect3 id="zend.search.lucene.index-creation.optimization.maxbuffereddocs">
            <title>Опция автоматической оптимизации <emphasis>MaxBufferedDocs</emphasis><!--<emphasis>MaxBufferedDocs</emphasis> auto-optimization option--></title>
            <para>
                <emphasis>MaxBufferedDocs</emphasis> является наименьшим
                количеством документов, необходимым для того, чтобы
                документы из памяти были переписаны в новый сегмент.
<!--
                <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> может быть получен или
                установлен через методы <varname>$index->getMaxBufferedDocs()</varname>
                и <varname>$index->setMaxBufferedDocs($maxBufferedDocs)</varname>
                соответственно.
<!--
                <emphasis>MaxBufferedDocs</emphasis> can be retrieved or set by
                <varname>$index->getMaxBufferedDocs()</varname> or
                <varname>$index->setMaxBufferedDocs($maxBufferedDocs)</varname> calls.
-->
            </para>
            <para>
                Значение опции по умолчанию равно 10.
<!--
                Default value is 10.
-->
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.index-creation.optimization.maxmergedocs">
            <title>Опция автоматической оптимизации <emphasis>MaxMergeDocs</emphasis><!--<emphasis>MaxMergeDocs</emphasis> auto-optimization option--></title>
            <para>
                <emphasis>MaxMergeDocs</emphasis> является наибольшим количеством
                документов при достижении которого они всегда объединяются
                методом addDocument().
                Меньшие значения (т.е. меньше, чем 10.000) являются наилучшими для
                интерактивной индексации, так как ограничивает продолжительность
                пауз в течение индексации до нескольких секунд.
                Большие значения являются наилучшими для пакетной индексации и
                более быстрого поиска.
<!--
                <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> может быть получен или
                установлен через методы <varname>$index->getMaxMergeDocs()</varname>
                и <varname>$index->setMaxMergeDocs($maxMergeDocs)</varname>
                соответственно.
<!--
                <emphasis>MaxMergeDocs</emphasis> can be retrieved or set by
                <varname>$index->getMaxMergeDocs()</varname> or
                <varname>$index->setMaxMergeDocs($maxMergeDocs)</varname> calls.
-->
            </para>
            <para>
                Значение опции по умолчанию равно PHP_INT_MAX.
<!--
                Default value is PHP_INT_MAX.
-->
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.index-creation.optimization.mergefactor">
            <title>Опция автоматической оптимизации <emphasis>MergeFactor</emphasis><!--<emphasis>MergeFactor</emphasis> auto-optimization option--></title>
            <para>
                <emphasis>MergeFactor</emphasis> определяет, как часто
                сегменты индекса объединяются с помощью addDocument().
                Чем менше значение, тем меньше и объем
                оперативной памяти, используемой в процессе индексации, и поиск
                по неоптимизированному индексу производится быстрее,
                но скорость индексации снижается. Чем больше значение,
                тем больше и объем используемой оперативной памяти,
                и индексация производится быстрее,
                в то время как поиск по неоптимизированному индексу производится медленнее.
                Таким образом, большие значения (&gt; 10) являются наилучшими
                в случае пакетной индексации, а меньшие (&lt; 10) —
                для индексов, которые поддерживаются интерактивно.
<!--
                <emphasis>MergeFactor</emphasis> determines how often segment
                indices are merged by addDocument().
                With smaller values, less RAM is used while indexing, and
                searches on unoptimized indices are faster,
                but indexing speed is slower. With larger values, more RAM 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> является хорошим средством
                оценки среднего количества сегментов, объединяемых в одном
                прохождении автоматической оптимизации. Слишком большие значения
                приводят к созданию большого количества сегментов то того, как
                они объединятся в один новый. Это может вызвать
                сообщение об ошибке "failed to open stream: Too many open files".
                Данное ограничение зависит от операционной системы.
<!--
                <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 dependant.
-->
            </para>
            <para>
                <emphasis>MergeFactor</emphasis> может быть получен или
                установлен через методы <varname>$index->getMergeFactor()</varname>
                и <varname>$index->setMergeFactor($mergeFactor)</varname>
                соответственно.
<!--
                <emphasis>MergeFactor</emphasis> can be retrieved or set by
                <varname>$index->getMergeFactor()</varname> or
                <varname>$index->setMergeFactor($mergeFactor)</varname> calls.
-->
            </para>
            <para>
                Значение опции по умолчанию равно 10.
<!--
                Default value is 10.
-->
            </para>
            <para>
                Lucene Java и Luke (Lucene Index Toolbox -
                <ulink url="http://www.getopt.org/luke/">http://www.getopt.org/luke/</ulink>)
                также могут использоваться для оптимизации индекса.
<!--
                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 index.
-->
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.limitations">
        <title>Ограничения<!--Limitationas--></title>

        <para>
            Ограничения зависят от платформы.
<!--
            Limitations are platform dependent.
-->
        </para>

        <para>
            Для 32-битной платформы максимальный размер индекса составляет 2Гб.
<!--
            Maximum index size is 2GB for 32-bit platforms.
-->
        </para>
    </sect2>

</sect1>

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